@laburen/delta-sdk 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +29 -0
- package/LICENSE +21 -0
- package/README.md +133 -0
- package/dist/core/config.d.ts +44 -0
- package/dist/core/config.d.ts.map +1 -0
- package/dist/core/config.js +163 -0
- package/dist/core/config.js.map +1 -0
- package/dist/core/constantes.d.ts +15 -0
- package/dist/core/constantes.d.ts.map +1 -0
- package/dist/core/constantes.js +15 -0
- package/dist/core/constantes.js.map +1 -0
- package/dist/core/contadores.d.ts +28 -0
- package/dist/core/contadores.d.ts.map +1 -0
- package/dist/core/contadores.js +53 -0
- package/dist/core/contadores.js.map +1 -0
- package/dist/core/scrubbing.d.ts +10 -0
- package/dist/core/scrubbing.d.ts.map +1 -0
- package/dist/core/scrubbing.js +92 -0
- package/dist/core/scrubbing.js.map +1 -0
- package/dist/core/sesion.d.ts +9 -0
- package/dist/core/sesion.d.ts.map +1 -0
- package/dist/core/sesion.js +20 -0
- package/dist/core/sesion.js.map +1 -0
- package/dist/core/sobre.d.ts +46 -0
- package/dist/core/sobre.d.ts.map +1 -0
- package/dist/core/sobre.js +200 -0
- package/dist/core/sobre.js.map +1 -0
- package/dist/core/tipos.d.ts +154 -0
- package/dist/core/tipos.d.ts.map +1 -0
- package/dist/core/tipos.js +6 -0
- package/dist/core/tipos.js.map +1 -0
- package/dist/core/transporte.d.ts +24 -0
- package/dist/core/transporte.d.ts.map +1 -0
- package/dist/core/transporte.js +70 -0
- package/dist/core/transporte.js.map +1 -0
- package/dist/index.d.ts +2 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +2 -0
- package/dist/index.js.map +1 -0
- package/dist/telemetry/captura.d.ts +8 -0
- package/dist/telemetry/captura.d.ts.map +1 -0
- package/dist/telemetry/captura.js +136 -0
- package/dist/telemetry/captura.js.map +1 -0
- package/dist/telemetry/index.d.ts +5 -0
- package/dist/telemetry/index.d.ts.map +1 -0
- package/dist/telemetry/index.js +3 -0
- package/dist/telemetry/index.js.map +1 -0
- package/dist/telemetry/tipos.d.ts +2 -0
- package/dist/telemetry/tipos.d.ts.map +1 -0
- package/dist/telemetry/tipos.js +2 -0
- package/dist/telemetry/tipos.js.map +1 -0
- package/dist/telemetry/with-telemetry.d.ts +18 -0
- package/dist/telemetry/with-telemetry.d.ts.map +1 -0
- package/dist/telemetry/with-telemetry.js +81 -0
- package/dist/telemetry/with-telemetry.js.map +1 -0
- package/dist/telemetry/with-tool.d.ts +9 -0
- package/dist/telemetry/with-tool.d.ts.map +1 -0
- package/dist/telemetry/with-tool.js +20 -0
- package/dist/telemetry/with-tool.js.map +1 -0
- package/docs/que-se-manda.md +133 -0
- package/docs/superficies.md +239 -0
- package/docs/telemetria.md +258 -0
- package/docs/troubleshooting.md +115 -0
- package/package.json +61 -0
- package/src/core/config.ts +178 -0
- package/src/core/constantes.ts +17 -0
- package/src/core/contadores.ts +71 -0
- package/src/core/scrubbing.ts +104 -0
- package/src/core/sesion.ts +22 -0
- package/src/core/sobre.ts +236 -0
- package/src/core/tipos.ts +131 -0
- package/src/core/transporte.ts +93 -0
- package/src/index.ts +7 -0
- package/src/telemetry/captura.ts +161 -0
- package/src/telemetry/index.ts +16 -0
- package/src/telemetry/tipos.ts +13 -0
- package/src/telemetry/with-telemetry.ts +128 -0
- package/src/telemetry/with-tool.ts +23 -0
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
import { notifyUsable, validar } from "../core/config.js";
|
|
2
|
+
import { contarBeforeSend, contarInterno } from "../core/contadores.js";
|
|
3
|
+
import { aplicarBeforeSend, scrubEvento } from "../core/scrubbing.js";
|
|
4
|
+
import { armarEvento, armarSobre, extraerException, serializarAcotado } from "../core/sobre.js";
|
|
5
|
+
import { AVISO_CTX_ROTO, enviar, probarCtx } from "../core/transporte.js";
|
|
6
|
+
import { crearWithTool } from "./with-tool.js";
|
|
7
|
+
/** Descarta todo, pero `withTool` sigue corriendo la tool y re-lanzando: un cliente inerte no
|
|
8
|
+
* puede cambiar el comportamiento de la app. */
|
|
9
|
+
function clienteInerte() {
|
|
10
|
+
return {
|
|
11
|
+
captureException() { },
|
|
12
|
+
captureEvent() { },
|
|
13
|
+
withTool: crearWithTool(() => { }),
|
|
14
|
+
};
|
|
15
|
+
}
|
|
16
|
+
/** El `notify` de `CaptureOptions` es el camino multi-tenant que lee una fila de D1 en el momento
|
|
17
|
+
* del error, y ahí una columna puede venir NULL — el mismo agujero que la validación de la
|
|
18
|
+
* config, pero por evento. Si el override no es usable se descarta CON AVISO: el evento sale
|
|
19
|
+
* igual, con el `notify` de la config (que ya se validó), en vez de perderse mudo con un 400. */
|
|
20
|
+
function notifyDelEvento(override, notifyDeConfig) {
|
|
21
|
+
if (override === undefined)
|
|
22
|
+
return notifyDeConfig;
|
|
23
|
+
if (notifyUsable(override))
|
|
24
|
+
return override;
|
|
25
|
+
console.error("[delta-sdk] el notify de CaptureOptions no es usable (revisá channel/to): se descarta y el evento sale con el notify de la config");
|
|
26
|
+
return notifyDeConfig;
|
|
27
|
+
}
|
|
28
|
+
/** El núcleo explícito, y el camino principal: los dos wrappers se construyen sobre esto y
|
|
29
|
+
* ninguno puede hacer nada que esto no permita.
|
|
30
|
+
*
|
|
31
|
+
* Va llamado DENTRO de una invocación —`init()` de un Durable Object, un handler— y nunca a
|
|
32
|
+
* nivel de módulo: un valor aleatorio en el scope global hace fallar el deploy. */
|
|
33
|
+
export function createTelemetry(config) {
|
|
34
|
+
let avisado = false;
|
|
35
|
+
// Una vez por cliente y no una por captura: 40 capturas no pueden ser 40 líneas iguales.
|
|
36
|
+
const avisarCtxRoto = () => {
|
|
37
|
+
if (avisado)
|
|
38
|
+
return;
|
|
39
|
+
avisado = true;
|
|
40
|
+
console.error(AVISO_CTX_ROTO);
|
|
41
|
+
};
|
|
42
|
+
// El único punto de estrangulamiento: `validar` lee `service.name`, `organizationId`, `agentId`,
|
|
43
|
+
// `apiKey`, `surface` y `notify` de un `entrada` que puede ser cualquier cosa en runtime — un
|
|
44
|
+
// getter roto en CUALQUIERA de esos campos, o el objeto `config` entero armado como un `Proxy`
|
|
45
|
+
// hostil, puede lanzar antes de llegar al `try/catch` interno de `motivoNotifyInvalido`. Envolver
|
|
46
|
+
// acá cierra el invariante para TODO el objeto de entrada de una sola vez, en vez de una lista de
|
|
47
|
+
// campos que hay que mantener campo por campo.
|
|
48
|
+
let resultado;
|
|
49
|
+
try {
|
|
50
|
+
resultado = validar(config);
|
|
51
|
+
}
|
|
52
|
+
catch (error) {
|
|
53
|
+
console.error("[delta-sdk] no se pudo leer la config: este worker no va a reportar nada", error);
|
|
54
|
+
return clienteInerte();
|
|
55
|
+
}
|
|
56
|
+
if (!resultado.ok) {
|
|
57
|
+
console.error(`[delta-sdk] config inválida: este worker no va a reportar nada. Falta o está vacío: ${resultado.faltan.join(", ")}`);
|
|
58
|
+
return clienteInerte();
|
|
59
|
+
}
|
|
60
|
+
const cfg = resultado.config;
|
|
61
|
+
const ctx = probarCtx(config.ctx, avisarCtxRoto);
|
|
62
|
+
const capturar = (tipo, mensaje, exception, severityDefault, opciones) => {
|
|
63
|
+
try {
|
|
64
|
+
const armado = armarEvento({
|
|
65
|
+
tipo,
|
|
66
|
+
mensaje,
|
|
67
|
+
exception,
|
|
68
|
+
agentId: cfg.agentId,
|
|
69
|
+
surface: cfg.surface,
|
|
70
|
+
severityDefault,
|
|
71
|
+
opciones,
|
|
72
|
+
});
|
|
73
|
+
const limpio = scrubEvento(armado, cfg.scrub);
|
|
74
|
+
const final = aplicarBeforeSend(limpio, cfg.beforeSend);
|
|
75
|
+
if (final === null) {
|
|
76
|
+
// Un null cuenta como drop con razón `before_send`, que es una de las razones
|
|
77
|
+
// canónicas de Sentry.
|
|
78
|
+
contarBeforeSend();
|
|
79
|
+
return;
|
|
80
|
+
}
|
|
81
|
+
const sobre = armarSobre({
|
|
82
|
+
evento: final,
|
|
83
|
+
service: cfg.service,
|
|
84
|
+
// Los overrides por evento: un worker multi-tenant no conoce estos valores
|
|
85
|
+
// cuando se arma el cliente. `||` y no `??`: la config ya se validó no
|
|
86
|
+
// vacía, así que un "" del caller no puede ganarle al fallback bueno.
|
|
87
|
+
organizationId: opciones.organizationId || cfg.organizationId,
|
|
88
|
+
surface: cfg.surface,
|
|
89
|
+
notify: notifyDelEvento(opciones.notify, cfg.notify),
|
|
90
|
+
});
|
|
91
|
+
const { body } = serializarAcotado(sobre);
|
|
92
|
+
enviar({
|
|
93
|
+
body,
|
|
94
|
+
apiKey: cfg.apiKey,
|
|
95
|
+
url: cfg.ingestUrl,
|
|
96
|
+
ctx,
|
|
97
|
+
debug: cfg.debug,
|
|
98
|
+
avisarCtxRoto,
|
|
99
|
+
});
|
|
100
|
+
}
|
|
101
|
+
catch (error) {
|
|
102
|
+
// Última red. La superficie pública entera está envuelta: el SDK no puede lanzar ni
|
|
103
|
+
// con la config más rara. Es la quinta forma de perder un evento, y se
|
|
104
|
+
// cuenta igual que las otras cuatro: sin esto el sobre siguiente reportaba los cuatro
|
|
105
|
+
// contadores en cero, como si nada hubiera pasado.
|
|
106
|
+
contarInterno();
|
|
107
|
+
console.error("[delta-sdk] no se pudo reportar el evento", error);
|
|
108
|
+
}
|
|
109
|
+
};
|
|
110
|
+
/** Devuelve void, nunca una promesa, y nunca lanza. No se puede `await` a propósito:
|
|
111
|
+
* esperarlo le sumaría 40-150 ms a cada respuesta del agente.
|
|
112
|
+
*
|
|
113
|
+
* El try/catch de acá es una red DISTINTA de la de `capturar`: `extraerException` lee
|
|
114
|
+
* `.name`/`.message`/`.stack` de un valor que viene del cliente y que nadie validó, y un
|
|
115
|
+
* getter roto (una lib de source maps, un mock) puede lanzar ahí, antes de que exista ningún
|
|
116
|
+
* evento que meter en la red de `capturar`. Sin esto el throw se escapa de la superficie
|
|
117
|
+
* pública y, peor, `withTool` lo re-lanza a ÉL en vez del error original de la tool. */
|
|
118
|
+
const captureException = (error, opciones = {}) => {
|
|
119
|
+
let exception;
|
|
120
|
+
try {
|
|
121
|
+
exception = extraerException(error);
|
|
122
|
+
}
|
|
123
|
+
catch (fallo) {
|
|
124
|
+
console.error("[delta-sdk] no se pudo leer el error recibido", fallo);
|
|
125
|
+
exception = { type: "UnknownError" };
|
|
126
|
+
}
|
|
127
|
+
capturar("error", exception?.message, exception, "error", opciones);
|
|
128
|
+
};
|
|
129
|
+
/** El default es `warning` y no `error` porque un captureEvent típico registra una falla que
|
|
130
|
+
* el código ya manejó: se guarda en D1 y no despierta a nadie. */
|
|
131
|
+
const captureEvent = (message, opciones = {}) => {
|
|
132
|
+
capturar("event", message, undefined, "warning", opciones);
|
|
133
|
+
};
|
|
134
|
+
return { captureException, captureEvent, withTool: crearWithTool(captureException) };
|
|
135
|
+
}
|
|
136
|
+
//# sourceMappingURL=captura.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"captura.js","sourceRoot":"","sources":["../../src/telemetry/captura.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACxE,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACtE,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAShG,OAAO,EAAE,cAAc,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAC1E,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE/C;iDACiD;AACjD,SAAS,aAAa;IACrB,OAAO;QACN,gBAAgB,KAAI,CAAC;QACrB,YAAY,KAAI,CAAC;QACjB,QAAQ,EAAE,aAAa,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC;KACjC,CAAC;AACH,CAAC;AAED;;;kGAGkG;AAClG,SAAS,eAAe,CAAC,QAA4B,EAAE,cAAsB;IAC5E,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,cAAc,CAAC;IAClD,IAAI,YAAY,CAAC,QAAQ,CAAC;QAAE,OAAO,QAAQ,CAAC;IAC5C,OAAO,CAAC,KAAK,CACZ,mIAAmI,CACnI,CAAC;IACF,OAAO,cAAc,CAAC;AACvB,CAAC;AAED;;;;oFAIoF;AACpF,MAAM,UAAU,eAAe,CAAC,MAAuB;IACtD,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,yFAAyF;IACzF,MAAM,aAAa,GAAG,GAAS,EAAE;QAChC,IAAI,OAAO;YAAE,OAAO;QACpB,OAAO,GAAG,IAAI,CAAC;QACf,OAAO,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;IAC/B,CAAC,CAAC;IAEF,iGAAiG;IACjG,8FAA8F;IAC9F,+FAA+F;IAC/F,kGAAkG;IAClG,kGAAkG;IAClG,+CAA+C;IAC/C,IAAI,SAAqC,CAAC;IAC1C,IAAI,CAAC;QACJ,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,OAAO,CAAC,KAAK,CACZ,0EAA0E,EAC1E,KAAK,CACL,CAAC;QACF,OAAO,aAAa,EAAE,CAAC;IACxB,CAAC;IACD,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,CAAC;QACnB,OAAO,CAAC,KAAK,CACZ,uFAAuF,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACpH,CAAC;QACF,OAAO,aAAa,EAAE,CAAC;IACxB,CAAC;IAED,MAAM,GAAG,GAAG,SAAS,CAAC,MAAM,CAAC;IAC7B,MAAM,GAAG,GAAG,SAAS,CAAC,MAAM,CAAC,GAAG,EAAE,aAAa,CAAC,CAAC;IAEjD,MAAM,QAAQ,GAAG,CAChB,IAAuB,EACvB,OAA2B,EAC3B,SAAkD,EAClD,eAAyB,EACzB,QAAwB,EACjB,EAAE;QACT,IAAI,CAAC;YACJ,MAAM,MAAM,GAAG,WAAW,CAAC;gBAC1B,IAAI;gBACJ,OAAO;gBACP,SAAS;gBACT,OAAO,EAAE,GAAG,CAAC,OAAO;gBACpB,OAAO,EAAE,GAAG,CAAC,OAAO;gBACpB,eAAe;gBACf,QAAQ;aACR,CAAC,CAAC;YACH,MAAM,MAAM,GAAG,WAAW,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC;YAC9C,MAAM,KAAK,GAAG,iBAAiB,CAAC,MAAM,EAAE,GAAG,CAAC,UAAU,CAAC,CAAC;YACxD,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;gBACpB,8EAA8E;gBAC9E,uBAAuB;gBACvB,gBAAgB,EAAE,CAAC;gBACnB,OAAO;YACR,CAAC;YAED,MAAM,KAAK,GAAG,UAAU,CAAC;gBACxB,MAAM,EAAE,KAAK;gBACb,OAAO,EAAE,GAAG,CAAC,OAAO;gBACpB,2EAA2E;gBAC3E,uEAAuE;gBACvE,sEAAsE;gBACtE,cAAc,EAAE,QAAQ,CAAC,cAAc,IAAI,GAAG,CAAC,cAAc;gBAC7D,OAAO,EAAE,GAAG,CAAC,OAAO;gBACpB,MAAM,EAAE,eAAe,CAAC,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC;aACpD,CAAC,CAAC;YACH,MAAM,EAAE,IAAI,EAAE,GAAG,iBAAiB,CAAC,KAAK,CAAC,CAAC;YAE1C,MAAM,CAAC;gBACN,IAAI;gBACJ,MAAM,EAAE,GAAG,CAAC,MAAM;gBAClB,GAAG,EAAE,GAAG,CAAC,SAAS;gBAClB,GAAG;gBACH,KAAK,EAAE,GAAG,CAAC,KAAK;gBAChB,aAAa;aACb,CAAC,CAAC;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,oFAAoF;YACpF,uEAAuE;YACvE,sFAAsF;YACtF,mDAAmD;YACnD,aAAa,EAAE,CAAC;YAChB,OAAO,CAAC,KAAK,CAAC,2CAA2C,EAAE,KAAK,CAAC,CAAC;QACnE,CAAC;IACF,CAAC,CAAC;IAEF;;;;;;;6FAOyF;IACzF,MAAM,gBAAgB,GAAG,CAAC,KAAc,EAAE,WAA2B,EAAE,EAAQ,EAAE;QAChF,IAAI,SAAsC,CAAC;QAC3C,IAAI,CAAC;YACJ,SAAS,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAAC;QACrC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,OAAO,CAAC,KAAK,CAAC,+CAA+C,EAAE,KAAK,CAAC,CAAC;YACtE,SAAS,GAAG,EAAE,IAAI,EAAE,cAAc,EAAE,CAAC;QACtC,CAAC;QACD,QAAQ,CAAC,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;IACrE,CAAC,CAAC;IAEF;uEACmE;IACnE,MAAM,YAAY,GAAG,CAAC,OAAe,EAAE,WAA2B,EAAE,EAAQ,EAAE;QAC7E,QAAQ,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;IAC5D,CAAC,CAAC;IAEF,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,QAAQ,EAAE,aAAa,CAAC,gBAAgB,CAAC,EAAE,CAAC;AACtF,CAAC"}
|
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
export { createTelemetry } from "./captura.js";
|
|
2
|
+
export type { CaptureOptions, CtxLike, Envelope, HandlerTelemetryConfig, Notify, RetryInfo, Severity, Surface, TelemetryClient, TelemetryConfig, TelemetryEvent, } from "./tipos.js";
|
|
3
|
+
export type { Handlers } from "./with-telemetry.js";
|
|
4
|
+
export { withTelemetry } from "./with-telemetry.js";
|
|
5
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/telemetry/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,YAAY,EACX,cAAc,EACd,OAAO,EACP,QAAQ,EACR,sBAAsB,EACtB,MAAM,EACN,SAAS,EACT,QAAQ,EACR,OAAO,EACP,eAAe,EACf,eAAe,EACf,cAAc,GACd,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC"}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/telemetry/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAe/C,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC"}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"tipos.d.ts","sourceRoot":"","sources":["../../src/telemetry/tipos.ts"],"names":[],"mappings":"AAAA,YAAY,EACX,cAAc,EACd,OAAO,EACP,QAAQ,EACR,sBAAsB,EACtB,MAAM,EACN,SAAS,EACT,QAAQ,EACR,OAAO,EACP,eAAe,EACf,eAAe,EACf,cAAc,GACd,MAAM,kBAAkB,CAAC"}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"tipos.js","sourceRoot":"","sources":["../../src/telemetry/tipos.ts"],"names":[],"mappings":""}
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
import type { HandlerTelemetryConfig } from "../core/tipos.js";
|
|
2
|
+
/** `(...args: never[]) => unknown` es el supertipo de cualquier función, sin usar `any`: deja
|
|
3
|
+
* pasar el handler tal como lo escribió el implementador, con SUS tipos de Cloudflare. */
|
|
4
|
+
type HandlerCualquiera = (...args: never[]) => unknown;
|
|
5
|
+
export interface Handlers {
|
|
6
|
+
fetch?: HandlerCualquiera;
|
|
7
|
+
queue?: HandlerCualquiera;
|
|
8
|
+
scheduled?: HandlerCualquiera;
|
|
9
|
+
}
|
|
10
|
+
/** Envuelve el `export default` de un worker. Recibe la config como FUNCIÓN de `env` y no como
|
|
11
|
+
* objeto ya armado, porque el `env` no existe a nivel de módulo y evaluar la config ahí sería
|
|
12
|
+
* el mismo error que genera ids en el scope global.
|
|
13
|
+
*
|
|
14
|
+
* Solo ve lo que ESCAPA del handler: un `catch` que loguea y devuelve un valor no deja escapar
|
|
15
|
+
* nada, y el wrapper no se entera. Envolver no reemplaza revisar los `catch` que ya existen. */
|
|
16
|
+
export declare function withTelemetry<Env, H extends Handlers>(configFn: (env: Env) => HandlerTelemetryConfig, handlers: H): H;
|
|
17
|
+
export {};
|
|
18
|
+
//# sourceMappingURL=with-telemetry.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"with-telemetry.d.ts","sourceRoot":"","sources":["../../src/telemetry/with-telemetry.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAGX,sBAAsB,EAGtB,MAAM,kBAAkB,CAAC;AAG1B;2FAC2F;AAC3F,KAAK,iBAAiB,GAAG,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,CAAC;AAEvD,MAAM,WAAW,QAAQ;IACxB,KAAK,CAAC,EAAE,iBAAiB,CAAC;IAC1B,KAAK,CAAC,EAAE,iBAAiB,CAAC;IAC1B,SAAS,CAAC,EAAE,iBAAiB,CAAC;CAC9B;AAsFD;;;;;iGAKiG;AACjG,wBAAgB,aAAa,CAAC,GAAG,EAAE,CAAC,SAAS,QAAQ,EACpD,QAAQ,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,sBAAsB,EAC9C,QAAQ,EAAE,CAAC,GACT,CAAC,CAcH"}
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
import { queueMaxRetriesUsable } from "../core/config.js";
|
|
2
|
+
import { createTelemetry } from "./captura.js";
|
|
3
|
+
/** El nombre del handler ES la superficie. No hay nada que el implementador pueda escribir mal,
|
|
4
|
+
* y a diferencia de los comentarios del repo, el nombre del handler no miente. */
|
|
5
|
+
const SUPERFICIE_POR_HANDLER = {
|
|
6
|
+
fetch: "worker",
|
|
7
|
+
queue: "queue",
|
|
8
|
+
scheduled: "cron",
|
|
9
|
+
};
|
|
10
|
+
/** Los números del reintento que el SDK puede leer del runtime. En `queue` salen del batch; en
|
|
11
|
+
* las otras dos superficies los pone el default de la superficie. */
|
|
12
|
+
function opcionesDelHandler(surface, primero, queueMaxRetries) {
|
|
13
|
+
if (surface !== "queue")
|
|
14
|
+
return {};
|
|
15
|
+
const mensajes = primero?.messages ?? [];
|
|
16
|
+
if (mensajes.length === 0)
|
|
17
|
+
return {};
|
|
18
|
+
// Un batch se reintenta ENTERO: el máximo es el intento que puede ser el final. Con el
|
|
19
|
+
// mínimo, la alerta terminal podría no dispararse nunca.
|
|
20
|
+
const attempt = Math.max(...mensajes.map((mensaje) => mensaje.attempts ?? 1));
|
|
21
|
+
// Un batch no tiene un único mensaje del que colgar el id. Para capturar por mensaje va
|
|
22
|
+
// createTelemetry, y está documentado en docs/superficies.md.
|
|
23
|
+
const primerMensaje = mensajes.length === 1 ? mensajes[0] : undefined;
|
|
24
|
+
const workUnitId = primerMensaje?.id ?? null;
|
|
25
|
+
// max_retries son los reintentos DESPUÉS de la primera entrega: limit = max_retries + 1. Si
|
|
26
|
+
// no está, se omite en vez de adivinar.
|
|
27
|
+
return queueMaxRetries === undefined
|
|
28
|
+
? { retry: { attempt, workUnitId } }
|
|
29
|
+
: { retry: { attempt, limit: queueMaxRetries + 1, workUnitId } };
|
|
30
|
+
}
|
|
31
|
+
function envolver(surface, configFn, handler) {
|
|
32
|
+
return async (primero, env, ctx) => {
|
|
33
|
+
let cliente = null;
|
|
34
|
+
let cfg = null;
|
|
35
|
+
try {
|
|
36
|
+
cfg = configFn(env);
|
|
37
|
+
// `surface` y `ctx` los pone el wrapper: el tipo se los prohíbe al implementador para
|
|
38
|
+
// que no pueda pisarlos con un valor equivocado.
|
|
39
|
+
const { surface: _surface, ctx: _ctx, ...resto } = cfg;
|
|
40
|
+
cliente = createTelemetry({ ...resto, surface, ctx });
|
|
41
|
+
}
|
|
42
|
+
catch (error) {
|
|
43
|
+
// Si la telemetría no arranca, el handler del cliente corre igual.
|
|
44
|
+
console.error("[delta-sdk] no se pudo inicializar la telemetría; el handler sigue igual", error);
|
|
45
|
+
}
|
|
46
|
+
try {
|
|
47
|
+
return await handler(primero, env, ctx);
|
|
48
|
+
}
|
|
49
|
+
catch (error) {
|
|
50
|
+
// `cfg` es la config CRUDA que devolvió `configFn`, no la `ConfigValidada` de
|
|
51
|
+
// `createTelemetry`: este camino no pasa por `validar`, así que hay que sanearlo acá
|
|
52
|
+
// también. El aviso de un valor inválido ya lo emite `createTelemetry` más arriba,
|
|
53
|
+
// al validar la misma config para construir `cliente`.
|
|
54
|
+
const queueMaxRetriesCrudo = cfg?.queueMaxRetries;
|
|
55
|
+
const queueMaxRetries = queueMaxRetriesUsable(queueMaxRetriesCrudo)
|
|
56
|
+
? queueMaxRetriesCrudo
|
|
57
|
+
: undefined;
|
|
58
|
+
cliente?.captureException(error, opcionesDelHandler(surface, primero, queueMaxRetries));
|
|
59
|
+
// Se re-lanza igual que en withTool: el runtime tiene que ver el mismo error para
|
|
60
|
+
// decidir el 500 o el reintento del batch.
|
|
61
|
+
throw error;
|
|
62
|
+
}
|
|
63
|
+
};
|
|
64
|
+
}
|
|
65
|
+
/** Envuelve el `export default` de un worker. Recibe la config como FUNCIÓN de `env` y no como
|
|
66
|
+
* objeto ya armado, porque el `env` no existe a nivel de módulo y evaluar la config ahí sería
|
|
67
|
+
* el mismo error que genera ids en el scope global.
|
|
68
|
+
*
|
|
69
|
+
* Solo ve lo que ESCAPA del handler: un `catch` que loguea y devuelve un valor no deja escapar
|
|
70
|
+
* nada, y el wrapper no se entera. Envolver no reemplaza revisar los `catch` que ya existen. */
|
|
71
|
+
export function withTelemetry(configFn, handlers) {
|
|
72
|
+
const salida = { ...handlers };
|
|
73
|
+
for (const nombre of ["fetch", "queue", "scheduled"]) {
|
|
74
|
+
const handler = handlers[nombre];
|
|
75
|
+
if (handler === undefined)
|
|
76
|
+
continue;
|
|
77
|
+
salida[nombre] = envolver(SUPERFICIE_POR_HANDLER[nombre], configFn, handler);
|
|
78
|
+
}
|
|
79
|
+
return salida;
|
|
80
|
+
}
|
|
81
|
+
//# sourceMappingURL=with-telemetry.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"with-telemetry.js","sourceRoot":"","sources":["../../src/telemetry/with-telemetry.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
import type { CaptureOptions, TelemetryClient } from "../core/tipos.js";
|
|
2
|
+
/** Envuelve una tool de MCP. El implementador NO escribe captureException en ninguna tool: lo
|
|
3
|
+
* hace este wrapper, una vez, para todas las que envuelva. Ese es el aporte.
|
|
4
|
+
*
|
|
5
|
+
* Tres requisitos, no sugerencias: reenvía TODOS los argumentos porque el SDK invoca con
|
|
6
|
+
* `(args, extra)`; re-lanza EL MISMO objeto de error porque su mensaje es el que ve el usuario
|
|
7
|
+
* final; y es arrow function para no introducir un `this` propio. */
|
|
8
|
+
export declare function crearWithTool(capturar: (error: unknown, opciones: CaptureOptions) => void): TelemetryClient["withTool"];
|
|
9
|
+
//# sourceMappingURL=with-tool.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"with-tool.d.ts","sourceRoot":"","sources":["../../src/telemetry/with-tool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAExE;;;;;sEAKsE;AACtE,wBAAgB,aAAa,CAC5B,QAAQ,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,cAAc,KAAK,IAAI,GAC1D,eAAe,CAAC,UAAU,CAAC,CAY7B"}
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
/** Envuelve una tool de MCP. El implementador NO escribe captureException en ninguna tool: lo
|
|
2
|
+
* hace este wrapper, una vez, para todas las que envuelva. Ese es el aporte.
|
|
3
|
+
*
|
|
4
|
+
* Tres requisitos, no sugerencias: reenvía TODOS los argumentos porque el SDK invoca con
|
|
5
|
+
* `(args, extra)`; re-lanza EL MISMO objeto de error porque su mensaje es el que ve el usuario
|
|
6
|
+
* final; y es arrow function para no introducir un `this` propio. */
|
|
7
|
+
export function crearWithTool(capturar) {
|
|
8
|
+
return (nombre, fn) => async (...args) => {
|
|
9
|
+
try {
|
|
10
|
+
return await fn(...args);
|
|
11
|
+
}
|
|
12
|
+
catch (error) {
|
|
13
|
+
// El reporte vive acá y en ningún otro lado. Y solo llega si `fn` LANZA: una tool
|
|
14
|
+
// que atrapa su propio error y devuelve un valor no pasa por acá.
|
|
15
|
+
capturar(error, { workUnit: nombre });
|
|
16
|
+
throw error;
|
|
17
|
+
}
|
|
18
|
+
};
|
|
19
|
+
}
|
|
20
|
+
//# sourceMappingURL=with-tool.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"with-tool.js","sourceRoot":"","sources":["../../src/telemetry/with-tool.ts"],"names":[],"mappings":"AAEA;;;;;sEAKsE;AACtE,MAAM,UAAU,aAAa,CAC5B,QAA4D;IAE5D,OAAO,CAA4B,MAAc,EAAE,EAAqC,EAAE,EAAE,CAC3F,KAAK,EAAE,GAAG,IAAU,EAAc,EAAE;QACnC,IAAI,CAAC;YACJ,OAAO,MAAM,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC;QAC1B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,kFAAkF;YAClF,kEAAkE;YAClE,QAAQ,CAAC,KAAK,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC;YACtC,MAAM,KAAK,CAAC;QACb,CAAC;IACF,CAAC,CAAC;AACJ,CAAC"}
|
|
@@ -0,0 +1,133 @@
|
|
|
1
|
+
# Qué se manda: el contrato con la ingesta
|
|
2
|
+
|
|
3
|
+
Esta página describe el sobre (`Envelope`) que el SDK arma y manda a `telemetry.laburen.com/events`,
|
|
4
|
+
los formatos exactos de cada campo, y la división de trabajo entre el SDK y la ingesta.
|
|
5
|
+
|
|
6
|
+
## 1. El payload de ejemplo
|
|
7
|
+
|
|
8
|
+
```json
|
|
9
|
+
{
|
|
10
|
+
"sdk": { "name": "@laburen/delta-sdk", "version": "1.0.0" },
|
|
11
|
+
"sent_at": "2026-07-30T18:22:10.200Z",
|
|
12
|
+
"drops": { "incompletos": 0, "fallados": 0, "before_send": 0, "recortados": 0, "internos": 0 },
|
|
13
|
+
"session": "1a08cf9c",
|
|
14
|
+
"resource": {
|
|
15
|
+
"service": { "name": "mi-mcp", "version": "1.0.0", "environment": "production" },
|
|
16
|
+
"client": { "organization_id": "org_ejemplo" },
|
|
17
|
+
"surface": "durable_object"
|
|
18
|
+
},
|
|
19
|
+
"notify": { "slack": { "enabled": true, "channel": "C00000000000" } },
|
|
20
|
+
"events": [{
|
|
21
|
+
"event_id": "9f8c1e2a-1b3d-4a5c-9e6f-7a8b9c0d1e2f",
|
|
22
|
+
"seq": 17,
|
|
23
|
+
"timestamp": "2026-07-30T18:22:10.123Z",
|
|
24
|
+
"type": "error",
|
|
25
|
+
"severity": "error",
|
|
26
|
+
"message": "mi_tool falló al renovar el token",
|
|
27
|
+
"context": { "agent_id": "agent_ejemplo", "work_unit": "mi_tool", "trace_id": "tr_9f3c..." },
|
|
28
|
+
"retry": { "attempt": 1, "limit": 1, "is_final_attempt": true, "work_unit_id": null },
|
|
29
|
+
"exception": { "type": "Error", "message": "Token no disponible", "stacktrace": "…" }
|
|
30
|
+
}]
|
|
31
|
+
}
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
> El campo `drops` lleva **cinco** contadores (`incompletos`, `fallados`, `before_send`,
|
|
35
|
+
> `recortados`, `internos` — sección 4), no dos: son las cinco formas en que un evento puede no
|
|
36
|
+
> llegar completo a D1.
|
|
37
|
+
|
|
38
|
+
## 2. Formatos exactos
|
|
39
|
+
|
|
40
|
+
| Campo | Formato |
|
|
41
|
+
|---|---|
|
|
42
|
+
| `event_id` | UUID v4, **en minúsculas** |
|
|
43
|
+
| `timestamp`, `sent_at` | ISO 8601 UTC, **con milisegundos y `Z`** |
|
|
44
|
+
| `seq` | entero **≥ 1** |
|
|
45
|
+
| `type` | `"error"` \| `"event"` |
|
|
46
|
+
| `severity` | `"debug"` \| `"info"` \| `"warning"` \| `"error"` \| `"fatal"` |
|
|
47
|
+
| `surface` | uno de los seis de `docs/superficies.md`: `worker`, `durable_object`, `workflow`, `queue`, `alarm`, `cron` |
|
|
48
|
+
| `channel` (dentro de `notify`) | `/^[CGD][A-Z0-9]{8,}$/` — un id de canal de Slack real |
|
|
49
|
+
|
|
50
|
+
`new Date().toISOString()` produce exactamente el formato ISO 8601 UTC con milisegundos y `Z` que se
|
|
51
|
+
pide. `crypto.randomUUID()` produce un UUID v4 en minúsculas. **El SDK no formatea nada a mano**: usa
|
|
52
|
+
estas dos funciones del runtime tal cual.
|
|
53
|
+
|
|
54
|
+
## 3. `session` + `seq`: para qué sirven, y su límite honesto
|
|
55
|
+
|
|
56
|
+
`session` identifica al isolate (se genera una vez, la primera vez que hace falta, y no cambia
|
|
57
|
+
mientras el isolate viva). `seq` es un contador que arranca en 1 y sube de a uno por cada evento de
|
|
58
|
+
esa sesión, y **nunca se reinicia**.
|
|
59
|
+
|
|
60
|
+
Juntos le permiten a la ingesta notar que faltó algo: si llegan los `seq` 1, 2 y 4 de la misma
|
|
61
|
+
`session`, la ingesta sabe que el 3 **existió y se perdió** en algún punto del camino.
|
|
62
|
+
|
|
63
|
+
**El límite honesto:** este mecanismo detecta huecos **en el medio** de una secuencia, no una **cola
|
|
64
|
+
cortada al final**. Si el isolate muere de golpe después de mandar el `seq` 4, y los envíos 5, 6 y 7
|
|
65
|
+
nunca llegaron a salir del todo, la ingesta solo ve hasta el 4 — no tiene forma de saber que el 5, el
|
|
66
|
+
6 y el 7 alguna vez existieron. `session` y `seq` prueban huecos, no el tamaño real de lo que se
|
|
67
|
+
perdió al final.
|
|
68
|
+
|
|
69
|
+
## 4. Los cinco contadores de `drops`
|
|
70
|
+
|
|
71
|
+
| Contador | Qué es |
|
|
72
|
+
|---|---|
|
|
73
|
+
| `incompletos` | `disparados − completados − fallados`: envíos que se dispararon y **no** terminaron ni con éxito ni con una excepción de red — quedaron a mitad de camino porque el isolate murió antes de que el `fetch` resolviera, **o siguen en vuelo** (ver el límite honesto más abajo) |
|
|
74
|
+
| `fallados` | envíos donde el `fetch` mismo lanzó (problema de red o DNS) |
|
|
75
|
+
| `before_send` | eventos descartados porque `beforeSend` devolvió `null` |
|
|
76
|
+
| `recortados` | sobres que hubo que recortar para entrar en el tope de 512 KB (ver sección 5) |
|
|
77
|
+
| `internos` | eventos que se perdieron porque algo entre armar el evento y mandarlo lanzó una excepción (por ejemplo, un `attributes` con un getter roto) — la única razón sin una causa de negocio detrás |
|
|
78
|
+
|
|
79
|
+
**El límite honesto de `incompletos`: mezcla "en vuelo" con "perdido", y en un sobre suelto no se
|
|
80
|
+
puede leer como pérdida.** El `drops` de un sobre es un snapshot tomado en `armarSobre`, **antes**
|
|
81
|
+
de que el `enviar` de ESE MISMO evento termine. Con varias capturas seguidas en la misma invocación,
|
|
82
|
+
cada sobre ve los envíos anteriores todavía pendientes: `incompletos` sube de 0 a 1 a 2 sin que se
|
|
83
|
+
haya perdido nada, porque esos POST siguen en vuelo, no fallaron. **Por eso `incompletos` solo sirve
|
|
84
|
+
agregado sobre muchos isolates**, donde ese sesgo del último evento en vuelo se promedia y lo que
|
|
85
|
+
queda es la señal real de pérdida por ciclo de vida. Mirado así — en agregado, no sobre un sobre
|
|
86
|
+
individual — es el número que decide si hace falta poner una cola de Cloudflare Queues delante de la
|
|
87
|
+
ingesta, en vez de discutirlo por intuición: si `incompletos` es consistentemente ~0, el POST directo
|
|
88
|
+
alcanza; si no, hay pérdida real que una cola resolvería.
|
|
89
|
+
|
|
90
|
+
## 5. Los límites, y quién los aplica
|
|
91
|
+
|
|
92
|
+
| Límite | Valor | Quién lo aplica |
|
|
93
|
+
|---|---|---|
|
|
94
|
+
| `stacktrace` | 8 KB | los dos lados: el SDK trunca antes de mandar, la ingesta trunca de nuevo del lado servidor |
|
|
95
|
+
| `message` (y `exception.message`) | 2 KB | los dos lados |
|
|
96
|
+
| claves de `attributes` | primeras 64 | los dos lados |
|
|
97
|
+
| cuerpo del sobre completo | 512 KB | **solo el cliente recorta.** El servidor **no trunca** este límite: lo rechaza directo con `413` |
|
|
98
|
+
|
|
99
|
+
Que los dos lados trunquen los primeros tres límites no es redundancia inútil: el cliente lo hace
|
|
100
|
+
para no perder el sobre entero antes de mandarlo, la ingesta lo hace de nuevo para no confiar en que
|
|
101
|
+
el cliente lo haya hecho bien.
|
|
102
|
+
|
|
103
|
+
**El tope de 512 KB del cuerpo es distinto: no se trunca del lado servidor, se rechaza con `413`.**
|
|
104
|
+
Por eso el SDK tiene que recortar **antes** de mandar. El SDK **nunca descarta un evento por ser
|
|
105
|
+
grande**: si el JSON serializado supera el tope, recorta en pasos (primero el `stacktrace` a 1 KB,
|
|
106
|
+
después lo borra del todo, después vacía `attributes`, y por último recorta el `message` a 256
|
|
107
|
+
caracteres), deteniéndose apenas el sobre entra en el tope. El evento siempre sale, aunque llegue con
|
|
108
|
+
menos detalle.
|
|
109
|
+
|
|
110
|
+
## 6. Los códigos de respuesta reales
|
|
111
|
+
|
|
112
|
+
| Código | Cuándo | Qué hace el SDK |
|
|
113
|
+
|---|---|---|
|
|
114
|
+
| `200` | guardado (con `{accepted, duplicates, alerted, throttled}`) | nada |
|
|
115
|
+
| `400` | payload inválido, o más de 100 eventos por sobre | **no reintenta.** Con `debug: true`, un `console.warn` |
|
|
116
|
+
| `401` | bearer inválido | **no reintenta.** `console.error` siempre, con o sin `debug` — es config rota y hay que verla |
|
|
117
|
+
| `413` | cuerpo > 512 KB | **no reintenta.** No debería pasar si el SDK recorta bien — ver `docs/troubleshooting.md` |
|
|
118
|
+
| `503` | falló D1, o una excepción no manejada en la ingesta | **no reintenta.** Con `debug: true`, un `console.warn` |
|
|
119
|
+
|
|
120
|
+
**El SDK no reintenta en ninguno de estos casos.** Cualquier respuesta —éxito o error— cuenta como
|
|
121
|
+
`completado`, nunca como `fallado` (`fallado` es solo cuando el `fetch` mismo lanza, por red o DNS).
|
|
122
|
+
|
|
123
|
+
## 7. Additive-only, y el orden de deploy
|
|
124
|
+
|
|
125
|
+
**El contrato es additive-only:** se agregan campos opcionales, nunca se renombra ni se saca nada.
|
|
126
|
+
La ingesta ignora los campos que no conoce, así que un worker con una versión vieja del SDK sigue
|
|
127
|
+
funcionando indefinidamente.
|
|
128
|
+
|
|
129
|
+
**El orden de deploy importa, y es siempre el mismo: la ingesta va antes que el paquete.** Los enums
|
|
130
|
+
de `type`, `severity` y `surface` son **cerrados** del lado de la ingesta: un valor que la ingesta no
|
|
131
|
+
reconoce todavía se rechaza con `400`. Si una versión nueva del SDK agrega un valor a alguno de esos
|
|
132
|
+
enums, la ingesta que lo va a aceptar tiene que estar en producción **antes** de que ese SDK se
|
|
133
|
+
publique — al revés, esos eventos se pierden con `400` en vez de guardarse.
|