risicare 0.9.2 → 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 +254 -0
  2. package/README.md +194 -58
  3. package/dist/frameworks/instructor.cjs +383 -117
  4. package/dist/frameworks/instructor.cjs.map +1 -1
  5. package/dist/frameworks/instructor.js +383 -117
  6. package/dist/frameworks/instructor.js.map +1 -1
  7. package/dist/frameworks/langchain.cjs +396 -130
  8. package/dist/frameworks/langchain.cjs.map +1 -1
  9. package/dist/frameworks/langchain.js +396 -130
  10. package/dist/frameworks/langchain.js.map +1 -1
  11. package/dist/frameworks/langgraph.cjs +396 -130
  12. package/dist/frameworks/langgraph.cjs.map +1 -1
  13. package/dist/frameworks/langgraph.js +396 -130
  14. package/dist/frameworks/langgraph.js.map +1 -1
  15. package/dist/frameworks/llamaindex.cjs +396 -130
  16. package/dist/frameworks/llamaindex.cjs.map +1 -1
  17. package/dist/frameworks/llamaindex.js +396 -130
  18. package/dist/frameworks/llamaindex.js.map +1 -1
  19. package/dist/index.cjs +1136 -240
  20. package/dist/index.cjs.map +1 -1
  21. package/dist/index.d.cts +151 -26
  22. package/dist/index.d.ts +151 -26
  23. package/dist/index.js +1132 -240
  24. package/dist/index.js.map +1 -1
  25. package/dist/providers/anthropic/index.cjs +467 -137
  26. package/dist/providers/anthropic/index.cjs.map +1 -1
  27. package/dist/providers/anthropic/index.js +467 -137
  28. package/dist/providers/anthropic/index.js.map +1 -1
  29. package/dist/providers/bedrock/index.cjs +409 -128
  30. package/dist/providers/bedrock/index.cjs.map +1 -1
  31. package/dist/providers/bedrock/index.js +409 -128
  32. package/dist/providers/bedrock/index.js.map +1 -1
  33. package/dist/providers/cerebras/index.cjs +414 -133
  34. package/dist/providers/cerebras/index.cjs.map +1 -1
  35. package/dist/providers/cerebras/index.js +414 -133
  36. package/dist/providers/cerebras/index.js.map +1 -1
  37. package/dist/providers/cohere/index.cjs +414 -133
  38. package/dist/providers/cohere/index.cjs.map +1 -1
  39. package/dist/providers/cohere/index.js +414 -133
  40. package/dist/providers/cohere/index.js.map +1 -1
  41. package/dist/providers/google/index.cjs +414 -133
  42. package/dist/providers/google/index.cjs.map +1 -1
  43. package/dist/providers/google/index.js +414 -133
  44. package/dist/providers/google/index.js.map +1 -1
  45. package/dist/providers/groq/index.cjs +414 -133
  46. package/dist/providers/groq/index.cjs.map +1 -1
  47. package/dist/providers/groq/index.js +414 -133
  48. package/dist/providers/groq/index.js.map +1 -1
  49. package/dist/providers/huggingface/index.cjs +414 -133
  50. package/dist/providers/huggingface/index.cjs.map +1 -1
  51. package/dist/providers/huggingface/index.js +414 -133
  52. package/dist/providers/huggingface/index.js.map +1 -1
  53. package/dist/providers/mistral/index.cjs +414 -133
  54. package/dist/providers/mistral/index.cjs.map +1 -1
  55. package/dist/providers/mistral/index.js +414 -133
  56. package/dist/providers/mistral/index.js.map +1 -1
  57. package/dist/providers/ollama/index.cjs +414 -133
  58. package/dist/providers/ollama/index.cjs.map +1 -1
  59. package/dist/providers/ollama/index.js +414 -133
  60. package/dist/providers/ollama/index.js.map +1 -1
  61. package/dist/providers/openai/index.cjs +452 -135
  62. package/dist/providers/openai/index.cjs.map +1 -1
  63. package/dist/providers/openai/index.js +452 -135
  64. package/dist/providers/openai/index.js.map +1 -1
  65. package/dist/providers/together/index.cjs +414 -133
  66. package/dist/providers/together/index.cjs.map +1 -1
  67. package/dist/providers/together/index.js +414 -133
  68. package/dist/providers/together/index.js.map +1 -1
  69. package/dist/providers/vercel-ai/index.cjs +398 -132
  70. package/dist/providers/vercel-ai/index.cjs.map +1 -1
  71. package/dist/providers/vercel-ai/index.js +398 -132
  72. package/dist/providers/vercel-ai/index.js.map +1 -1
  73. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -6,6 +6,260 @@ 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
+
80
+ ## [0.10.0] — 2026-10-23
81
+
82
+ ### ⚠ Behaviour change — prompt and completion content is captured by default (R9)
83
+
84
+ **What changes for you.** If you upgrade and change nothing, `init()` now sends the text of your
85
+ prompts and completions to Risicare, and Risicare stores it. From 0.5.2 to 0.9.2 this text stayed in
86
+ your process unless you set `traceContent: true` or `RISICARE_TRACE_CONTENT=true`. Now
87
+ `traceContent` defaults to `true`. This covers the provider patches and the content keys that you
88
+ set by hand (for example `span.setAttribute('gen_ai.prompt.0.content', ...)`). Only `patchOpenAI`
89
+ and `patchAnthropic` write prompt and completion text; the other providers write none, as before.
90
+ The model, the token counts, the latency, the cost, the roles, the errors and your own attributes
91
+ are sent in both cases, as before.
92
+
93
+ **To keep the old behaviour, turn capture off explicitly:**
94
+
95
+ ```ts
96
+ init({ apiKey: 'rsk-...', traceContent: false });
97
+ // or: RISICARE_TRACE_CONTENT=false
98
+ ```
99
+
100
+ The option wins over the environment variable, in both directions. When the variable is set, a value
101
+ other than `true`, `1` or `yes` turns capture off (`on` does not turn it on). When it is not set, the
102
+ default applies. With capture off, each content-keyed attribute is replaced with
103
+ `<risicare:content-omitted>`, as in 0.5.2 and later.
104
+
105
+ **The project switch.** You can also turn off content capture in the project settings. The gateway
106
+ then drops the content of that project, also when the SDK sends it. The SDK switch stays. Use it
107
+ when prompt and completion text must not leave your process: the project switch acts after the text
108
+ has left.
109
+
110
+ With `traceContent: false`, the SDK still sends the status message, the exception message, the stack
111
+ trace (which repeats the message), `error.message` and `exception.message`. Only the project switch
112
+ masks them, at the gateway. Error diagnosis needs them, and an error message can contain part of a
113
+ prompt.
114
+
115
+ **A second `init()`.** The first `init()` still wins. When a later `init()` gives a different
116
+ `traceContent`, the SDK now writes a console warning that names both values, so that an early `init()` (for example in a
117
+ library) cannot make your capture setting void in silence. Call `shutdown()` first to change it.
118
+
119
+ **Why this is a MINOR change.** In 0.x the MINOR number is the breaking signal (see the top of this
120
+ file), and a changed default is a breaking change. So the release that carries this entry is a MINOR
121
+ release, not a PATCH.
122
+
123
+ ### Added — cached and reasoning token counts (R31)
124
+
125
+ **What changes for you.** The LLM span now has the cached and reasoning token counts when the
126
+ provider response gives them. The SDK sends three new attributes with the OpenTelemetry GenAI names:
127
+
128
+ - `gen_ai.usage.cache_read.input_tokens`: the input tokens that the provider read from its prompt
129
+ cache.
130
+ - `gen_ai.usage.cache_write.input_tokens`: the input tokens that the provider wrote to its prompt
131
+ cache. OpenTelemetry renamed this key from `cache_creation` to `cache_write` on 2026-08-20. The
132
+ SDK uses the new name.
133
+ - `gen_ai.usage.reasoning.output_tokens`: the output tokens that the model used for reasoning.
134
+
135
+ The SDK reads these fields:
136
+
137
+ - `patchOpenAI`, `chat.completions.create`, with and without `stream: true`:
138
+ `usage.prompt_tokens_details.cached_tokens`, `usage.prompt_tokens_details.cache_write_tokens` and
139
+ `usage.completion_tokens_details.reasoning_tokens`. A stream gives them only in its usage chunk,
140
+ so set `stream_options: { include_usage: true }`.
141
+ - `patchAnthropic`, `messages.create`, with and without `stream: true`:
142
+ `usage.cache_read_input_tokens`, `usage.cache_creation_input_tokens` and
143
+ `usage.output_tokens_details.thinking_tokens`. A stream gives them in `message_start` and in
144
+ `message_delta`. The counts of `message_delta` are cumulative, so a count there replaces the count
145
+ of `message_start`.
146
+
147
+ The SDK sends a key only when the response gives an integer for its field. A real 0 is sent. When
148
+ the response does not give a count, or gives null, the key is absent. The SDK does not calculate or
149
+ estimate a count.
150
+
151
+ `gen_ai.usage.prompt_tokens`, `gen_ai.usage.completion_tokens`, `gen_ai.usage.total_tokens` and the
152
+ cost do not change. The OpenAI prompt count includes the cached tokens. The Anthropic
153
+ `input_tokens` does not include the cache tokens, and the SDK sends it unchanged. The three keys are
154
+ not content: `traceContent: false` keeps them. The other providers do not send these keys yet.
155
+
156
+ ### Changed — with content capture off, the content gate strips the content keys of more frameworks
157
+
158
+ **What changes for you.** This change applies only when `traceContent: false`. With
159
+ `traceContent: true`, the SDK sends the same values as before.
160
+
161
+ With `traceContent: false`, the SDK replaces the value of a content attribute with
162
+ `<risicare:content-omitted>` before the span leaves your process. The SDK now uses the same rule
163
+ as the ingest gateway (content-key spec v2, R41) and as the Python SDK. Before this change, the SDK
164
+ sent the keys below, and only the gateway removed them. The SDK now replaces these values:
165
+
166
+ - Vercel AI SDK: `ai.prompt`, `ai.prompt.messages`, `ai.prompt.tools`, `ai.response.text`,
167
+ `ai.response.object`, `ai.response.toolCalls`, `ai.response.reasoning`, `ai.response.files`,
168
+ `ai.toolCall.args`, `ai.toolCall.result`, `ai.value`, `ai.values` and the older `ai.result.text`,
169
+ `ai.result.object` and `ai.result.toolCalls`.
170
+ - Google ADK: `gcp.vertex.agent.llm_request`, `gcp.vertex.agent.llm_response`,
171
+ `gcp.vertex.agent.tool_call_args`, `gcp.vertex.agent.tool_response` and `gcp.vertex.agent.data`.
172
+ - Pydantic AI: `pydantic_ai.all_messages`, `final_result`, `model_request_parameters`,
173
+ `tool_arguments` and `tool_response`.
174
+ - OpenLLMetry CrewAI: each key that starts with `crewai.`, for example `crewai.task.description`
175
+ and `crewai.crew.tasks`. The SDK keeps a key whose last segment the KEEP rule names (a role, a
176
+ name, an id, a type, a model, a count, a length or a token count), for example
177
+ `crewai.agent.role` and `crewai.crew.task_count`.
178
+ - Mastra: `mastra.<span type>.input` and `mastra.<span type>.output`.
179
+ - OpenInference, OpenLLMetry and Semantic Kernel: `agent.goal`, `agent.backstory`, `llm.tools`,
180
+ `llm.available_functions`, `gen_ai.task.input`, `gen_ai.task.output` and
181
+ `sk.available_functions`.
182
+ - Lists of tool definitions: the `description`, `parameters` and `json_schema` of each tool in
183
+ `llm.tools.*`, `llm.request.functions.*` and `gen_ai.tool.definitions.*`, and `tool.parameters`.
184
+ The SDK keeps the `description` of one tool on a tool span (`tool.description`).
185
+ - The arguments of a LiteLLM function call (`gen_ai.completion.<i>.function_call.arguments`) and the
186
+ text of an OpenInference prompt (`llm.prompts.<i>.prompt.text`).
187
+
188
+ Span events: an event with the name `gen_ai.user.message`, `gen_ai.system.message`,
189
+ `gen_ai.assistant.message`, `gen_ai.tool.message` or `gen_ai.choice`, or a name that starts with
190
+ `gen_ai.content.`, holds one message. These are the OpenTelemetry v1.36 message events and the
191
+ OpenLLMetry content events. In such an event, the SDK now replaces the value of each attribute, also
192
+ `message`, `body`, `tool.result` and `tool_calls`. It keeps only these keys: `gen_ai.system`,
193
+ `gen_ai.provider.name`, the keys of the exact KEEP list (for example
194
+ `gen_ai.response.content_type`), and a key whose last segment the KEEP rule names (for example
195
+ `role`, `id`, `index` and `finish_reason`). The event name does not change. The attributes of other
196
+ events (also the `exception` event of `recordException`) and of links use the key rule, as before.
197
+
198
+ The `mask` callback does not change. With `traceContent: false`, the SDK still sends the status message, the exception message, the stack
199
+ trace (which repeats the message), `error.message` and `exception.message`. Only the project switch
200
+ masks them, at the gateway.
201
+ Each key of the SDK's own corpus (`tests/fixtures/content-keys-v2.json`) has the same
202
+ result as before. If a dashboard or a custom exporter reads one of the keys above while capture is
203
+ off, it now gets the marker.
204
+
205
+ **Your own objects are not changed.** The gate replaced values in place, so the object that you gave to
206
+ `addEvent()` and `addLink()` was changed too (later, on the export worker). The gate now strips a copy. The span
207
+ that is sent is stripped as before.
208
+
209
+ **Kept, as the gateway keeps them:** `crewai.agent.llm` (a model name) and `crewai.crew.process`
210
+ (sequential or hierarchical). Their last segments `llm` and `process` are KEEP segments.
211
+
212
+ **The request parameters (content-key corpus version 4).** With `traceContent: false`, the SDK now
213
+ applies the value rule of the joint content-key corpus version 4
214
+ (`tests/fixtures/content-keys-v4.json`, a byte-identical copy of the gateway's file). The rule
215
+ applies to `llm.invocation_parameters`, the OpenInference request parameters. The SDK keeps this
216
+ key, and it reads its value as a JSON object or as the JSON text of a JSON object:
217
+
218
+ - The SDK replaces the value of each of these keys with the marker, at every depth of the value:
219
+ `additional_instructions`, `chat_history`, `contents`, `documents`, `functions`, `input`,
220
+ `input_text`, `instructions`, `message`, `messages`, `preamble`, `prediction`, `prompt`, `system`,
221
+ `system_instruction`, `texts`, `tool_config` and `tools`. A key also matches when it has the same
222
+ letters after `A` to `Z` become lower case and each `_` is removed, so `systemInstruction`,
223
+ `SYSTEM` and `inputText` match. Other letters do not change. A dotted key matches when one of its
224
+ parts matches (`app.prompt`).
225
+ - The SDK applies the key rule to each other entry, with the key path
226
+ `llm.invocation_parameters.<path>`. For example, `extra_body.metadata.content` gets the marker,
227
+ and `temperature`, `max_tokens` and `response_format` stay.
228
+ - Text at any depth that starts with `{` or `[` (after spaces, tabs and line ends) is JSON text. The
229
+ SDK reads it with the same rule and, when a value in it gets the marker, writes it back as compact
230
+ JSON. When the text is not valid JSON (for example, text that was cut, a number such as `1e400`,
231
+ or a stop sequence such as `[/INST]`), the SDK replaces it with the marker.
232
+ - A flat key `llm.invocation_parameters.<path>` gets the same rule: the marker when a part of
233
+ `<path>` matches a listed key or the key rule marks the key; else the SDK reads its value as
234
+ above.
235
+ - The SDK writes the JSON text of the whole value back as compact JSON.
236
+ - When the value is not a JSON object (for example, text that is not JSON, an array or a number),
237
+ the SDK replaces the whole value with the marker.
238
+
239
+ The rule also applies to the attributes of an event or a link, and to a nested value at the path
240
+ `llm` > `invocation_parameters`. When `llm` holds JSON text, the SDK reads the text; when the text
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`.
246
+
247
+ **This is a MINOR change.** With capture off, more attribute values now reach Risicare and your own
248
+ exporters as `<risicare:content-omitted>`. A reader that used those values must change.
249
+
250
+ ### Fixed — content capture never fails a call because of a message that it cannot read
251
+
252
+ **What changes for you.** With `traceContent: true`, `patchOpenAI` and `patchAnthropic` read the
253
+ role and the text of your messages before they call the provider. When a property access of a
254
+ message threw (for example a class instance whose `role` getter throws), your call threw that error
255
+ and the request was not sent. Now the SDK does that reading in the same guard as its reading of the
256
+ response. Your call goes to the provider with the messages unchanged. The span gets
257
+ `risicare.observer_error` with the error class name. The message keys that the SDK read before the
258
+ error stay on the span (for example the role of a message whose block type failed); the rest of that
259
+ message and the messages after it are not recorded. The span status does not change. With
260
+ `traceContent: false`,
261
+ the SDK does not read the messages, as before.
262
+
9
263
  ## [0.9.2] — 2026-10-17
10
264
 
11
265
  ### Changed — the npm tarball now carries CHANGELOG.md (issue #95)
package/README.md CHANGED
@@ -43,8 +43,10 @@ await shutdown();
43
43
  ```
44
44
 
45
45
  The SDK sends one span for the agent function and one span for the LLM call,
46
- in the same trace. The LLM span has the model, the latency, the token counts
47
- and the cost. You see them in the [Risicare dashboard](https://app.risicare.ai).
46
+ in the same trace. The LLM span has the model, the latency, the token counts,
47
+ the cost and, by default, the prompt and completion text (see
48
+ [Prompt content is captured by default](#prompt-content-is-captured-by-default)).
49
+ You see them in the [Risicare dashboard](https://app.risicare.ai).
48
50
 
49
51
  ## Two hosts
50
52
 
@@ -99,21 +101,31 @@ import * as risicare from 'risicare';
99
101
  import type { Span, Tracer } from 'risicare';
100
102
  ```
101
103
 
102
- ## Prompt content is NOT captured by default
104
+ ## Prompt content is captured by default
103
105
 
104
- **`traceContent` defaults to `false`** (since 0.5.2, the first published version with this default). Your prompts and completions
105
- stay in your process. Everything else — model, token counts, latency, cost,
106
- errors, and any attributes you set — is captured as normal, so the
107
- dashboard, cost tracking and error diagnosis all work unchanged.
106
+ **`traceContent` defaults to `true`.** The SDK sends your prompts and
107
+ completions to Risicare, and Risicare stores them. Everything else — model,
108
+ token counts, latency, cost, errors, and any attributes you set — is captured
109
+ as normal, so the dashboard, cost tracking and error diagnosis all work.
108
110
 
109
- To send prompt and completion text as well, opt in:
111
+ To stop the capture of prompt and completion text, set it off in your code or
112
+ in the environment:
110
113
 
111
114
  ```typescript
112
- init({ apiKey: 'rsk-...', traceContent: true });
113
- // or set RISICARE_TRACE_CONTENT=true
115
+ init({ apiKey: 'rsk-...', traceContent: false });
116
+ // or set RISICARE_TRACE_CONTENT=false
114
117
  ```
115
118
 
116
- **Which providers capture text.** With `traceContent: true`:
119
+ The argument wins over the environment variable. You can also turn off content
120
+ capture in the project settings. The gateway then drops content for that
121
+ project, also when the SDK still sends it.
122
+
123
+ With `traceContent: false`, the SDK still sends the status message, the
124
+ exception message, the stack trace (which repeats the message), `error.message`
125
+ and `exception.message`. Only the project switch masks them, at the gateway.
126
+ Error diagnosis needs them, and an error message can contain part of a prompt.
127
+
128
+ **Which providers capture text.** With `traceContent` on (the default):
117
129
 
118
130
  - `patchOpenAI` and `patchAnthropic` capture the prompt and the completion text.
119
131
  They write the first 10 messages to `gen_ai.prompt.N.role` and
@@ -129,14 +141,20 @@ init({ apiKey: 'rsk-...', traceContent: true });
129
141
 
130
142
  **Error text is not covered by this switch.** The error message from a
131
143
  provider can contain your prompt text. For example, a 400 error can repeat
132
- part of the prompt. The SDK sends error messages also when `traceContent` is
133
- off, because error diagnosis uses them.
144
+ part of the prompt.
145
+ With `traceContent: false`, the SDK still sends the status message, the
146
+ exception message, the stack trace (which repeats the message), `error.message`
147
+ and `exception.message`. Only the project switch masks them, at the gateway.
134
148
 
135
- **Upgrading from 0.5.0 or earlier?** This is a behaviour change: content that
136
- used to be sent is no longer sent unless you opt in. In those versions the flag
137
- also did not work for content you set by hand — `traceContent: false` did not
138
- stop a `span.setAttribute('gen_ai.prompt.0.content', ...)` from reaching us.
139
- Both are fixed together.
149
+ **Upgrading from 0.9.2 or earlier?** This is a behaviour change. From 0.5.2
150
+ to 0.9.2 the default was `false`: prompts and completions stayed in your
151
+ process unless you opted in. Now they are sent unless you stop them. To keep
152
+ the old behaviour, add `traceContent: false` or set
153
+ `RISICARE_TRACE_CONTENT=false`.
154
+
155
+ The flag covers content that you set by hand too (since 0.5.2). For example,
156
+ `traceContent: false` stops a `span.setAttribute('gen_ai.prompt.0.content', ...)`
157
+ from reaching us. In 0.5.0 and earlier the flag did not do this.
140
158
 
141
159
  When capture is off, content-bearing attributes are **replaced** with
142
160
  `<risicare:content-omitted>` rather than removed, so "no prompt was sent" stays
@@ -151,7 +169,7 @@ on every content-bearing field of every span before export, for every
151
169
  exporter:
152
170
 
153
171
  ```typescript
154
- init({ apiKey: 'rsk-...', traceContent: true, mask: (key, value) => value });
172
+ init({ apiKey: 'rsk-...', mask: (key, value) => value });
155
173
  ```
156
174
 
157
175
 
@@ -160,7 +178,7 @@ init({ apiKey: 'rsk-...', traceContent: true, mask: (key, value) => value });
160
178
  - **12 LLM providers** — OpenAI, Anthropic, Google, Mistral, Groq, Cohere, Together, Ollama, HuggingFace, Cerebras, Bedrock, Vercel AI
161
179
  - **4 framework integrations** — LangChain, LangGraph, Instructor, LlamaIndex
162
180
  - **Error Diagnosis (beta)** — LLM-powered root cause analysis with fix suggestions; auto-apply not yet wired (see "Error Diagnosis" section below)
163
- - **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()`
164
182
  - **Streaming** — `tracedStream()` traces an async iterator (see "Streaming" below)
165
183
  - **Context propagation** — Automatic across `async/await`, `Promise` and `setTimeout`. An `EventEmitter` listener runs in the context of the `emit()` call
166
184
  - **Zero runtime dependencies** — No bloat in your node_modules
@@ -296,12 +314,110 @@ await traceThink('analyze', fn)()
296
314
  await traceDecide('choose', fn)()
297
315
  await traceAct('execute', fn)()
298
316
  reportError(error) // Report caught errors for diagnosis
299
- 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")
300
318
  tracedStream(asyncIterable, 'stream') // Trace async iterators
301
319
  await flush(5000) // Wait for delivery; false when a span or a score was lost
302
- 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
+ ```
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
+ });
303
337
  ```
304
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
+
305
421
  ## Delivery: flush, shutdown and metrics
306
422
 
307
423
  - `await flush(timeoutMs?)` waits for the queued spans and the pending scores
@@ -357,13 +473,21 @@ await shutdown(5000) // Deliver what it can in the time, th
357
473
  rules above. A loss that was not reported is not carried over. Report the old
358
474
  client's loss with `flush()` or `getMetrics()` before you call `init()` again.
359
475
  - `await shutdown(timeoutMs?)` is the call that ends a process in a fixed time
360
- (default 5000 ms). At the deadline it stops the export in flight. It counts
361
- the spans that it did not deliver as `shutdown_residue`, with one WARNING.
362
- - 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()`.
363
485
  - `getMetrics()` gives `exportedSpans` (spans that the backend accepted),
364
486
  `rejectedSpans`, `droppedSpans`, `droppedSpansByReason` (`queue_full`,
365
- `transport_refused`, `shutdown_residue`, `unacknowledged`), `failedExports`,
366
- `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
367
491
  spans that were sent, or that could not be serialized, and that the
368
492
  backend's answer did not account for. `failedExports` counts the export
369
493
  calls that failed as a whole. A later round can still deliver those spans, so
@@ -373,9 +497,10 @@ await shutdown(5000) // Deliver what it can in the time, th
373
497
  status of 300 or more, an error or a timeout adds 1 to `failedScores`. The
374
498
  first failure writes one WARNING at once. Failures in the next 10 seconds
375
499
  are counted, and the next WARNING gives their number. A score that `score()`
376
- refuses at the call (a value that is not a number or is outside 0 to 1, an
377
- empty trace id or name) writes one WARNING, is not sent, and also adds 1 to
378
- `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()`
379
504
  or the SDK's own drain, tracing off, no key), nothing is counted.
380
505
  At most 50 score requests run at one time. Up to 1,000 scores wait for a free
381
506
  slot, with no timer: the 2000 ms bound starts when the request starts. A score
@@ -505,34 +630,45 @@ up, it writes at most one WARNING an hour. A batch that the backend discards, an
505
630
  the full queue drops in the pause, are counted in `getMetrics().droppedQuota` (the same number as
506
631
  `droppedSpansByReason.quota_exceeded`). They are also in the flat dropped total, and not in `rejectedSpans`. They are not stored.
507
632
 
508
- ## Known limitation — span loss during a backend outage
509
-
510
- The SDK does **not** keep spans through a long outage of the Risicare backend.
511
- Nothing throws in your application. The SDK writes a WARNING, `flush()`
512
- returns `false`, and `getMetrics()` counts the lost spans in
513
- `droppedSpansByReason.transport_refused`.
514
-
515
- The HTTP exporter opens a circuit breaker after **5 consecutive failed export
516
- calls** and holds it open for **60 seconds**. While it is open, an export
517
- returns failure at once and does not use the network. A batch that fails is
518
- put back in the queue at most 3 times. Against an open breaker these 3
519
- attempts fail at once, so the spans are dropped. For the rest of the cooldown
520
- the SDK does not send, also when your backend is healthy again.
521
-
522
- The thresholds count **failed calls, not seconds**. When the 5th consecutive
523
- failure occurs depends on your span rate and on how fast your endpoint fails.
524
- A short failure that stays under 5 consecutive failed calls does not open the
525
- breaker. Tracked as `F-SDKBLIP-001`.
526
-
527
- One export call sends a batch at most 3 times. A 401 or 403 answer is sent
528
- once in each export call: the endpoint refused the API key, and the same key
529
- gets the same answer. At the first failed export of an outage (at most once in
530
- 5 minutes), the SDK writes the WARNING "spans are NOT reaching ...". It gives
531
- the HTTP status of the last answer, or the error code when there was no answer.
532
- For a 401 or 403 it tells you to check the API key. When the kind of failure
533
- changes in one outage (for example a 401, then no answer), the SDK writes one more
534
- WARNING. An endpoint URL with credentials (a user name or a password before the
535
- 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.
536
672
 
537
673
  The SDK removes its API key from each text that it logs: in any case of letters,
538
674
  and also when the key is percent-encoded. An endpoint is logged without its user