Configuración del pipeline de OpenTelemetry

Módulo 7 · Administración y medición · Lección 4 de 6

Al terminar esta lección podrás configurar y desplegar un pipeline de OTel para Claude Code, elegir la ruta de exportación adecuada para el entorno del cliente y aplicar la configuración en toda la organización mediante managed settings.

Envía cada evento de ejecución a tu SIEM.

Qué captura

La fuente de ejecución que las superficies de metadatos no pueden darte.

Los registros de auditoría te dicen quién inició sesión. La Compliance API te dice qué se dijo. OTel te dice qué se ejecutó. Cada llamada a herramienta, cada comando bash y cada invocación MCP se convierte en un evento estructurado que se envía a tu SIEM en tiempo real.

Cuando el equipo de seguridad de un cliente quiere saber si un desarrollador ejecutó un comando bash concreto contra una base de datos de producción, OTel es el único mecanismo que puede responderlo. El flujo de eventos incluye el nombre de la herramienta, la decisión (aprobada o rechazada) y, con OTEL_LOG_TOOL_DETAILS=1, el propio comando.

Qué obtienes

Un flujo OTLP en tiempo real de cada llamada a herramienta

Ocho métricas con nombre que cubren sesiones, tokens, costo, líneas de código, commits, pull requests, decisiones de edición de código y tiempo activo. Eventos de log estructurados para cada llamada a herramienta, solicitud de API e invocación MCP. Todo se transmite a cualquier backend compatible con OTLP.

Opciones de exportación

OTLP, Prometheus o consola

Las métricas admiten OTLP, Prometheus o consola. Los eventos (logs) admiten OTLP o consola. Puedes enrutar las métricas a un backend y los eventos a otro usando variables de entorno de exportador separadas. El protocolo por defecto es gRPC en el puerto 4317.

Los límites de privacidad

El contenido de las conversaciones no se captura por defecto

El texto de las conversaciones no se captura a menos que se establezca explícitamente OTEL_LOG_USER_PROMPTS=1. Los parámetros de herramientas y los comandos bash requieren OTEL_LOG_TOOL_DETAILS=1 como opt-in independiente. El contenido completo de la salida de las herramientas (contenido de archivos sin procesar, salida de comandos) requiere OTEL_LOG_TOOL_CONTENT=1, que además necesita la beta de trazado (CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1) y se trunca a 60 KB. Ambos indicadores están desactivados por defecto.

Cuándo usarlo

Alertas de seguridad, atribución de costos y dashboards

Alertas de seguridad en tiempo real, integración con SIEM, atribución de costos por equipo o centro de costos, dashboards de uso de herramientas y cualquier escenario en el que necesites saber qué ejecutó Claude Code, no solo que hubo una sesión.

Regla de trabajo

OTel captura qué se ejecutó. La Compliance API captura qué se discutió. Los registros de auditoría capturan eventos administrativos.

Arquitectura del pipeline

Cinco pasos desde cero hasta un flujo OTLP activo

La configuración vive por completo en variables de entorno. No hay cambios de código ni integración de SDK. Los mismos cinco pasos se aplican tanto si el cliente usa Splunk, Datadog, Cribl o cualquier backend OTLP.

flowchart TD
    P1["1. Activar el interruptor maestro: CLAUDE_CODE_ENABLE_TELEMETRY=1"] --> P2["2. Elegir los exportadores"]
    P2 --> P3["3. Configurar el endpoint OTLP y la autenticación"]
    P3 --> P4["4. Desplegar mediante managed settings"]
    P4 --> P5["5. Verificar con un intervalo de exportación corto"]

1. Activa el interruptor maestro

Define CLAUDE_CODE_ENABLE_TELEMETRY=1. Es obligatorio: no se transmite nada sin él. Todas las demás variables de OTel se ignoran si este indicador no está presente. Esta única variable es la puerta de entrada de todo el pipeline.

2. Elige los exportadores

Define OTEL_METRICS_EXPORTER=otlp para las métricas y OTEL_LOGS_EXPORTER=otlp para los eventos. Usa console para depuración local. Prometheus está disponible si el cliente usa un stack compatible con Prometheus. Puedes combinar exportadores entre tipos de señal.

3. Configura el endpoint OTLP y la autenticación

Define OTEL_EXPORTER_OTLP_ENDPOINT con la URL del collector y OTEL_EXPORTER_OTLP_HEADERS con el token bearer de Authorization. El protocolo por defecto es gRPC en el puerto 4317. Usa OTEL_EXPORTER_OTLP_PROTOCOL=http/json si el collector del cliente no admite gRPC.

4. Despliega mediante managed settings

Envía el bloque de variables de entorno a managed-settings.json mediante MDM. Las variables definidas aquí tienen alta precedencia y los desarrolladores no pueden sobrescribirlas. Es la única vía escalable para organizaciones con 100 o más desarrolladores. Los tokens sensibles quedan fuera de los entornos de los desarrolladores.

5. Verifica con un intervalo de exportación corto

Define temporalmente OTEL_METRIC_EXPORT_INTERVAL=10000 (10 segundos en lugar de los 60 segundos por defecto). Ejecuta una sesión, comprueba en el backend que llegan datos y elimina la sobrescritura antes del despliegue en producción.

Configuración por entorno

Las mismas variables. Tres configuraciones distintas.

Las variables de entorno son idénticas en todos los entornos. Lo que cambia es a qué exportadores apuntas, qué señales opcionales habilitas y cómo defines los valores. Cada uno de los siguientes bloques es una configuración completa y funcional.

1. Desarrollo y depuración local

Usa exportadores de consola mientras configuras. Nada sale de la máquina. Es útil para verificar que OTel está conectado y emitiendo antes de apuntar a un backend real.

CLAUDE_CODE_ENABLE_TELEMETRY=1
OTEL_METRICS_EXPORTER=console
OTEL_LOGS_EXPORTER=console
OTEL_METRIC_EXPORT_INTERVAL=10000  # 10 s para una retroalimentación más rápida; revertir antes de producción

La salida de la consola aparece en la terminal. Ejecuta una sesión corta de Claude Code y busca la salida de métricas y eventos. Si no aparece nada, confirma que CLAUDE_CODE_ENABLE_TELEMETRY=1 está definido antes que las demás variables en el entorno.

2. Producción con OTLP

Conecta directamente con el collector OTLP del cliente. gRPC es el valor por defecto y la opción de menor latencia. Usa http/json si el collector no admite gRPC.

CLAUDE_CODE_ENABLE_TELEMETRY=1
OTEL_METRICS_EXPORTER=otlp
OTEL_LOGS_EXPORTER=otlp
OTEL_EXPORTER_OTLP_PROTOCOL=grpc
OTEL_EXPORTER_OTLP_ENDPOINT=http://collector.example.com:4317
OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer your-token

Despliégalo mediante managed-settings.json, no mediante .env. El encabezado de autenticación contiene un token bearer. Si lo subes a un repositorio o lo dejas en un archivo .env compartido, expones las credenciales. Las managed settings desplegadas por MDM mantienen el token fuera del alcance de los desarrolladores.

3. Atribución multiequipo

Añade OTEL_RESOURCE_ATTRIBUTES para etiquetar cada métrica y evento con etiquetas de departamento, equipo o centro de costos. Estos atributos llegan a los dashboards automáticamente y alimentan los informes de atribución de costos sin transformaciones en el backend.

CLAUDE_CODE_ENABLE_TELEMETRY=1
OTEL_METRICS_EXPORTER=otlp
OTEL_LOGS_EXPORTER=otlp
OTEL_EXPORTER_OTLP_ENDPOINT=http://collector.example.com:4317
OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer your-token
OTEL_RESOURCE_ATTRIBUTES=department=engineering,team.id=platform,cost_center=eng-123

Envía un bloque OTEL_RESOURCE_ATTRIBUTES distinto por equipo mediante MDM. Cada equipo recibe sus etiquetas incorporadas en el momento del despliegue. El collector recibe datos ya etiquetados sin necesidad de un paso de enriquecimiento.

Tipos de señal

Ocho métricas. Decenas de eventos. Los indicadores opt-in determinan lo que ves.

Las métricas se transmiten por defecto en cuanto activas el interruptor maestro. Los eventos requieren definir OTEL_LOGS_EXPORTER. Todo lo demás es opt-in.

flowchart TD
    A["CLAUDE_CODE_ENABLE_TELEMETRY=1 (interruptor maestro)"] --> B["Métricas: activas por defecto"]
    A --> C["OTEL_LOGS_EXPORTER definido"]
    C --> D["Eventos: llamadas a herramientas, API, MCP, autenticación y cambios de permisos"]
    D --> E["OTEL_LOG_TOOL_DETAILS=1: parámetros y comandos bash"]
    D --> F["OTEL_LOG_TOOL_CONTENT=1 + CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1: contenido de herramientas (máx. 60 KB)"]
    G["OTEL_LOG_USER_PROMPTS=1: texto de las conversaciones (opt-in explícito)"]

Métricas (activadas por defecto)

Sin opt-in adicional. Ocho métricas de series temporales con nombre: sesiones, tokens, cost.usage (en USD), líneas de código, commits, pull requests, decisiones de edición de código y tiempo activo. Todas se transmiten de forma continua en cuanto se define CLAUDE_CODE_ENABLE_TELEMETRY=1. No requieren opt-ins adicionales. cost.usage incluye atributos de modelo, query_source, velocidad, esfuerzo y atribución de herramientas.

Eventos (requieren OTEL_LOGS_EXPORTER)

Cada llamada a herramienta, solicitud de API, cambio de modo de permisos, conexión MCP y evento de autenticación se registra como log estructurado. Requieren OTEL_LOGS_EXPORTER=otlp. Los parámetros de herramientas y los comandos bash requieren OTEL_LOG_TOOL_DETAILS=1 como segundo opt-in. El contenido completo de la salida de las herramientas (contenido de archivos sin procesar, salida de comandos) requiere OTEL_LOG_TOOL_CONTENT=1 más la beta de trazado (CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1), y se trunca a 60 KB.

Atribución de costos (integrada en cost.usage)

La métrica cost.usage lleva los atributos model, query_source, speed, effort, agent.name, skill.name, plugin.name, mcp_server.name y mcp_tool.name. Añade OTEL_RESOURCE_ATTRIBUTES para superponer etiquetas a nivel de organización (departamento, cost_center). Ambos llegan a los dashboards sin transformaciones en el backend.

Eventos de seguridad (opt-in parcial)

Las decisiones de herramientas (aprobadas o rechazadas), los cambios de modo de permisos y las conexiones a servidores MCP se capturan por defecto cuando OTEL_LOGS_EXPORTER está definido. El contenido de los comandos bash requiere OTEL_LOG_TOOL_DETAILS=1. El contenido completo de entrada y salida de las herramientas requiere OTEL_LOG_TOOL_CONTENT=1 más la beta de trazado (CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1); el contenido se trunca a 60 KB. Activa solo lo que exija la política de seguridad.

Comprueba tu comprensión

Escenario · Decisiones de despliegue

Cuatro decisiones de configuración. Cada una tiene una opción incorrecta técnicamente defendible. Ocho puntos en total. Cada opción vale 2 puntos (mejor), 1 (parcial) o 0 (incorrecta).

Estás desplegando OTel para un cliente de 500 desarrolladores. Su CISO quiere que los eventos de ejecución de herramientas lleguen a Splunk. El liderazgo de ingeniería quiere atribución de costos a nivel de departamento. TI quiere que la configuración se envíe mediante MDM para que los desarrolladores no puedan cambiarla. Elige una opción en cada decisión y compara tu criterio con la explicación.

Decisión 1 de 4 · Ejecución de herramientas en Splunk

El CISO quiere que cada comando bash ejecutado mediante Claude Code aparezca como evento estructurado en Splunk. ¿Qué configuración lo consigue?

• A. Definir OTEL_METRICS_EXPORTER=otlp
• B. Definir OTEL_LOGS_EXPORTER=otlp y OTEL_LOG_TOOL_DETAILS=1
• C. Definir OTEL_LOGS_EXPORTER=otlp sin los detalles de herramientas

Ver respuesta

Mejor opción: B (2 puntos). Parcial: C (1 punto). Incorrecta: A (0 puntos).

A. Definir OTEL_METRICS_EXPORTER=otlp (incorrecta, 0 puntos). Las métricas llegarán a Splunk, incluidos los recuentos de sesiones, el uso de tokens y los datos de cost.usage. El CISO tendrá datos cuantitativos de la actividad de los desarrolladores.

Retroalimentación: Las métricas muestran el uso agregado, no las llamadas individuales a herramientas. El CISO necesita el flujo de eventos (OTEL_LOGS_EXPORTER=otlp) más los detalles de herramientas (OTEL_LOG_TOOL_DETAILS=1). Las métricas por sí solas no cumplen un requisito de alerta de seguridad.

B. Definir OTEL_LOGS_EXPORTER=otlp y OTEL_LOG_TOOL_DETAILS=1 (mejor, 2 puntos). Los eventos de ejecución de herramientas, incluidos los comandos bash, llegan a Splunk como eventos de log estructurados. OTEL_LOG_TOOL_DETAILS añade el contenido del comando a cada evento.

Retroalimentación: Correcto. OTEL_LOGS_EXPORTER activa el flujo de eventos; OTEL_LOG_TOOL_DETAILS=1 añade el contenido del comando. Se requieren ambos. Sin OTEL_LOG_TOOL_DETAILS, Splunk recibe eventos de sesión pero no los comandos en sí.

C. Definir OTEL_LOGS_EXPORTER=otlp sin los detalles de herramientas (parcial, 1 punto). Los eventos de sesión, los cambios de permisos y las decisiones sobre herramientas llegarán a Splunk. Sin el indicador OTEL_LOG_TOOL_DETAILS, el contenido de los comandos bash no se incluirá.

Retroalimentación: Acertaste con el exportador, pero también hace falta OTEL_LOG_TOOL_DETAILS=1. Sin él, Splunk recibe eventos que confirman que se llamó a una herramienta, pero no se incluye el contenido del comando.

Decisión 2 de 4 · Atribución de costos por departamento

El liderazgo de ingeniería quiere ver cost.usage desglosado por departamento en los dashboards. Los 500 desarrolladores comparten una misma organización de Claude. ¿Cómo atribuyes los costos?

• A. Crear claves de API separadas por departamento
• B. Añadir OTEL_RESOURCE_ATTRIBUTES con etiquetas de departamento y centro de costos mediante MDM
• C. Crear organizaciones de Claude separadas por departamento

Ver respuesta

Mejor opción: B (2 puntos). Parcial: A (1 punto). Incorrecta: C (0 puntos).

A. Crear claves de API separadas por departamento (parcial, 1 punto). La segmentación de claves de API permite dirigir los datos de facturación al centro de costos correcto a nivel de API. Cada departamento usa su propia clave.

Retroalimentación: Las claves de API separadas pueden ofrecer cierta segmentación del uso a nivel de API, pero no etiquetan directamente las métricas de OTel. OTEL_RESOURCE_ATTRIBUTES es el patrón adecuado para atribuir los datos de OTel a equipos dentro de una misma organización.

B. Añadir OTEL_RESOURCE_ATTRIBUTES con etiquetas de departamento y centro de costos mediante MDM (mejor, 2 puntos). OTEL_RESOURCE_ATTRIBUTES etiqueta cada métrica y evento de una máquina con las etiquetas especificadas. Envía bloques de atributos distintos por equipo mediante MDM y las etiquetas llegan a los dashboards automáticamente.

Retroalimentación: Correcto. OTEL_RESOURCE_ATTRIBUTES enviado mediante managed settings etiqueta cada métrica y evento con la etiqueta de departamento. Llega a la métrica cost.usage y aparece en los dashboards automáticamente. No hace falta reestructurar la organización.

C. Crear organizaciones de Claude separadas por departamento (incorrecta, 0 puntos). Las organizaciones separadas ofrecen aislamiento completo del gasto. El uso de cada departamento se rastrea de forma independiente, sin riesgo de contaminación cruzada en los informes.

Retroalimentación: Las organizaciones separadas generan sobrecarga de gestión y no ayudan con la atribución de OTel dentro de un despliegue compartido. OTEL_RESOURCE_ATTRIBUTES enviado mediante MDM es la vía escalable.

Decisión 3 de 4 · Despliegue en toda la organización

TI necesita desplegar la configuración de OTel en 500 equipos de desarrolladores. Los desarrolladores no deben poder anular los ajustes de telemetría. ¿Cuál es la vía de despliegue?

• A. Escribir un runbook de onboarding y pedir a los desarrolladores que definan las variables de entorno
• B. Enviar el bloque de variables de entorno en managed-settings.json mediante la plataforma MDM
• C. Confirmar las variables de entorno en un archivo .env compartido en la raíz del proyecto

Ver respuesta

Mejor opción: B (2 puntos). Parcial: C (1 punto). Incorrecta: A (0 puntos).

A. Escribir un runbook de onboarding y pedir a los desarrolladores que definan las variables de entorno (incorrecta, 0 puntos). Un runbook bien documentado da a los desarrolladores instrucciones claras. La mayoría de los ingenieros seguirá una guía de configuración clara si forma parte del onboarding.

Retroalimentación: Los runbooks dependen de la acción del desarrollador y producen una cobertura inconsistente. A 500 desarrolladores, la configuración manual deja huecos en los datos y sin imposición. MDM es la vía correcta.

B. Enviar el bloque de variables de entorno en managed-settings.json mediante la plataforma MDM (mejor, 2 puntos). Las variables de entorno en managed-settings.json tienen alta precedencia y no pueden ser sobrescritas por el entorno local del desarrollador ni por archivos .env. Es el patrón estándar de despliegue empresarial.

Retroalimentación: Correcto. Las managed settings mediante MDM son la única vía escalable y exigible. Las variables de entorno en managed-settings.json tienen alta precedencia y no pueden ser sobrescritas por el entorno local del desarrollador.

C. Confirmar las variables de entorno en un archivo .env compartido en la raíz del proyecto (parcial, 1 punto). Un .env compartido en el repositorio principal garantiza que cada desarrollador que clone el proyecto reciba la configuración automáticamente. Es un enfoque ligero que no requiere infraestructura MDM.

Retroalimentación: Un .env compartido en el repositorio funcionará para los proyectos que lo carguen, pero puede ser sobrescrito por archivos .env locales y no debería contener tokens de autenticación sensibles. MDM es el enfoque adecuado para un despliegue a 500 desarrolladores.

Decisión 4 de 4 · Pregunta de privacidad del CISO

El CISO pregunta: ¿se capturan las conversaciones de los desarrolladores en el flujo de OTel? ¿Cuál es la respuesta precisa?

• A. Sí, el pipeline captura el contenido de las conversaciones con fines de cumplimiento
• B. Puede capturarse si se activa explícitamente, así que el CISO debe comprobar si ese indicador está definido
• C. No. El contenido de los prompts no se captura por defecto. OTEL_LOG_USER_PROMPTS=1 es un opt-in que no está en la configuración actual

Ver respuesta

Mejor opción: C (2 puntos). Parcial: B (1 punto). Incorrecta: A (0 puntos).

A. Sí, el pipeline captura el contenido de las conversaciones con fines de cumplimiento (incorrecta, 0 puntos). Capturar el contenido de las conversaciones es un beneficio significativo para el cumplimiento. El CISO querrá saber que estos datos se retienen y que pueden revisarse.

Retroalimentación: Confirmar que las conversaciones se capturan es incorrecto y supone una tergiversación significativa. OTel captura eventos de ejecución, no contenido de conversaciones. La captura de prompts requiere un opt-in explícito que está desactivado por defecto.

B. Puede capturarse si se activa explícitamente, así que el CISO debe comprobar si ese indicador está definido (parcial, 1 punto). El encuadre de opt-in es correcto. Explicar que un indicador explícito controla esto deja la decisión en manos del cliente.

Retroalimentación: Plantearlo como “puede activarse” sin indicar el valor por defecto deja al CISO con dudas sobre lo que ya está fluyendo. La respuesta más útil: por defecto, no se captura contenido de prompts.

C. No. El contenido de los prompts no se captura por defecto. OTEL_LOG_USER_PROMPTS=1 es un opt-in que no está en la configuración actual (mejor, 2 puntos). OTel captura eventos de ejecución, no contenido de conversaciones. La captura de prompts requiere un indicador de opt-in explícito que está desactivado por defecto y que no está incluido en este despliegue.

Retroalimentación: Correcto. El valor por defecto preserva la privacidad. El contenido de los prompts requiere OTEL_LOG_USER_PROMPTS=1 como opt-in explícito, que no está en la configuración actual. El CISO necesita esta claridad para informar con precisión a los equipos legal y de privacidad.

Ver debrief y texto de cierre

La fuente asigna un texto de cierre según la puntuación final, sobre un máximo de 8 puntos.

Arquitecto de pipeline (7 u 8 puntos). Acertaste los indicadores de exportación, el patrón de atribución, la ruta de despliegue y los valores por defecto de privacidad. Es el panorama completo que necesitan el CISO y el liderazgo de ingeniería.

Base sólida, ajusta los valores por defecto (4 a 6 puntos). La arquitectura está. Las decisiones que fallaron mezclaron métricas con eventos o dejaron fuera el valor por defecto de privacidad. Repasa los temas y vuelve después.

Revisa el inicio rápido (0 a 3 puntos). Los indicadores opt-in y el patrón de managed settings son los puntos en los que centrarse. Los temas 2 y 3 los cubren con detalle.

Artefacto del curso · Aporte de la lección 4

OTel Configuration + Dashboard Spec

Ya puedes configurar el pipeline completo. Este aporte es el bloque de configuración de OTel que el equipo de DevOps de tu cliente desplegará: la pila de variables de entorno y la entrada en managed-settings que envía la telemetría a su backend.

1. Escribe el bloque de variables de entorno: CLAUDE_CODE_ENABLE_TELEMETRY=1, el tipo de exportador elegido y el endpoint del backend de observabilidad del cliente. Elige el exportador que encaje con su stack existente y anota por qué.
2. Escribe la entrada de telemetría en managed-settings.json para el despliegue en toda la organización. Es lo que entregas al responsable de DevOps. Confirma que se aplica antes de que los desarrolladores instalen Claude Code.
3. Indica qué tipos de señal transmitirá tu configuración por defecto (métricas y eventos) y cuáles requieren opt-in explícito (contenido de los prompts, detalles de herramientas). Documenta la decisión de opt-in para la revisión de seguridad del cliente.

Ideas clave

Cinco variables de entorno. Un pipeline. Sin conjeturas.

• Puedes configurar un pipeline de OTel funcional desde cero, explicar la diferencia entre métricas y eventos y desplegar la configuración en toda la organización mediante managed settings.
• OTel no captura el contenido de las conversaciones por defecto; la captura de los prompts es un opt-in explícito que está desactivado salvo que lo actives.
• Usa OTEL_LOG_TOOL_DETAILS=1 para capturar comandos bash, y OTEL_LOG_TOOL_CONTENT=1 (con la beta de trazado) solo si la política de seguridad lo exige.
• Despliega la configuración con managed settings para que los desarrolladores no puedan modificarla y para no exponer los tokens en sus entornos.

La lección 5 cubre la ventana de 180 días de los registros de auditoría, los tres patrones de acceso (exportación CSV, Compliance API y feed SIEM de OTel) y cómo elegir el adecuado para cada escenario de cliente.

Siguiente: Audit logs y consultas