Observability¶

GTB services emit the three OpenTelemetry signals — traces, metrics and logs — over OTLP/HTTP to a collector. The plumbing lives as subpackages of pkg/telemetry, over a shared OTel core, and the per-request instrumentation lives beside the request logging in pkg/http and pkg/grpc.

This is distinct from the product analytics in the same package. Analytics is the vendor learning about users and runs on informed consent (opt-in). Observability is the operator instrumenting their own service and runs on implied consent (configuration). The two share the telemetry.* config root and the export core, but never a consent gate. See The two consent models.

Package layout¶

Setup¶

telemetry.Setup is the one call that wires everything from props.Props:

func Setup(ctx context.Context, p *props.Props, controller controls.Controllable) (Shutdown, error)

It resolves each signal from config, builds only the enabled providers, installs them as the OTel globals, sets the W3C trace-context + baggage propagators, and — when a controller is supplied — registers a telemetry service so the providers flush on graceful stop. Call it in serve, after the controller exists:

controller := controls.NewController(ctx, controls.WithLogger(p.Logger))

if _, err := telemetry.Setup(ctx, p, controller); err != nil {
    return err
}

Signals whose telemetry.<signal>.enabled is false are skipped, so an unconfigured service pays nothing.

Transport instrumentation¶

Spans and the standard server metrics come from the OTel contrib libraries, wrapped as one-line helpers that read the global providers Setup installed.

gRPC — a stats handler passed to Register:

grpcSrv, _ := grpc.Register(ctx, "grpc", controller, p.Config, p.Logger,
    grpc.OTelStatsHandler())

HTTP — a Chain-compatible middleware. Put it ahead of the logging middleware so the access log can read the active span:

chain := http.NewChain(
    http.OTelMiddleware("macguffin"),
    http.LoggingMiddleware(p.Logger),
)
http.Register(ctx, "http", controller, p.Config, p.Logger, mux, http.WithMiddleware(chain))

Custom, business-level instrumentation needs no GTB API — use the OTel globals directly:

ctx, span := otel.Tracer("macguffin/store").Start(ctx, "Store.Create")
defer span.End()

Trace correlation in logs¶

When OTelMiddleware / OTelStatsHandler precede the request logging, the logging middleware and interceptor pull the active span from the request context and add trace_id and span_id to the access log. Because they are ordinary log fields, the correlation reaches both the human-readable stderr output (so kubectl logs line up with traces) and any OTLP log records exported via the logs bridge. With no active span the fields are simply absent.

Configuration¶

All under the telemetry.* root, resolved shared-then-per-signal (the same shared-plus-override style as pkg/tls). An empty endpoint is intentional — it lets the OTel SDK read the standard OTEL_EXPORTER_OTLP_* environment variables.

Per-signal endpoint, headers and insecure override the shared values individually.

The two consent models¶

The defining distinction of this package:

• Informed consent — analytics. telemetry.Collector collects usage data about the user. It is off by default and runs only on opt-in (telemetry.enabled), with TelemetryConfig.ForceEnabled for enterprise embedded config. Unchanged by observability.
• Implied consent — observability. Setup collects operational data about the service, emitted by the operator to the operator's own collector. It is gated only by telemetry.<signal>.enabled, never by telemetry.enabled. Enabling tracing does not enable analytics, and disabling analytics does not disable tracing. There is no consent prompt, no machine-ID hashing and no GDPR deletion flow on this path — those are analytics concerns.

The principle: the kind of data decides the consent model. Personal/usage data needs informed consent; operational data runs on implied consent. The CLI and the web service are the canonical homes of each.

Lifecycle¶

Each provider batches and exports asynchronously, and flushes its buffer on Shutdown. Setup registers that shutdown as a controller service, so a SIGTERM drains telemetry in the same graceful window that drains in-flight requests — no dropped spans on a clean stop. Callers without a controller get a Shutdown return value to defer themselves.