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.
- package/CHANGELOG.md +76 -5
- package/README.md +157 -39
- package/dist/frameworks/instructor.cjs +338 -117
- package/dist/frameworks/instructor.cjs.map +1 -1
- package/dist/frameworks/instructor.js +338 -117
- package/dist/frameworks/instructor.js.map +1 -1
- package/dist/frameworks/langchain.cjs +351 -130
- package/dist/frameworks/langchain.cjs.map +1 -1
- package/dist/frameworks/langchain.js +351 -130
- package/dist/frameworks/langchain.js.map +1 -1
- package/dist/frameworks/langgraph.cjs +351 -130
- package/dist/frameworks/langgraph.cjs.map +1 -1
- package/dist/frameworks/langgraph.js +351 -130
- package/dist/frameworks/langgraph.js.map +1 -1
- package/dist/frameworks/llamaindex.cjs +351 -130
- package/dist/frameworks/llamaindex.cjs.map +1 -1
- package/dist/frameworks/llamaindex.js +351 -130
- package/dist/frameworks/llamaindex.js.map +1 -1
- package/dist/index.cjs +808 -226
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +137 -21
- package/dist/index.d.ts +137 -21
- package/dist/index.js +804 -226
- package/dist/index.js.map +1 -1
- package/dist/providers/anthropic/index.cjs +351 -130
- package/dist/providers/anthropic/index.cjs.map +1 -1
- package/dist/providers/anthropic/index.js +351 -130
- package/dist/providers/anthropic/index.js.map +1 -1
- package/dist/providers/bedrock/index.cjs +346 -125
- package/dist/providers/bedrock/index.cjs.map +1 -1
- package/dist/providers/bedrock/index.js +346 -125
- package/dist/providers/bedrock/index.js.map +1 -1
- package/dist/providers/cerebras/index.cjs +351 -130
- package/dist/providers/cerebras/index.cjs.map +1 -1
- package/dist/providers/cerebras/index.js +351 -130
- package/dist/providers/cerebras/index.js.map +1 -1
- package/dist/providers/cohere/index.cjs +351 -130
- package/dist/providers/cohere/index.cjs.map +1 -1
- package/dist/providers/cohere/index.js +351 -130
- package/dist/providers/cohere/index.js.map +1 -1
- package/dist/providers/google/index.cjs +351 -130
- package/dist/providers/google/index.cjs.map +1 -1
- package/dist/providers/google/index.js +351 -130
- package/dist/providers/google/index.js.map +1 -1
- package/dist/providers/groq/index.cjs +351 -130
- package/dist/providers/groq/index.cjs.map +1 -1
- package/dist/providers/groq/index.js +351 -130
- package/dist/providers/groq/index.js.map +1 -1
- package/dist/providers/huggingface/index.cjs +351 -130
- package/dist/providers/huggingface/index.cjs.map +1 -1
- package/dist/providers/huggingface/index.js +351 -130
- package/dist/providers/huggingface/index.js.map +1 -1
- package/dist/providers/mistral/index.cjs +351 -130
- package/dist/providers/mistral/index.cjs.map +1 -1
- package/dist/providers/mistral/index.js +351 -130
- package/dist/providers/mistral/index.js.map +1 -1
- package/dist/providers/ollama/index.cjs +351 -130
- package/dist/providers/ollama/index.cjs.map +1 -1
- package/dist/providers/ollama/index.js +351 -130
- package/dist/providers/ollama/index.js.map +1 -1
- package/dist/providers/openai/index.cjs +351 -130
- package/dist/providers/openai/index.cjs.map +1 -1
- package/dist/providers/openai/index.js +351 -130
- package/dist/providers/openai/index.js.map +1 -1
- package/dist/providers/together/index.cjs +351 -130
- package/dist/providers/together/index.cjs.map +1 -1
- package/dist/providers/together/index.js +351 -130
- package/dist/providers/together/index.js.map +1 -1
- package/dist/providers/vercel-ai/index.cjs +351 -130
- package/dist/providers/vercel-ai/index.cjs.map +1 -1
- package/dist/providers/vercel-ai/index.js +351 -130
- package/dist/providers/vercel-ai/index.js.map +1 -1
- 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
|
|
171
|
-
the SDK replaces it with the marker. The SDK reads an object through its JSON form, so
|
|
172
|
-
object does not change. Before this change, the SDK sent the value of
|
|
173
|
-
whole, and only the gateway replaced the content keys in it. The gateway
|
|
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
|
-
- **
|
|
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(
|
|
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(
|
|
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
|
|
379
|
-
|
|
380
|
-
|
|
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`, `
|
|
384
|
-
`
|
|
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
|
|
395
|
-
|
|
396
|
-
|
|
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
|
-
##
|
|
527
|
-
|
|
528
|
-
The SDK
|
|
529
|
-
|
|
530
|
-
|
|
531
|
-
|
|
532
|
-
|
|
533
|
-
|
|
534
|
-
|
|
535
|
-
|
|
536
|
-
|
|
537
|
-
|
|
538
|
-
|
|
539
|
-
|
|
540
|
-
|
|
541
|
-
|
|
542
|
-
|
|
543
|
-
|
|
544
|
-
|
|
545
|
-
|
|
546
|
-
|
|
547
|
-
|
|
548
|
-
|
|
549
|
-
|
|
550
|
-
|
|
551
|
-
|
|
552
|
-
|
|
553
|
-
|
|
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
|