tracing

package
v0.26.0 Latest Latest
Warning

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

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

Documentation

Overview

Package tracing initializes OpenTelemetry tracing for the Gantry agent so that an image pull can be followed end to end.

containerd 2.x already instruments its own pull path and propagates the W3C traceparent header on registry HTTP calls (see containerd pkg/tracing/tracing.go and plugin/otlp.go). Gantry is the next hop on that path, so continuing the incoming context turns

kubelet PullImage -> containerd PullImage -> fetchLayer/unpackLayer
  -> Gantry mirror -> peer transfer endpoint OR upstream registry

into a single trace. Without this package the trace dead-ends at Gantry.

Tracing is OFF by default: nothing is exported and no collector connection is opened unless OTEL_TRACES_EXPORTER selects OTLP. An agent running with the default DaemonSet env therefore pays no collection cost.

Index

Constants

View Source
const (
	// AttrDigest is the content digest being served, e.g. sha256:abcd....
	AttrDigest = "gantry.digest"

	// AttrMediaType is the OCI media type of the blob or manifest.
	AttrMediaType = "gantry.media_type"

	// AttrBytes is the number of bytes moved by the span.
	AttrBytes = "gantry.bytes"

	// AttrCacheResult is "hit" or "miss" for the local content-store lookup.
	AttrCacheResult = "gantry.cache.result"

	// AttrSource is where the bytes came from: local, peer, or upstream.
	AttrSource = "gantry.source"

	// AttrPeerID identifies the peer that served or was attempted.
	AttrPeerID = "gantry.peer.id"

	// AttrRegistry is the upstream registry name the request resolved to.
	AttrRegistry = "gantry.registry"

	// AttrRepository is the OCI repository in the request path.
	AttrRepository = "gantry.repository"

	// AttrKind is "blob" or "manifest".
	AttrKind = "gantry.kind"

	// AttrStatusCode is the HTTP status Gantry returned or received.
	AttrStatusCode = "http.response.status_code"
	// AttrURLFull is the request URL recorded on a client span. It uses the
	// OpenTelemetry semantic-convention key so Gantry's spans line up with the
	// ones containerd and other OTel-instrumented components emit.
	//
	// Gantry always records this value redacted. The URL that goes on the wire
	// is a different URL; see the note on AttrURLRedacted.
	AttrURLFull = "url.full"
	// AttrURLRedacted reports whether any query value on AttrURLFull was
	// replaced with the REDACTED placeholder.
	//
	// It exists so a redaction bug is visible in the data rather than silently
	// plausible. A trace reader who knows Gantry redacts signed URLs cannot tell
	// a correctly redacted url.full from a matcher that stopped matching after a
	// provider renamed its parameters, and neither can an assertion. This flag
	// says whether the matcher fired for this request, so a regression that
	// starts exporting signatures shows up as url.redacted=false on a request
	// that also carries a signature-bearing parameter name.
	AttrURLRedacted = "gantry.url.redacted"
)

Attribute keys used across the Gantry pull path. Names follow OTel semantic-conventions naming (dotted, lowercase) with a gantry.* namespace for the domain-specific ones, so a collector can filter Gantry hops without matching unrelated instrumentation.

View Source
const (
	CacheHit  = "hit"
	CacheMiss = "miss"

	SourceLocal    = "local"
	SourcePeer     = "peer"
	SourceUpstream = "upstream"
)

Cache and source vocabulary. Exported so mirror, transfer, and origin all emit the same strings; a collector query that says source=peer has to mean the same thing on every hop.

View Source
const (
	EnvServiceName        = "OTEL_SERVICE_NAME"
	EnvResourceAttributes = "OTEL_RESOURCE_ATTRIBUTES"
	// EnvBatchDelay is the standard batch-processor schedule delay, in
	// milliseconds per the OTLP environment-variable specification.
	EnvBatchDelay = "OTEL_BSP_SCHEDULE_DELAY"
)

EnvServiceName and EnvResourceAttributes are the standard OTEL variables that name the service in a collector's service map.

View Source
const EnvExporter = "OTEL_TRACES_EXPORTER"

EnvExporter is the standard OTEL variable that selects the trace exporter. Gantry exports over OTLP/gRPC only, so any other value leaves tracing off. The OTLP/HTTP spelling is deliberately not accepted: silently ignoring a mis-set exporter is worse than staying off, and staying off is what happens either way.

View Source
const Scope = "github.com/Azure/unbounded/internal/gantry"

Scope is the instrumentation scope name carried by every span Gantry emits. One scope for the whole agent keeps a trace viewer from splitting a single pull across per-package scopes.

View Source
const ShutdownTimeout = 5 * time.Second

ShutdownTimeout bounds the final span flush at agent exit. Detached from the signal context on purpose: a collector that stops responding must not keep the agent alive past its termination grace period.

Variables

This section is empty.

Functions

func Bytes

func Bytes(n int64) attribute.KeyValue

Bytes returns the byte-count attribute.

func Cache

func Cache(hit bool) attribute.KeyValue

Cache returns the hit/miss attribute.

func Digest

func Digest(value string) attribute.KeyValue

Digest returns the digest attribute.

func Kind

func Kind(value string) attribute.KeyValue

Kind returns the blob/manifest attribute.

func MarkError

func MarkError(ctx context.Context, err error)

MarkError records err on the span active in ctx and sets error status, so a collector shows the failed hop instead of a silently truncated one. Safe to call on a no-op span and with a nil error.

func MediaType

func MediaType(value string) attribute.KeyValue

MediaType returns the media-type attribute.

func PeerID

func PeerID(value string) attribute.KeyValue

PeerID returns the peer identifier attribute.

func Provider

func Provider() trace.TracerProvider

Provider returns the global tracer provider, for handing to otelhttp so the HTTP wrappers emit into the same provider as the hand-started spans.

Resolved lazily for the same reason as Tracer: otelhttp captures the provider at wrapper-construction time, so a provider snapshot taken before Init would pin the no-op provider for the whole agent.

func Registry

func Registry(value string) attribute.KeyValue

Registry returns the upstream registry attribute.

func Repository

func Repository(value string) attribute.KeyValue

Repository returns the repository attribute.

func ServiceName

func ServiceName() string

ServiceName returns the resolved OTLP service.name, for logging at startup so an operator can confirm which identity this agent reports to the collector's service map.

func SetProviderForTest

func SetProviderForTest(provider trace.TracerProvider) trace.TracerProvider

SetProviderForTest installs provider as the global tracer provider and returns the previous one for restoration. Exported only so tests in other packages can assert on recorded spans; production code must call Init.

func Source

func Source(value string) attribute.KeyValue

Source returns the local/peer/upstream attribute.

func SpanFromContext

func SpanFromContext(ctx context.Context) trace.Span

SpanFromContext returns the span active in ctx, for sub-package code that needs to attach attributes but does not own the span lifecycle. Returns a non-recording span when tracing is disabled or no span is active, so calls are always safe.

func StatusCode

func StatusCode(code int) attribute.KeyValue

StatusCode returns the HTTP status attribute.

func Tracer

func Tracer() trace.Tracer

Tracer returns the agent's tracer from the global provider.

Call sites resolve it lazily on purpose: the global provider only becomes meaningful once Init has run, and a Tracer captured before Init would pin the no-op provider for the whole process lifetime.

Types

type Shutdown

type Shutdown func(context.Context) error

Shutdown flushes buffered spans and closes the exporter. It is a no-op when tracing was never enabled.

func Init

func Init(ctx context.Context) (Shutdown, error)

Init configures the global tracer provider and the W3C TraceContext propagator from the environment, and returns the shutdown handle.

When OTEL_TRACES_EXPORTER does not select OTLP, Init installs a no-op tracer provider and a no-op shutdown and returns a nil error. In that state every StartSpan in the agent returns a non-recording span, so the instrumentation at the mirror, transfer, and origin seams costs an interface call and nothing else.

Endpoint, headers, TLS, and compression all come from the standard OTEL_EXPORTER_OTLP_* variables, which otlptracegrpc reads on its own, so an operator configures Gantry the same way they configure any other OTel-instrumented process.

Jump to

Keyboard shortcuts

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