From observability
Configure OpenTelemetry context propagation (OTEL_PROPAGATORS) for services running in Kubernetes, especially when using mirrord to intercept or steal traffic. Use this skill whenever the user mentions OTEL_PROPAGATORS, OpenTelemetry propagators, trace context headers, W3C tracecontext, B3 headers, distributed tracing setup, OTel auto-instrumentation configuration, or configuring header propagation for mirrord sessions. Also trigger when someone asks about traceparent headers, baggage propagation, connecting local dev tracing to a cluster, or ensuring downstream services see the correct trace context when traffic is intercepted by mirrord. This skill covers env vars, Kubernetes Instrumentation CRDs, docker-compose, Spring Boot properties, and local dev config for mirrord users.
How this skill is triggered — by the user, by Claude, or both
Slash command
/observability:setup-otel-propagationThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Help developers configure `OTEL_PROPAGATORS` and related OpenTelemetry SDK environment variables
Help developers configure OTEL_PROPAGATORS and related OpenTelemetry SDK environment variables
so that trace context headers are properly injected and extracted across services — especially
when using mirrord to intercept traffic from a Kubernetes cluster.
When a developer runs mirrord in steal or mirror mode, their local process handles HTTP
requests that originated in the cluster. If the upstream service injected trace headers
(e.g., traceparent, X-B3-TraceId), the local process must:
Without matching OTEL_PROPAGATORS configuration, trace continuity breaks and downstream
services lose visibility into the request chain.
Read the propagators reference before generating any configuration:
view /path/to/this/skill/references/propagators-reference.md
This file contains the full list of valid propagator values, per-language quirks, Kubernetes Instrumentation CRD patterns, and common pitfalls.
Ask the user (only if not already clear from context):
http://otel-collector:4317)Default recommendation: tracecontext,baggage
Add others based on context:
| Scenario | Propagators |
|---|---|
| Standard W3C (recommended default) | tracecontext,baggage |
| Istio / Envoy service mesh | tracecontext,baggage,b3,b3multi |
| Zipkin ecosystem | b3multi or b3 |
| AWS X-Ray | xray (add tracecontext,baggage too) |
| Jaeger (legacy) | jaeger (add tracecontext,baggage too) |
| Mixed / migration | tracecontext,baggage,b3multi |
Based on deployment mode, produce ONE of the following output types:
export OTEL_PROPAGATORS="tracecontext,baggage"
export OTEL_SERVICE_NAME="my-service"
export OTEL_TRACES_EXPORTER="otlp"
export OTEL_EXPORTER_OTLP_ENDPOINT="http://otel-collector:4317"
export OTEL_EXPORTER_OTLP_PROTOCOL="grpc"
apiVersion: opentelemetry.io/v1alpha1
kind: Instrumentation
metadata:
name: my-instrumentation
namespace: <namespace>
spec:
exporter:
endpoint: http://otel-collector.<namespace>.svc.cluster.local:4317
propagators:
- tracecontext
- baggage
sampler:
type: parentbased_traceidratio
argument: "1"
Plus the annotation for the Deployment:
annotations:
instrumentation.opentelemetry.io/inject-<language>: "true"
spec:
template:
spec:
containers:
- name: my-container
env:
- name: OTEL_PROPAGATORS
value: "tracecontext,baggage"
- name: OTEL_SERVICE_NAME
value: "my-service"
- name: OTEL_TRACES_EXPORTER
value: "otlp"
- name: OTEL_EXPORTER_OTLP_ENDPOINT
value: "http://otel-collector:4317"
application.propertiesotel.propagators=tracecontext,baggage
otel.resource.attributes.service.name=my-service
otel.exporter.otlp.endpoint=http://otel-collector:4317
services:
my-service:
environment:
- OTEL_PROPAGATORS=tracecontext,baggage
- OTEL_SERVICE_NAME=my-service
- OTEL_TRACES_EXPORTER=otlp
- OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317
When the user is using mirrord, also generate the local-side configuration. The local process must use the same propagator set as the cluster services.
Environment variables for local dev session:
# Match cluster propagators exactly
export OTEL_PROPAGATORS="tracecontext,baggage"
export OTEL_SERVICE_NAME="my-service-local"
export OTEL_TRACES_EXPORTER="otlp"
# Point to local or cluster collector
export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4317"
Tip: If the cluster has an OTel Collector accessible via mirrord's network, the local process can reach it at its cluster-internal address since mirrord proxies outgoing traffic to the cluster.
mirrord.json env configuration — make sure OTEL_PROPAGATORS is included
in the mirrored environment:
{
"feature": {
"env": {
"include": "OTEL_PROPAGATORS;OTEL_SERVICE_NAME;OTEL_TRACES_EXPORTER;OTEL_EXPORTER_OTLP_ENDPOINT;OTEL_EXPORTER_OTLP_PROTOCOL;OTEL_TRACES_SAMPLER;OTEL_TRACES_SAMPLER_ARG;OTEL_RESOURCE_ATTRIBUTES"
}
}
}
Or if the user prefers to override locally (e.g., different service name):
{
"feature": {
"env": {
"include": "OTEL_PROPAGATORS;OTEL_EXPORTER_OTLP_ENDPOINT;OTEL_EXPORTER_OTLP_PROTOCOL",
"override": {
"OTEL_SERVICE_NAME": "my-service-local-dev"
}
}
}
}
After generating config, verify:
tracecontext, baggage, b3, b3multi, jaeger, ottrace, xray, xray-lambdahttp/protobuf;
if collector endpoint is :4317 (gRPC), set OTEL_EXPORTER_OTLP_ENDPOINT
to port 4318 insteadb3,b3multi to
propagators alongside tracecontext,baggageenv.include doesn't capture OTEL_PROPAGATORS,
the local process falls back to SDK defaults which may differ from cluster configotel.propagators overrides the env var
OTEL_PROPAGATORS; check bothOTEL_PROPAGATORS values that aren't in the OTel specInstrumentation CR without specifying propagators
explicitly (the defaults may vary between Operator versions)baggage propagator — it's almost always needed alongside
tracecontext for full context propagationENV if the OTel Operator is also
injecting them — they'll conflictGuides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.
npx claudepluginhub metalbear-co/observability-skills --plugin observability