Instrumentando un servicio Node.js con @vectry/node

La instrumentación fracasa por dos razones: es demasiado trabajo, o produce eventos que nadie puede usar después. Esta guía cubre ambas — cómo conectar @vectry/node a un servicio en minutos, y cómo diseñar eventos que sigan siendo explicables dentro de un año.

Instala e inicializa

npm install @vectry/node

import { Vectry } from '@vectry/node';

const vectry = new Vectry({
  apiKey: process.env.VECTRY_API_KEY,
});

Un cliente por proceso. El SDK agrupa y envía eventos de forma asíncrona — capture() resuelve rápido y nunca se sienta en tu request path.

Diseña primero el namespace

Cada evento lleva un namespace con la gramática {dominio}.{entidad}.{operación}:

• inventory.item.updated
• auth.session.created
• billing.invoice.issued

Resiste la tentación de inventar nombres libres. El namespace es cómo los humanos filtran streams, cómo los dashboards agrupan señales y cómo tu yo del futuro encuentra cualquier cosa. Si no puedes nombrar el dominio y la entidad, aún no has decidido qué es el evento.

La operación es el contrato

El objeto operation es lo que hace que un evento de Vectry sea más que una línea de log:

await vectry.capture({
  namespace: 'inventory.item.updated',
  actor_id: 'usr-99992',
  actor_type: 'user',
  operation: {
    type: 'updated',
    system_domain: 'inventory',
    system_entity: 'item',
    system_entity_id: 'item-3339',
    changes: {
      original: { quantity: 3 },
      updated: { quantity: 5 },
    },
  },
});

Tres reglas que seguimos internamente:

1. Nombra siempre la instancia. system_entity_id es lo que permite que traces e hilos se ensamblen alrededor de algo real.
2. Haz diff solo de lo que cambió. changes es un diff a nivel de campo, no un snapshot completo — pequeño, legible, auditable.
3. Los eventos no mutantes también tienen objetivo. Una operación signaled o evaluated nombra la entidad que evaluó, aunque nada haya cambiado.

Los actores nunca son opcionales

actor_type acepta user, system, ai y device. La tentación es dejar todo en system y seguir — no lo hagas. Cuando un agente de IA actúa sobre tu operación, actor_type: 'ai' es la diferencia entre una decisión auditable y una anónima. Un evento sin actor real es un bug, no un dato.

Dónde capturar

Pon las llamadas de captura en la frontera del dominio, no en los controllers: el método de servicio que realmente muta la entidad es el único lugar que conoce los valores originales y actualizados. Instrumenta ahí una vez, y cada caller — handler HTTP, consumidor de cola, cron — emite el mismo evento bien formado.

Esa es toda la disciplina. Una gramática, capturada donde vive la verdad, con el actor adjunto. Todo lo demás — traces, hilos, explicaciones, anomalías — Vectry lo construye desde ahí.