tracecontext

package
v1.60.0 Latest Latest
Warning

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

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

Documentation

Overview

Package tracecontext is the krateo.io/traceparent rule both Krateo runtimes apply, so that a composition's reconcile trace (unstructured-runtime) and its provider's managed-resource trace (provider-runtime) relate to an upstream trace in the same way. It holds the pure parent-or-link rule (Decide), the reconcile root span (StartReconcile), the act step that joins the upstream trace (StartActStep), ordinary steps (StartStep), the inbound context for injectors (Inbound), and the three annotation keys. The design is provider-runtime's docs/design-tracing.md (§6.2, decisions D6 and D8).

Two seams differ from where this code started:

  • the Start functions take the CALLER's trace.Tracer, because the instrumentation scope must identify the runtime, not this package. A nil Tracer starts nothing, and with it StartReconcile allocates nothing for an object without krateo.io/traceparent. A non-nil Tracer, even a no-op one, means tracing is on;
  • the inbound span context StartReconcile stores with tracing off is exported as WithInbound / Inbound, because the injectors that read it stay in each runtime.

The rule (D8)

Every reconcile is its own trace: the root is always a new root, linked to the object's krateo.io/traceparent when it is valid. Only the pass's FIRST ACT for a new value joins the upstream trace, as the act step's parent; the root and the act then link to each other (the root to the act only when the act is sampled). A value already continued, or whose window has closed, is linked and never joined. See Decide for the ordered rules.

The contract each runtime implements itself

The pure rule is here; its state is not, because it is tied to each runtime's reconciler. A runtime adopting this package must keep, per object:

  • a memo keyed by namespaced name, holding the uid, and replaced when the uid or the canonical value differs; created only when tracing is on and Decide returned a WriteMarker other than Never; dropped on NotFound (tracing on or off), on finalizer removal, when the annotation goes away or stops parsing, and when a read shows the marker. It supplies Decide's remembered and firstSeen;
  • the marker krateo.io/traceparent-continued, written with value Decision.Marker when Decision.WriteMarker says: BeforeFirstAction is just before the pass's first create, update or delete (a pass that does not act writes nothing); Now is right after the root starts, past the pause check and any path that releases the object without acting, and before anything acts. Write it with an optimistic-lock merge patch on a copy, copy back only the resourceVersion and the marker, and requeue BEFORE acting on a conflict;
  • the marker write's outcome: on success, or NotFound (the object is gone), remember the value as marked; on a conflict, requeue before acting and leave the memo as it was, so the next pass reads the object afresh; on any other error (RBAC, an admission webhook), remember the value as failed, record the trace.marker_failed event on the root, log once per object, and let the pass go on and act. Later passes pass a marked or failed value as Decide's remembered, so they link; a seen-only value passes firstSeen and no remembered;
  • write the marker at most once per pass;
  • the act step: call StartActStep with d.Remote only when d.Mode is Parent, and only for the pass's FIRST create, update or delete; every other act step, and every act in NoParent or Link mode, is StartStep (or StartActStep with an invalid upstream). d.Remote is valid in Link mode too, so passing it unconditionally re-joins the upstream on every acting pass. The act step is the call that APPLIES changes, and only the code making it knows whether it does. provider-runtime's act steps are Create/Update/Delete, its Observe being a pure read. unstructured-runtime opens one around Create/Update/Delete too, and a handler whose Observe applies changes declares its act there with controller.StartAct, right before the mutating call: the composition-dynamic-controller's Observe applies the release's children (plumbing helm Reconcile) only when the release exists, so treating every Observe as the act would join a new object's upstream at an Observe that applied nothing and leave the install that follows linked, not joined. A handler-declared act follows the same rules as the runtime's: the marker is written BEFORE the mutating call, with the outcomes above (success or NotFound: marked; a conflict: requeue before acting, so it delays the act by one requeue; any other error: failed, and the act goes on). The handler declares it only on the path that actually mutates, once per pass; a later call in the same pass opens nothing.

provider-runtime's pkg/reconciler/traces.go is the reference implementation of that contract.

Not shared

Left to each runtime, deliberately: error and status handling on spans (provider-runtime cuts an error description at 4096 bytes, records an exception event, never sets Ok, and records a panic as "panic"); the act and step names and the instrumentation scope, which belong to the caller; what Object carries (Kind without its group, Namespace "" for a cluster-scoped object); and which context an injector stamps a child from, which decides whether the downstream work chains to this pass.

Index

Constants

View Source
const (
	// EventReconcilePaused is recorded on the reconcile root when the pass returns at a pause
	// check without acting. The root is still emitted, because the controller IS alive; the event
	// is what tells a paused object from a freshly reconciled one (unstructured-runtime#78).
	EventReconcilePaused = "reconcile.paused"
	// EventMarkerFailed is recorded on the root when the krateo.io/traceparent-continued marker
	// write fails with anything but a conflict or NotFound (see the package doc's contract).
	EventMarkerFailed = "trace.marker_failed"
	// EventConflict is recorded when a write in the pass loses an optimistic-concurrency race,
	// with AttrStep naming where.
	EventConflict = "k8s.conflict"
)

Span events and attribute keys both runtimes emit, so a query or a sampler rule reads the same bytes whichever runtime produced the span (agreed with the provider-runtime session, 2026-11-11). Runtime-specific events, such as provider-runtime's rate-limit governor events, stay in that runtime.

View Source
const (
	// AnnotationKeyTraceparent carries a W3C traceparent onto an object another Krateo controller
	// reconciles.
	AnnotationKeyTraceparent = "krateo.io/traceparent"
	// AnnotationKeyTracestate carries the matching W3C tracestate.
	AnnotationKeyTracestate = "krateo.io/tracestate"
	// AnnotationKeyTraceparentContinued records the traceparent value this object's reconciler has
	// continued, so later passes link to it instead of joining it. It belongs to the object it is
	// written on: never copy it onto another object.
	AnnotationKeyTraceparentContinued = "krateo.io/traceparent-continued"
)

The annotation keys of the cross-runtime trace contract. Both runtimes alias these: a composition and its provider's managed resource must read and write the same bytes.

View Source
const (
	AttrObjectKind      = attribute.Key("k8s.object.kind")
	AttrObjectName      = attribute.Key("k8s.object.name")
	AttrObjectNamespace = attribute.Key("k8s.object.namespace")
)

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

View Source
const AttrActed = attribute.Key("provider_runtime.acted")

AttrActed is a bool, true on the reconcile root of any pass that starts an act step (StartActStep, i.e. a create, update or delete, or a handler-declared act such as unstructured-runtime's controller.StartAct), whether or not that act joins an upstream trace. It is never set to false. The collector's tail sampler keeps traces carrying it: a pass that made changes keeps its record, including a non-joined act, which lives in the root's own trace. Set it with MarkActed. Same "provider_runtime." prefix as AttrStep, for the same reason.

View Source
const AttrStep = attribute.Key("provider_runtime.step")

AttrStep names the step an EventConflict happened in. The KEY is shared; its VALUES are each runtime's own (provider-runtime's map its conflict sites). The string keeps provider-runtime's original "provider_runtime." prefix on purpose: renaming it would move provider-runtime's exported name and every query that already reads it.

View Source
const DefaultContinueWindow = 10 * time.Minute

DefaultContinueWindow is how long a new traceparent value keeps making Parent passes that don't act before Decide turns them into Link passes (provider-runtime's default; its docs/design-tracing.md).

View Source
const (
	SpanReconcile = "reconcile"
)

The span names this package starts. SpanReconcile is the root; act and step names are the caller's (provider-runtime uses create/update/delete; unstructured-runtime its own phases).

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 Inbound

func Inbound(ctx context.Context) trace.SpanContext

Inbound is the span context StartReconcile stored with tracing OFF: the annotation's, when it was valid, else the invalid span context. Injectors fall back to it only when there is no active span; it never carries the krateo.io/traceparent-continued marker, and an outbound HTTP injector must not use it (provider-runtime's InjectHeader reads only the active span).

func MarkActed added in v1.48.0

func MarkActed(ctx context.Context)

MarkActed sets AttrActed=true on the span active in ctx, which must be the pass's reconcile root (the ctx StartReconcile returned, or one derived from it before any act step starts). StartActStep calls it in both its branches, so a runtime whose every act goes through StartActStep never calls it directly. A runtime that acts WITHOUT opening a step span (unstructured-runtime opens one only for the joined act) calls it at each act instead. It only ever sets true; with no recording span in ctx it does nothing.

func StartActStep

func StartActStep(ctx context.Context, tracer trace.Tracer, 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):

The caller passes upstream = d.Remote only when d.Mode is Parent and this is the pass's first act step; StartActStep doesn't check the mode.

  • 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, when the root is sampled;
  • 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.

The two links follow ONE rule (provider-runtime#74): each is added only when its target is sampled, because an unsampled span is never exported and a link to it would point at nothing. "Sampled" is the HEAD decision, the SDK sampler's. Whether either target is STORED is the collector's (tail sampling), so neither link is guaranteed to resolve in a backend; the rule only keeps this process from writing a link it already knows points nowhere. Before v1.48.0 the act linked to its root unconditionally.

In both cases, joined or not, it first marks the root in ctx with AttrActed (MarkActed).

With upstream invalid it is an ordinary StartStep child of the root. With tracer nil it starts nothing and marks nothing.

func StartReconcile

func StartReconcile(ctx context.Context, tracer trace.Tracer, 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 tracer nil it starts nothing and allocates nothing beyond the context value. It returns ctx carrying d.Remote, when that's valid, for the runtime's injectors only (Inbound), and the no-op span. tracer is the CALLER's: its instrumentation scope identifies the runtime.

func StartStep

func StartStep(ctx context.Context, tracer trace.Tracer, step string) (context.Context, trace.Span)

StartStep opens the child span named step under the reconcile root in ctx, with tracer. It's SpanKindInternal and has no attributes of its own. With tracer nil it starts nothing and returns ctx and the no-op span.

func WithInbound

func WithInbound(ctx context.Context, sc trace.SpanContext) context.Context

WithInbound returns ctx carrying sc as the inbound span context, for a runtime's injectors to fall back to when tracing is off. StartReconcile does this itself with a nil tracer; it is exported so a runtime can do the same on a path that does not start a span.

Types

type Decision

type Decision struct {
	// Mode is how the reconcile relates to Remote.
	Mode Mode
	// Remote is the annotation's span context. It is valid in Parent and Link.
	Remote trace.SpanContext
	// Marker is the krateo.io/traceparent-continued value to write, or "" when
	// WriteMarker is Never.
	Marker string
	// WriteMarker is when the reconciler writes Marker.
	WriteMarker When
}

A Decision is what Decide concluded for one reconcile.

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 int

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.

const (
	// NoParent: the object carries no valid traceparent. The root has no link.
	NoParent Mode = iota
	// 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
	// Link: the value was already continued, or its window has closed. The root
	// links to it, and nothing is its child.
	Link
)

func (Mode) String

func (m Mode) String() string

type Object

type Object struct {
	// Kind is the Kind alone, such as Repo, without its group.
	Kind string
	// Name is the object's name.
	Name string
	// Namespace is the object's namespace, "" for a cluster-scoped object.
	Namespace string
}

Object names the object a reconcile is about.

type When

type When int

When says when the reconciler writes Decision.Marker.

const (
	// Never: there's no marker to write.
	Never When = iota
	// BeforeFirstAction: just before the pass's first Create, Update or Delete
	// call. A pass that doesn't act writes nothing.
	BeforeFirstAction
	// Now: right after the span starts, past the pause and Orphan checks.
	Now
)

func (When) String

func (w When) String() string

Jump to

Keyboard shortcuts

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