risicare 0.7.0 → 0.9.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/README.md +346 -68
- package/dist/frameworks/instructor.cjs +790 -5
- package/dist/frameworks/instructor.cjs.map +1 -1
- package/dist/frameworks/instructor.js +780 -5
- package/dist/frameworks/instructor.js.map +1 -1
- package/dist/frameworks/langchain.cjs +790 -5
- package/dist/frameworks/langchain.cjs.map +1 -1
- package/dist/frameworks/langchain.d.cts +3 -2
- package/dist/frameworks/langchain.d.ts +3 -2
- package/dist/frameworks/langchain.js +780 -5
- package/dist/frameworks/langchain.js.map +1 -1
- package/dist/frameworks/langgraph.cjs +790 -5
- package/dist/frameworks/langgraph.cjs.map +1 -1
- package/dist/frameworks/langgraph.js +780 -5
- package/dist/frameworks/langgraph.js.map +1 -1
- package/dist/frameworks/llamaindex.cjs +801 -5
- package/dist/frameworks/llamaindex.cjs.map +1 -1
- package/dist/frameworks/llamaindex.d.cts +3 -2
- package/dist/frameworks/llamaindex.d.ts +3 -2
- package/dist/frameworks/llamaindex.js +791 -5
- package/dist/frameworks/llamaindex.js.map +1 -1
- package/dist/index.cjs +1219 -212
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +250 -44
- package/dist/index.d.ts +250 -44
- package/dist/index.js +1219 -212
- package/dist/index.js.map +1 -1
- package/dist/providers/anthropic/index.cjs +1601 -36
- package/dist/providers/anthropic/index.cjs.map +1 -1
- package/dist/providers/anthropic/index.d.cts +3 -1
- package/dist/providers/anthropic/index.d.ts +3 -1
- package/dist/providers/anthropic/index.js +1591 -36
- package/dist/providers/anthropic/index.js.map +1 -1
- package/dist/providers/bedrock/index.cjs +850 -32
- package/dist/providers/bedrock/index.cjs.map +1 -1
- package/dist/providers/bedrock/index.js +840 -32
- package/dist/providers/bedrock/index.js.map +1 -1
- package/dist/providers/cerebras/index.cjs +1534 -30
- package/dist/providers/cerebras/index.cjs.map +1 -1
- package/dist/providers/cerebras/index.js +1524 -30
- package/dist/providers/cerebras/index.js.map +1 -1
- package/dist/providers/cohere/index.cjs +1557 -102
- package/dist/providers/cohere/index.cjs.map +1 -1
- package/dist/providers/cohere/index.js +1547 -102
- package/dist/providers/cohere/index.js.map +1 -1
- package/dist/providers/google/index.cjs +1562 -60
- package/dist/providers/google/index.cjs.map +1 -1
- package/dist/providers/google/index.js +1552 -60
- package/dist/providers/google/index.js.map +1 -1
- package/dist/providers/groq/index.cjs +1534 -30
- package/dist/providers/groq/index.cjs.map +1 -1
- package/dist/providers/groq/index.js +1524 -30
- package/dist/providers/groq/index.js.map +1 -1
- package/dist/providers/huggingface/index.cjs +1622 -25
- package/dist/providers/huggingface/index.cjs.map +1 -1
- package/dist/providers/huggingface/index.d.cts +0 -9
- package/dist/providers/huggingface/index.d.ts +0 -9
- package/dist/providers/huggingface/index.js +1612 -25
- package/dist/providers/huggingface/index.js.map +1 -1
- package/dist/providers/mistral/index.cjs +1535 -54
- package/dist/providers/mistral/index.cjs.map +1 -1
- package/dist/providers/mistral/index.js +1525 -54
- package/dist/providers/mistral/index.js.map +1 -1
- package/dist/providers/ollama/index.cjs +1559 -93
- package/dist/providers/ollama/index.cjs.map +1 -1
- package/dist/providers/ollama/index.js +1549 -93
- package/dist/providers/ollama/index.js.map +1 -1
- package/dist/providers/openai/index.cjs +1598 -61
- package/dist/providers/openai/index.cjs.map +1 -1
- package/dist/providers/openai/index.d.cts +6 -1
- package/dist/providers/openai/index.d.ts +6 -1
- package/dist/providers/openai/index.js +1588 -61
- package/dist/providers/openai/index.js.map +1 -1
- package/dist/providers/together/index.cjs +1534 -30
- package/dist/providers/together/index.cjs.map +1 -1
- package/dist/providers/together/index.js +1524 -30
- package/dist/providers/together/index.js.map +1 -1
- package/dist/providers/vercel-ai/index.cjs +1288 -17
- package/dist/providers/vercel-ai/index.cjs.map +1 -1
- package/dist/providers/vercel-ai/index.d.cts +0 -6
- package/dist/providers/vercel-ai/index.d.ts +0 -6
- package/dist/providers/vercel-ai/index.js +1278 -17
- package/dist/providers/vercel-ai/index.js.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -7,7 +7,9 @@ AI agent observability and error diagnosis for Node.js and TypeScript.
|
|
|
7
7
|
[](https://www.npmjs.com/package/risicare)
|
|
8
8
|
[](LICENSE)
|
|
9
9
|
|
|
10
|
-
Monitor your AI agents in production.
|
|
10
|
+
Monitor your AI agents in production. Patch your LLM client, wrap your agent,
|
|
11
|
+
and the SDK sends a span for each traced call to Risicare. Risicare then
|
|
12
|
+
diagnoses the errors and suggests fixes.
|
|
11
13
|
|
|
12
14
|
## Quickstart
|
|
13
15
|
|
|
@@ -20,11 +22,8 @@ import { init, agent, shutdown } from 'risicare';
|
|
|
20
22
|
import { patchOpenAI } from 'risicare/openai';
|
|
21
23
|
import OpenAI from 'openai';
|
|
22
24
|
|
|
23
|
-
// 1. Initialize
|
|
24
|
-
init({
|
|
25
|
-
apiKey: 'rsk-...',
|
|
26
|
-
endpoint: 'https://ingest.risicare.ai',
|
|
27
|
-
});
|
|
25
|
+
// 1. Initialize (for the hosted service, set no endpoint)
|
|
26
|
+
init({ apiKey: 'rsk-...' });
|
|
28
27
|
|
|
29
28
|
// 2. Patch your LLM client
|
|
30
29
|
const openai = patchOpenAI(new OpenAI());
|
|
@@ -38,18 +37,73 @@ const myAgent = agent({ name: 'research-agent' }, async (query: string) => {
|
|
|
38
37
|
return response.choices[0].message.content;
|
|
39
38
|
});
|
|
40
39
|
|
|
41
|
-
// Run it
|
|
40
|
+
// Run it
|
|
42
41
|
const result = await myAgent('What is quantum computing?');
|
|
43
42
|
await shutdown();
|
|
44
43
|
```
|
|
45
44
|
|
|
46
|
-
|
|
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).
|
|
48
|
+
|
|
49
|
+
## Two hosts
|
|
50
|
+
|
|
51
|
+
The SDK sends data to two hosts:
|
|
52
|
+
|
|
53
|
+
- **Spans** go to `endpoint`. The default is `https://ingest.risicare.ai`.
|
|
54
|
+
- **Scores and fix reads** go to `apiEndpoint`. The default is `https://api.risicare.ai`.
|
|
55
|
+
|
|
56
|
+
For the hosted service, set neither. For your own deployment, set `endpoint`
|
|
57
|
+
(or `RISICARE_ENDPOINT`). Scores and fix reads go to the first of these that
|
|
58
|
+
is set:
|
|
59
|
+
|
|
60
|
+
1. the `apiEndpoint` option;
|
|
61
|
+
2. the `endpoint` option, unless it is the default ingest host;
|
|
62
|
+
3. the `RISICARE_API_ENDPOINT` environment variable;
|
|
63
|
+
4. the `RISICARE_ENDPOINT` environment variable, if you gave no `endpoint`
|
|
64
|
+
option and it is not the default ingest host;
|
|
65
|
+
5. the default, `https://api.risicare.ai`.
|
|
66
|
+
|
|
67
|
+
The SDK ignores the default ingest host (`https://ingest.risicare.ai`) when it
|
|
68
|
+
selects the api host, and goes to the next step. So your key does not go to a
|
|
69
|
+
host that you did not name. Only that exact value is ignored (letter case, a
|
|
70
|
+
`:443` port and slashes at the end do not matter). A different form, for
|
|
71
|
+
example `http://ingest.risicare.ai` or `https://ingest.risicare.ai/v1`, is a
|
|
72
|
+
host that you named, and the SDK uses it. A value that is empty, or that has
|
|
73
|
+
ASCII whitespace only, is "not set". `RISICARE_ENDPOINT=https://my-host` alone sends spans, scores and fix
|
|
74
|
+
reads to `https://my-host`.
|
|
75
|
+
|
|
76
|
+
## Configuration
|
|
77
|
+
|
|
78
|
+
`RISICARE_TRACING` is trimmed and compared without case:
|
|
79
|
+
|
|
80
|
+
| Value | Result |
|
|
81
|
+
|-------|--------|
|
|
82
|
+
| `true`, `1`, `yes`, `on` | tracing on |
|
|
83
|
+
| `false`, `0`, `no`, `off` | tracing off |
|
|
84
|
+
| unset, empty, or whitespace only | the default applies |
|
|
85
|
+
| any other value | tracing off, with one WARNING that names the value |
|
|
86
|
+
|
|
87
|
+
The `enabled` option has priority over the variable. With no API key, tracing
|
|
88
|
+
is off, whatever `enabled` or `RISICARE_TRACING` says (see "A note on running
|
|
89
|
+
without an API key").
|
|
90
|
+
|
|
91
|
+
## Imports
|
|
92
|
+
|
|
93
|
+
The package has no default export. Use named imports or a namespace import.
|
|
94
|
+
`Span` and `Tracer` are types only: import them with `import type`.
|
|
95
|
+
|
|
96
|
+
```typescript
|
|
97
|
+
import { init, agent } from 'risicare';
|
|
98
|
+
import * as risicare from 'risicare';
|
|
99
|
+
import type { Span, Tracer } from 'risicare';
|
|
100
|
+
```
|
|
47
101
|
|
|
48
102
|
## Prompt content is NOT captured by default
|
|
49
103
|
|
|
50
|
-
|
|
104
|
+
**`traceContent` defaults to `false`** (since 0.5.2, the first published version with this default). Your prompts and completions
|
|
51
105
|
stay in your process. Everything else — model, token counts, latency, cost,
|
|
52
|
-
|
|
106
|
+
errors, and any attributes you set — is captured as normal, so the
|
|
53
107
|
dashboard, cost tracking and error diagnosis all work unchanged.
|
|
54
108
|
|
|
55
109
|
To send prompt and completion text as well, opt in:
|
|
@@ -59,6 +113,25 @@ init({ apiKey: 'rsk-...', traceContent: true });
|
|
|
59
113
|
// or set RISICARE_TRACE_CONTENT=true
|
|
60
114
|
```
|
|
61
115
|
|
|
116
|
+
**Which providers capture text.** With `traceContent: true`:
|
|
117
|
+
|
|
118
|
+
- `patchOpenAI` and `patchAnthropic` capture the prompt and the completion text.
|
|
119
|
+
They write the first 10 messages to `gen_ai.prompt.N.role` and
|
|
120
|
+
`gen_ai.prompt.N.content`. They write the completion to
|
|
121
|
+
`gen_ai.completion.content`. `patchAnthropic` also writes a string `system`
|
|
122
|
+
prompt to `gen_ai.system_prompt`. The SDK cuts each text at 10,000 characters
|
|
123
|
+
(Unicode code points). It cuts the system prompt at 5,000. `patchOpenAI` also
|
|
124
|
+
captures text for a client of an OpenAI-compatible host.
|
|
125
|
+
- For a streamed call, they capture the prompt only, not the completion.
|
|
126
|
+
- `patchGoogleAI`, `patchMistral`, `patchGroq`, `patchCohere`, `patchTogether`,
|
|
127
|
+
`patchOllama`, `patchHuggingFace`, `patchCerebras`, `patchBedrock` and
|
|
128
|
+
`patchVercelAI` capture no prompt or completion text.
|
|
129
|
+
|
|
130
|
+
**Error text is not covered by this switch.** The error message from a
|
|
131
|
+
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.
|
|
134
|
+
|
|
62
135
|
**Upgrading from 0.5.0 or earlier?** This is a behaviour change: content that
|
|
63
136
|
used to be sent is no longer sent unless you opt in. In those versions the flag
|
|
64
137
|
also did not work for content you set by hand — `traceContent: false` did not
|
|
@@ -73,9 +146,9 @@ Since 0.7.0, the gate also covers the OpenTelemetry GenAI, OpenInference and
|
|
|
73
146
|
CrewAI content keys, for example `input.value`, `output.value`,
|
|
74
147
|
`gen_ai.input.messages` and `gen_ai.output.messages`.
|
|
75
148
|
|
|
76
|
-
If you want content captured but redacted first, use the `mask` hook
|
|
77
|
-
|
|
78
|
-
|
|
149
|
+
If you want content captured but redacted first, use the `mask` hook. It runs
|
|
150
|
+
on every content-bearing field of every span before export, for every
|
|
151
|
+
exporter:
|
|
79
152
|
|
|
80
153
|
```typescript
|
|
81
154
|
init({ apiKey: 'rsk-...', traceContent: true, mask: (key, value) => value });
|
|
@@ -87,31 +160,91 @@ init({ apiKey: 'rsk-...', traceContent: true, mask: (key, value) => value });
|
|
|
87
160
|
- **12 LLM providers** — OpenAI, Anthropic, Google, Mistral, Groq, Cohere, Together, Ollama, HuggingFace, Cerebras, Bedrock, Vercel AI
|
|
88
161
|
- **4 framework integrations** — LangChain, LangGraph, Instructor, LlamaIndex
|
|
89
162
|
- **Error Diagnosis (beta)** — LLM-powered root cause analysis with fix suggestions; auto-apply not yet wired (see "Error Diagnosis" section below)
|
|
90
|
-
- **Evaluation scores** — Rate agent quality with `score()`
|
|
91
|
-
- **Streaming
|
|
92
|
-
- **Context propagation** — Automatic across `async/await`, `Promise
|
|
163
|
+
- **Evaluation scores** — Rate agent quality with `score()`
|
|
164
|
+
- **Streaming** — `tracedStream()` traces an async iterator (see "Streaming" below)
|
|
165
|
+
- **Context propagation** — Automatic across `async/await`, `Promise` and `setTimeout`. An `EventEmitter` listener runs in the context of the `emit()` call
|
|
93
166
|
- **Zero runtime dependencies** — No bloat in your node_modules
|
|
94
167
|
- **Dual CJS/ESM** — Works with `require()` and `import`
|
|
95
168
|
- **Full TypeScript** — Strict types and IntelliSense out of the box
|
|
96
|
-
- **
|
|
97
|
-
- **
|
|
169
|
+
- **Background export** — Async batch export with circuit breaker and retry
|
|
170
|
+
- **Low cost when disabled** — a frozen no-op span
|
|
98
171
|
|
|
99
172
|
## LLM Providers
|
|
100
173
|
|
|
101
174
|
```typescript
|
|
175
|
+
import OpenAI from 'openai';
|
|
102
176
|
import { patchOpenAI } from 'risicare/openai';
|
|
103
177
|
import { patchAnthropic } from 'risicare/anthropic';
|
|
104
|
-
import {
|
|
178
|
+
import { patchGoogleAI } from 'risicare/google';
|
|
105
179
|
// ... and 9 more
|
|
106
180
|
|
|
107
181
|
const openai = patchOpenAI(new OpenAI());
|
|
108
|
-
//
|
|
182
|
+
// chat.completions.create and embeddings.create are now traced
|
|
109
183
|
```
|
|
110
184
|
|
|
111
185
|
All 12 providers:
|
|
112
186
|
|
|
113
187
|
`openai` · `anthropic` · `google` · `mistral` · `groq` · `cohere` · `together` · `ollama` · `huggingface` · `cerebras` · `bedrock` · `vercel-ai`
|
|
114
188
|
|
|
189
|
+
`patchOpenAI` also traces an OpenAI-compatible host (`baseURL`). It sets the
|
|
190
|
+
provider name (`gen_ai.system`) from the host for DeepSeek, Together, Groq, xAI,
|
|
191
|
+
Fireworks, Baseten, Novita and BytePlus (`api.byteplus.com` and
|
|
192
|
+
`ark.cn-beijing.byteplus.com`). Any other host is named `openai`.
|
|
193
|
+
|
|
194
|
+
### Streaming
|
|
195
|
+
|
|
196
|
+
The caller gets the provider's own promise and stream objects. The SDK counts
|
|
197
|
+
only the chunks that the caller reads. It does not read ahead. The span of a
|
|
198
|
+
stream ends once, when the stream ends, with `stream.end_reason`:
|
|
199
|
+
|
|
200
|
+
| `stream.end_reason` | When | Status |
|
|
201
|
+
|---|---|---|
|
|
202
|
+
| `done` | The caller read the stream to its end. | ok |
|
|
203
|
+
| `return` | The caller stopped early (`break`, `return()`). | ok |
|
|
204
|
+
| `abort` | An abort stopped the stream: `controller.abort()` or the request `signal` (OpenAI, Anthropic, Groq, Together, Cerebras), the request `abortSignal` (Cohere), Ollama `abort()`, `cancel()`, or an `AbortError` that reached the caller. See the Google and Mistral limits. The span also gets `risicare.cancelled` = `true` and `risicare.cancel_type` = `AbortError`. | error |
|
|
205
|
+
| `error` | An error reached the caller. The span records it. | error |
|
|
206
|
+
| `handoff` | The caller took the data another way: `tee()`, `getReader()`, `toReadableStream()`, `pipeTo()`, `pipeThrough()` or `asResponse()`. | ok |
|
|
207
|
+
| `garbage` | Nothing holds the promise, the stream or an iterator, and no `next()` waits. The JavaScript engine decides when this is seen; it can be never. | ok |
|
|
208
|
+
| `shutdown` | `shutdown()` ends every stream span that is still open, and exports it. | ok |
|
|
209
|
+
|
|
210
|
+
The span has `stream.chunk_count`: the number of chunks that the caller read.
|
|
211
|
+
It has the token counts that the chunks gave: the usage chunk (OpenAI needs
|
|
212
|
+
`stream_options: { include_usage: true }`; also Groq, Together, Cerebras,
|
|
213
|
+
Hugging Face), `message_start` and `message_delta` (Anthropic), the last
|
|
214
|
+
`usageMetadata` (Google), the chunk `usage` (Mistral), the last chunk with
|
|
215
|
+
`done` (Ollama), `message-end` (Cohere). A count that the stream did not give
|
|
216
|
+
stays empty. The span does not capture the streamed completion text.
|
|
217
|
+
|
|
218
|
+
Call `shutdown()` before the process stops. A span that is still open is lost
|
|
219
|
+
if the process stops without it.
|
|
220
|
+
|
|
221
|
+
Limits:
|
|
222
|
+
|
|
223
|
+
- Cohere: `stream.controller.abort()` does not stop a Cohere stream, so it is
|
|
224
|
+
not an abort. The request option `abortSignal` stops it, and is an abort.
|
|
225
|
+
- Google, the request `signal`: the Google SDK changes the abort into a
|
|
226
|
+
`GoogleGenerativeAIError`. A read after the abort ends the span as `error`,
|
|
227
|
+
not `abort`. An abort with no read after it ends as `garbage` or
|
|
228
|
+
`shutdown`, status ok.
|
|
229
|
+
- Mistral, the request `signal` (`fetchOptions.signal`): a read after the
|
|
230
|
+
abort gets an `AbortError`, and the span ends as `abort`. The SDK cannot see
|
|
231
|
+
this signal, so an abort with no read after it ends as `garbage` or
|
|
232
|
+
`shutdown`, status ok.
|
|
233
|
+
- Google `result.response`: the Google SDK gives the aggregated response also
|
|
234
|
+
when nobody reads `result.stream`. If the caller never takes `result.stream`,
|
|
235
|
+
the span ends as `done` when `result.response` settles, with the tokens of
|
|
236
|
+
the aggregated response and `stream.chunk_count` = 0 (`error` if it
|
|
237
|
+
rejects). If the caller takes `result.stream`, the stream decides the end.
|
|
238
|
+
A stream that the caller takes after the span ended is not counted.
|
|
239
|
+
- `handoff`: the SDK does not see the chunks after the handoff, so the chunk
|
|
240
|
+
and token counts cover only the chunks read before it.
|
|
241
|
+
- Bedrock (`ConverseStreamCommand`): the SDK does not read the stream. The
|
|
242
|
+
span ends when `send()` returns. It has no token counts.
|
|
243
|
+
- Vercel AI (`tracedStreamText`): the span ends through the `streamText`
|
|
244
|
+
callbacks: `onFinish` (`done`, with the usage), `onAbort` (`abort`) or an
|
|
245
|
+
error chunk (`error`). With no callback, it ends as `garbage` or at
|
|
246
|
+
`shutdown()`.
|
|
247
|
+
|
|
115
248
|
## Framework Integrations
|
|
116
249
|
|
|
117
250
|
```typescript
|
|
@@ -130,13 +263,24 @@ const client = patchInstructor(instructor);
|
|
|
130
263
|
|
|
131
264
|
// LlamaIndex
|
|
132
265
|
import { RisicareLlamaIndexHandler } from 'risicare/llamaindex';
|
|
266
|
+
const liHandler = new RisicareLlamaIndexHandler();
|
|
267
|
+
for (const name of RisicareLlamaIndexHandler.EVENT_NAMES) {
|
|
268
|
+
Settings.callbackManager.on(name, (e) => liHandler.onEvent(e)); // Settings from 'llamaindex'
|
|
269
|
+
}
|
|
133
270
|
```
|
|
134
271
|
|
|
272
|
+
The LangChain and LlamaIndex handlers give one LLM span for each model call.
|
|
273
|
+
Use one handler: two handler instances on one call (for example one in the model
|
|
274
|
+
constructor and one in `invoke`) give two LLM spans. LangChain's `ChatOpenAI` and LlamaIndex's `OpenAI` make their own OpenAI client.
|
|
275
|
+
`patchOpenAI` changes only the client that you give to it, so it does not add a
|
|
276
|
+
second span to these calls. You need `withSuppression()` only when the same call
|
|
277
|
+
also goes through a client that you patched.
|
|
278
|
+
|
|
135
279
|
## Core API
|
|
136
280
|
|
|
137
281
|
```typescript
|
|
138
282
|
import {
|
|
139
|
-
init, shutdown,
|
|
283
|
+
init, flush, shutdown, // Lifecycle
|
|
140
284
|
agent, session, // Identity & grouping
|
|
141
285
|
traceThink, traceDecide, traceAct, // Decision phases
|
|
142
286
|
reportError, score, // Diagnosis & evaluation
|
|
@@ -144,48 +288,150 @@ import {
|
|
|
144
288
|
} from 'risicare';
|
|
145
289
|
|
|
146
290
|
init({ apiKey, endpoint }) // Initialize SDK
|
|
147
|
-
agent(
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
await
|
|
151
|
-
await
|
|
152
|
-
await
|
|
291
|
+
// agent(), session() and the trace* functions are WRAPPER FACTORIES:
|
|
292
|
+
// they return a function that you then call. Note the trailing ().
|
|
293
|
+
await agent({ name }, fn)() // Run fn with agent identity
|
|
294
|
+
await session({ sessionId, userId }, fn)() // Run fn in a user session
|
|
295
|
+
await traceThink('analyze', fn)()
|
|
296
|
+
await traceDecide('choose', fn)()
|
|
297
|
+
await traceAct('execute', fn)()
|
|
153
298
|
reportError(error) // Report caught errors for diagnosis
|
|
154
299
|
score(traceId, 'quality', 0.92) // Record evaluation score [0.0-1.0]
|
|
155
300
|
tracedStream(asyncIterable, 'stream') // Trace async iterators
|
|
156
|
-
await
|
|
301
|
+
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
|
|
157
303
|
```
|
|
158
304
|
|
|
305
|
+
## Delivery: flush, shutdown and metrics
|
|
306
|
+
|
|
307
|
+
- `await flush(timeoutMs?)` waits for the queued spans and the pending scores
|
|
308
|
+
(default 5000 ms). It returns `true` only when the gateway acknowledged every
|
|
309
|
+
span and every score that the SDK accepted since the previous `flush()`
|
|
310
|
+
returned (or since `init()`), and nothing is queued or in flight. When the SDK
|
|
311
|
+
has no evidence of delivery, `flush()` is not `true`.
|
|
312
|
+
- A loss of any kind makes exactly one `flush()` return `false`: the next one
|
|
313
|
+
that ends. A loss is a drop for any reason (`shutdown_residue` included), a
|
|
314
|
+
rejection, a failed score, and a score that `score()` refuses at the call. It
|
|
315
|
+
also raises a counter with a named reason: `droppedSpansByReason`,
|
|
316
|
+
`rejectedSpans` or `failedScores`. A `flush()` that returns `false` at its
|
|
317
|
+
deadline, while none of these counters went up since the previous `flush()`,
|
|
318
|
+
means that spans are still in flight: they are not lost. `flush()` only waits.
|
|
319
|
+
It does not stop a request that is already sent. With more than one exporter,
|
|
320
|
+
a batch counts as delivered when the first exporter that succeeds takes it:
|
|
321
|
+
`flush()` can then return `true` while another exporter refused the batch.
|
|
322
|
+
- `flush()` returns `false` when the SDK is not active: before `init()`, with
|
|
323
|
+
tracing off at `init()` (`enabled: false`, `RISICARE_TRACING=false`), and with
|
|
324
|
+
no API key. `isEnabled()` is `false` in the same cases, and after `shutdown()`
|
|
325
|
+
or the SDK's own drain at SIGTERM or SIGINT.
|
|
326
|
+
- A `flush()` that comes while a `shutdown()` runs (your own call, or the SDK's
|
|
327
|
+
drain at SIGTERM or SIGINT) waits for that shutdown, inside its own deadline,
|
|
328
|
+
and then reports the real outcome of what the SDK accepted, with the same
|
|
329
|
+
loss rule. So does a `flush()` after `shutdown()`. It never answers from the
|
|
330
|
+
state of an empty queue.
|
|
331
|
+
- A span that ends while a `shutdown()` runs (your own call, or the SDK's drain
|
|
332
|
+
at SIGTERM or SIGINT) joins that drain, and is exported before the drain ends.
|
|
333
|
+
A span that ends after the drain has stopped taking spans (nothing was left
|
|
334
|
+
to export, a round failed, or its time ended) is counted at once as
|
|
335
|
+
`shutdown_residue`, with one WARNING for the first one, and one `flush()`
|
|
336
|
+
returns `false`. It is never dropped without a count.
|
|
337
|
+
- At SIGTERM and SIGINT the SDK drains what it holds. In both orders of
|
|
338
|
+
registration `flush()` reports the real outcome, and your listener runs once
|
|
339
|
+
and decides the exit. When your application has its own listener for the
|
|
340
|
+
signal when the signal arrives, the SDK does not raise the signal again and
|
|
341
|
+
does not end the process. When it has none at that moment, and had none when
|
|
342
|
+
it called `init()`, the SDK raises the signal again after its drain, so that
|
|
343
|
+
the default action ends the process. A listener that you add during the
|
|
344
|
+
drain runs on that second signal.
|
|
345
|
+
- The order of registration does change one thing: which spans your listener
|
|
346
|
+
makes are delivered. Node calls the listeners in the order of registration. A
|
|
347
|
+
listener that you register BEFORE `init()` runs before the SDK's: the spans
|
|
348
|
+
that it ends before it first waits are in the queue when the SDK drains, and
|
|
349
|
+
are delivered. A listener that you register AFTER `init()` runs after the
|
|
350
|
+
SDK's drain started. A span that it ends can miss the drain, when the drain
|
|
351
|
+
has stopped taking spans (nothing was left to export, a round failed, or its
|
|
352
|
+
time ended). That span is counted as `shutdown_residue`, and one `flush()`
|
|
353
|
+
returns `false`. A span that ends after the drain ended is counted in the same
|
|
354
|
+
way, in both orders. If your listener must make spans that are delivered,
|
|
355
|
+
register it before `init()`, or end the spans before the signal.
|
|
356
|
+
- A new `init()` (after `shutdown()`) starts a new count: "since `init()`" in the
|
|
357
|
+
rules above. A loss that was not reported is not carried over. Report the old
|
|
358
|
+
client's loss with `flush()` or `getMetrics()` before you call `init()` again.
|
|
359
|
+
- `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.
|
|
363
|
+
- `getMetrics()` gives `exportedSpans` (spans that the backend accepted),
|
|
364
|
+
`rejectedSpans`, `droppedSpans`, `droppedSpansByReason` (`queue_full`,
|
|
365
|
+
`transport_refused`, `shutdown_residue`, `unacknowledged`), `failedExports`,
|
|
366
|
+
`failedScores`, the queue numbers and `sdkState`. `unacknowledged` counts
|
|
367
|
+
spans that were sent, or that could not be serialized, and that the
|
|
368
|
+
backend's answer did not account for. `failedExports` counts the export
|
|
369
|
+
calls that failed as a whole. A later round can still deliver those spans, so
|
|
370
|
+
it is not a loss counter: the loss counters are `droppedSpansByReason`,
|
|
371
|
+
`rejectedSpans` and `failedScores`.
|
|
372
|
+
- `score()` stops its request after 2000 ms and does not follow a redirect. A
|
|
373
|
+
status of 300 or more, an error or a timeout adds 1 to `failedScores`. The
|
|
374
|
+
first failure writes one WARNING at once. Failures in the next 10 seconds
|
|
375
|
+
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()`
|
|
379
|
+
or the SDK's own drain, tracing off, no key), nothing is counted.
|
|
380
|
+
At most 50 score requests run at one time. Up to 1,000 scores wait for a free
|
|
381
|
+
slot, with no timer: the 2000 ms bound starts when the request starts. A score
|
|
382
|
+
that comes when 1,000 already wait fails at once and is counted. When the bound
|
|
383
|
+
of `flush()` or `shutdown()` ends, the scores that still wait fail and are not
|
|
384
|
+
sent.
|
|
385
|
+
|
|
159
386
|
## Error Diagnosis
|
|
160
387
|
|
|
161
|
-
> **Beta
|
|
162
|
-
> Together.AI Llama-3.3-70B
|
|
163
|
-
> fixes land in your dashboard as `status=draft` for human review.
|
|
164
|
-
> deployment, A/B rollout
|
|
165
|
-
>
|
|
166
|
-
> error diagnosis** today; auto-apply will follow.
|
|
388
|
+
> **Beta.** The Risicare service detects an error, diagnoses it and suggests a
|
|
389
|
+
> fix. The diagnosis runs on the service, with Together.AI Llama-3.3-70B.
|
|
390
|
+
> Suggested fixes land in your dashboard as `status=draft` for human review.
|
|
391
|
+
> Automatic deployment, A/B rollout and learning from outcomes are not
|
|
392
|
+
> available. Treat this as **AI-assisted error diagnosis**.
|
|
167
393
|
|
|
168
|
-
When your agent fails
|
|
394
|
+
When your agent fails:
|
|
169
395
|
|
|
170
|
-
1.
|
|
171
|
-
|
|
172
|
-
|
|
396
|
+
1. The SDK records the error on the span and gives it an error code
|
|
397
|
+
(`error.code`). The taxonomy has 154 codes in 10 modules (TOOL, MEMORY,
|
|
398
|
+
REASONING, OUTPUT and others). The SDK's own rules give 18 of them. An
|
|
399
|
+
error that no rule matches gets a 19th, `TOOL.EXECUTION.CRASHED`.
|
|
400
|
+
2. The Risicare service diagnoses the root cause.
|
|
401
|
+
3. The service writes a fix suggestion that you can review in the dashboard
|
|
402
|
+
and apply manually.
|
|
173
403
|
|
|
174
404
|
```typescript
|
|
175
405
|
try {
|
|
176
406
|
await myAgent(input);
|
|
177
407
|
} catch (error) {
|
|
178
|
-
reportError(error); //
|
|
408
|
+
reportError(error); // Records the error for diagnosis; the fix lands as a draft for review
|
|
179
409
|
}
|
|
180
410
|
```
|
|
181
411
|
|
|
182
412
|
## Fix application is off by default
|
|
183
413
|
|
|
184
|
-
**Since 0.7.0, FixRuntime starts only when you opt in.**
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
414
|
+
**Since 0.7.0, FixRuntime starts only when you opt in.** During the beta, the
|
|
415
|
+
Risicare service does not give fixes to customer projects, so FixRuntime has no
|
|
416
|
+
effect for them. Through 0.6.0, FixRuntime started automatically when you set an
|
|
417
|
+
API key.
|
|
418
|
+
|
|
419
|
+
When FixRuntime is on, it reads the active fixes for your project from Risicare.
|
|
420
|
+
The fix interceptor enforces guard fixes on these paths only: `interceptCall` and
|
|
421
|
+
`interceptResponse` on the runtime, and the input guards of the patched OpenAI
|
|
422
|
+
chat call. The guards do not run when a framework integration suppresses provider
|
|
423
|
+
instrumentation. A failed input guard throws `GuardRejectedError` before the LLM
|
|
424
|
+
call. The input guards check messages that have text content: a string, or the
|
|
425
|
+
`text` parts of a list. A guard pattern that is not usable (not a string, empty,
|
|
426
|
+
longer than 500 characters, or JavaScript cannot use it) rejects the call. The
|
|
427
|
+
provider path does not apply prompt, parameter or fallback fixes.
|
|
428
|
+
|
|
429
|
+
Each SDK uses its own regular-expression engine. These constructs can give a
|
|
430
|
+
different result in JavaScript and Python: `$` before a final newline, Unicode
|
|
431
|
+
case folding, `\d` and `\w` on non-ASCII text, and a `]` first in a class.
|
|
432
|
+
JavaScript rejects a pattern that contains `\N{...}` or `\U........`. A pattern
|
|
433
|
+
has no time bound: a pattern with nested repeats can take a very long time on a
|
|
434
|
+
long input.
|
|
189
435
|
|
|
190
436
|
When FixRuntime is off, the SDK does not request `/fixes/active`, and it does
|
|
191
437
|
not change your LLM calls. Tracing, error reporting and scores are not affected.
|
|
@@ -226,44 +472,76 @@ const myAgent = agent({ name: 'planner', role: 'coordinator' }, async (input) =>
|
|
|
226
472
|
|
|
227
473
|
## Sessions
|
|
228
474
|
|
|
229
|
-
Group traces from the same user conversation
|
|
475
|
+
Group traces from the same user conversation. `withSession` runs the callback
|
|
476
|
+
now and returns its result:
|
|
230
477
|
|
|
231
478
|
```typescript
|
|
232
|
-
|
|
479
|
+
import { withSession } from 'risicare';
|
|
480
|
+
|
|
481
|
+
const result = await withSession(
|
|
233
482
|
{ sessionId: 'sess-abc123', userId: 'user-456' },
|
|
234
483
|
() => myAgent(userMessage)
|
|
235
484
|
);
|
|
236
485
|
```
|
|
237
486
|
|
|
487
|
+
`session()` does not run the callback. It returns a wrapped function, which you
|
|
488
|
+
call later, for example once for each request.
|
|
489
|
+
|
|
238
490
|
## Known limitation — span loss during a backend outage
|
|
239
491
|
|
|
240
|
-
The SDK does **not**
|
|
241
|
-
|
|
242
|
-
|
|
492
|
+
The SDK does **not** keep spans through a long outage of the Risicare backend.
|
|
493
|
+
Nothing throws in your application. The SDK writes a WARNING, `flush()`
|
|
494
|
+
returns `false`, and `getMetrics()` counts the lost spans in
|
|
495
|
+
`droppedSpansByReason.transport_refused`.
|
|
243
496
|
|
|
244
497
|
The HTTP exporter opens a circuit breaker after **5 consecutive failed export
|
|
245
|
-
calls** and holds it open for **60 seconds
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
healthy again.
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
498
|
+
calls** and holds it open for **60 seconds**. While it is open, an export
|
|
499
|
+
returns failure at once and does not use the network. A batch that fails is
|
|
500
|
+
put back in the queue at most 3 times. Against an open breaker these 3
|
|
501
|
+
attempts fail at once, so the spans are dropped. For the rest of the cooldown
|
|
502
|
+
the SDK does not send, also when your backend is healthy again.
|
|
503
|
+
|
|
504
|
+
The thresholds count **failed calls, not seconds**. When the 5th consecutive
|
|
505
|
+
failure occurs depends on your span rate and on how fast your endpoint fails.
|
|
506
|
+
A short failure that stays under 5 consecutive failed calls does not open the
|
|
507
|
+
breaker. Tracked as `F-SDKBLIP-001`.
|
|
508
|
+
|
|
509
|
+
One export call sends a batch at most 3 times. A 401 or 403 answer is sent
|
|
510
|
+
once in each export call: the endpoint refused the API key, and the same key
|
|
511
|
+
gets the same answer. At the first failed export of an outage (at most once in
|
|
512
|
+
5 minutes), the SDK writes the WARNING "spans are NOT reaching ...". It gives
|
|
513
|
+
the HTTP status of the last answer, or the error code when there was no answer.
|
|
514
|
+
For a 401 or 403 it tells you to check the API key. When the kind of failure
|
|
515
|
+
changes in one outage (for example a 401, then no answer), the SDK writes one more
|
|
516
|
+
WARNING. An endpoint URL with credentials (a user name or a password before the
|
|
517
|
+
host) is not supported: `fetch` does not send a request to it.
|
|
518
|
+
|
|
519
|
+
The SDK removes its API key from each text that it logs: in any case of letters,
|
|
520
|
+
and also when the key is percent-encoded. An endpoint is logged without its user
|
|
521
|
+
name, password and query. A secret that you put in another place of a URL (for
|
|
522
|
+
example in its path) is logged as you gave it.
|
|
258
523
|
|
|
259
524
|
## A note on running without an API key
|
|
260
525
|
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
526
|
+
With no API key (an empty one, or one of only whitespace, counts as none) the SDK
|
|
527
|
+
sends nothing to Risicare, whatever `RISICARE_TRACING`, `enabled` or `enable()`
|
|
528
|
+
says. Tracing is off:
|
|
529
|
+
`isEnabled()` is `false`, `flush()` returns `false`, and the metrics show
|
|
530
|
+
nothing exported. The SDK says so once, at `init()`, in one WARNING on stderr:
|
|
531
|
+
there is no API key, nothing is sent, `flush()` returns `false`, and how to set
|
|
532
|
+
the key. There is no WARNING when you turned tracing off on purpose
|
|
533
|
+
(`enabled: false`, `RISICARE_TRACING=false`).
|
|
534
|
+
|
|
535
|
+
The SDK also prints no span without a key, with `debug: true` too. It performs no
|
|
536
|
+
redaction of its own, so printing would put prompts, completions and anything
|
|
537
|
+
else in your attributes onto your stderr. (The Python SDK prints spans with
|
|
538
|
+
`debug=True` and no key. They are display only: never counted, never sent.)
|
|
539
|
+
|
|
540
|
+
The SDK trims the key. An `apiKey` option that is empty, or only whitespace, counts
|
|
541
|
+
as "not given": the SDK then uses `RISICARE_API_KEY`.
|
|
542
|
+
|
|
543
|
+
Not active means not true: `flush()` also returns `false` before `init()` and
|
|
544
|
+
with tracing off at `init()`.
|
|
267
545
|
|
|
268
546
|
## Requirements
|
|
269
547
|
|