OpenTelemetry end-to-end: instrumentação app → backend

// instrumentation.js — rodado antes do app inicializar
import { NodeSDK } from '@opentelemetry/sdk-node';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-grpc';
import { OTLPMetricExporter } from '@opentelemetry/exporter-metrics-otlp-grpc';
import { Resource } from '@opentelemetry/resources';
import { SemanticResourceAttributes } from '@opentelemetry/semantic-conventions';

const sdk = new NodeSDK({
  resource: new Resource({
    [SemanticResourceAttributes.SERVICE_NAME]: 'checkout-api',
    [SemanticResourceAttributes.SERVICE_VERSION]: process.env.APP_VERSION,
    [SemanticResourceAttributes.DEPLOYMENT_ENVIRONMENT]: process.env.NODE_ENV,
  }),
  traceExporter: new OTLPTraceExporter({ url: 'http://otel-collector:4317' }),
  metricExporter: new OTLPMetricExporter({ url: 'http://otel-collector:4317' }),
  instrumentations: [getNodeAutoInstrumentations({
    // Remove instrumentação barulhenta se precisar
    '@opentelemetry/instrumentation-fs': { enabled: false },
  })],
});

sdk.start();

# Rode com a instrumentação carregada ANTES da app
node --require ./instrumentation.js server.js

# Ou (mais recente) via package.json:
# "scripts": { "start": "node --import ./instrumentation.js server.js" }

# Instala SDK + auto-instrumentations pra libs populares
pip install opentelemetry-distro opentelemetry-exporter-otlp
opentelemetry-bootstrap -a install

# Rode a app embrulhada
OTEL_SERVICE_NAME=checkout-api \
  OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317 \
  OTEL_RESOURCE_ATTRIBUTES=deployment.environment=production \
  opentelemetry-instrument python app.py

# app.py — spans manuais pra lógica de negócio
from opentelemetry import trace, metrics

tracer = trace.get_tracer(__name__)
meter = metrics.get_meter(__name__)

orders_counter = meter.create_counter(
    "orders_created_total",
    description="Número de pedidos criados",
)

async def create_order(data: dict):
    with tracer.start_as_current_span("create_order") as span:
        span.set_attribute("user.id", data["user_id"])
        span.set_attribute("cart.item_count", len(data["items"]))
        span.set_attribute("cart.total_cents", data["total_cents"])

        # Sub-span pra lógica de validação
        with tracer.start_as_current_span("validate_inventory"):
            await validate_inventory(data["items"])

        # Sub-span pra payment
        with tracer.start_as_current_span("charge_payment") as pay_span:
            try:
                result = await charge(data["user_id"], data["total_cents"])
                pay_span.set_attribute("payment.gateway", result.gateway)
            except PaymentError as e:
                pay_span.set_status(trace.StatusCode.ERROR, str(e))
                pay_span.record_exception(e)
                raise

        orders_counter.add(1, {"tier": data.get("user_tier", "free")})
        return {"id": order_id}

# otel-collector-config.yaml
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

  # também aceita formatos alternativos pra migração
  jaeger:
    protocols:
      grpc: { endpoint: 0.0.0.0:14250 }
  prometheus:
    config:
      scrape_configs:
        - job_name: 'apps'
          static_configs:
            - targets: ['app:9090']

processors:
  batch:                      # agrupa antes de exportar — eficiência massiva
    timeout: 5s
    send_batch_size: 1024

  memory_limiter:              # evita OOM do Collector sob burst
    check_interval: 1s
    limit_mib: 500

  attributes:                  # scrub PII / transform attributes
    actions:
      - key: user.email
        action: delete
      - key: authorization
        action: delete
      - key: http.url
        action: update
        value: "REDACTED"
        pattern: "token=[^&]+"

  tail_sampling:               # amostragem inteligente — explicado abaixo
    decision_wait: 10s
    policies:
      - name: errors-policy
        type: status_code
        status_code: { status_codes: [ERROR] }
      - name: slow-policy
        type: latency
        latency: { threshold_ms: 500 }
      - name: random-policy
        type: probabilistic
        probabilistic: { sampling_percentage: 5 }

exporters:
  otlp/tempo:
    endpoint: tempo:4317
    tls: { insecure: true }
  prometheusremotewrite:
    endpoint: http://mimir:8080/api/v1/push
  loki:
    endpoint: http://loki:3100/loki/api/v1/push

service:
  pipelines:
    traces:
      receivers: [otlp, jaeger]
      processors: [memory_limiter, attributes, tail_sampling, batch]
      exporters: [otlp/tempo]
    metrics:
      receivers: [otlp, prometheus]
      processors: [memory_limiter, batch]
      exporters: [prometheusremotewrite]
    logs:
      receivers: [otlp]
      processors: [memory_limiter, attributes, batch]
      exporters: [loki]

# Request de A pra B
GET /api/items HTTP/1.1
Host: items-service
traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
             │  │                                 │                │
             │  └─ trace-id (hex, 16 bytes)       └─ parent-span  flags
             └─ version
tracestate: congo=t61rcWkgMzE,rojo=00f067aa0ba902b7       # vendor-specific extensions
baggage: user.tier=pro,tenant=acme                         # application-level context

# manual_propagation.py — para libs sem instrumentação automática
from opentelemetry.propagate import inject, extract
from opentelemetry import context

# ─ outbound: injetar ─
carrier = {}
inject(carrier)   # preenche carrier com traceparent, tracestate, baggage
# carrier = {"traceparent": "00-...-01", "tracestate": "..."}
response = await http.post(url, json=data, headers=carrier)

# ─ inbound: extrair ─
ctx = extract(incoming_headers)
with tracer.start_as_current_span("handle", context=ctx):
    # span novo virou child do span upstream
    ...

# tail_sampling — política inteligente no Collector
processors:
  tail_sampling:
    decision_wait: 10s        # aguarda trace completar
    num_traces: 100000         # buffer de traces em memória
    policies:
      # Sempre guardar traces com erro
      - name: errors
        type: status_code
        status_code: { status_codes: [ERROR] }

      # Sempre guardar traces lentos
      - name: slow
        type: latency
        latency: { threshold_ms: 1000 }

      # Sempre guardar algum endpoint crítico
      - name: checkout
        type: string_attribute
        string_attribute:
          key: url.path
          values: ["/checkout"]

      # Amostra 5% do resto
      - name: baseline
        type: probabilistic
        probabilistic: { sampling_percentage: 5 }

// Node.js — resource detectors
import { Resource } from '@opentelemetry/resources';
import { envDetector, hostDetector, processDetector } from '@opentelemetry/resources';
import { awsEcsDetector, awsEc2Detector } from '@opentelemetry/resource-detector-aws';
import { k8sAttributesDetector } from '@opentelemetry/resource-detector-kubernetes';

const sdk = new NodeSDK({
  resourceDetectors: [
    envDetector, hostDetector, processDetector,
    awsEc2Detector, awsEcsDetector,
    k8sAttributesDetector,
  ],
  // ...
});