@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,239 @@
|
|
|
1
|
+
# Superficies: qué cambia entre worker, durable object, workflow, queue, alarm y cron
|
|
2
|
+
|
|
3
|
+
El mismo `captureException` significa cosas distintas según dónde corre: cambia si el POST flotante
|
|
4
|
+
sobrevive, y de dónde sale el número de reintento. Esta página documenta esas diferencias.
|
|
5
|
+
|
|
6
|
+
## 1. La tabla completa
|
|
7
|
+
|
|
8
|
+
| `surface` | `ctx` es | ¿Flotante sobrevive? | `waitUntil` | `attempt` | `limit` | `work_unit_id` |
|
|
9
|
+
|---|---|---|---|---|---|---|
|
|
10
|
+
| `worker` | `ExecutionContext` | ❌ no | **obligatorio** | `1` | `1` | `null` |
|
|
11
|
+
| `durable_object` | `DurableObjectState` | ✅ sí | inofensivo si falta | `1` | `1` | `null` |
|
|
12
|
+
| `workflow` | `ExecutionContext` | ⚠️ sobrevivió en la medición¹ | usarlo | `ctx.attempt` del step² | `ctx.config.retries.limit`² | `event.instanceId`² |
|
|
13
|
+
| `queue` | `ExecutionContext` | ❌ no | **obligatorio** | `msg.attempts` | `queueMaxRetries + 1`³ | `msg.id` |
|
|
14
|
+
| `alarm` | `DurableObjectState` | (no medido) | usarlo | se omite⁴ | se omite⁴ | `null` |
|
|
15
|
+
| `cron` | `ExecutionContext` | (no medido) | **usarlo** | `1` | `1` | `null` |
|
|
16
|
+
|
|
17
|
+
¹ Sobrevivió porque había otro step después que mantuvo viva la instancia. **No es garantía.**
|
|
18
|
+
|
|
19
|
+
² `createTelemetry(config)` **no recibe el `ctx` del step de Workflow**, así que el SDK no puede leer
|
|
20
|
+
estos valores por su cuenta. El bloque `retry` se **omite** por default en `surface: "workflow"`
|
|
21
|
+
(sección 5); si el implementador quiere que el evento lleve estos números, los pasa a mano por
|
|
22
|
+
`CaptureOptions.retry`, leyéndolos de `ctx.attempt` y `ctx.config.retries.limit` del step.
|
|
23
|
+
|
|
24
|
+
³ Ver la sección 4: es el único que el runtime no expone en ningún lado, y el único con un
|
|
25
|
+
off-by-one.
|
|
26
|
+
|
|
27
|
+
⁴ Ver la sección 5: un valor inventado en `alarm` puede silenciar la alerta terminal para siempre.
|
|
28
|
+
|
|
29
|
+
## 2. La regla del `waitUntil`, y es una sola
|
|
30
|
+
|
|
31
|
+
**Si el `ctx` que se le pasó al SDK tiene `waitUntil`, se usa siempre.** No se decide por
|
|
32
|
+
superficie: es gratis, es inofensivo donde no hace falta (`durable_object`, donde el POST flotante ya
|
|
33
|
+
sobrevive sin él), y es **obligatorio** en las dos superficies donde el POST flotante se pierde
|
|
34
|
+
siempre que no se use (`worker` y `queue`).
|
|
35
|
+
|
|
36
|
+
## 3. `is_final_attempt = attempt >= limit`, nunca con `>`
|
|
37
|
+
|
|
38
|
+
`limit` son los intentos **totales**, no los reintentos. Con `limit: 3`, los intentos son 1, 2 y 3, y
|
|
39
|
+
el último es el que cumple `attempt === limit`. El SDK calcula `is_final_attempt` con `attempt >=
|
|
40
|
+
limit` en todos los casos donde lo calcula solo — mandalo así vos también si lo armás a mano por
|
|
41
|
+
`CaptureOptions.retry`.
|
|
42
|
+
|
|
43
|
+
## 4. `queue`: el `limit` que el runtime no da, y el off-by-one
|
|
44
|
+
|
|
45
|
+
En todas las demás superficies el `limit` sale del runtime o es una constante conocida. En `queue`
|
|
46
|
+
no: el runtime de Cloudflare Queues **no expone `max_retries` en ningún lado** — ni en el mensaje, ni
|
|
47
|
+
en su prototipo, ni en el `env`, ni en `batch` (su `metadata` son métricas de backlog, no config).
|
|
48
|
+
Hay que pedírselo al implementador.
|
|
49
|
+
|
|
50
|
+
Y acá está la trampa: `max_retries` del `wrangler.jsonc` **no es el total de intentos**, son los
|
|
51
|
+
reintentos *después* de la primera entrega:
|
|
52
|
+
|
|
53
|
+
| `max_retries` (wrangler.jsonc) | Entregas reales |
|
|
54
|
+
|---|---|
|
|
55
|
+
| `2` | **3** |
|
|
56
|
+
| `4` | **5** |
|
|
57
|
+
|
|
58
|
+
```
|
|
59
|
+
limit (intentos totales) = queueMaxRetries + 1
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
Por eso el campo de la config se llama **`queueMaxRetries`** y no `queueRetryLimit`: el
|
|
63
|
+
implementador copia **el mismo número, con el mismo nombre**, que ya tiene en su `wrangler.jsonc`,
|
|
64
|
+
sin hacer la cuenta a mano.
|
|
65
|
+
|
|
66
|
+
```jsonc
|
|
67
|
+
// wrangler.jsonc del worker de cliente
|
|
68
|
+
"consumers": [{ "queue": "mi-cola", "max_retries": 2 }]
|
|
69
|
+
```
|
|
70
|
+
```ts
|
|
71
|
+
// config del SDK — el mismo 2, sin convertir; el SDK calcula limit = 3
|
|
72
|
+
withTelemetry((env) => ({ /* ... */ queueMaxRetries: 2 }), { /* ... */ });
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
**Si `queueMaxRetries` no está**, el SDK **no adivina**: manda `attempt` y `work_unit_id`, y
|
|
76
|
+
**omite `limit` e `is_final_attempt`** por completo. La ingesta los tiene opcionales, así que el
|
|
77
|
+
evento es válido igual y cae en su regla por default de alertar cuando no sabe que un intento es
|
|
78
|
+
definitivo — es decir, **alerta en todos los intentos**. Es ruidoso, pero **nunca mudo**, y nunca
|
|
79
|
+
declara "definitivo" algo que no lo es.
|
|
80
|
+
|
|
81
|
+
## 5. Qué rellena el SDK automáticamente, y qué omite
|
|
82
|
+
|
|
83
|
+
| `surface` | ¿El SDK completa `retry` solo? |
|
|
84
|
+
|---|---|
|
|
85
|
+
| `worker` | Sí — valores neutros: `attempt: 1, limit: 1, is_final_attempt: true, work_unit_id: null` |
|
|
86
|
+
| `durable_object` | Sí — los mismos neutros |
|
|
87
|
+
| `cron` | Sí — los mismos neutros |
|
|
88
|
+
| `queue` (con `withTelemetry`) | Parcial — calcula `attempt` del batch y `work_unit_id` si aplica (sección 7); `limit` solo si se pasó `queueMaxRetries` |
|
|
89
|
+
| `queue` (con `createTelemetry` crudo) | No — se omite todo el bloque salvo que se pase `retry` a mano por `CaptureOptions` |
|
|
90
|
+
| `alarm` | **No, nunca** — se omite el bloque entero |
|
|
91
|
+
| `workflow` | **No, nunca** — se omite el bloque entero |
|
|
92
|
+
|
|
93
|
+
**En `alarm` y en `workflow` el bloque `retry` se omite entero — el SDK no lo rellena con valores
|
|
94
|
+
neutros.** Si tu worker necesita esos números en alguna de las dos superficies, tenés que pasarlos
|
|
95
|
+
vos a mano por `CaptureOptions.retry`, con el dato real:
|
|
96
|
+
|
|
97
|
+
- En `alarm`, si el worker maneja sus propios reintentos con un contador en el storage del Durable
|
|
98
|
+
Object, **no inventes un `limit` copiando ese contador**: con los neutros (`attempt: 1, limit: 1`)
|
|
99
|
+
un intento que todavía va a reintentar queda marcado como definitivo; con un `limit` inventado más
|
|
100
|
+
grande, el intento que sí agota los reintentos puede quedar **sin alertar como definitivo**. Ninguno
|
|
101
|
+
de los dos sirve — omitir es lo correcto salvo que tengas el dato real.
|
|
102
|
+
- En `workflow`, los números viven en el `ctx` del step (`ctx.attempt`, `ctx.config.retries.limit`),
|
|
103
|
+
que `createTelemetry(config)` **no recibe**: si los necesitás, pasalos leyéndolos del step.
|
|
104
|
+
|
|
105
|
+
**Regla general: si el SDK no puede saber un dato con certeza, lo omite en vez de inventarlo.** Un
|
|
106
|
+
valor inventado puede silenciar una alerta real.
|
|
107
|
+
|
|
108
|
+
## 6. Reintentos propios: las dos palancas
|
|
109
|
+
|
|
110
|
+
Si el worker reintenta **por su cuenta** —en cualquier superficie, no solo `alarm`— el SDK no puede
|
|
111
|
+
rellenar `retry` por él, y el implementador tiene que decidir con una de dos palancas.
|
|
112
|
+
|
|
113
|
+
| Origen del reintento | ¿El SDK sabe los números? | Ejemplo |
|
|
114
|
+
|---|---|---|
|
|
115
|
+
| **El runtime de Cloudflare** | ✅ sí — `workflow` (`ctx.attempt`) y `queue` (`msg.attempts` + `queueMaxRetries`) | sección 1 |
|
|
116
|
+
| **Un contador propio en storage** | ❌ no | un `alarm()` que guarda `retry_count` en el storage del Durable Object |
|
|
117
|
+
| **Un bucle propio en memoria** | ❌ no | un `for` con `MAX_ATTEMPTS` y un `sleep` entre vueltas |
|
|
118
|
+
| **El sistema que llama** | ❌ no, y no es computable | un worker que devuelve `500` para que el que lo llama reintente por su cuenta; o una política de reintento que vive en el prompt de un LLM |
|
|
119
|
+
|
|
120
|
+
**Las dos palancas, independientes entre sí:**
|
|
121
|
+
|
|
122
|
+
| Palanca | Cómo se usa | Cuándo conviene |
|
|
123
|
+
|---|---|---|
|
|
124
|
+
| **`severity`** | `"warning"` no llega al mínimo de alerta configurado en la ingesta → se guarda en D1 y no dispara Slack | reintentos propios, y en general cualquier "registrá esto pero no me despiertes" |
|
|
125
|
+
| **`retry.is_final_attempt`** | `false` → se guarda y no alerta | reintentos del runtime, donde el SDK sí sabe los números (sección 1) |
|
|
126
|
+
|
|
127
|
+
**Ejemplo 1 — alcanza con `severity` sola**, porque la rendición vive **dentro del mismo `catch`**
|
|
128
|
+
que el contador:
|
|
129
|
+
|
|
130
|
+
```ts
|
|
131
|
+
} catch (error) {
|
|
132
|
+
const retryCount = (await this.ctx.storage.get("retry_count")) ?? 0;
|
|
133
|
+
|
|
134
|
+
telemetry.captureException(error, {
|
|
135
|
+
workUnit: "launch-workflow",
|
|
136
|
+
severity: retryCount >= MAX_RETRIES ? "error" : "warning",
|
|
137
|
+
attributes: { retryCount },
|
|
138
|
+
});
|
|
139
|
+
|
|
140
|
+
// ...el resto del catch, igual que antes (guarda el contador, agenda la próxima alarma)
|
|
141
|
+
}
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
Los intentos intermedios quedan en D1 como `warning` (se pueden investigar, pero no alertan); suena
|
|
145
|
+
una sola alerta, la del intento que se rinde y descarta el trabajo — que es la que importa.
|
|
146
|
+
|
|
147
|
+
**Ejemplo 2 — hacen falta las dos cosas**, porque la rendición está **fuera** del `catch` y sin
|
|
148
|
+
ningún `error` en scope:
|
|
149
|
+
|
|
150
|
+
```ts
|
|
151
|
+
for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
|
|
152
|
+
try {
|
|
153
|
+
return await intentar();
|
|
154
|
+
} catch (error) {
|
|
155
|
+
telemetry.captureException(error, { // intermedios: se guardan, no alertan
|
|
156
|
+
workUnit: "reenvio-cola",
|
|
157
|
+
severity: "warning",
|
|
158
|
+
attributes: { attempt, limit: MAX_ATTEMPTS },
|
|
159
|
+
});
|
|
160
|
+
}
|
|
161
|
+
if (attempt < MAX_ATTEMPTS) await sleep(RETRY_DELAY_MS * attempt);
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
telemetry.captureEvent("reenvio-cola: agotados los intentos, mensaje descartado", {
|
|
165
|
+
workUnit: "reenvio-cola",
|
|
166
|
+
severity: "error", // ← esta sí alerta
|
|
167
|
+
attributes: { limit: MAX_ATTEMPTS },
|
|
168
|
+
});
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
Bajar todo a `"warning"` acá silenciaría también la rendición final, que es la que importa; por eso
|
|
172
|
+
hacen falta las dos palancas: `severity: "warning"` en los intentos intermedios y un
|
|
173
|
+
`captureEvent(..., { severity: "error" })` explícito en la rendición. Es `captureEvent` y no
|
|
174
|
+
`captureException` porque en ese punto **no hay ningún objeto `Error`** — es el estado D de
|
|
175
|
+
[telemetria.md](./telemetria.md#5-los-cuatro-estados-del-código-existente).
|
|
176
|
+
|
|
177
|
+
## 7. El batch de `queue` con `withTelemetry`
|
|
178
|
+
|
|
179
|
+
Cuando `withTelemetry` envuelve un handler `queue` y ese handler lanza, reporta:
|
|
180
|
+
|
|
181
|
+
- **`attempt`: el máximo** entre todos los mensajes del batch (`Math.max(...batch.messages.map(m =>
|
|
182
|
+
m.attempts))`), no el mínimo. Un batch se reintenta **entero**: no hay un único "intento del
|
|
183
|
+
batch" salvo el peor de sus mensajes, y ese máximo es el que puede coincidir con el intento final.
|
|
184
|
+
Usar el mínimo podría hacer que la alerta terminal **nunca se dispare**, porque siempre habría
|
|
185
|
+
algún mensaje "más nuevo" con menos intentos.
|
|
186
|
+
- **`work_unit_id`: solo si el batch trae exactamente un mensaje.** Con más de un mensaje no hay un
|
|
187
|
+
único id del que colgarlo, y se manda `null`.
|
|
188
|
+
|
|
189
|
+
**Para capturar un evento por cada mensaje del batch** —en vez de uno solo por todo el batch fallido—
|
|
190
|
+
la herramienta correcta es `createTelemetry` usado **adentro del loop**, no `withTelemetry`:
|
|
191
|
+
|
|
192
|
+
```ts
|
|
193
|
+
import { createTelemetry } from "@laburen/delta-sdk/telemetry";
|
|
194
|
+
|
|
195
|
+
export default {
|
|
196
|
+
async queue(batch: MessageBatch<Job>, env: Env, ctx: ExecutionContext) {
|
|
197
|
+
const telemetry = createTelemetry({
|
|
198
|
+
service: { name: "mi-worker", version: "1.0.0" },
|
|
199
|
+
surface: "queue",
|
|
200
|
+
organizationId: env.MI_ORGANIZATION_ID,
|
|
201
|
+
agentId: env.MI_AGENT_ID,
|
|
202
|
+
apiKey: env.LABUREN_TELEMETRY_KEY,
|
|
203
|
+
notify: { slack: { enabled: true, channel: env.MI_SLACK_CHANNEL_ID } },
|
|
204
|
+
ctx,
|
|
205
|
+
});
|
|
206
|
+
|
|
207
|
+
for (const mensaje of batch.messages) {
|
|
208
|
+
try {
|
|
209
|
+
await procesar(mensaje.body);
|
|
210
|
+
} catch (error) {
|
|
211
|
+
telemetry.captureException(error, {
|
|
212
|
+
workUnit: "queue:procesar",
|
|
213
|
+
retry: {
|
|
214
|
+
attempt: mensaje.attempts,
|
|
215
|
+
limit: 3, // queueMaxRetries (2) + 1 — la misma cuenta de la sección 4
|
|
216
|
+
workUnitId: mensaje.id,
|
|
217
|
+
},
|
|
218
|
+
});
|
|
219
|
+
}
|
|
220
|
+
}
|
|
221
|
+
},
|
|
222
|
+
};
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
`createTelemetry` con `surface: "queue"` no completa `retry` por su cuenta (a diferencia de
|
|
226
|
+
`withTelemetry`, que sí lee el batch): acá el implementador arma el bloque a mano, mensaje por
|
|
227
|
+
mensaje, con la misma regla de `limit = queueMaxRetries + 1` de la sección 4.
|
|
228
|
+
|
|
229
|
+
## 8. `surface` es obligatorio en `createTelemetry`, y no se escribe con `withTelemetry`
|
|
230
|
+
|
|
231
|
+
`createTelemetry` **exige** `surface` en la config: no hay ningún handler del que deducirla, porque
|
|
232
|
+
es exactamente el caso del Durable Object (`init()` no es un handler con nombre reconocible) y del
|
|
233
|
+
Workflow (donde el punto de captura suele estar dentro de un step, no en un `export default` con
|
|
234
|
+
`fetch`/`queue`/`scheduled`).
|
|
235
|
+
|
|
236
|
+
`withTelemetry`, en cambio, **prohíbe** que la config traiga `surface`: el tipo de la config que
|
|
237
|
+
recibe la marca como `never`, así que escribirla es un error de compilación. La superficie se deduce
|
|
238
|
+
del nombre del handler (`fetch` → `worker`, `queue` → `queue`, `scheduled` → `cron`), porque el
|
|
239
|
+
nombre no puede escribirse mal.
|
|
@@ -0,0 +1,258 @@
|
|
|
1
|
+
# La puerta `/telemetry`, guía larga
|
|
2
|
+
|
|
3
|
+
Esta es la referencia completa de `@laburen/delta-sdk/telemetry`: la config campo por campo, las
|
|
4
|
+
`CaptureOptions`, el scrubbing y el `beforeSend`. Para los ejemplos copiables y rápidos, empezá por
|
|
5
|
+
el [README](../README.md). Para qué cambia según dónde corre tu worker, ver
|
|
6
|
+
[superficies.md](./superficies.md). Para el contrato exacto que viaja por la red, ver
|
|
7
|
+
[que-se-manda.md](./que-se-manda.md).
|
|
8
|
+
|
|
9
|
+
## 1. Las tres formas, y para qué sirve cada una
|
|
10
|
+
|
|
11
|
+
| Forma | Cuándo | Qué resuelve |
|
|
12
|
+
|---|---|---|
|
|
13
|
+
| **`createTelemetry(config)` + `captureException`/`captureEvent`** | **cualquier situación — es el camino principal** | el núcleo explícito. Devuelve el **cliente**, y las otras dos formas se construyen sobre esto |
|
|
14
|
+
| `withTelemetry(configFn, handlers)` | worker plano, `queue`, `cron` | envuelve el `export default`; provee `env` y `ctx`; deduce la superficie por el nombre del handler; captura lo que **escapa** del handler |
|
|
15
|
+
| `telemetry.withTool(nombre, fn)` | tools de MCP que **hoy no atrapan su error** | envuelve una tool; captura y **re-lanza**; ahorra escribir el `try/catch` |
|
|
16
|
+
|
|
17
|
+
**`createTelemetry` es el camino principal.** Los dos wrappers son atajos que se arman encima: ni
|
|
18
|
+
`withTelemetry` ni `withTool` pueden hacer nada que `createTelemetry` no permita. Si mañana aparece
|
|
19
|
+
una superficie o un caso que los wrappers no cubren, el núcleo ya lo resuelve.
|
|
20
|
+
|
|
21
|
+
Los dos wrappers **solo ven lo que escapa** de la función que envuelven. Un `catch` que loguea y
|
|
22
|
+
devuelve un valor —o un `.catch(() => {})`— nunca deja escapar nada, así que el wrapper no se
|
|
23
|
+
entera. En la práctica, el grueso del trabajo de instrumentar un worker existente **no** es envolver
|
|
24
|
+
con estos wrappers: es sumar `captureException`/`captureEvent` a mano dentro de los `catch` que ya
|
|
25
|
+
existen. Ver la sección 5.
|
|
26
|
+
|
|
27
|
+
## 2. La config, campo por campo
|
|
28
|
+
|
|
29
|
+
Esta es la config que recibe `createTelemetry`. `withTelemetry` recibe la misma forma **menos**
|
|
30
|
+
`surface` y `ctx` (los pone el wrapper — ver [superficies.md](./superficies.md#8-surface-es-obligatorio-en-createtelemetry-y-no-se-escribe-con-withtelemetry)).
|
|
31
|
+
|
|
32
|
+
| Campo | Tipo | ¿Obligatorio? | Notas |
|
|
33
|
+
|---|---|---|---|
|
|
34
|
+
| `service` | `{ name: string; version?: string; environment?: string }` | Sí (`name`) | va a `resource.service` del sobre |
|
|
35
|
+
| `surface` | `"worker" \| "durable_object" \| "workflow" \| "queue" \| "alarm" \| "cron"` | Sí, en `createTelemetry` | **no se escribe** con `withTelemetry`: se deduce del nombre del handler |
|
|
36
|
+
| `organizationId` | `string` | Sí | identidad del cliente; se puede pisar por evento (sección 4) |
|
|
37
|
+
| `agentId` | `string` | Sí | qué agente falló; se puede pisar por evento |
|
|
38
|
+
| `apiKey` | `string` | Sí | viene de un **secret** del `env` (`wrangler secret put`), nunca de una `var` |
|
|
39
|
+
| `notify` | `Notify` (unión discriminada, ver abajo) | Sí | a qué canal alertar; se puede pisar por evento |
|
|
40
|
+
| `ctx` | `{ waitUntil?: (p: Promise<unknown>) => void }` | No | el `ExecutionContext`/`DurableObjectState` real de tu handler lo satisface. Sin él, el POST flotante puede perderse en `worker` y `queue` — ver `docs/superficies.md` |
|
|
41
|
+
| `ingestUrl` | `string` | No | **solo desarrollo local**; en producción la URL es una constante del paquete |
|
|
42
|
+
| `scrub` | `string[]` | No | términos propios que se suman a la denylist (sección 8) |
|
|
43
|
+
| `beforeSend` | `(evento: TelemetryEvent) => TelemetryEvent \| null` | No | escape hatch (sección 9) |
|
|
44
|
+
| `debug` | `boolean` | No | prende un `console.warn` extra en las respuestas `4xx`/`5xx` de la ingesta |
|
|
45
|
+
| `queueMaxRetries` | `number` | No | solo tiene efecto en `surface: "queue"` — el mismo número del `max_retries` del `wrangler.jsonc`, ver `docs/superficies.md` |
|
|
46
|
+
|
|
47
|
+
**Nada más es obligatorio.** Los seis campos obligatorios son `service` (con `name`), `surface`
|
|
48
|
+
(solo en `createTelemetry`), `organizationId`, `agentId`, `apiKey` y `notify`. Si alguno llega vacío
|
|
49
|
+
o falta, `createTelemetry` no lanza: devuelve un cliente inerte que descarta todo y emite **un solo**
|
|
50
|
+
`console.error` con el detalle de qué falta, visible en `wrangler tail`.
|
|
51
|
+
|
|
52
|
+
Esto incluye un canal **declarado** (`enabled: true`) cuyo `channel` o `to` está vacío o mal
|
|
53
|
+
formado: no alcanza con que el otro canal esté bien completo, el canal que declaraste tiene que
|
|
54
|
+
estarlo. Es distinto de `queueMaxRetries`: si ese campo llega con algo que no es un entero ≥ 0, no
|
|
55
|
+
invalida el resto de la config — el SDK lo ignora, avisa con su propio `console.error`, y el
|
|
56
|
+
cliente sigue reportando normalmente, solo que sin `retry.limit` en `surface: "queue"`.
|
|
57
|
+
|
|
58
|
+
`Notify` es una unión discriminada, no campos opcionales sueltos: una config con `notify` inválido
|
|
59
|
+
**no compila**, en vez de fallar recién en producción con el `400` de la ingesta.
|
|
60
|
+
|
|
61
|
+
```ts
|
|
62
|
+
type Slack = { enabled: false } | { enabled: true; channel: string };
|
|
63
|
+
type Email = { enabled: false } | { enabled: true; to: [string, ...string[]] };
|
|
64
|
+
|
|
65
|
+
type Notify =
|
|
66
|
+
| { slack: Extract<Slack, { enabled: true }>; email?: Email }
|
|
67
|
+
| { slack?: Slack; email: Extract<Email, { enabled: true }> };
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
Un `notify: {}`, un `slack: { enabled: true }` sin `channel`, o un `email` prendido con `to: []` son
|
|
71
|
+
errores de TypeScript, no un `400` que hay que descubrir en producción.
|
|
72
|
+
|
|
73
|
+
## 3. `CaptureOptions`, campo por campo
|
|
74
|
+
|
|
75
|
+
El segundo argumento de `captureException` y de `captureEvent`.
|
|
76
|
+
|
|
77
|
+
| Campo | Tipo | Va a |
|
|
78
|
+
|---|---|---|
|
|
79
|
+
| `workUnit` | `string` | `context.work_unit` |
|
|
80
|
+
| `traceId` | `string` | `context.trace_id` |
|
|
81
|
+
| `conversationId` | `string` | `context.conversation_id` |
|
|
82
|
+
| `requestId` | `string` | `context.request_id` |
|
|
83
|
+
| `severity` | `Severity` (`"debug" \| "info" \| "warning" \| "error" \| "fatal"`) | `severity` — default `"error"` en `captureException`, `"warning"` en `captureEvent` |
|
|
84
|
+
| `attributes` | `Record<string, string \| number \| boolean>` | `attributes` |
|
|
85
|
+
| `retry` | `RetryInfo` (`{ attempt?, limit?, isFinalAttempt?, workUnitId? }`) | `retry` — si no viene, el default lo pone la superficie (ver `docs/superficies.md`) |
|
|
86
|
+
| `fingerprint` | `string[]` | `fingerprint` — si va, la ingesta lo usa tal cual en vez de calcular la huella |
|
|
87
|
+
| `agentId` | `string` | `context.agent_id` — **override multi-tenant**, sección 4 |
|
|
88
|
+
| `organizationId` | `string` | `resource.client.organization_id` — **override multi-tenant**, sección 4 |
|
|
89
|
+
| `notify` | `Notify` | `notify` — **override multi-tenant**, sección 4 |
|
|
90
|
+
|
|
91
|
+
## 4. Multi-tenant: cuando la identidad del cliente no está en el `env`
|
|
92
|
+
|
|
93
|
+
El caso simple es un worker que atiende a un solo cliente: `organizationId`, `agentId` y el canal de
|
|
94
|
+
Slack se ponen una vez en la config y no cambian nunca. En un worker **multi-tenant** —un solo
|
|
95
|
+
deploy que atiende a varios clientes— eso no alcanza: la identidad no se conoce cuando se arma la
|
|
96
|
+
config, sale de un header, o de una fila de base de datos leída recién en el momento del error.
|
|
97
|
+
|
|
98
|
+
Para eso, `agentId`, `organizationId` y `notify` se pueden **pisar por evento** vía `CaptureOptions`
|
|
99
|
+
(sección 3). El cliente se crea una vez con valores por default (o genéricos), y en el punto del
|
|
100
|
+
error —donde ya se sabe de quién es— se sobreescriben.
|
|
101
|
+
|
|
102
|
+
El caso límite es el `alarm()` de un Durable Object, donde no hay `env` ni request de la cual colgar
|
|
103
|
+
la identidad, pero sí está a mano lo que se leyó del storage:
|
|
104
|
+
|
|
105
|
+
```ts
|
|
106
|
+
// dentro del alarm() de un Durable Object multi-tenant.
|
|
107
|
+
// configCliente salió del storage: no hay env ni request acá.
|
|
108
|
+
telemetry.captureException(error, {
|
|
109
|
+
workUnit: "alarm:tarea-programada",
|
|
110
|
+
severity: retryCount >= MAX_RETRIES ? "error" : "warning",
|
|
111
|
+
agentId: configCliente.agentId,
|
|
112
|
+
organizationId: configCliente.organizationId,
|
|
113
|
+
notify: { slack: { enabled: true, channel: configCliente.slackChannelId } },
|
|
114
|
+
});
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
Sin este override, los workers multi-tenant reportarían todo bajo un id genérico y **todas las
|
|
118
|
+
alertas caerían en un solo canal de Slack**, que es justo el problema que se quiere evitar. Para los
|
|
119
|
+
workers de un solo cliente no cambia nada: se ignoran los tres campos y el sobre siempre lleva los
|
|
120
|
+
valores de la config.
|
|
121
|
+
|
|
122
|
+
## 5. Los cuatro estados del código existente
|
|
123
|
+
|
|
124
|
+
Todo camino de error de un worker ya escrito cae en uno de estos cuatro estados. La pregunta que los
|
|
125
|
+
separa no es "¿la función atrapa el error?" sino **"¿el error llega hasta el borde que el wrapper
|
|
126
|
+
envuelve?"**
|
|
127
|
+
|
|
128
|
+
| Estado | Ejemplo típico | ¿Lo ve un wrapper? | Qué hacer |
|
|
129
|
+
|---|---|---|---|
|
|
130
|
+
| **A. El error llega al borde envuelto** | una tool sin ningún `try/catch` propio | ✅ sí | envolver con `withTool` / `withTelemetry`, y listo |
|
|
131
|
+
| **B. Atrapa, loguea y devuelve** | `catch (e) { console.error(e); return { isError: true } }` | ❌ no | sumar `captureException` **adentro** del `catch` que ya está |
|
|
132
|
+
| **C. Mudo** | `.catch(() => {})` o `catch { }` sin cuerpo | ❌ no | darle cuerpo a la cláusula / reemplazar el callback vacío |
|
|
133
|
+
| **D. Nunca hay un `Error`** | `if (!res.ok) { console.error(...); return null }` | ❌ no | **escribir la detección que no existe** y usar `captureEvent` |
|
|
134
|
+
|
|
135
|
+
**Dos matices que evitan trabajo inútil:**
|
|
136
|
+
|
|
137
|
+
- **No todo estado C hay que instrumentarlo.** Un `.catch(() => "")` que solo existe para leer el
|
|
138
|
+
body de una respuesta que **ya falló**, y armar el mensaje de un error que se lanza dos líneas
|
|
139
|
+
después, no esconde ninguna pérdida real. Instrumentarlo produciría un evento inútil por cada
|
|
140
|
+
intento de leer ese body — en un repo real, 14 eventos de ruido por cada falla real. Hay que
|
|
141
|
+
distinguir el C que descarta una falla del C benigno de lectura de body.
|
|
142
|
+
- **No todo estado A es "envolver y listo".** Un `catch { throw new Error("algo falló") }` es
|
|
143
|
+
técnicamente un A —el error llega al borde—, pero el wrapper agarra un error **sintético, sin la
|
|
144
|
+
causa original**. El evento llega a D1 sin la información que hace falta para diagnosticar. Vale
|
|
145
|
+
la pena revisar si el `catch` que re-lanza está perdiendo el error de origen (por ejemplo, sin
|
|
146
|
+
usar `cause`) antes de asumir que envolver alcanza.
|
|
147
|
+
|
|
148
|
+
## 6. El estado B no es una migración mecánica
|
|
149
|
+
|
|
150
|
+
Cuando el estado B ya tiene un `catch` que loguea y devuelve un valor —como el de la sección 5—, es
|
|
151
|
+
tentador borrar el `catch` para que lo agarre el wrapper de más arriba. **No hagas eso por
|
|
152
|
+
default.** Borrarlo cambia lo que ve el usuario final: en vez de un mensaje de error controlado
|
|
153
|
+
(`"Ocurrió un error: ..."`), el usuario recibe lo que arme el framework por su cuenta (por ejemplo,
|
|
154
|
+
la respuesta de error genérica del framework de MCP). Eso es una decisión de producto, no una
|
|
155
|
+
migración mecánica.
|
|
156
|
+
|
|
157
|
+
**Por default: sumar la línea de `captureException` y dejar el `catch` como está.** Es la opción que
|
|
158
|
+
no cambia el comportamiento observable del worker.
|
|
159
|
+
|
|
160
|
+
## 7. `captureEvent` vs `captureException`
|
|
161
|
+
|
|
162
|
+
`captureEvent` es la herramienta del estado D (sección 5): cuando no hay ningún objeto `Error` que
|
|
163
|
+
pasar.
|
|
164
|
+
|
|
165
|
+
| | `captureException` | `captureEvent` |
|
|
166
|
+
|---|---|---|
|
|
167
|
+
| Primer argumento | `unknown` — se le extrae `type`, `message` y `stacktrace` | `string` — va tal cual a `message` |
|
|
168
|
+
| `type` del evento | `"error"` | `"event"` |
|
|
169
|
+
| `severity` por default | `"error"` | **`"warning"`** |
|
|
170
|
+
| Bloque `exception` | sí | **no se manda** |
|
|
171
|
+
|
|
172
|
+
El default de severidad es distinto porque un `captureEvent` típico registra una falla que el código
|
|
173
|
+
**ya manejó** (un `!res.ok`, un resultado vacío): con `"warning"` se guarda en D1 y no despierta a
|
|
174
|
+
nadie. Quien quiera alertar lo sube a `"error"` explícitamente.
|
|
175
|
+
|
|
176
|
+
**Regla del `fingerprint` (o, si no se pasa, del `message`):** sin `stacktrace`, la ingesta agrupa
|
|
177
|
+
por el texto del mensaje. Si el mensaje lleva ids que cambian entre invocaciones (`ticket:157249`,
|
|
178
|
+
una duración en ms), cada ocurrencia genera un grupo nuevo y el dedup de la ingesta deja de servir.
|
|
179
|
+
**El `message` va sin interpolar ids; los ids van en `attributes`.**
|
|
180
|
+
|
|
181
|
+
```ts
|
|
182
|
+
// ✅ agrupa bien: un solo grupo para todas las fallas de este tipo
|
|
183
|
+
telemetry.captureEvent("mi-integracion: crearTicket devolvió no-2xx", {
|
|
184
|
+
workUnit: "crear-ticket",
|
|
185
|
+
attributes: { status: res.status, ticket_id: ticketId },
|
|
186
|
+
});
|
|
187
|
+
|
|
188
|
+
// ❌ un grupo nuevo por cada ticket distinto
|
|
189
|
+
telemetry.captureEvent(`Falló la asignación del ticket ${ticketId} (HTTP ${res.status})`);
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
## 8. Scrubbing
|
|
193
|
+
|
|
194
|
+
Los workers pasan credenciales por headers propios de cada integración (`x-api-key`,
|
|
195
|
+
`x-service-token`, y similares), y nada de eso puede terminar en un log ni en una fila de D1. El
|
|
196
|
+
scrubbing corre en tres capas, en orden:
|
|
197
|
+
|
|
198
|
+
**Capa 1 — la denylist por default.** Sobre las **claves** de `attributes` y sobre el texto de
|
|
199
|
+
`message`, `exception.message` y `exception.stacktrace`, corren dos reglas con alcance **distinto a
|
|
200
|
+
propósito**:
|
|
201
|
+
|
|
202
|
+
- **`clave: valor` / `clave=valor`** (con dos puntos o igual): se redacta todo lo que sigue en la
|
|
203
|
+
línea. Esta regla corre para **toda la denylist**, porque el separador ya dice sin ambigüedad "lo
|
|
204
|
+
que sigue es un valor" (`Authorization: Bearer eyJ…` → `Authorization: [redactado]`).
|
|
205
|
+
- **`clave valor`** (palabra suelta, sin separador): se redacta **solo la palabra que sigue**, y esta
|
|
206
|
+
regla corre **únicamente para `bearer`** y para los términos que el propio cliente agrega vía
|
|
207
|
+
`scrub` — nunca para el resto de la denylist. La razón: sin un separador no hay forma de distinguir
|
|
208
|
+
un valor real de la palabra siguiente en una frase común, y términos como `token` o `password`
|
|
209
|
+
aparecen todo el tiempo en prosa que no tiene ningún secreto (`"Token no disponible"`, `"Password
|
|
210
|
+
reset required"`). Aplicar la regla agresiva ahí mutilaría esos mensajes sin necesidad. Con
|
|
211
|
+
`bearer` la apuesta vale la pena porque casi el 100% de sus apariciones reales son un header sin
|
|
212
|
+
dos puntos (`Bearer eyJ…`); con los términos que el cliente agrega vía `scrub` también, porque ahí
|
|
213
|
+
la agresividad es la que pidió explícitamente.
|
|
214
|
+
|
|
215
|
+
> **Consecuencia asumida:** un mensaje como `"password hunter2"`, escrito **sin** dos puntos, ya
|
|
216
|
+
> **no** se redacta — no matchea ninguna de las dos reglas de la denylist genérica. La defensa real
|
|
217
|
+
> sigue siendo no meter secretos en el texto de un mensaje de error; esta capa ataja descuidos, no
|
|
218
|
+
> los reemplaza.
|
|
219
|
+
|
|
220
|
+
Sobre las **claves** de `attributes` el chequeo es distinto: si la clave **contiene** (substring,
|
|
221
|
+
sin importar mayúsculas) cualquier término de la denylist o de `scrub`, el **valor entero** se
|
|
222
|
+
reemplaza por `[redactado]`, sin mirar el contenido.
|
|
223
|
+
|
|
224
|
+
La denylist completa: `secret`, `token`, `apikey`, `api_key`, `password`, `authorization`,
|
|
225
|
+
`bearer`, `cookie`, `credential`, `private_key`.
|
|
226
|
+
|
|
227
|
+
**Capa 2 — `scrub: string[]` en la config.** Suma términos propios de ese cliente a la denylist, con
|
|
228
|
+
las mismas dos reglas de arriba (y, para esos términos, también la regla agresiva de "palabra
|
|
229
|
+
suelta").
|
|
230
|
+
|
|
231
|
+
**Capa 3 — `beforeSend(evento) => evento | null`.** El escape hatch final: recibe el evento **ya
|
|
232
|
+
scrubbeado** por las capas 1 y 2, y puede modificarlo libremente o **devolver `null` para
|
|
233
|
+
descartarlo**. Un `null` cuenta como un drop con razón `before_send` en el sobre.
|
|
234
|
+
|
|
235
|
+
**Dos límites, escritos como límites y no como garantías:**
|
|
236
|
+
|
|
237
|
+
- **El scrubbing por substring es una red, no una garantía.** Un secreto guardado en un campo
|
|
238
|
+
llamado `config` (que no matchea ningún término de la denylist) no se detecta. La defensa real es
|
|
239
|
+
no meter secretos en el mensaje de error; esta capa ataja los descuidos más comunes, no los
|
|
240
|
+
reemplaza.
|
|
241
|
+
- **`context.work_unit` no se scrubbea.** Es el nombre de una tool o de un paso de código —no un dato
|
|
242
|
+
de usuario—, así que no metas ahí nada sensible. Ver también
|
|
243
|
+
[troubleshooting.md](./troubleshooting.md).
|
|
244
|
+
|
|
245
|
+
## 9. `beforeSend`
|
|
246
|
+
|
|
247
|
+
- Recibe el evento **ya scrubbeado** (después de las capas 1 y 2 de la sección 8), no el evento
|
|
248
|
+
crudo.
|
|
249
|
+
- Devolver `null` **descarta** el evento; se cuenta como drop con razón `before_send`.
|
|
250
|
+
- **Si `beforeSend` lanza una excepción**, el SDK la atrapa, emite un `console.error`, y **el evento
|
|
251
|
+
se manda igual, sin aplicar el `beforeSend`.** Un `beforeSend` roto nunca hace perder un evento.
|
|
252
|
+
|
|
253
|
+
## 10. Los datos sensibles son opt-in
|
|
254
|
+
|
|
255
|
+
Prompts, argumentos de tools y resultados **no se capturan nunca por default**. En concreto,
|
|
256
|
+
`withTool` **no manda los `args` de la tool que envuelve** al evento de telemetría. Si un
|
|
257
|
+
implementador los quiere en el evento —para diagnosticar mejor una falla puntual—, los pasa a mano
|
|
258
|
+
por `attributes` (con cuidado de no incluir ahí nada sensible sin querer, ver sección 8).
|
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
# Troubleshooting
|
|
2
|
+
|
|
3
|
+
Una sección por síntoma. Si tu problema no está acá, el TypeScript real está en
|
|
4
|
+
`node_modules/@laburen/delta-sdk/src/`, y se puede leer directamente.
|
|
5
|
+
|
|
6
|
+
## "No llega nada"
|
|
7
|
+
|
|
8
|
+
Revisá en este orden:
|
|
9
|
+
|
|
10
|
+
1. **¿Aparece en `wrangler tail` el `console.error` de "config inválida"?** Si sale
|
|
11
|
+
`[delta-sdk] config inválida: este worker no va a reportar nada. Falta o está vacío: ...`, falta
|
|
12
|
+
o está vacío alguno de los campos obligatorios de la config (`service.name`, `organizationId`,
|
|
13
|
+
`agentId`, `apiKey`, `surface`, `notify`) — normalmente porque una variable del `env` no está
|
|
14
|
+
seteada como se esperaba. Esto incluye un canal de `notify` declarado (`enabled: true`) pero con
|
|
15
|
+
el `channel` o el `to` vacío o mal formado: no alcanza con que el otro canal esté bien. Revisá
|
|
16
|
+
`docs/telemetria.md` para la lista completa.
|
|
17
|
+
2. **¿Aparece el aviso del `ctx` no invocable?** Si ves *"El `ctx` recibido tiene `waitUntil` pero
|
|
18
|
+
no es invocable"*, le estás pasando al SDK una **copia** del `ExecutionContext`/`DurableObjectState`
|
|
19
|
+
en vez del original. Ver la sección dedicada más abajo.
|
|
20
|
+
3. **¿El `catch` de donde esperás que salga el evento hace `return` en vez de dejar que el error
|
|
21
|
+
escape?** Los wrappers (`withTool`, `withTelemetry`) solo ven lo que **escapa** de la función que
|
|
22
|
+
envuelven. Un `catch` que loguea y devuelve un valor —o un `.catch(() => {})`— no reporta nada, y
|
|
23
|
+
no es un bug: es el límite documentado en `docs/telemetria.md`. La solución es sumar
|
|
24
|
+
`captureException`/`captureEvent` **adentro** de ese `catch`.
|
|
25
|
+
4. **¿El `apiKey` es el secret correcto?** Un `401` de la ingesta sale **siempre** por
|
|
26
|
+
`console.error`, con o sin `debug` activado, porque es config rota y tiene que verse. Si no ves
|
|
27
|
+
ese `console.error` en `wrangler tail`, la clave está llegando bien y el problema es otro de los
|
|
28
|
+
tres de arriba.
|
|
29
|
+
|
|
30
|
+
## `error 1042`
|
|
31
|
+
|
|
32
|
+
Un `fetch` de un Worker plano a **otro** worker de la misma cuenta en un dominio `*.workers.dev`
|
|
33
|
+
devuelve `1042` **siempre** — no es intermitente, y falla igual con `await`, con `waitUntil` o sin
|
|
34
|
+
nada. Por esto la URL de la ingesta (`telemetry.laburen.com`) es un **Custom Domain** y una
|
|
35
|
+
**constante del paquete**, no algo que se arme a partir de un nombre `.workers.dev`.
|
|
36
|
+
|
|
37
|
+
Si ves este error, alguien pasó un `ingestUrl` apuntando a un dominio `workers.dev` (recordá que
|
|
38
|
+
`ingestUrl` es **solo** para desarrollo local — en producción no hace falta tocarlo).
|
|
39
|
+
|
|
40
|
+
## `401`
|
|
41
|
+
|
|
42
|
+
Bearer inválido: el `apiKey` que llegó no es el que la ingesta espera para esa organización. El SDK
|
|
43
|
+
**no reintenta** y emite un `console.error` **sin depender de `debug`**, porque es config rota, no un
|
|
44
|
+
problema transitorio.
|
|
45
|
+
|
|
46
|
+
Revisá que el secret esté cargado con `wrangler secret put LABUREN_TELEMETRY_KEY` (o el nombre que
|
|
47
|
+
uses) y **no** como una `var` del `wrangler.jsonc` — una `var` queda en texto plano en el repo y en
|
|
48
|
+
el dashboard, y además es fácil que quede desactualizada sin que nadie note el 401 en producción.
|
|
49
|
+
|
|
50
|
+
## `413`
|
|
51
|
+
|
|
52
|
+
Cuerpo de la request > 512 KB. Esto **no debería pasar en el uso normal**: el orden real del
|
|
53
|
+
pipeline es `scrubEvento` → `aplicarBeforeSend` → `armarSobre` → `serializarAcotado` — **el recorte
|
|
54
|
+
corre DESPUÉS de `beforeSend`, no antes**. Un `beforeSend` que agranda el evento (por ejemplo,
|
|
55
|
+
concatenando datos extra en `attributes` o en `message`) **también pasa por el recorte**: esa no es
|
|
56
|
+
una causa posible del `413`.
|
|
57
|
+
|
|
58
|
+
La única causa viva es esta:
|
|
59
|
+
|
|
60
|
+
**El exceso de tamaño no está en ninguno de los tres campos que el SDK sabe recortar.** El recorte
|
|
61
|
+
por tamaño achica, en este orden, el `stacktrace` (a 1 KB), después lo borra del todo, después vacía
|
|
62
|
+
`attributes`, y por último recorta el `message` a 256 caracteres — y se detiene ahí, sin llegar nunca
|
|
63
|
+
a descartar el evento. Si lo que hace enorme al sobre es **otro** campo — un `fingerprint` con
|
|
64
|
+
muchas entradas larguísimas, o un `work_unit`/`trace_id`/`conversation_id` gigantesco puesto a mano
|
|
65
|
+
por `CaptureOptions` — el recorte **no lo toca**, el sobre sale del mismo tamaño, y la ingesta lo
|
|
66
|
+
rechaza con `413`. Es un límite conocido del recorte actual: revisá el tamaño de lo que pasás en
|
|
67
|
+
`fingerprint` y en los identificadores de `context` si ves un `413`.
|
|
68
|
+
|
|
69
|
+
## "El worker no deploya"
|
|
70
|
+
|
|
71
|
+
*"Disallowed operation called within global scope."* El SDK está diseñado para no generar ids ni
|
|
72
|
+
hacer ningún I/O al importarse, así que el culpable de este error casi siempre es código del propio
|
|
73
|
+
worker: **`createTelemetry` no puede llamarse a nivel de módulo.** Tiene que ir dentro de `init()`
|
|
74
|
+
(en un Durable Object) o dentro del handler correspondiente (en un worker plano). Y ojo:
|
|
75
|
+
**`wrangler dev` local no detecta este error** — solo aparece recién al hacer el deploy real.
|
|
76
|
+
|
|
77
|
+
## "El `ctx` tiene `waitUntil` pero no es invocable"
|
|
78
|
+
|
|
79
|
+
El texto completo del aviso, que vas a ver en `wrangler tail`:
|
|
80
|
+
|
|
81
|
+
```
|
|
82
|
+
[delta-sdk] El `ctx` recibido tiene `waitUntil` pero no es invocable: parece una copia
|
|
83
|
+
hecha con spread u Object.create (patrón habitual para inyectar `props` en un McpAgent).
|
|
84
|
+
Los eventos se van a PERDER en surface 'worker' y 'queue'. Pasale a createTelemetry el
|
|
85
|
+
ExecutionContext original del handler, no la copia — podés seguir usando la copia para
|
|
86
|
+
el McpAgent, son dos consumidores distintos.
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
**Causa:** un patrón común del ecosistema `agents`/`McpAgent` copia el `ExecutionContext` con
|
|
90
|
+
`Object.assign(Object.create(ctx), ctx, { props })` o con `{ ...ctx, props }`, para poder inyectarle
|
|
91
|
+
`props` (que en el objeto real es `readonly`). El problema es que `Object.assign` y el spread solo
|
|
92
|
+
copian propiedades **propias enumerables**; en un objeto nativo del runtime, `waitUntil` vive en el
|
|
93
|
+
prototipo. La copia **hereda el método pero no la identidad del objeto nativo**, así que al
|
|
94
|
+
invocarlo el motor lo rechaza (es el equivalente de un `TypeError: Illegal invocation`).
|
|
95
|
+
|
|
96
|
+
**El arreglo:** el `ExecutionContext` original está en scope en el mismo punto donde se hace la
|
|
97
|
+
copia — no hace falta elegir entre uno y el otro. **El framework de MCP se queda con la copia** (la
|
|
98
|
+
necesita para `props`) **y el SDK recibe el original**: son dos consumidores distintos del `ctx`, y
|
|
99
|
+
no compiten por él.
|
|
100
|
+
|
|
101
|
+
---
|
|
102
|
+
|
|
103
|
+
## Dos límites honestos
|
|
104
|
+
|
|
105
|
+
**El scrubbing es una red, no una garantía.** Redacta por *substring* sobre nombres de clave y sobre
|
|
106
|
+
texto libre; un secreto guardado en un campo llamado, por ejemplo, `config` (que no contiene ningún
|
|
107
|
+
término de la denylist) **no se detecta**. La defensa real sigue siendo no meter secretos en el
|
|
108
|
+
mensaje de error — el scrubbing ataja descuidos, no los reemplaza. Y puede tener **falsos
|
|
109
|
+
positivos**: un mensaje como `"el token expiró"` puede quedar parcialmente redactado aunque no
|
|
110
|
+
llevara ningún secreto. Se calibra con datos reales de producción, no en el vacío; ver
|
|
111
|
+
`docs/telemetria.md` para el detalle completo de las reglas.
|
|
112
|
+
|
|
113
|
+
**`context.work_unit` no se scrubbea.** Es el nombre de una tool o de un paso de un workflow —no un
|
|
114
|
+
dato de usuario—, así que no metas ahí nada sensible: una tool llamada, por ejemplo, `refreshToken`
|
|
115
|
+
aparece tal cual en el evento.
|