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
- func Bytes(n int64) attribute.KeyValue
- func Cache(hit bool) attribute.KeyValue
- func Digest(value string) attribute.KeyValue
- func Kind(value string) attribute.KeyValue
- func MarkError(ctx context.Context, err error)
- func MediaType(value string) attribute.KeyValue
- func PeerID(value string) attribute.KeyValue
- func Provider() trace.TracerProvider
- func Registry(value string) attribute.KeyValue
- func Repository(value string) attribute.KeyValue
- func ServiceName() string
- func SetProviderForTest(provider trace.TracerProvider) trace.TracerProvider
- func Source(value string) attribute.KeyValue
- func SpanFromContext(ctx context.Context) trace.Span
- func StatusCode(code int) attribute.KeyValue
- func Tracer() trace.Tracer
- type Shutdown
Constants ¶
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.
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.
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.
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.
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.
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 MarkError ¶
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 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 Repository ¶
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 SpanFromContext ¶
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 ¶
StatusCode returns the HTTP status attribute.
Types ¶
type Shutdown ¶
Shutdown flushes buffered spans and closes the exporter. It is a no-op when tracing was never enabled.
func Init ¶
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.