Trazas (OpenTelemetry)

• @botmesh/core trae los hooks de trazas: una interfaz mínima BotTracer, un no-op por defecto y bot.tracing. Sin dependencias nuevas.
• @botmesh/otel los adapta a OpenTelemetry y además publica bot.metrics() como métricas de OpenTelemetry.
• @botmesh/ai añade spans de modelo, herramientas y recuperación a la misma traza.

​

Inicio rápido

pnpm add @botmesh/otel @opentelemetry/api @opentelemetry/sdk-node \
  @opentelemetry/exporter-trace-otlp-http @opentelemetry/exporter-metrics-otlp-http @opentelemetry/sdk-metrics

// telemetry.ts — cárgalo antes que el bot (p. ej. `node --import ./telemetry.js bot.js`)
import { NodeSDK } from '@opentelemetry/sdk-node'
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http'
import { OTLPMetricExporter } from '@opentelemetry/exporter-metrics-otlp-http'
import { PeriodicExportingMetricReader } from '@opentelemetry/sdk-metrics'

export const sdk = new NodeSDK({
  serviceName: 'bot-ventas',
  traceExporter: new OTLPTraceExporter({ url: 'http://localhost:4318/v1/traces' }),
  metricReaders: [new PeriodicExportingMetricReader({
    exporter: new OTLPMetricExporter({ url: 'http://localhost:4318/v1/metrics' }),
  })],
})
sdk.start()

// bot.ts
import { Bot } from '@botmesh/core'
import { aiPlugin } from '@botmesh/ai'
import { createOtelTracer, otelMetricsPlugin } from '@botmesh/otel'
import { sdk } from './telemetry.js'

const bot = new Bot({
  provider,
  telemetry: {
    tracer: await createOtelTracer(),
    // La misma clave en todas las réplicas: los ids con hash coinciden entre procesos y reinicios.
    idKey: process.env.TRACE_ID_KEY,
  },
})
bot.plug(otelMetricsPlugin())   // bot.metrics() como métricas de OpenTelemetry
bot.plug(aiPlugin({ /* … */ })) // los spans de IA entran solos en la misma traza

process.on('SIGTERM', async () => {
  await bot.stop()
  await sdk.shutdown()          // vacía los spans y métricas que siguen en buffer
})

​

Backends locales

​

Jaeger

docker run --rm --name jaeger -p 16686:16686 -p 4318:4318 jaegertracing/jaeger:latest

​

Grafana Tempo + Grafana

services:
  tempo:
    image: grafana/tempo:latest
    command: ['-config.file=/etc/tempo.yaml']
    volumes: ['./tempo.yaml:/etc/tempo.yaml']
    ports: ['4318:4318', '3200:3200']
  grafana:
    image: grafana/grafana:latest
    environment:
      GF_AUTH_ANONYMOUS_ENABLED: 'true'
      GF_AUTH_ANONYMOUS_ORG_ROLE: Admin
    volumes: ['./grafana-datasources.yaml:/etc/grafana/provisioning/datasources/datasources.yaml']
    ports: ['3000:3000']

server:
  http_listen_port: 3200
distributor:
  receivers:
    otlp:
      protocols:
        http:
          endpoint: 0.0.0.0:4318
storage:
  trace:
    backend: local
    local: { path: /var/tempo/traces }
    wal: { path: /var/tempo/wal }

apiVersion: 1
datasources:
  - name: Tempo
    type: tempo
    access: proxy
    url: http://tempo:3200
    isDefault: true

​

Cómo se ve un mensaje

bot.inbound                      consumer · bot.event.kind=message · bot.inbound.outcome=dispatched
├─ bot.persist                   escrituras de chat / contacto / mensaje
└─ bot.dispatch                  bot.queue.wait_ms · bot.dispatch.stage=matcher
   └─ bot.handler                bot.handler.stage=matcher · bot.matcher.kind=text · bot.flow.id=pedido
      └─ bot.conversation.turn   bot.conversation.reason=start · parked=true
         ├─ chat claude-…        gen_ai.* (modelo, tokens, motivo de fin)
         │  └─ (span http de la llamada al SDK, de su propia instrumentación)
         ├─ execute_tool buscar  bot.ai.tool.outcome=ok
         └─ bot.pace             retraso + escribiendo…
            └─ bot.send          client · bot.send.outcome=ok
               └─ (span http de la llamada al provider)

​

Catálogo de spans

​

Atributos

​

Turnos de conversación

• el primer turno empieza bajo el handler (o bot.trigger) que la inició: reason: start o dormant (un flujo persistente retomado desde su checkpoint); el destino de un c.goto() empieza bajo el turno que hizo el goto: reason: goto;
• quedarse esperando en un ask cierra el turno con bot.conversation.parked = true;
• una respuesta abre el siguiente turno bajo el span de dispatch del mensaje que respondió: reason: reply;
• el timeout de una espera abre un turno raíz enlazado al primero (reason: timeout), porque ningún mensaje lo causó; un callback de c.idle() que salta mientras la conversación espera corre también en un turno raíz (reason: idle), que vuelve a quedar en espera si el callback solo respondió, o lleva el resultado si terminó o redirigió la conversación;
• un error lanzado por la conversación (o por un callback de inactividad) se registra en el turno donde ocurrió;
• una conversación retomada desde un checkpoint que escribió otra réplica o un proceso anterior (un flujo persistente tras un reinicio, un flujo reenviado por coordination.handover, un stub de hand-over reiniciado con fallback: 'restart') empieza bajo el dispatch del mensaje que la despertó y queda enlazada al turno que escribió el checkpoint; ver Entre réplicas y reinicios;
• el final de la conversación pone bot.conversation.outcome (completed, ended, guarded, cancelled, timedOut, retriesExceeded, error) en el turno abierto; una conversación abortada mientras esperaba (/reset, handoff, stop()) recibe un turno corto de cierre (reason: end).

​

Entre réplicas y reinicios

• Solo se transportan ids con forma W3C (32/16 hex en minúsculas, lo que produce OpenTelemetry). Un tracer con otros ids no guarda nada y el turno simplemente no tiene enlace. Un valor guardado mal formado se ignora.
• El contexto guardado es siempre el del último turno que escribió o quedó en espera: un stub de hand-over se reescribe cuando un turno posterior queda en espera (solo con telemetría; si no, solo se refresca antes de caducar), y el marcador de espera de un paso reenviado también lo actualiza. Un turno cuyo contexto no se puede transportar conserva el que ya estaba guardado en vez de borrarlo.
• Una función handover.fallback propia recibe el contexto en info.trace, para enlazar sus propios spans.
• formatTraceparent(spanContext) y parseTraceparent(traceparent, tracestate?) se exportan desde @botmesh/core/spi para tu propia propagación.

​

Tareas programadas

​

Spans de IA

​

Tus propios spans

bot.when('pedido', async (ctx) => {
  const pedido = await bot.tracing.trace('erp.lookup', { kind: 'client' }, () => erp.buscar(ctx.body))
  await ctx.reply(`Pedido ${pedido.id}`)
})

​

Métricas

​

Datos personales

• Nunca se registran: cuerpos de mensaje, captions, prompts, respuestas del modelo, argumentos y resultados de herramientas, c.state, respuestas de ask, texto de comandos desconocidos ni payloads crudos del provider.
• Los mensajes de error pueden contener texto del usuario: solo se registran la clase y el código del error, salvo que pongas telemetry.errorMessages: true.
• Los ids siguen telemetry.ids:
  • 'hash' (por defecto): HMAC-SHA256, base64url, 16 caracteres. La clave es telemetry.idKey; sin ella se usa una clave aleatoria por proceso, y los hashes no coinciden entre réplicas ni reinicios. Pon el mismo secreto en todas partes para buscar las trazas de un chat.
  • 'raw': el id tal cual lo da el provider; en WhatsApp es un número de teléfono, un dato personal.
  • 'omit': sin ids.

​

Configuración

new Bot({
  provider,
  telemetry: {
    tracer,                          // BotTracer (obligatorio)
    ids: 'hash',                     // 'hash' | 'raw' | 'omit'
    idKey: process.env.TRACE_ID_KEY, // string | Uint8Array
    errorMessages: false,
    spans: { persist: true, pace: true, streamUpdates: false },
  },
})

​

Muestreo

​

Otros backends y tests

import { createRecordingTracer, createTestBot } from '@botmesh/core/testing'

const rec = createRecordingTracer()
const { bot, chat } = await createTestBot({ telemetry: { tracer: rec.tracer, ids: 'raw' } })
bot.when('hola', (ctx) => ctx.reply('buenas'))
await chat.send('hola')
expect(rec.parentOf(rec.find('bot.send')!)?.name).toBe('bot.pace')

​

Límites

• Reproducciones durables: un registro entrante que reproduce el motor de durabilidad (tras una caída o un reintento) no tiene span bot.inbound; su bot.dispatch es un span raíz.
• Varias réplicas: una conversación retomada en otra réplica (o tras un reinicio) empieza una traza nueva enlazada a la anterior, no una continuación (ver Entre réplicas y reinicios). Una conversación traspasada antes de activar la telemetría, o por una réplica sin ella, no tiene enlace.
• Spans de OpenTelemetry de terceros dentro de una conversación retomada (código después de await c.ask()) cuelgan del contexto propio de OpenTelemetry, que sigue siendo el del primer turno; los spans del bot sí cuelgan bien.
• Vaciar el buffer es cosa del SDK: llama a sdk.shutdown() después de bot.stop().