from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.resources import Resource

# Initialize tracer provider with resource attributes
resource = Resource.create({"service.name": "order-service", "deployment.environment": "production"})
provider = TracerProvider(resource=resource)
provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))
trace.set_tracer_provider(provider)

tracer = trace.get_tracer("order-service.tracer")

def process_order(order_id: str):
    with tracer.start_as_current_span("process_order") as span:
        span.set_attribute("order.id", order_id)
        span.set_attribute("order.status", "pending")
        # Business logic here
        validate_payment(order_id)
        return {"status": "success"}

from opentelemetry.propagate import inject, extract
from opentelemetry.propagators.textmap import DictGetter
import requests

# Client: Inject trace context into HTTP headers
def call_payment_service(order_id: str):
    headers = {}
    inject(headers)  # Injects traceparent, tracestate
    with tracer.start_as_current_span("call_payment_service") as span:
        span.set_attribute("http.method", "POST")
        span.set_attribute("http.url", "https://payment-api/process")
        response = requests.post(
            "https://payment-api/process",
            json={"order_id": order_id},
            headers=heade

rs ) return response.json()

Server: Extract trace context from incoming request

from flask import Flask, request from opentelemetry.instrumentation.flask import FlaskInstrumentor

app = Flask(name) FlaskInstrumentor().instrument_app(app) # Auto-injects extraction

@app.route("/process", methods=["POST"]) def handle_payment(): # Context is automatically extracted by instrumentation with tracer.start_as_current_span("handle_payment") as span: span.set_attribute("payment.amount", request.json.get("amount")) # Process payment return {"status": "processed"}

### 3. Async/Queue Tracing (Kafka Example)
Message queues break synchronous call chains. Context must be serialized into message headers or payloads.
```python
from opentelemetry.propagate import inject
from kafka import KafkaProducer, KafkaConsumer
import json

producer = KafkaProducer(bootstrap_servers='localhost:9092')

def publish_order_event(order_data: dict):
    headers = []
    inject(headers, setter=lambda carrier, key, value: carrier.append((key, value.encode())))
    
    producer.send(
        'orders',
        value=json.dumps(order_data).encode(),
        headers=headers
    )
    producer.flush()

# Consumer side extracts context
consumer = KafkaConsumer('orders', bootstrap_servers='localhost:9092')
for message in consumer:
    ctx = extract(message.headers)
    with tracer.start_as_current_span("consume_order", context=ctx) as span:
        span.set_attribute("messaging.destination", "orders")
        span.set_attribute("messaging.message_id", str(message.offset))
        # Process event

4. Sampling Configuration

Unsampled traces in high-throughput systems cause storage explosion and performance degradation.

from opentelemetry.sdk.trace.sampling import TraceIdRatioBased, ALWAYS_ON, ALWAYS_OFF

# 10% sampling for production, always sample errors
provider = TracerProvider(
    sampler=TraceIdRatioBased(0.1),
    resource=resource
)

In production, combine head sampling with tail-based sampling (via OpenTelemetry Collector) to retain traces containing errors or high latency, regardless of initial probability.

---

Pitfall Guide

1. Over-Instrumentation & Span Noise

Symptom: Traces contain hundreds of spans per request; UI becomes unusable; storage costs spike.
Root Cause: Instrumenting every function, library call, or internal loop iteration.
Mitigation: Instrument at service boundaries and critical business operations. Use library auto-instrumentation for frameworks (Flask, FastAPI, Django, gRPC) but disable low-value spans via configuration. Apply semantic conventions to avoid custom span proliferation.

2. Ignoring Sampling Strategies

Symptom: Tracing backend crashes under load; traces disappear during incidents; budget overruns.
Root Cause: Default ALWAYS_ON sampling in production environments handling >10k RPS.
Mitigation: Implement head sampling (probabilistic) at the SDK level. Deploy tail sampling in the OpenTelemetry Collector to retain error/latency outliers. Tune ratios based on traffic volume and retention policies.

3. Context Leakage in Async/Threaded Environments

Symptom: Traces split into orphaned segments; parent-child relationships break; latency attribution incorrect.
Root Cause: Failing to propagate context across thread pools, async tasks, or worker queues.
Mitigation: Explicitly pass context objects when spawning tasks. Use framework-specific instrumentation (e.g., opentelemetry-instrumentation-asyncio, Celery instrumentation). Verify context continuity in unit tests.

4. Inconsistent Span Naming & Semantic Conventions

Symptom: Dashboards show fragmented span names; automated alerting fails; cross-team trace correlation breaks.
Root Cause: Teams invent naming schemes; ignore OpenTelemetry semantic conventions.
Mitigation: Adopt OTel semantic conventions for HTTP, DB, messaging, and RPC. Enforce naming via linting or CI checks. Standardize span names as operation.resource (e.g., GET /users/{id}).

5. Missing Baggage for Cross-Service Correlation

Symptom: Cannot trace requests across tenant boundaries; audit trails lack business context; debugging requires manual log correlation.
Root Cause: Baggage API ignored or disabled due to security concerns.
Mitigation: Propagate non-sensitive business keys (tenant ID, user ID, session ID) via baggage. Sanitize and validate baggage at service boundaries. Disable baggage for PII/credentials. Use allowlists.

6. Vendor Lock-in & OpenTelemetry Misuse

Symptom: Migration to new backend requires rewriting instrumentation; SDK version conflicts; vendor-specific APIs leak into codebase.
Root Cause: Using vendor SDKs instead of OTel API; hardcoding exporter endpoints; bypassing standard context propagation.
Mitigation: Code against opentelemetry-api only. Configure exporters via environment variables or collector YAML. Avoid vendor-specific trace enrichments. Treat OTel as the single source of truth.

---

Production Bundle

✅ Deployment Checklist

• SDK initialized with TracerProvider and resource attributes (service.name, environment)
• Auto-instrumentation applied to web frameworks, DB drivers, HTTP clients, and message brokers
• Context propagation verified across HTTP, gRPC, and async boundaries
• Sampling strategy configured (head + tail) with documented retention policy
• Baggage allowlist defined and PII/secret filtering enforced
• Semantic conventions applied to all custom spans
• OpenTelemetry Collector deployed with receivers, processors, and exporters
• Trace backend configured (Jaeger, Tempo, Datadog, New Relic, or custom)
• Alerting rules created on trace error rates and p95 latency thresholds
• Load testing validates trace throughput without latency degradation
• Documentation includes span naming guide and context propagation examples
• Rollback plan includes disabling tracing via feature flag or env var

📊 Decision Matrix

Criteria	Probability Sampling	Tail Sampling	Always On	Vendor SDK	OpenTelemetry
Latency Impact	Low	Medium (collector)	High	Low-Medium	Low
Storage Cost	Predictable	Optimized	Unbounded	High	Optimized
Error Visibility	May miss	Guaranteed	Guaranteed	Guaranteed	Guaranteed
Migration Flexibility	High	High	Low	Low	High
Team Complexity	Low	Medium	Low	Low	Medium
Best For	>50k RPS, cost-sensitive	Incident-heavy systems	Low-traffic, compliance	Rapid prototyping	Production standard

Recommendation: Use OpenTelemetry + Tail Sampling for production. Reserve probability sampling for development/staging. Avoid vendor SDKs in greenfield projects.

⚙️ Config Template (OpenTelemetry Collector)

receivers:
  otlp:
    protocols:
      grpc:
      http:

processors:
  batch:
    timeout: 5s
    send_batch_size: 8192
  probabilistic_sampler:
    sampling_percentage: 20
  tail_sampling:
    policies:
      - name: error-traces
        type: status_code
        status_code: { status_codes: [ "ERROR" ] }
      - name: high-latency
        type: latency
        latency: { threshold_ms: 500 }

exporters:
  otlp/jaeger:
    endpoint: jaeger-collector:4317
    tls:
      insecure: true
  logging:
    loglevel: debug

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch, probabilistic_sampler, tail_sampling]
      exporters: [otlp/jaeger, logging]

Notes: Deploy collector as sidecar or daemonset. Tune batch and sampler thresholds based on traffic. Use logging exporter only for debugging; remove in production.

🚀 Quick Start (10 Minutes)

1. Install SDK: pip install opentelemetry-api opentelemetry-sdk opentelemetry-exporter-otlp-proto-grpc
2. Initialize Tracer: Add provider setup with service.name and OTLPSpanExporter to your application entry point.
3. Instrument Framework: Run opentelemetry-instrument flask run (or equivalent for FastAPI/Django) to auto-inject HTTP spans.
4. Configure Collector: Deploy the YAML config above to a local Docker container or Kubernetes pod.
5. Verify: Send a test request, open your trace backend (e.g., Jaeger UI), and confirm traceparent propagation and span hierarchy. Add sampling and baggage as needed.

---

Distributed tracing is not a monitoring add-on; it is a architectural contract for observability. When patterns are applied consistently, traces become the backbone of incident response, capacity planning, and service reliability engineering. Start with boundaries, enforce conventions, sample intelligently, and treat context as a first-class citizen. The result is not just visibility, but velocity.