tracing

package
v1.14.3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 11, 2026 License: Apache-2.0 Imports: 13 Imported by: 0

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

View Source
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
)
View Source
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
)
View Source
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).

View Source
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.

View Source
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.

View Source
const (
	AttrObjectKind      = tracecontext.AttrObjectKind
	AttrObjectName      = tracecontext.AttrObjectName
	AttrObjectNamespace = tracecontext.AttrObjectNamespace
)

The root span's attribute keys: exactly these three, as unstructured-runtime sets them.

View Source
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).

View Source
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

func HasActiveSpan(ctx context.Context) bool

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

func Inject(ctx context.Context, obj metav1.Object) bool

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

func InjectAnnotations(ctx context.Context, annotations map[string]string) bool

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

func InjectHeader(ctx context.Context, h http.Header) bool

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 RecordError

func RecordError(span trace.Span, err error)

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.

func Truncate

func Truncate(s string) string

Truncate cuts s to at most MaxErrorText bytes, without splitting a rune.

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.

  1. R isn't valid: NoParent, Never.
  2. R is continued: Link, Never.
  3. window is 0: Parent, Now.
  4. firstSeen is zero, or now - firstSeen < window: Parent, BeforeFirstAction.
  5. 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.

type Step

type Step string

A Step names the write that returned a conflict, as the k8s.conflict event's provider_runtime.step attribute. The set is every kerrors.IsConflict site in the reconciler, and the marker write.

const (
	StepConnect       Step = "connect"
	StepObserve       Step = "observe"
	StepHandshake     Step = "handshake"
	StepFinalizer     Step = "finalizer"
	StepCreatePending Step = "create_pending"
	StepCreate        Step = "create"
	StepLateInit      Step = "late_init"
	StepMarker        Step = "marker"
)

func Steps

func Steps() []Step

Steps returns every Step, in the order above, as a new slice each call.

type When

type When = tracecontext.When

When says when the reconciler writes Decision.Marker.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL