Observabilidad

JamJet emite trazas estructuradas, métricas y logs para cada ejecución — compatible con OpenTelemetry y las herramientas que ya usas.

Qué se instrumenta

Cada ejecución de JamJet emite automáticamente:

Trazas — spans por ejecución y por nodo con tiempos, modelo, conteo de tokens
Métricas — duración de ejecución, profundidad de cola, latencia de nodo, uso de tokens, tasas de error
Logs — logs JSON estructurados para cada transición de estado
Eventos — el log completo de eventos de ejecución (consultable mediante jamjet inspect)

OpenTelemetry

JamJet es completamente nativo de OpenTelemetry. Configura un exportador OTLP en jamjet.toml:

[telemetry]
enabled = true
service_name = "my-agent"
service_version = "0.2.0"

[telemetry.otlp]
endpoint = "http://localhost:4317"   # OTLP gRPC

# o

endpoint = "http://localhost:4318"   # OTLP HTTP

Esto funciona con cualquier backend compatible con OTLP:

Estructura de trazas

Cada ejecución produce una jerarquía de trazas:

execution exec_01JM4X8NKWP2 (2.1s)
├── node:search (search) [tool] 823ms
│   └── mcp.call brave-search/web_search 820ms
├── node:draft (draft) [model] 1.1s
│   └── model.call claude-sonnet-4-6 1.09s
│       ├── input_tokens: 412
│       └── output_tokens: 891
└── node:evaluate (evaluate) [eval] 180ms
    └── eval.llm_judge claude-haiku 178ms
        └── score: 4.7

Atributos de span

JamJet sigue las convenciones semánticas GenAI para spans de modelo:

Atributo	Valor
`gen_ai.system`	`anthropic`, `openai`, etc.
`gen_ai.request.model`	ID del modelo
`gen_ai.usage.input_tokens`	Conteo de tokens de entrada
`gen_ai.usage.output_tokens`	Conteo de tokens de salida
`jamjet.workflow.id`	ID del workflow
`jamjet.workflow.version`	Versión del workflow
`jamjet.execution.id`	ID de ejecución
`jamjet.node.id`	ID del nodo
`jamjet.node.kind`	Tipo de nodo

Métricas de Prometheus

Habilita el endpoint de scrape de Prometheus:

[telemetry.prometheus]
enabled = true
port = 9090

Métricas disponibles:

Métrica	Tipo	Descripción
`jamjet_executions_total`	Counter	Total de ejecuciones por flujo + estado
`jamjet_execution_duration_ms`	Histogram	Tiempo de ejecución de extremo a extremo
`jamjet_node_duration_ms`	Histogram	Tiempo de ejecución por nodo según tipo de nodo
`jamjet_queue_depth`	Gauge	Ejecuciones pendientes en cola
`jamjet_model_tokens_total`	Counter	Uso de tokens por modelo y dirección
`jamjet_model_cost_usd_total`	Counter	Costo estimado por modelo

Ejemplo de consulta Prometheus para latencia p99 de ejecución:

histogram_quantile(0.99,
  rate(jamjet_execution_duration_ms_bucket[5m])
)

Panel de Grafana

Importa el panel oficial de JamJet para Grafana (ID: jamjet-runtime) para obtener una vista general preconfigurada:

Rendimiento de ejecución y tasa de errores
Distribución de latencia del modelo
Uso de tokens y costo a lo largo del tiempo
Profundidad de cola y saturación de workers

Logs estructurados

JamJet emite logs JSON estructurados a stdout por defecto:

{
  "timestamp": "2026-03-07T09:31:00.012Z",
  "level": "info",
  "event": "node_completed",
  "execution_id": "exec_01JM4X8NKWP2",
  "workflow_id": "research-agent",
  "node_id": "think",
  "node_kind": "model",
  "model": "claude-haiku-4-5-20251001",
  "duration_ms": 512,
  "input_tokens": 64,
  "output_tokens": 312
}

Configura el nivel y formato de logs en jamjet.toml:

[logging]
level = "info"       # debug | info | warn | error
format = "json"      # json | text

Inspección de ejecuciones

El comando jamjet inspect te da la traza completa de ejecución localmente sin necesidad de ningún backend de observabilidad:

jamjet inspect exec_01JM4X8NKWP2
jamjet inspect exec_01JM4X8NKWP2 --events    # línea de tiempo completa de eventos
jamjet inspect exec_01JM4X8NKWP2 --state     # solo estado final

Alertas

Con Prometheus + Alertmanager, añade alertas para:


# alerts.yml

groups:
  - name: jamjet
    rules:
      - alert: HighExecutionErrorRate
        expr: |
          rate(jamjet_executions_total{status="failed"}[5m]) /
          rate(jamjet_executions_total[5m]) > 0.05
        for: 2m
        annotations:
          summary: "Tasa de error de JamJet superior al 5%"

      - alert: ExecutionQueueBacklog
        expr: jamjet_queue_depth > 100
        for: 5m
        annotations:
          summary: "La cola de ejecución de JamJet se está acumulando"

nota: Toda la telemetría es opcional en jamjet dev. En implementaciones de producción, la telemetría está habilitada por defecto para garantizar visibilidad del comportamiento del agente.

Observabilidad

On this page