tracing

Documentation

Overview

Package tracing installs an OpenTelemetry tracer provider configured from the standard OTEL_* environment variables. If neither an OTLP endpoint nor OTEL_TRACES_EXPORTER is set, Init returns a no-op shutdown but still installs the W3C TraceContext + Baggage propagator so inbound traceparent headers are honoured.

The exporter is selected by go.opentelemetry.io/contrib/exporters/autoexport, which reads OTEL_TRACES_EXPORTER ("otlp" by default; "console" or "none" also supported) and OTEL_EXPORTER_OTLP_PROTOCOL ("http/protobuf" by default; "grpc" supported).

Service identity is supplied two ways: the serviceName and serviceVersion arguments to Init are written as semconv attributes when non-empty, and OTEL_SERVICE_NAME / OTEL_RESOURCE_ATTRIBUTES override them. There is no OTEL_SERVICE_VERSION env var — pass the build version as the second argument or include service.version in OTEL_RESOURCE_ATTRIBUTES.

Resource attributes come from process/OS/container detectors merged with OTEL_RESOURCE_ATTRIBUTES. Kubernetes attrs (k8s.pod.name, k8s.namespace.name, k8s.node.name) should be rendered into that variable via the downward API at deploy time, e.g.:

env:
  - name: POD_NAME
    valueFrom: { fieldRef: { fieldPath: metadata.name } }
  - name: POD_NAMESPACE
    valueFrom: { fieldRef: { fieldPath: metadata.namespace } }
  - name: NODE_NAME
    valueFrom: { fieldRef: { fieldPath: spec.nodeName } }
  - name: OTEL_RESOURCE_ATTRIBUTES
    value: "k8s.pod.name=$(POD_NAME),k8s.namespace.name=$(POD_NAMESPACE),k8s.node.name=$(NODE_NAME)"

Index

• type Option
  • func WithResourceOptions(opts ...resource.Option) Option
  • func WithServiceName(name string) Option
  • func WithServiceVersion(version string) Option
• type Shutdown
  • func Init(ctx context.Context, opts ...Option) (Shutdown, error)

Examples

• Init (Basic)
• Init (ExtraResourceAttributes)

Types

type Option

type Option func(*config)

Option configures Init. The zero set of options gives an unconfigured service: the W3C propagator is installed and a no-op Shutdown is returned.

func WithResourceOptions

func WithResourceOptions(opts ...resource.Option) Option

WithResourceOptions appends resource.Option values to the toolkit's resource.New option list. Use to add extra attributes (deployment.environment, custom labels) or detectors (k8s, AWS, GCP). The toolkit's own options — semconv ServiceName/Version, Process, OS, Container, FromEnv — are applied first; caller-supplied options follow.

func WithServiceName

func WithServiceName(name string) Option

WithServiceName sets semconv.ServiceName on the TracerProvider's Resource. OTEL_SERVICE_NAME / OTEL_RESOURCE_ATTRIBUTES take precedence; empty leaves the env vars in charge.

func WithServiceVersion

func WithServiceVersion(version string) Option

WithServiceVersion sets semconv.ServiceVersion. There is no OTEL_SERVICE_VERSION env var; pass the build version here or in OTEL_RESOURCE_ATTRIBUTES.

type Shutdown

type Shutdown func(ctx context.Context) error

Shutdown drains any pending spans. Idempotent.

func Init

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

Init installs the global OpenTelemetry TracerProvider and the W3C TraceContext + Baggage propagators.

Init must be called at most once per process. A second call installs a new global TracerProvider, leaving the first one's BatchSpanProcessor goroutine running with no way to recover a reference for shutdown.

The exporter (OTLP/HTTP, OTLP/gRPC, console, or none) is selected by autoexport from OTEL_TRACES_EXPORTER + OTEL_EXPORTER_OTLP_PROTOCOL. Resource attributes come from process/OS/container detectors merged with OTEL_RESOURCE_ATTRIBUTES and any caller-supplied WithResourceOptions; render Kubernetes attrs (k8s.pod.name, k8s.namespace.name, k8s.node.name) into OTEL_RESOURCE_ATTRIBUTES via the downward API.

If no OTLP endpoint and no OTEL_TRACES_EXPORTER are set, Init still installs the propagator (so inbound traceparent headers propagate) and returns a no-op Shutdown.

Example (Basic)

ExampleInit_basic shows the typical service composition root.

package main

import (
	"context"

	"github.com/giantswarm/mcp-toolkit/tracing"
)

func main() {
	shutdown, err := tracing.Init(context.Background(),
		tracing.WithServiceName("your-mcp"),
		tracing.WithServiceVersion("1.2.3"),
	)
	if err != nil {
		panic(err)
	}
	defer func() { _ = shutdown(context.Background()) }()
}

Example (ExtraResourceAttributes)

ExampleInit_extraResourceAttributes shows how to attach deployment-specific attributes (environment, cluster, region) to every emitted span without going through OTEL_RESOURCE_ATTRIBUTES.

package main

import (
	"context"

	"go.opentelemetry.io/otel/attribute"
	"go.opentelemetry.io/otel/sdk/resource"

	"github.com/giantswarm/mcp-toolkit/tracing"
)

func main() {
	shutdown, err := tracing.Init(context.Background(),
		tracing.WithServiceName("your-mcp"),
		tracing.WithServiceVersion("1.2.3"),
		tracing.WithResourceOptions(resource.WithAttributes(
			attribute.String("deployment.environment", "production"),
			attribute.String("cluster.name", "glean"),
		)),
	)
	if err != nil {
		panic(err)
	}
	defer func() { _ = shutdown(context.Background()) }()
}