OpenTelemetry

OpenTelemetry es el estándar de CNCF para recopilar datos de telemetría (trazas, métricas, registros) de aplicaciones e infraestructura.

Instalación

Node.js/JavaScript

# Paquetes principales
npm install @opentelemetry/api @opentelemetry/sdk-node

# Auto-instrumentación
npm install @opentelemetry/auto

# Exportadores
npm install @opentelemetry/exporter-trace-otlp-http
npm install @opentelemetry/exporter-metrics-otlp-http

# Instrumentación para librerías
npm install @opentelemetry/instrumentation-express
npm install @opentelemetry/instrumentation-http
npm install @opentelemetry/instrumentation-pg

Python

# Paquetes principales
pip install opentelemetry-api
pip install opentelemetry-sdk

# Exportadores
pip install opentelemetry-exporter-otlp
pip install opentelemetry-exporter-jaeger

# Instrumentación
pip install opentelemetry-instrumentation-flask
pip install opentelemetry-instrumentation-requests
pip install opentelemetry-instrumentation-sqlalchemy

Java

# Dependencias de Maven
<dependency>
    <groupId>io.opentelemetry</groupId>
    <artifactId>opentelemetry-api</artifactId>
    <version>1.28.0</version>
</dependency>

<dependency>
    <groupId>io.opentelemetry</groupId>
    <artifactId>opentelemetry-sdk</artifactId>
    <version>1.28.0</version>
</dependency>

# Auto-instrumentación del agente Java
wget https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/download/v1.28.0/opentelemetry-javaagent.jar

Configuración Básica

Tracing de Node.js

// tracing.js
const { NodeSDK } = require("@opentelemetry/sdk-node");
const { getNodeAutoInstrumentations } = require("@opentelemetry/auto-instrumentations-node");
const { OTLPTraceExporter } = require("@opentelemetry/exporter-trace-otlp-http");

const sdk = new NodeSDK({
  traceExporter: new OTLPTraceExporter({
    url: "http://localhost:4318/v1/traces"
  }),
  instrumentations: [getNodeAutoInstrumentations()]
});

sdk.start();

console.log("Tracing initialized");

Tracing de Python

# tracing.py
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.instrumentation.flask import FlaskInstrumentor
from opentelemetry.instrumentation.requests import RequestsInstrumentor

# Configurar exportador OTLP
otlp_exporter = OTLPSpanExporter(
    endpoint="http://localhost:4318/v1/traces"
)

# Configurar proveedor de rastreador
trace.set_tracer_provider(TracerProvider())
trace.get_tracer_provider().add_span_processor(
    BatchSpanProcessor(otlp_exporter)
)

# Auto-instrumentar librerías
FlaskInstrumentor().instrument()
RequestsInstrumentor().instrument()

tracer = trace.get_tracer(__name__)

Tracing de Java

# Ejecutar con agente Java
java -javaagent:opentelemetry-javaagent.jar \
  -Dotel.exporter.otlp.endpoint=http://localhost:4318 \
  -Dotel.service.name=my-app \
  -jar app.jar

Instrumentación Manual

Crear Spans

// Node.js
const { trace } = require("@opentelemetry/api");
const tracer = trace.getTracer("my-app");

const span = tracer.startSpan("process-request", {
  attributes: {
    "http.method": "GET",
    "http.url": "/api/users"
  }
});

try {
  // Realizar trabajo
  span.addEvent("Processing user data");
  span.setStatus({ code: 0 });
} catch (error) {
  span.recordException(error);
  span.setStatus({ code: 2, message: error.message });
} finally {
  span.end();
}

# Python
from opentelemetry import trace

tracer = trace.get_tracer(__name__)

with tracer.start_as_current_span("process_request") as span:
    span.set_attribute("http.method", "GET")
    span.set_attribute("http.url", "/api/users")

    try:
        # Realizar trabajo
        span.add_event("Processing user data")
    except Exception as e:
        span.record_exception(e)
        raise

Recopilación de Métricas

Métricas de JavaScript

// metrics.js
const { MeterProvider, PeriodicExportingMetricReader } = require("@opentelemetry/sdk-metrics");
const { OTLPMetricExporter } = require("@opentelemetry/exporter-metrics-otlp-http");

const reader = new PeriodicExportingMetricReader({
  exporter: new OTLPMetricExporter({
    url: "http://localhost:4318/v1/metrics"
  })
});

const meterProvider = new MeterProvider({ reader });
const meter = meterProvider.getMeter("my-app");

// Crear contador
const requestCounter = meter.createCounter("http.requests", {
  description: "Total HTTP requests"
});

requestCounter.add(1, {
  "http.method": "GET",
  "http.status_code": 200
});

// Crear histograma
const latencyHistogram = meter.createHistogram("http.duration", {
  unit: "ms",
  description: "HTTP request duration"
});

latencyHistogram.record(123, {
  "http.method": "GET"
});

Métricas de Python

# metrics.py
from opentelemetry.sdk.metrics import MeterProvider
from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
from opentelemetry.exporter.otlp.proto.http.metric_exporter import OTLPMetricExporter

reader = PeriodicExportingMetricReader(
    OTLPMetricExporter(endpoint="http://localhost:4318/v1/metrics")
)
meter_provider = MeterProvider(metric_readers=[reader])
meter = meter_provider.get_meter("my-app")

# Contador
request_counter = meter.create_counter(
    "http.requests",
    description="Total HTTP requests"
)
request_counter.add(1, {"http.method": "GET", "http.status_code": 200})

# Histograma
latency_histogram = meter.create_histogram(
    "http.duration",
    unit="ms",
    description="HTTP request duration"
)
latency_histogram.record(123, {"http.method": "GET"})

Configuración de Exportadores

Exportador OTLP

// Sobre HTTP
const { OTLPTraceExporter } = require("@opentelemetry/exporter-trace-otlp-http");

const exporter = new OTLPTraceExporter({
  url: "http://localhost:4318/v1/traces",
  headers: {
    "api-key": "your-api-key"
  },
  concurrencyLimit: 10,
  timeoutMillis: 30000
});

// Sobre gRPC
const { OTLPTraceExporter } = require("@opentelemetry/exporter-trace-otlp-grpc");

const exporter = new OTLPTraceExporter({
  url: "grpc://localhost:4317"
});

Exportador Jaeger

// Node.js
const { JaegerExporter } = require("@opentelemetry/exporter-jaeger");

const exporter = new JaegerExporter({
  host: "localhost",
  port: 6831,
  serviceName: "my-app"
});

# Python
from opentelemetry.exporter.jaeger.thrift import JaegerExporter

jaeger_exporter = JaegerExporter(
    agent_host_name="localhost",
    agent_port=6831,
)

trace.get_tracer_provider().add_span_processor(
    BatchSpanProcessor(jaeger_exporter)
)

Exportador Zipkin

// Node.js
const { ZipkinExporter } = require("@opentelemetry/exporter-zipkin");

const exporter = new ZipkinExporter({
  url: "http://localhost:9411/api/v2/spans",
  serviceName: "my-app"
});

Propagación de Contexto

Contexto de Traza W3C

// Configuración de propagador
const { W3CTraceContextPropagator } = require("@opentelemetry/core");
const { CompositePropagator } = require("@opentelemetry/core");

const propagator = new CompositePropagator({
  propagators: [new W3CTraceContextPropagator()]
});

// Extraer contexto de solicitud
const ctx = propagator.extract(context.active(), {
  get: (key) => req.headers[key.toLowerCase()]
});

// Inyectar contexto en solicitud saliente
propagator.inject(ctx, carrier, {
  set: (key, value) => outgoingRequest.headers[key] = value
});

Procesamiento por Lotes

JavaScript

const { BatchSpanProcessor } = require("@opentelemetry/sdk-trace-node");

const batchProcessor = new BatchSpanProcessor(otlpExporter, {
  maxQueueSize: 2048,
  maxExportBatchSize: 512,
  scheduledDelayMillis: 5000,
  exportTimeoutMillis: 30000
});

tracerProvider.addSpanProcessor(batchProcessor);

Configuración de Docker Compose

# docker-compose.yml
version: '3'
services:
  otel-collector:
    image: otel/opentelemetry-collector:latest
    ports:
      - "4317:4317"  # OTLP gRPC
      - "4318:4318"  # OTLP HTTP
      - "9411:9411"  # Zipkin
    volumes:
      - ./otel-config.yaml:/etc/otel-collector-config.yaml
    command: ["--config=/etc/otel-collector-config.yaml"]

  jaeger:
    image: jaegertracing/all-in-one:latest
    ports:
      - "6831:6831/udp"
      - "16686:16686"  # Jaeger UI

  prometheus:
    image: prom/prometheus:latest
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml

Mejores Prácticas

• Inicializar rastreo temprano en el inicio de la aplicación
• Usar propagación de contexto para rastreo distribuido entre servicios
• Establecer atributos significativos de span para depuración y filtrado
• Implementar muestreo para reducir gastos generales en sistemas de alto tráfico
• Configurar procesadores por lotes para mejor rendimiento
• Usar registros estructurados junto con spans
• Monitorear la salud del exportador y exportaciones fallidas
• Establecer umbrales de alerta para latencia de trazas
• Usar instrumentación personalizada para métricas de negocio
• Documentar atributos de span personalizados y sus significados
• Revisar y actualizar regularmente paquetes de instrumentación
• Probar muestreo de trazas en entornos similares a producción

Recursos

• Documentación de OpenTelemetry
• Paquetes de Instrumentación
• Especificaciones de Protocolo
• Slack de Comunidad

---

Última actualización: 2025-03-30