risicare 0.10.0 → 0.11.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.
Files changed (73) hide show
  1. package/CHANGELOG.md +76 -5
  2. package/README.md +157 -39
  3. package/dist/frameworks/instructor.cjs +338 -117
  4. package/dist/frameworks/instructor.cjs.map +1 -1
  5. package/dist/frameworks/instructor.js +338 -117
  6. package/dist/frameworks/instructor.js.map +1 -1
  7. package/dist/frameworks/langchain.cjs +351 -130
  8. package/dist/frameworks/langchain.cjs.map +1 -1
  9. package/dist/frameworks/langchain.js +351 -130
  10. package/dist/frameworks/langchain.js.map +1 -1
  11. package/dist/frameworks/langgraph.cjs +351 -130
  12. package/dist/frameworks/langgraph.cjs.map +1 -1
  13. package/dist/frameworks/langgraph.js +351 -130
  14. package/dist/frameworks/langgraph.js.map +1 -1
  15. package/dist/frameworks/llamaindex.cjs +351 -130
  16. package/dist/frameworks/llamaindex.cjs.map +1 -1
  17. package/dist/frameworks/llamaindex.js +351 -130
  18. package/dist/frameworks/llamaindex.js.map +1 -1
  19. package/dist/index.cjs +808 -226
  20. package/dist/index.cjs.map +1 -1
  21. package/dist/index.d.cts +137 -21
  22. package/dist/index.d.ts +137 -21
  23. package/dist/index.js +804 -226
  24. package/dist/index.js.map +1 -1
  25. package/dist/providers/anthropic/index.cjs +351 -130
  26. package/dist/providers/anthropic/index.cjs.map +1 -1
  27. package/dist/providers/anthropic/index.js +351 -130
  28. package/dist/providers/anthropic/index.js.map +1 -1
  29. package/dist/providers/bedrock/index.cjs +346 -125
  30. package/dist/providers/bedrock/index.cjs.map +1 -1
  31. package/dist/providers/bedrock/index.js +346 -125
  32. package/dist/providers/bedrock/index.js.map +1 -1
  33. package/dist/providers/cerebras/index.cjs +351 -130
  34. package/dist/providers/cerebras/index.cjs.map +1 -1
  35. package/dist/providers/cerebras/index.js +351 -130
  36. package/dist/providers/cerebras/index.js.map +1 -1
  37. package/dist/providers/cohere/index.cjs +351 -130
  38. package/dist/providers/cohere/index.cjs.map +1 -1
  39. package/dist/providers/cohere/index.js +351 -130
  40. package/dist/providers/cohere/index.js.map +1 -1
  41. package/dist/providers/google/index.cjs +351 -130
  42. package/dist/providers/google/index.cjs.map +1 -1
  43. package/dist/providers/google/index.js +351 -130
  44. package/dist/providers/google/index.js.map +1 -1
  45. package/dist/providers/groq/index.cjs +351 -130
  46. package/dist/providers/groq/index.cjs.map +1 -1
  47. package/dist/providers/groq/index.js +351 -130
  48. package/dist/providers/groq/index.js.map +1 -1
  49. package/dist/providers/huggingface/index.cjs +351 -130
  50. package/dist/providers/huggingface/index.cjs.map +1 -1
  51. package/dist/providers/huggingface/index.js +351 -130
  52. package/dist/providers/huggingface/index.js.map +1 -1
  53. package/dist/providers/mistral/index.cjs +351 -130
  54. package/dist/providers/mistral/index.cjs.map +1 -1
  55. package/dist/providers/mistral/index.js +351 -130
  56. package/dist/providers/mistral/index.js.map +1 -1
  57. package/dist/providers/ollama/index.cjs +351 -130
  58. package/dist/providers/ollama/index.cjs.map +1 -1
  59. package/dist/providers/ollama/index.js +351 -130
  60. package/dist/providers/ollama/index.js.map +1 -1
  61. package/dist/providers/openai/index.cjs +351 -130
  62. package/dist/providers/openai/index.cjs.map +1 -1
  63. package/dist/providers/openai/index.js +351 -130
  64. package/dist/providers/openai/index.js.map +1 -1
  65. package/dist/providers/together/index.cjs +351 -130
  66. package/dist/providers/together/index.cjs.map +1 -1
  67. package/dist/providers/together/index.js +351 -130
  68. package/dist/providers/together/index.js.map +1 -1
  69. package/dist/providers/vercel-ai/index.cjs +351 -130
  70. package/dist/providers/vercel-ai/index.cjs.map +1 -1
  71. package/dist/providers/vercel-ai/index.js +351 -130
  72. package/dist/providers/vercel-ai/index.js.map +1 -1
  73. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -6,6 +6,77 @@ Pre-1.0 (0.x): the MINOR number is the breaking signal. A change that can
6
6
  break an existing caller ships as a MINOR bump. Other fixes and additions ship
7
7
  as PATCH bumps.
8
8
 
9
+ ## [0.11.0] — 2026-10-26
10
+
11
+ ### ⚠ Behaviour change — delivery during a gateway outage (W2-1c)
12
+
13
+ **What changes for you.** The HTTP exporter now keeps a batch through a gateway outage for up to
14
+ `retryHorizonS` (default 300 s), where 0.10.0 gave up after 3 attempts in each of 4 rounds (a few
15
+ seconds). The Python SDK has the same policy, with the same numbers. See "Delivery during a
16
+ gateway outage" in the README for the one table.
17
+
18
+ - Retried: HTTP 408, 429, 500, 502, 503, 504, a connection error and a timeout. The wait is
19
+ full-jitter exponential backoff, base 1 s, cap 30 s. A `Retry-After` header (seconds or, new,
20
+ an HTTP date) replaces the wait when it is more than 0 s; its old 10 s cap is gone (the cap is
21
+ the horizon).
22
+ - Sent once: every other status (400, 401, 403, 404, 422 and the rest), a redirect, a 2xx that is
23
+ not a Risicare ack, an ack of 0 and 0. The batch processor no longer puts such a batch back in
24
+ the queue 3 times: the batch is dropped as `transport_refused` after its one request.
25
+ - 413: the batch is split in two, one time. A half that gets 413 again is dropped with the new
26
+ reason `too_large` (one WARNING, one time).
27
+ - A batch that is not delivered within the horizon is dropped with the new reason
28
+ `retry_exhausted`. **A gateway outage that is longer than the horizon loses spans.**
29
+ - A full queue now drops the OLDEST queued span (`queue_full`) and keeps the new one. Through
30
+ 0.10.0 it dropped the new span.
31
+ - The circuit breaker counts a call that ends refused, or that used up its retries, except when
32
+ the last answer was 429 or 503. With the default horizon it opens only after five batches in a
33
+ row were retried for 300 s each.
34
+ - `shutdown()` has a new default budget of 10 s (`shutdownTimeoutS`; it was 5 s), also at
35
+ `beforeExit`, SIGTERM and SIGINT. A batch that waits for a retry gets one more attempt at once,
36
+ and a failed attempt is not retried, so a dead gateway costs one attempt for each batch, not the
37
+ budget. `docker stop` waits 10 s by default: set `shutdownTimeoutS` lower when your application
38
+ needs time for its own cleanup.
39
+ - `getMetrics()` has `attempts` and `oldestPendingAgeS`, and `droppedSpansByReason` has
40
+ `retry_exhausted` and `too_large`.
41
+ - New `init()` options: `retryHorizonS` and `shutdownTimeoutS`. `HttpExporter` has
42
+ `retryHorizonS`. Its `maxRetries` is now an optional limit on the attempts for one request
43
+ body (default: none; it was 3), and `attemptsPerExport` is `undefined` without it.
44
+ - The half-open probe of the circuit breaker follows the policy (through 0.10.0 it was one
45
+ attempt with no retry), as in Python.
46
+ - A retry wait does not keep the process alive: `beforeExit` starts `shutdown()`, which ends it.
47
+ - A `flush()` that is running when a `shutdown()` starts now waits for that shutdown, as a
48
+ `flush()` that comes during a `shutdown()` already did.
49
+ - The default of `flush()` stays 5000 ms (`FLUSH_BUDGET_MS`); `SHUTDOWN_BUDGET_MS` is now 10000.
50
+
51
+ ### Changed — score v2: typed values, kinds and session scores (W2-5)
52
+
53
+ - `score({ name, value, traceId, spanId, sessionId, comment, kind })`; `kind` defaults to
54
+ `annotation`. `value` is a finite number (any range), a string of 1 to 256 characters
55
+ (categorical) or a boolean. `kind` is `annotation`, `eval`, `feedback` or `outcome`. A score can
56
+ be on a session (`sessionId`) with no trace. README: "Scores, feedback and outcomes".
57
+ - The request body is the v2 body of `POST /v1/scores` (risicare-api PR #82): `value` and `kind`,
58
+ and no `score` field. **Release order:** release this SDK only after an api with score v2 is
59
+ live. An api without it refuses the v2 body (HTTP 422), and then every score fails.
60
+ - The positional form `score(traceId, name, value, { spanId, comment })` still sends the score.
61
+ The first such call in the process writes one WARNING.
62
+ - What changes for an existing call: a number outside 0.0 to 1.0 is sent (through 0.10.0 it was
63
+ refused at the call); `true` and `false` are sent as booleans (through 0.10.0 as 1 and 0);
64
+ a name longer than 128 characters is refused at the call with a WARNING and counted in
65
+ `failedScores` (the api refuses it too). A number that is not finite stays refused.
66
+
67
+ ### Added — the user, session, release and tags of a trace (W2-2)
68
+
69
+ - `setUser(id)`, `setSession(id)`, `setRelease(version)` and `addTags([...])` write
70
+ `user.id`, `session.id`, `risicare.release` and `tag.tags` (an array) on the current span, and on
71
+ each other span of the same trace that ends after the call (also the open root span), unless
72
+ that span has the attribute already. A span of another trace never gets them. Outside a span a
73
+ helper sets nothing, returns `false` and writes one WARNING. The values of the last 10,000 traces
74
+ are kept.
75
+ - README: "Identity: user, session, release and tags", and the table "What each dashboard column
76
+ reads" for User, Session, Release, Environment, Tags and Agent. `init({ serviceVersion })` (or
77
+ `RISICARE_SERVICE_VERSION`) is the no-code route for the release: it puts `service.version` on
78
+ every span.
79
+
9
80
  ## [0.10.0] — 2026-10-23
10
81
 
11
82
  ### ⚠ Behaviour change — prompt and completion content is captured by default (R9)
@@ -167,11 +238,11 @@ key, and it reads its value as a JSON object or as the JSON text of a JSON objec
167
238
 
168
239
  The rule also applies to the attributes of an event or a link, and to a nested value at the path
169
240
  `llm` > `invocation_parameters`. When `llm` holds JSON text, the SDK reads the text; when the text
170
- starts as JSON and is not valid JSON (for example, text that was cut at the attribute length limit),
171
- the SDK replaces it with the marker. The SDK reads an object through its JSON form, so your own
172
- object does not change. Before this change, the SDK sent the value of `llm.invocation_parameters`
173
- whole, and only the gateway replaced the content keys in it. The gateway applies the same rule to
174
- the request parameters; it does not read JSON text at `llm`.
241
+ starts as JSON and is not valid JSON (for example, text that was cut short or a number such as
242
+ `1e400`), the SDK replaces it with the marker. The SDK reads an object through its JSON form, so
243
+ your own object does not change. Before this change, the SDK sent the value of
244
+ `llm.invocation_parameters` whole, and only the gateway replaced the content keys in it. The gateway
245
+ applies the same rule to the request parameters; it does not read JSON text at `llm`.
175
246
 
176
247
  **This is a MINOR change.** With capture off, more attribute values now reach Risicare and your own
177
248
  exporters as `<risicare:content-omitted>`. A reader that used those values must change.
package/README.md CHANGED
@@ -178,7 +178,7 @@ init({ apiKey: 'rsk-...', mask: (key, value) => value });
178
178
  - **12 LLM providers** — OpenAI, Anthropic, Google, Mistral, Groq, Cohere, Together, Ollama, HuggingFace, Cerebras, Bedrock, Vercel AI
179
179
  - **4 framework integrations** — LangChain, LangGraph, Instructor, LlamaIndex
180
180
  - **Error Diagnosis (beta)** — LLM-powered root cause analysis with fix suggestions; auto-apply not yet wired (see "Error Diagnosis" section below)
181
- - **Evaluation scores** — Rate agent quality with `score()`
181
+ - **Scores, feedback and outcomes** — Record a judgment, an evaluator verdict, user feedback or a business result with `score()`
182
182
  - **Streaming** — `tracedStream()` traces an async iterator (see "Streaming" below)
183
183
  - **Context propagation** — Automatic across `async/await`, `Promise` and `setTimeout`. An `EventEmitter` listener runs in the context of the `emit()` call
184
184
  - **Zero runtime dependencies** — No bloat in your node_modules
@@ -314,12 +314,110 @@ await traceThink('analyze', fn)()
314
314
  await traceDecide('choose', fn)()
315
315
  await traceAct('execute', fn)()
316
316
  reportError(error) // Report caught errors for diagnosis
317
- score(traceId, 'quality', 0.92) // Record evaluation score [0.0-1.0]
317
+ score({ name: 'quality', value: 0.92, traceId }) // A number, a string or a boolean (see "Scores, feedback and outcomes")
318
318
  tracedStream(asyncIterable, 'stream') // Trace async iterators
319
319
  await flush(5000) // Wait for delivery; false when a span or a score was lost
320
- await shutdown(5000) // Deliver what it can in the time, then stop
320
+ await shutdown() // Deliver what it can in shutdownTimeoutS (10 s), then stop
321
321
  ```
322
322
 
323
+ ## Identity: user, session, release and tags
324
+
325
+ ```typescript
326
+ import { init, getTracer, setUser, setSession, setRelease, addTags } from 'risicare';
327
+
328
+ init({ apiKey: 'rsk-...', serviceVersion: '2026.10.24' }); // service.version on every span
329
+
330
+ await getTracer()!.startSpan({ name: 'handle-request' }, async () => {
331
+ setUser('user-42');
332
+ setSession('conv-7');
333
+ setRelease('2026.10.24-rc1');
334
+ addTags(['beta', 'eu']);
335
+ await getTracer()!.startSpan({ name: 'step' }, async () => {}); // gets all four when it ends
336
+ });
337
+ ```
338
+
339
+ Each helper writes one span attribute that the Risicare backend reads into a dashboard column:
340
+
341
+ - `setUser(id)` writes `user.id`.
342
+ - `setSession(id)` writes `session.id`.
343
+ - `setRelease(version)` writes `risicare.release`.
344
+ - `addTags([...])` writes `tag.tags`, an array. A later call adds to the earlier tags, in order,
345
+ with no repeats.
346
+
347
+ The current span gets the attribute at once. Each other span of the same trace that ends after the
348
+ call gets it when it ends, unless that span has the attribute already: the spans that are open (for
349
+ example the root span) and the spans that start later, in any async context. A span of another
350
+ trace never gets it, so a value cannot pass from one request to the next. A helper returns `true`
351
+ when it set the value. Outside a span there is no trace: it sets nothing, returns `false`, and the
352
+ first such call writes one WARNING. For a value that must apply before the first span, use
353
+ `withSession({ sessionId, userId }, fn)`. With no code at the call site, `init({ serviceVersion })`
354
+ or `RISICARE_SERVICE_VERSION` puts `service.version` on every span, and the Release column uses it
355
+ when no span of the trace has `risicare.release`. The values of the last 10,000 traces are kept.
356
+
357
+ ## What each dashboard column reads
358
+
359
+ The backend takes the first value that is set, in this order, from the attributes of each span.
360
+
361
+ | Column | Read from (first that is set) | Set it with the SDK |
362
+ |--------|-------------------------------|---------------------|
363
+ | User | `session.user_id`, `user_id`, `user.id`, `enduser.id`, `llm.user`, `ai.telemetry.metadata.userId` (at most 256 characters) | `setUser(id)` (`user.id`); `withSession({ userId })` writes `session.user_id`, which comes first |
364
+ | Session | the span's session field, then `session.id`, `gen_ai.conversation.id`, `gcp.vertex.agent.session_id`, `ai.telemetry.metadata.sessionId` | `withSession({ sessionId })` (the session field, first); `setSession(id)` (`session.id`) |
365
+ | Release | `risicare.release`; then `service.version` (the OpenTelemetry resource attribute, then the span attribute); then the deployment id; then the first 12 characters of the git commit | `setRelease(version)` (`risicare.release`); `init({ serviceVersion })` or `RISICARE_SERVICE_VERSION` (`service.version`, no other code) |
366
+ | Environment | `deployment.environment.name`, `deployment.environment` (resource attribute, then span attribute); else the environment of the request | `init({ environment })` or `RISICARE_ENVIRONMENT` (default `development`) |
367
+ | Tags | `tag.tags`, `framework.langchain.tags`, `framework.llamaindex.tags`, `langsmith.span.tags`, `ai.telemetry.metadata.tags`, all merged: at most 50 tags, each at most 200 characters; an array, a JSON array text or a comma-separated text | `addTags([...])` (`tag.tags`) |
368
+ | Agent | the span's agent fields (id and name), then `agent.name` and `gen_ai.agent.name` for the name | `agent({ name }, fn)` or `withAgent(...)` |
369
+
370
+ An application that uses another OpenTelemetry SDK sets the same attributes on its spans, and
371
+ `service.version` as a resource attribute, with no Risicare code.
372
+
373
+ ## Scores, feedback and outcomes
374
+
375
+ ```typescript
376
+ import { init, getTracer, getCurrentTraceId, score } from 'risicare';
377
+
378
+ init({ apiKey: 'rsk-...' });
379
+
380
+ let traceId = '';
381
+ await getTracer()!.startSpan({ name: 'answer-question' }, async () => {
382
+ traceId = getCurrentTraceId()!;
383
+ });
384
+
385
+ // A person's judgment of the answer
386
+ score({ name: 'quality', value: 0.92, traceId, kind: 'annotation' });
387
+ // The verdict of an evaluator (a model or a rule)
388
+ score({ name: 'groundedness', value: 'partly_grounded', traceId, kind: 'eval' });
389
+ // The end user's reaction
390
+ score({ name: 'thumbs_up', value: false, traceId, kind: 'feedback', comment: 'The answer missed the refund policy' });
391
+ // A result that your own system knows
392
+ score({ name: 'ticket_resolved', value: true, sessionId: 'conv-7', kind: 'outcome' });
393
+ ```
394
+
395
+ A score is a named value on a trace, a span or a session. `kind` says what the judgment is:
396
+
397
+ | `kind` | Use it for | Example |
398
+ |--------|-----------|---------|
399
+ | `annotation` (the default) | the judgment of a person who reviewed the trace | a reviewer rates an answer 4 of 5 |
400
+ | `eval` | the verdict of an evaluator: a model (LLM as a judge) or a rule | a groundedness check returns `'partly_grounded'` |
401
+ | `feedback` | the reaction of your end user | a thumbs-down, a star rating, a comment |
402
+ | `outcome` | a result that your own system knows: resolved, refunded, goal met | the support ticket of the session was resolved |
403
+
404
+ **An `outcome` is a result that your own system knows, and no model infers it.** Send it from the
405
+ code that knows the result (the ticket system, the payment, the order), when it knows it; it can
406
+ come minutes or days after the trace.
407
+
408
+ The type of `value` decides how the score is stored: a finite number (any range, for example a
409
+ rating from 1 to 5) is numeric, a string of 1 to 256 characters is categorical, `true` or `false`
410
+ is boolean. `name` is 1 to 128 characters. Give `traceId` (32 lowercase hex characters, for
411
+ example from `getCurrentTraceId()`), `sessionId` (1 to 255 characters), or both; `spanId` needs
412
+ `traceId`. `comment` is at most 4,096 characters, and a `mask` of `init()` sees it under the key
413
+ `score.comment`. A score that does not meet these rules is refused at the call with a WARNING and
414
+ counted in `failedScores`.
415
+
416
+ The positional form of 0.10.0 and earlier, `score(traceId, name, value, { spanId, comment })`,
417
+ still sends the score, and the first such call in the process writes one WARNING. `score()` sends
418
+ the score to the api host (see "Two hosts"). For what happens when a score fails, see "Delivery:
419
+ flush, shutdown and metrics".
420
+
323
421
  ## Delivery: flush, shutdown and metrics
324
422
 
325
423
  - `await flush(timeoutMs?)` waits for the queued spans and the pending scores
@@ -375,13 +473,21 @@ await shutdown(5000) // Deliver what it can in the time, th
375
473
  rules above. A loss that was not reported is not carried over. Report the old
376
474
  client's loss with `flush()` or `getMetrics()` before you call `init()` again.
377
475
  - `await shutdown(timeoutMs?)` is the call that ends a process in a fixed time
378
- (default 5000 ms). At the deadline it stops the export in flight. It counts
379
- the spans that it did not deliver as `shutdown_residue`, with one WARNING.
380
- - A timeout that is not a finite number means 5000 ms.
476
+ (default: the `shutdownTimeoutS` of `init()`, 10 s; it is also the budget of the
477
+ SDK's own drain at `beforeExit`, SIGTERM and SIGINT). A batch that waits for a retry
478
+ gets one more attempt at once, and a failed attempt is not retried. At the deadline
479
+ it stops the export in flight. It counts the spans that it did not deliver as
480
+ `shutdown_residue`, with one WARNING. `docker stop` waits 10 s by default: when your
481
+ application needs time for its own cleanup, set `shutdownTimeoutS` lower or raise
482
+ the grace period.
483
+ - A timeout that is not a finite number means the default: 5000 ms for `flush()`, the
484
+ `shutdownTimeoutS` budget for `shutdown()`.
381
485
  - `getMetrics()` gives `exportedSpans` (spans that the backend accepted),
382
486
  `rejectedSpans`, `droppedSpans`, `droppedSpansByReason` (`queue_full`,
383
- `transport_refused`, `shutdown_residue`, `unacknowledged`), `failedExports`,
384
- `failedScores`, the queue numbers and `sdkState`. `unacknowledged` counts
487
+ `transport_refused`, `retry_exhausted`, `too_large`, `shutdown_residue`,
488
+ `unacknowledged`, `quota_exceeded`), `failedExports`, `attempts`,
489
+ `oldestPendingAgeS`, `failedScores`, the queue numbers and `sdkState`. See
490
+ "Delivery during a gateway outage" for each drop reason. `unacknowledged` counts
385
491
  spans that were sent, or that could not be serialized, and that the
386
492
  backend's answer did not account for. `failedExports` counts the export
387
493
  calls that failed as a whole. A later round can still deliver those spans, so
@@ -391,9 +497,10 @@ await shutdown(5000) // Deliver what it can in the time, th
391
497
  status of 300 or more, an error or a timeout adds 1 to `failedScores`. The
392
498
  first failure writes one WARNING at once. Failures in the next 10 seconds
393
499
  are counted, and the next WARNING gives their number. A score that `score()`
394
- refuses at the call (a value that is not a number or is outside 0 to 1, an
395
- empty trace id or name) writes one WARNING, is not sent, and also adds 1 to
396
- `failedScores`. When the SDK is not active (before `init()`, after `shutdown()`
500
+ refuses at the call (a value that is not a finite number, a string of 1 to 256
501
+ characters or a boolean; an empty name or one longer than 128 characters; no
502
+ trace and no session; an unknown kind; the other rules of "Scores, feedback and
503
+ outcomes") writes one WARNING, is not sent, and also adds 1 to `failedScores`. When the SDK is not active (before `init()`, after `shutdown()`
397
504
  or the SDK's own drain, tracing off, no key), nothing is counted.
398
505
  At most 50 score requests run at one time. Up to 1,000 scores wait for a free
399
506
  slot, with no timer: the 2000 ms bound starts when the request starts. A score
@@ -523,34 +630,45 @@ up, it writes at most one WARNING an hour. A batch that the backend discards, an
523
630
  the full queue drops in the pause, are counted in `getMetrics().droppedQuota` (the same number as
524
631
  `droppedSpansByReason.quota_exceeded`). They are also in the flat dropped total, and not in `rejectedSpans`. They are not stored.
525
632
 
526
- ## Known limitation — span loss during a backend outage
527
-
528
- The SDK does **not** keep spans through a long outage of the Risicare backend.
529
- Nothing throws in your application. The SDK writes a WARNING, `flush()`
530
- returns `false`, and `getMetrics()` counts the lost spans in
531
- `droppedSpansByReason.transport_refused`.
532
-
533
- The HTTP exporter opens a circuit breaker after **5 consecutive failed export
534
- calls** and holds it open for **60 seconds**. While it is open, an export
535
- returns failure at once and does not use the network. A batch that fails is
536
- put back in the queue at most 3 times. Against an open breaker these 3
537
- attempts fail at once, so the spans are dropped. For the rest of the cooldown
538
- the SDK does not send, also when your backend is healthy again.
539
-
540
- The thresholds count **failed calls, not seconds**. When the 5th consecutive
541
- failure occurs depends on your span rate and on how fast your endpoint fails.
542
- A short failure that stays under 5 consecutive failed calls does not open the
543
- breaker. Tracked as `F-SDKBLIP-001`.
544
-
545
- One export call sends a batch at most 3 times. A 401 or 403 answer is sent
546
- once in each export call: the endpoint refused the API key, and the same key
547
- gets the same answer. At the first failed export of an outage (at most once in
548
- 5 minutes), the SDK writes the WARNING "spans are NOT reaching ...". It gives
549
- the HTTP status of the last answer, or the error code when there was no answer.
550
- For a 401 or 403 it tells you to check the API key. When the kind of failure
551
- changes in one outage (for example a 401, then no answer), the SDK writes one more
552
- WARNING. An endpoint URL with credentials (a user name or a password before the
553
- host) is not supported: `fetch` does not send a request to it.
633
+ ## Delivery during a gateway outage (retry policy)
634
+
635
+ The SDK's HTTP exporter keeps a batch and sends it again while the gateway is down, for a
636
+ fixed time. The Python SDK has the same policy, with the same numbers.
637
+
638
+ | Case | What the SDK does | Drop reason |
639
+ |------|-------------------|-------------|
640
+ | HTTP 408, 429, 500, 502, 503 or 504, a connection error, a timeout | It sends the batch again. The wait before retry *n* (0 for the first retry) is a random part of `min(30 s, 1 s × 2^n)` (full jitter). A `Retry-After` header (seconds or an HTTP date) replaces the wait when it is more than 0 s. | — |
641
+ | The batch is still not delivered at the retry horizon: `retryHorizonS`, default **300 s**, from its first attempt | It stops and drops the batch. No wait goes past the horizon. | `retry_exhausted` |
642
+ | HTTP 413 (the request is too large) | It splits the batch in two, one time, and sends both halves. A half that gets 413 again is dropped. One WARNING, one time. | `too_large` |
643
+ | HTTP 400, 401, 403, 404, 422 and every other status; a redirect; a 2xx that is not a Risicare ack; an ack of 0 and 0 | It sends the batch once. A retry cannot change the answer. | `transport_refused` |
644
+ | The queue is full (`maxQueueSize`, default 10,000 spans) | It drops the oldest queued span and keeps the new one. Memory stays bounded by the queue. Nothing is written to disk. | `queue_full` |
645
+ | 5 export calls in a row fail (a batch sent once and refused, or a batch that used up its retries; not when the last answer was 429 or 503) | The circuit breaker opens for 60 s. A batch is then dropped with no request. After 60 s, the next batch is the probe. | `transport_refused` |
646
+ | `shutdown()` | It sends for at most `shutdownTimeoutS` (default **10 s**). A retry wait ends at once, and a failed attempt is not retried. Spans that it cannot send are counted. | `shutdown_residue` |
647
+
648
+ **A gateway outage that is longer than the retry horizon loses spans.** The oldest batch is
649
+ dropped when it reaches the horizon, and a full queue drops its oldest spans. Nothing throws
650
+ in your application. The SDK writes a WARNING, `flush()` returns `false`, and
651
+ `getMetrics().droppedSpansByReason` counts each lost span under its reason. To wait longer,
652
+ raise `retryHorizonS` in `init()`; the queue still holds at most `maxQueueSize` spans.
653
+
654
+ While the SDK retries, `getMetrics().oldestPendingAgeS` grows: it is the age of the oldest span
655
+ that is queued or in an export. `attempts` counts the HTTP requests (each retry and each half of
656
+ a split included) of an export call when that call ends, so the requests of a batch that is
657
+ still retrying are added when it is delivered or dropped. `flush()` does not stop a retry: it
658
+ returns `false` at its deadline while the batch waits. The wait does not keep the process alive: when nothing else runs, Node's
659
+ `beforeExit` starts the SDK's `shutdown()`, which ends the wait. A retry can send a span a
660
+ second time when the gateway stored it but its answer did not arrive.
661
+
662
+ A 401 or 403 answer is sent once in each export call: the endpoint refused the API key, and
663
+ the same key gets the same answer. The WARNING "spans are NOT reaching ..." comes at the first
664
+ failure of an outage (at most once in 5 minutes): for a retryable answer after the third
665
+ failed attempt of a batch, or when its retries end before that. It gives the HTTP status of
666
+ the last answer, or the error code when there was no answer. For a 401 or 403 it tells you to
667
+ check the API key. When the kind of failure changes in one outage (for example a 401, then no
668
+ answer), the SDK writes one more WARNING. A batch that is dropped as `retry_exhausted` gets one
669
+ more WARNING (at most once in 5 minutes) that names the attempts and the last answer. An
670
+ endpoint URL with credentials (a user name or a password before the host) is not supported:
671
+ `fetch` does not send a request to it, and the SDK does not retry it.
554
672
 
555
673
  The SDK removes its API key from each text that it logs: in any case of letters,
556
674
  and also when the key is percent-encoded. An endpoint is logged without its user