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 caller's step that APPLIES changes: Create/Update/Delete in provider-runtime, whose Observe is a pure read; Observe in the composition-dynamic- controller, whose Observe applies the release's children (plumbing helm Reconcile). The marker is written before that step, so for the cdc a conflict delays the first Observe of a new value by one requeue.
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
- func Canonical(sc trace.SpanContext) string
- func Inbound(ctx context.Context) trace.SpanContext
- func StartActStep(ctx context.Context, tracer trace.Tracer, obj Object, step string, ...) (context.Context, trace.Span)
- func StartReconcile(ctx context.Context, tracer trace.Tracer, obj Object, d Decision, ...) (context.Context, trace.Span)
- func StartStep(ctx context.Context, tracer trace.Tracer, step string) (context.Context, trace.Span)
- func WithInbound(ctx context.Context, sc trace.SpanContext) context.Context
- type Decision
- type Mode
- type Object
- type When
Constants ¶
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.
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.
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.
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.
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).
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 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;
- 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 tracer nil it starts 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 ¶
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 ¶
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.
- 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 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 )
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.