OpenTelemetry

Cómo funciona

Las APIs, SDKs e instrumentaciones generan señales. OTLP define su transporte y el Collector puede recibirlas, transformarlas y enviarlas a uno o varios backends. La propagación de contexto relaciona spans de una misma operación distribuida.

Ejemplo: recibir trazas localmente

Esta configuración mínima de un OpenTelemetry Collector habilita OTLP por HTTP y muestra trazas para diagnóstico local:

receivers:
  otlp:
    protocols:
      http:
        endpoint: 127.0.0.1:4318
exporters:
  debug: {}
service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [debug]

La aplicación instrumentada debe enviar trazas al receptor. En producción, configura un exportador hacia el backend elegido.

Señales y conceptos

Concepto	Descripción
Trace / span	Operación distribuida y cada uno de sus pasos, con duración, atributos y estado
Métricas	Contadores, histogramas y gauges agregados
Logs	Registros, correlacionados con la traza activa
Resource	Quién emite: service.name, versión, entorno, host, pod
Contexto	trace_id y span_id propagados entre servicios (cabecera W3C traceparent)
Baggage	Pares clave-valor que viajan con el contexto (con cuidado: se propagan a terceros)

Las convenciones semánticas fijan nombres comunes (http.request.method, db.system, messaging.destination.name) para que los paneles y consultas funcionen igual en todos los servicios y backends.

Instrumentación automática

# Java: agente sin cambiar el código
java -javaagent:opentelemetry-javaagent.jar -jar app.jar

# Python
pip install opentelemetry-distro opentelemetry-exporter-otlp
opentelemetry-bootstrap -a install
opentelemetry-instrument uvicorn app.main:app

# Configuración común por variables de entorno
export OTEL_SERVICE_NAME=api-solicitudes
export OTEL_RESOURCE_ATTRIBUTES=deployment.environment.name=prod,service.version=1.8.0
export OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
export OTEL_TRACES_SAMPLER=parentbased_traceidratio
export OTEL_TRACES_SAMPLER_ARG=0.2

La instrumentación automática cubre frameworks web, clientes HTTP, JDBC, Kafka y muchas librerías más.

Spans manuales para la lógica de negocio

from opentelemetry import trace

tracer = trace.get_tracer("originacion")

def evaluar_solicitud(solicitud):
    with tracer.start_as_current_span("evaluar_solicitud") as span:
        span.set_attribute("solicitud.producto", solicitud.producto)
        span.set_attribute("solicitud.pais", solicitud.pais)
        try:
            resultado = motor_reglas.evaluar(solicitud)
            span.set_attribute("solicitud.decision", resultado.decision)
            return resultado
        except Exception as e:
            span.record_exception(e)
            span.set_status(trace.Status(trace.StatusCode.ERROR))
            raise

No pongas datos personales (documento, nombre) en atributos; usa identificadores internos.

Collector para producción

processors:
  memory_limiter:
    check_interval: 1s
    limit_percentage: 80
  batch: {}
  attributes/redactar:
    actions:
      - key: http.request.header.authorization
        action: delete
  tail_sampling:
    policies:
      - {
          name: errores,
          type: status_code,
          status_code: { status_codes: [ERROR] },
        }
      - { name: lentas, type: latency, latency: { threshold_ms: 2000 } }
      - {
          name: muestra,
          type: probabilistic,
          probabilistic: { sampling_percentage: 10 },
        }

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [memory_limiter, attributes/redactar, tail_sampling, batch]
      exporters: [otlp/backend]

Patrón de despliegue	Descripción
Agente	Collector por nodo o sidecar; recoge y enriquece cerca de la aplicación
Gateway	Collectors centrales que aplican muestreo, redacción y envío

El tail sampling necesita ver todos los spans de una traza en el mismo collector: en un gateway con varias réplicas, enruta por trace_id (exportador con load balancing).

Adopción en una organización

Define una configuración base común (atributos de recurso, muestreo, exportador) distribuida en una librería o imagen, y valida en CI que cada servicio declara service.name. Distribuciones como Grafana Alloy y backends como SigNoz, Tempo o los de cada nube reciben OTLP sin cambios en el código.

Criterios de implementación

Define nombres de servicios, convenciones y muestreo. Evita incluir datos sensibles y controla atributos de alta cardinalidad. El Collector procesa señales; el almacenamiento y los paneles pertenecen a otras herramientas.