Documentation
¶
Overview ¶
Package tracing is the API-only half of provider-runtime's OpenTelemetry tracing (docs/design-tracing.md). It holds the provider the reconcilers use, the krateo.io/traceparent parent-or-link rule (Decide), the reconcile root span (StartReconcile), the act step that joins the upstream trace (StartActStep), and the functions that carry a trace context onto a Kubernetes object (Inject, InjectAnnotations) or an HTTP request (InjectHeader).
The rule and the spans live in plumbing's tracecontext, which unstructured-runtime applies too, so both runtimes relate to an upstream trace in the same way. This package delegates to it and keeps its own API: its Start functions take a TracerProvider and start spans in ScopeName's instrumentation scope.
It depends on the OpenTelemetry API only, never on the SDK or an exporter, so the reconciler imports it without linking an OTLP exporter into every provider. telemetry.Setup builds the SDK pipeline and hands it here with SetTracerProvider.
Propagation rules ¶
Inject and InjectAnnotations write the context onto an object another Krateo controller reconciles, and only there. Callers must follow these rules, which docs/usage.md repeats:
- Only onto an object another Krateo controller reconciles: a composition, or another provider's managed resource. Never onto a Pod, ConfigMap or Secret, and never onto the managed resource being reconciled, whose annotation is input.
- Only on a write the caller makes anyway: a create, or an update that changes the object. A write made only to refresh the annotation makes every downstream pass see a new value.
- Never in a status write: the status subresource drops metadata. When the change that matters is in status, write the annotation in a separate metadata write.
- Stamp before the change that triggers the work. When the context and the change that makes the downstream controller act are two writes, write the annotation first, so the downstream pass that acts has its act step joined to the context.
- Never copy krateo.io/traceparent-continued: it belongs to the object it is written on.
InjectHeader is for outbound HTTP calls. It reads only the active span, so with tracing off it sends nothing, and it never overwrites a traceparent the request already carries.
Index ¶
- Constants
- func Canonical(sc trace.SpanContext) string
- func HasActiveSpan(ctx context.Context) bool
- func Inject(ctx context.Context, obj metav1.Object) bool
- func InjectAnnotations(ctx context.Context, annotations map[string]string) bool
- func InjectHeader(ctx context.Context, h http.Header) bool
- func MarkActed(ctx context.Context)
- func RecordError(span trace.Span, err error)
- func SetTracerProvider(tp trace.TracerProvider)
- func StartActStep(ctx context.Context, tp trace.TracerProvider, obj Object, step string, ...) (context.Context, trace.Span)
- func StartReconcile(ctx context.Context, tp trace.TracerProvider, obj Object, d Decision, ...) (context.Context, trace.Span)
- func StartStep(ctx context.Context, tp trace.TracerProvider, step string) (context.Context, trace.Span)
- func TracerProvider() trace.TracerProvider
- func Truncate(s string) string
- type Decision
- type Mode
- type Object
- type Step
- type When
Constants ¶
const ( // NoParent: the object carries no valid traceparent. The root has no link. NoParent = tracecontext.NoParent // Parent: the traceparent's value is new. The root links to it, and the // pass's first act step (create, update or delete) is its child. Parent = tracecontext.Parent // Link: the value was already continued, or its window has closed. The root // links to it, and nothing is its child. Link = tracecontext.Link )
const ( // Never: there's no marker to write. Never = tracecontext.Never // BeforeFirstAction: just before the pass's first Create, Update or Delete // call. A pass that doesn't act writes nothing. BeforeFirstAction = tracecontext.BeforeFirstAction // Now: right after the span starts, past the pause and Orphan checks. Now = tracecontext.Now )
const ( // SpanReconcile is the root span of one reconcile. SpanReconcile = tracecontext.SpanReconcile // SpanConnect, SpanObserve, SpanCreate, SpanUpdate and SpanDelete are the // children around the provider's calls. SpanConnect = "connect" SpanObserve = "observe" SpanCreate = "create" SpanUpdate = "update" SpanDelete = "delete" )
Span names: a fixed set, never one per object (docs/design-tracing.md §4).
const ( // EventRateLimitDeferred: the governor deferred the pass's next call. EventRateLimitDeferred = "ratelimit.deferred" // EventReconcilePaused: the pause annotation short-circuited the pass. EventReconcilePaused = tracecontext.EventReconcilePaused // EventConflict: the pass requeued because a write returned a conflict. EventConflict = tracecontext.EventConflict // EventMarkerFailed: the marker write failed with anything but a conflict. EventMarkerFailed = tracecontext.EventMarkerFailed )
Events on the root span (docs/design-tracing.md §4.5). EventReconcilePaused, EventConflict and EventMarkerFailed, and the AttrStep key below, are plumbing's tracecontext constants, which unstructured-runtime emits too. The rate-limit events and keys are provider-runtime's own.
const ( AttrRateLimitKey = attribute.Key("provider_runtime.ratelimit.key") AttrRateLimitCause = attribute.Key("provider_runtime.ratelimit.cause") AttrRateLimitRequeueAfter = attribute.Key("provider_runtime.ratelimit.requeue_after_s") AttrRateLimitUntil = attribute.Key("provider_runtime.ratelimit.until") AttrStep = tracecontext.AttrStep )
Event attribute keys.
const ( AttrObjectKind = tracecontext.AttrObjectKind AttrObjectName = tracecontext.AttrObjectName AttrObjectNamespace = tracecontext.AttrObjectNamespace )
The root span's attribute keys: exactly these three, as unstructured-runtime sets them.
const AttrActed = tracecontext.AttrActed
AttrActed is a bool on the reconcile root, true when the pass started an act step (create, update or delete), joined upstream or not, and never set false. The collector's tail sampler keeps the traces that carry it, so every change a provider makes keeps its reconcile (provider-runtime#74, docs/design-tracing.md §6.7). It's plumbing's tracecontext key, which unstructured-runtime sets too.
const MaxErrorText = 4096
MaxErrorText bounds the status description and the exception.message attribute. The SDK bounds neither: SetStatus keeps the whole description, and event attributes are cut by count, not length. Error text often embeds an HTTP body (docs/design-tracing.md §7).
const ScopeName = "github.com/krateo-platformops/provider-runtime"
ScopeName is the instrumentation scope of every span provider-runtime starts. The meter in pkg/telemetry uses the same name.
Variables ¶
This section is empty.
Functions ¶
func Canonical ¶
func Canonical(sc trace.SpanContext) string
Canonical is sc's traceparent as W3C TraceContext writes it: version 00, lower-case hex, and only the sampled and random flags. It's the form the marker records, and "" for an invalid sc.
func HasActiveSpan ¶
HasActiveSpan reports whether ctx holds a span with a valid span context, which is when InjectHeader would set a header. A transport calls it first, so it clones a request only when there's something to set.
func Inject ¶
Inject writes ctx's trace context onto obj, an object another Krateo controller reconciles: krateo.io/traceparent, and krateo.io/tracestate when the context has one. The context is the active span's, or with tracing off the inbound context the reconciler carried.
It overwrites: an existing krateo.io/traceparent is replaced, and an existing krateo.io/tracestate is replaced when the context has a tracestate and removed when it has none, so a stale tracestate never travels with a new traceparent. Without a valid context it returns false and changes nothing. It never writes krateo.io/traceparent-continued.
See the package documentation for where to call it: only onto an object another Krateo controller reconciles, only on a write the caller makes anyway, never in a status write, and before the change that triggers the work.
func InjectAnnotations ¶
InjectAnnotations does what Inject does, on an annotations map. It returns false and changes nothing when ctx has no valid trace context, or when annotations is nil.
func InjectHeader ¶
InjectHeader sets the W3C traceparent header on h, and tracestate when there is one, from ctx's active span only. It never uses the inbound context, so with tracing off it sends nothing. It never overwrites a traceparent h already has, which comes from a more specific span in the same process, such as an otelhttp client span. It never sets baggage. It reports whether it set the header.
func MarkActed ¶ added in v1.15.0
MarkActed sets AttrActed on the span active in ctx, which must be the pass's reconcile root. StartActStep marks the root itself, so a caller needs MarkActed only for an act it opens with StartStep. Without a recording span in ctx it does nothing.
func RecordError ¶
RecordError records err on span as an exception event and sets the span's status to Error, both with the error text cut to MaxErrorText bytes on a rune boundary. A nil err records nothing.
func SetTracerProvider ¶
func SetTracerProvider(tp trace.TracerProvider)
SetTracerProvider sets the provider the reconcilers use when they're given none of their own. telemetry.Setup calls it when tracing is on. A provider that builds its own SDK TracerProvider calls it too, so the reconciler's spans go through that pipeline. nil turns tracing off.
func StartActStep ¶ added in v1.14.1
func StartActStep(ctx context.Context, tp trace.TracerProvider, obj Object, step string, upstream trace.SpanContext) (context.Context, trace.Span)
StartActStep opens an act step, the create, update or delete span around the provider's call, for obj. With upstream valid, it is the first act for a new krateo.io/traceparent value (D8):
- its parent is upstream, so the act and the calls it makes join the upstream trace;
- it carries one link back to the reconcile root in ctx;
- it carries the root's three k8s.object attributes, since it isn't the root's child and its root is often not stored;
- the root gains a link to it (Span.AddLink), when the act is sampled. An unsampled act, which a parent-based sampler makes under an unsampled upstream, is never exported, so the root doesn't point at it.
With upstream invalid it is an ordinary StartStep child of the root. With tp nil it starts nothing.
func StartReconcile ¶
func StartReconcile(ctx context.Context, tp trace.TracerProvider, obj Object, d Decision, start time.Time) (context.Context, trace.Span)
StartReconcile opens the reconcile root span for obj, starting at start. Every reconcile is its own trace (docs/design-tracing.md, D8): the root is always a new root, never a child of d.Remote and never of a span already in ctx. When d.Remote is valid (modes Parent and Link) it carries one link to it; with NoParent it has none. Only the pass's first act step for a new value joins the upstream trace (StartActStep), which adds a second link, from the root to that act. The span is SpanKindServer, named reconcile, with exactly the attributes k8s.object.kind, k8s.object.name and k8s.object.namespace.
With tp nil it starts nothing. It returns ctx carrying d.Remote, when that's valid, for Inject and InjectAnnotations only, and the no-op span.
func StartStep ¶
func StartStep(ctx context.Context, tp trace.TracerProvider, step string) (context.Context, trace.Span)
StartStep opens the child span named step under the reconcile root in ctx, with tp's tracer. It's SpanKindInternal and has no attributes of its own. With tp nil it starts nothing and returns ctx and the no-op span.
func TracerProvider ¶
func TracerProvider() trace.TracerProvider
TracerProvider returns the provider SetTracerProvider set, or nil when tracing is off. A reconciler reads it on every pass, with one atomic load.
Types ¶
type Decision ¶
type Decision = tracecontext.Decision
A Decision is what Decide concluded for one reconcile.
- Mode is how the reconcile relates to Remote.
- Remote is the annotation's span context. It is valid in Parent and Link.
- Marker is the krateo.io/traceparent-continued value to write, or "" when WriteMarker is Never.
- WriteMarker is when the reconciler writes Marker.
func Decide ¶
func Decide(annotations map[string]string, remembered string, firstSeen, now time.Time, window time.Duration) Decision
Decide applies the parent-or-link rule of docs/design-tracing.md §6.2. It is pure, and it allocates nothing when the object carries no krateo.io/traceparent.
- annotations are the object's annotations.
- remembered is the value this process already marked, or failed to mark, on this object, or "".
- firstSeen is when this process first saw the annotation's current value, by the monotonic clock. The zero time means first sight, with the window open.
- window is how long a new value keeps making Parent passes that don't act. 0 means Parent with WriteMarker Now on the first pass: the first-sight rule.
The rules, in order. R is the annotation's span context. R is continued when the object's marker, or remembered, has R's trace ID and span ID.
- R isn't valid: NoParent, Never.
- R is continued: Link, Never.
- window is 0: Parent, Now.
- firstSeen is zero, or now - firstSeen < window: Parent, BeforeFirstAction.
- Otherwise: Link, Now.
type Mode ¶
type Mode = tracecontext.Mode
Mode is how a reconcile relates to the object's krateo.io/traceparent (docs/design-tracing.md §6.2, D8). In every mode the reconcile root is a new root; the modes differ in its link and in whether an act step joins the upstream trace.
type Object ¶
type Object = tracecontext.Object
Object names the object a reconcile is about.
- Kind is the Kind alone, such as Repo, without its group.
- Name is the object's name.
- Namespace is the object's namespace, "" for a cluster-scoped object.