Supervisar un agente de código en la empresa: telemetría, barreras de seguridad y dashboard

Supervisar un agente de código (Claude Code, Codex, Cursor): telemetría OpenTelemetry documentada, hooks de seguridad y dashboard de uso en Dynatrace.
Superviser un agent de code en entreprise : télémétrie, garde-fous et tableau de bord

Supervisar un agente de código como Claude Code, Codex o Cursor pasa a ser una cuestión de explotación en cuanto la herramienta sale del puesto de un pionero para llegar al de cien desarrolladores. El agente lanza comandos de shell, modifica archivos, llama a servidores MCP y consume tokens facturados. Sin telemetría, el equipo de plataforma no sabe quién lo usa, qué ejecuta ni cuánto cuesta, y descubre las desviaciones cuando llega la factura o el incidente.

La buena noticia: los tres fabricantes documentan hoy una exportación OpenTelemetry y un mecanismo de hooks. La mala: no cubren las mismas señales, no se configuran en el mismo sitio y no tienen los mismos valores por defecto para los datos sensibles.

Esta guía compara lo que realmente está documentado, propone una arquitectura de recogida común hacia Dynatrace SaaS o Dynatrace Managed y ofrece las consultas de un primer dashboard de uso. Las capacidades citadas proceden de la documentación de los fabricantes consultada en octubre de 2026; evolucionan rápido.

Supervisar un agente de código: lo que documenta cada fabricante

Sesión de Codex CLI en un terminal: cabecera con el modelo y el directorio de trabajo, petición para explicar una base de código y después plan actualizado en cinco pasos marcables
Source : github.com

Una sesión de un agente de código se parece a esta: un modelo, un directorio de trabajo, una petición y después una serie de decisiones y de llamadas a herramientas. Esa serie es lo que hay que hacer observable.

Claude Code

  • Señales: métricas (entre ellas claude_code.session.count, claude_code.token.usage, claude_code.cost.usage en USD, claude_code.lines_of_code.count) y eventos mediante el protocolo de logs (tool_decision, tool_result, api_request, permission_mode_changed, mcp_server_connection…). Las trazas están en beta y requieren CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1 además de CLAUDE_CODE_ENABLE_TELEMETRY=1.
  • Configuración central: archivo de ajustes gestionados, /etc/claude-code/managed-settings.json en Linux. Las variables de exportación colocadas en el .claude/settings.json de un repositorio se ignoran: un repositorio no puede redirigir la telemetría.
  • Datos sensibles: el contenido de los prompts, los detalles de las herramientas (comandos Bash, nombres de servidores y de herramientas MCP) y el contenido de los resultados están desactivados por defecto (OTEL_LOG_USER_PROMPTS, OTEL_LOG_TOOL_DETAILS, OTEL_LOG_TOOL_CONTENT). La dirección de correo del usuario forma parte de los atributos estándar cuando está disponible.

Codex

  • Señales: eventos de logs (codex.tool_decision, codex.tool_result, codex.api_request, codex.user_prompt…) y métricas como codex.tool.call y codex.tool.call.duration_ms. Existen las claves otel.trace_exporter y otel.metrics_exporter; esta última vale statsig por defecto.
  • Configuración: sección [otel] de ~/.codex/config.toml, desactivada por defecto; en empresa, capa gestionada /etc/codex/managed_config.toml.
  • Datos sensibles: log_user_prompt = false por defecto, prompts ocultos.

Cursor

  • Señales: exportación OpenTelemetry reservada al plan Enterprise, ejecutada en los servidores de Cursor. Métricas cursor.token.usage, cursor.tool.calls (con cursor.tool.kind = builtin o mcp) y cursor.cost.usage, presentada como una estimación y no como una factura; logs de llamadas a la API, de errores y de hooks.
  • Configuración: Team Settings > OpenTelemetry Export. Transporte OTLP/HTTP protobuf únicamente, hacia una URL HTTPS pública; Cursor añade /v1/metrics y /v1/logs.
  • Datos sensibles: la familia conversation_content está desactivada por defecto y hoy solo cubre los Cloud Agents y Grok Bot.

Qué trazar y qué no trazar

Parte de las preguntas de explotación, no de la lista de atributos:

  • Adopción: sesiones por equipo y por semana;
  • Coste: tokens y coste estimado por equipo y por modelo;
  • Acciones: herramientas aceptadas y rechazadas, y por quién (configuración, hook o usuario);
  • Escaladas: paso a un modo de permisos más amplio;
  • Salud: errores de API y llamadas a herramientas fallidas.

El contenido de los prompts y de los resultados no es necesario para estas preguntas. Déjalo desactivado, informa a los equipos de lo que se recoge y seudonimiza la identidad si el dashboard no necesita el nombre.

Una arquitectura de recogida común

Haz converger los puestos hacia un OpenTelemetry Collector de empresa, que filtra, enriquece y exporta a Dynatrace:

Esquema de la documentación de OpenTelemetry: una aplicación con el SDK de OpenTelemetry envía OTLP a un OpenTelemetry Collector, que exporta a un backend
Source : opentelemetry.io

Dos restricciones de Dynatrace guían los ajustes. La API OTLP no acepta gRPC, solo HTTP. Y las métricas deben estar en temporalidad delta, que es el valor por defecto de Claude Code y el formato de Cursor; el tema se detalla en nuestro artículo sobre la temporalidad de las métricas OTLP.

Paso 1: Claude Code, mediante ajustes gestionados

Extractos de documentación: archivo managed-settings.json de Claude Code con CLAUDE_CODE_ENABLE_TELEMETRY y las variables OTEL_ de exportación, y después la sección [otel] del config.toml de Codex con environment, exporter y log_user_prompt

El ejemplo de la documentación usa gRPC hacia el Collector, lo que sirve porque el Collector traduce a HTTP. Para una pasarela HTTP:

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "https://otel-gw.example.internal:4318",
    "OTEL_RESOURCE_ATTRIBUTES": "department=engineering,team.id=platform"
  }
}

Cuando OTEL_EXPORTER_OTLP_ENDPOINT está definido en los ajustes gestionados, Claude Code elimina al arrancar los puntos de conexión por señal definidos por los desarrolladores. OTEL_RESOURCE_ATTRIBUTES añade el equipo a cada métrica y a cada evento (pares clave=valor separados por comas, sin espacios).

Paso 2: Codex, sección [otel]

[otel]
environment = "prod"
log_user_prompt = false
exporter = { otlp-http = {
  endpoint = "https://otel-gw.example.internal:4318/v1/logs",
  protocol = "binary"
}}

Despliégala en /etc/codex/managed_config.toml para que se aplique en cada ejecución.

Paso 3: Cursor, desde la consola de equipo

En Team Settings > OpenTelemetry Export: crea el destino con la URL base sin /v1 y una cabecera de autenticación, lanza Test connection y después Enable. La exportación sale de los servidores de Cursor, desde direcciones IP de origen fijas publicadas en la documentación: tu pasarela debe ser accesible desde internet, con TLS.

Paso 4: el Collector hacia Dynatrace

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318
processors:
  attributes/pseudo:
    actions:
      - key: user.email
        action: hash
  batch: {}
exporters:
  otlphttp:
    endpoint: ${env:DT_ENDPOINT}
    headers:
      Authorization: "Api-Token ${env:DT_API_TOKEN}"
service:
  pipelines:
    metrics:
      receivers: [otlp]
      processors: [attributes/pseudo, batch]
      exporters: [otlphttp]
    logs:
      receivers: [otlp]
      processors: [attributes/pseudo, batch]
      exporters: [otlphttp]

DT_ENDPOINT vale https://<env-id>.live.dynatrace.com/api/v2/otlp en SaaS y https://<votre-domaine>/e/<env-id>/api/v2/otlp en Managed. El token lleva los scopes metrics.ingest y logs.ingest (y openTelemetryTrace.ingest si activas las trazas). La puesta en marcha detallada está en nuestra guía del Collector de OpenTelemetry hacia Dynatrace.

Las barreras de seguridad mediante hooks

La telemetría constata; los hooks impiden. Las tres herramientas exponen un evento previo a la ejecución de un comando:

  • Claude Code: hook PreToolUse con un matcher (por ejemplo Bash); un código de salida 2 bloquea la llamada a la herramienta. En los ajustes gestionados, allowManagedHooksOnly restringe los hooks a los de la organización.
  • Codex: hook PreToolUse; un rechazo se hace con permissionDecision: "deny" o con un código de salida 2. allow_managed_hooks_only = true se establece en requirements.toml. La documentación advierte de que un error, un tiempo de espera agotado o una respuesta mal formada puede dejar pasar la herramienta.
  • Cursor: beforeShellExecution y beforeMCPExecution en hooks.json; el código 2 bloquea, los demás códigos de fallo dejan pasar (fail-open). Los hooks de empresa se colocan en /etc/cursor/hooks.json en Linux.

Quédate con el punto en común: un hook que falla no es un hook que bloquea. Monitoriza también los hooks: Claude Code emite hook_execution_complete y Cursor cursor.hook.execution_complete. Para los servidores MCP a los que llaman estos agentes, consulta nuestra guía sobre el aislamiento de servidores MCP STDIO.

Un dashboard de uso en Dynatrace SaaS

Empieza mirando la forma real de los eventos recibidos: fetch logs | filter isNotNull(event.name) | limit 20. Los nombres de atributo de abajo son los de la documentación de Claude Code; compruébalos en tu entorno.

// Coût estimé et requêtes par équipe, 7 jours
fetch logs, from: now() - 7d
| filter event.name == "api_request"
| summarize cout_usd = sum(toDouble(cost_usd)), requetes = count(), by: { team.id }

// Outils refusés, et par quelle source
fetch logs, from: now() - 7d
| filter event.name == "tool_decision" and decision == "reject"
| summarize refus = count(), by: { tool_name, source }

// Passages à un mode de permission plus large
fetch logs, from: now() - 7d
| filter event.name == "permission_mode_changed"
| summarize changements = count(), by: { from_mode, to_mode }

Para las métricas de Cursor y Codex, la documentación de Dynatrace indica que se puede añadir automáticamente un sufijo a la clave (por ejemplo .count para un contador): comprueba la clave exacta antes de construir un tile timeseries. Las bases de estos comandos están en nuestra ficha de DQL filter, summarize y timeseries.

Dynatrace Managed recibe las mismas métricas por la API OTLP y las explora con el metric selector y Data Explorer; las consultas DQL sobre logs de arriba requieren Grail, es decir, Dynatrace SaaS.

Cómo comprobar que funciona

  1. Claude Code: lanza una sesión; la documentación indica que claude_code.session.count se emite al arrancar. Para una exportación solo de logs, envía un prompt y busca el evento user_prompt.
  2. Codex: cambia temporalmente exporter a otlp-http en un puesto de pruebas y comprueba la llegada de los eventos codex.api_request.
  3. Cursor: el botón Test connection valida la URL y la autenticación; la exportación empieza después en aproximadamente un minuto.
  4. En el Collector, el exportador debug añadido temporalmente muestra cada lote recibido.

Buenas prácticas

  • Configuración central (ajustes gestionados, archivo gestionado, consola de equipo), nunca por repositorio.
  • Contenido desactivado por defecto; activación puntual y documentada para una investigación.
  • Atributo de equipo en cada señal para dashboards por equipo sin identidad nominal.
  • Alertas sobre tendencias (coste, rechazos, escaladas), no sobre cada evento.
  • Hooks probados en caso de fallo: comprueba qué ocurre cuando el script falla o supera su tiempo de espera.

Preguntas frecuentes

¿Hace falta un Collector o se puede enviar directamente a Dynatrace?

El envío directo es posible si la herramienta habla OTLP/HTTP y acepta la cabecera de autenticación esperada. El Collector sigue siendo aconsejable: convierte gRPC en HTTP, seudonimiza y centraliza el token de Dynatrace.

¿Permiten estos datos medir la productividad?

Miden el uso (sesiones, líneas modificadas, commits), no el valor producido. Úsalos para gestionar la capacidad y el coste, no para evaluar personas.

¿Qué diferencia hay con la monitorización de un agente de IA propio?

Aquí la instrumentación la aporta el fabricante: tú eliges qué activar, no qué emitir. Para un agente que desarrollas tú, se aplican las convenciones GenAI de OpenTelemetry, como en nuestra guía para observar los agentes MCP.

Conclusión

Supervisar un agente de código en la empresa se resume en tres gestos: activar la telemetría documentada por el fabricante desde una configuración central, hacerla pasar por un Collector que proteja los datos y colocar hooks cuyos fallos también se monitorizan. Empieza por la adopción y el coste, añade los rechazos y las escaladas, y alerta después sobre las tendencias.

span.observer es un blog independiente de la comunidad, no afiliado a Dynatrace LLC ni a los fabricantes de las herramientas citadas. Dynatrace es una marca de Dynatrace LLC. Fuentes: monitorización de Claude Code, configuración avanzada de Codex, OpenTelemetry Export de Cursor; estas capacidades evolucionan con cada versión.

Total
0
Shares
Leave a Reply

Your email address will not be published. Required fields are marked *

Previous Post
Empoisonnement d'outils MCP : le détecter avec les traces et les logs

Envenenamiento de herramientas MCP: detéctalo con trazas y logs

Next Post
Garde-fous agents IA en production : NeMo Guardrails, Llama Guard et OpenShell côté exploitation

Barreras de seguridad para agentes de IA en producción: NeMo Guardrails, Llama Guard y OpenShell desde la explotación

Related Posts