pctx

Documentation

Overview

Package pctx implements contexts for Pachyderm.

Contexts are the root of most tracing, logging, auth, etc. This package manages a context that is set up to do all of those things. (At the time of this writing, actually just logging, but the FUTURE is bright.)

GETTING A CONTEXT

If you are creating a new application, use `Background` to get the root context and derive all future contexts from that. HTTP and gRPC servers have an interceptor to do this already.

If you need to gradually introduce contexts into an existing package, use `TODO` to get one to use as needed.

DERIVED CONTEXTS

It goes without saying that it is perfectly safe to use context.WithTimeout, context.WithCancel, context.WithValue, etc. The derived context will inherit the capabilities of its parent.

Sometimes you want to spin-off a long-running operation with a name and some fields. The Child function in this package takes care of this for you. `Child(parent, "name", [options...])`. Each Child call changes the name of the underlying instrumentation, concatenating its own name with the parent's name and a dot. So as you get deeper into children, you might see that the logs come from something like "PPS.master.pipelineController(default/edges).outgoingHttp", allowing you to see where about in the stack the data came from.

The convention is to use oneCamelCaseWord for the logger name, and for parents to name their children. Instead of:

func worker(ctx context.Context) {
    ctx = pctx.Child(ctx, "worker")
    ...
}

Prefer:

go s.worker(pctx.Child(ctx, "worker"))

Index

• func Background(process string) context.Context
• func Child(ctx context.Context, name string, opts ...Option) context.Context
• func TODO() context.Context
• func TestContext(t testing.TB, options ...TestOption) context.Context
• func WithCancel(root context.Context) (context.Context, context.CancelFunc)
• type Option
  • func WithCounter[T meters.Monoid](metric string, zero T, options ...meters.Option) Option
  • func WithDelta[T meters.Signed](metric string, threshold T, options ...meters.Option) Option
  • func WithFields(fields ...zap.Field) Option
  • func WithGauge[T any](metric string, zero T, options ...meters.Option) Option
  • func WithOptions(opts ...zap.Option) Option
  • func WithServerID() Option
  • func WithoutRatelimit() Option
• type TestOption
  • func WithZapTestOptions(opts ...zaptest.LoggerOption) TestOption

Examples

• Child

Functions

func Background

func Background(process string) context.Context

Background returns a context for use in long-running background processes. If the background process needs to inherit something other than a clean non-cancelable context, use Child instead.

func Child

func Child(ctx context.Context, name string, opts ...Option) context.Context

Child returns a named child context, with additional options. The new name can be empty. Options are applied in an arbitrary order.

Calling Child with a name adds the name to the current name, separated by a dot. For example, Child(Child(Background(), "PPS"), "master") would result in logs and metrics in the PPS.master namespace. It is okay to add interesting data to these names, like fmt.Sprintf("pipelineController(%s)", pipeline.Name). We prefer camel case names, and () to quote dynamic data.

Example

log.InitPachctlLogger()
log.SetLevel(log.DebugLevel)
ctx := Background("")
meters.Inc(ctx, "counter", 1)
meters.Set(ctx, "gauge", 42)
meters.Sample(ctx, "sampler", "hi")

ctx, c := WithCancel(ctx)
ctx = Child(ctx, "aggregated", WithCounter("counter", 0, meters.WithFlushInterval(time.Second)))
ctx = Child(ctx, "", WithGauge("gauge", 0, meters.WithFlushInterval(time.Second)))
for i := 0; i < 1<<24; i++ {
	meters.Inc(ctx, "counter", 1)
	meters.Set(ctx, "gauge", i)
}
c()

func TODO

func TODO() context.Context

TODO returns a context for use in Pachyderm, for code that will be updated to take a proper context in the near future. It should not be used in new code.

func TestContext

func TestContext(t testing.TB, options ...TestOption) context.Context

TestContext returns a context suitable for use as the root context of tests.

func WithCancel

func WithCancel(root context.Context) (context.Context, context.CancelFunc)

WithCancel is a version of context.WithCancel that returns a cancellation function that sets the cancellation cause to the call frame that called the CancelFunc.

Types

type Option

type Option struct {
	// contains filtered or unexported fields
}

Option is an option for customizing a child context.

func WithCounter

func WithCounter[T meters.Monoid](metric string, zero T, options ...meters.Option) Option

WithCounter adds an aggregated counter metric to the context.

func WithDelta

func WithDelta[T meters.Signed](metric string, threshold T, options ...meters.Option) Option

WithDelta adds an aggregated delta metric to the context.

func WithFields

func WithFields(fields ...zap.Field) Option

WithFields returns a context that includes additional fields that appear on each log line.

func WithGauge

func WithGauge[T any](metric string, zero T, options ...meters.Option) Option

WithGauge adds an aggregated gauge metric to the context.

func WithOptions

func WithOptions(opts ...zap.Option) Option

WithOptions returns a context that modifies the logger with additional Zap options.

func WithServerID

func WithServerID() Option

WithServerID generates a server ID and attaches it to the context. It appears on each log produced by the child.

func WithoutRatelimit

func WithoutRatelimit() Option

WithoutRatelimit returns a context that does not rate limit its logs.

type TestOption

type TestOption func(o *testOptions)

TestOption allows you to supply configuration tweaks to TestContext.

func WithZapTestOptions

func WithZapTestOptions(opts ...zaptest.LoggerOption) TestOption

WithZapTestOptions supplies additional zaptest.LoggerOptions to the logger returned by TestContext. Raw zap options can be supplied by wrapping them with zaptest.WrapOptions, but note that behavior can be weird. Most tests will not need any logging options.