risicare 0.7.0 → 0.8.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 +282 -63
- 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 +1113 -176
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +234 -42
- package/dist/index.d.ts +234 -42
- package/dist/index.js +1113 -176
- 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,72 @@ 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 and no
|
|
88
|
+
explicit setting, tracing is off (see "A note on running without an API key").
|
|
89
|
+
|
|
90
|
+
## Imports
|
|
91
|
+
|
|
92
|
+
The package has no default export. Use named imports or a namespace import.
|
|
93
|
+
`Span` and `Tracer` are types only: import them with `import type`.
|
|
94
|
+
|
|
95
|
+
```typescript
|
|
96
|
+
import { init, agent } from 'risicare';
|
|
97
|
+
import * as risicare from 'risicare';
|
|
98
|
+
import type { Span, Tracer } from 'risicare';
|
|
99
|
+
```
|
|
47
100
|
|
|
48
101
|
## Prompt content is NOT captured by default
|
|
49
102
|
|
|
50
|
-
|
|
103
|
+
**`traceContent` defaults to `false`** (since 0.5.2, the first published version with this default). Your prompts and completions
|
|
51
104
|
stay in your process. Everything else — model, token counts, latency, cost,
|
|
52
|
-
|
|
105
|
+
errors, and any attributes you set — is captured as normal, so the
|
|
53
106
|
dashboard, cost tracking and error diagnosis all work unchanged.
|
|
54
107
|
|
|
55
108
|
To send prompt and completion text as well, opt in:
|
|
@@ -59,6 +112,25 @@ init({ apiKey: 'rsk-...', traceContent: true });
|
|
|
59
112
|
// or set RISICARE_TRACE_CONTENT=true
|
|
60
113
|
```
|
|
61
114
|
|
|
115
|
+
**Which providers capture text.** With `traceContent: true`:
|
|
116
|
+
|
|
117
|
+
- `patchOpenAI` and `patchAnthropic` capture the prompt and the completion text.
|
|
118
|
+
They write the first 10 messages to `gen_ai.prompt.N.role` and
|
|
119
|
+
`gen_ai.prompt.N.content`. They write the completion to
|
|
120
|
+
`gen_ai.completion.content`. `patchAnthropic` also writes a string `system`
|
|
121
|
+
prompt to `gen_ai.system_prompt`. The SDK cuts each text at 10,000 characters
|
|
122
|
+
(Unicode code points). It cuts the system prompt at 5,000. `patchOpenAI` also
|
|
123
|
+
captures text for a client of an OpenAI-compatible host.
|
|
124
|
+
- For a streamed call, they capture the prompt only, not the completion.
|
|
125
|
+
- `patchGoogleAI`, `patchMistral`, `patchGroq`, `patchCohere`, `patchTogether`,
|
|
126
|
+
`patchOllama`, `patchHuggingFace`, `patchCerebras`, `patchBedrock` and
|
|
127
|
+
`patchVercelAI` capture no prompt or completion text.
|
|
128
|
+
|
|
129
|
+
**Error text is not covered by this switch.** The error message from a
|
|
130
|
+
provider can contain your prompt text. For example, a 400 error can repeat
|
|
131
|
+
part of the prompt. The SDK sends error messages also when `traceContent` is
|
|
132
|
+
off, because error diagnosis uses them.
|
|
133
|
+
|
|
62
134
|
**Upgrading from 0.5.0 or earlier?** This is a behaviour change: content that
|
|
63
135
|
used to be sent is no longer sent unless you opt in. In those versions the flag
|
|
64
136
|
also did not work for content you set by hand — `traceContent: false` did not
|
|
@@ -73,9 +145,9 @@ Since 0.7.0, the gate also covers the OpenTelemetry GenAI, OpenInference and
|
|
|
73
145
|
CrewAI content keys, for example `input.value`, `output.value`,
|
|
74
146
|
`gen_ai.input.messages` and `gen_ai.output.messages`.
|
|
75
147
|
|
|
76
|
-
If you want content captured but redacted first, use the `mask` hook
|
|
77
|
-
|
|
78
|
-
|
|
148
|
+
If you want content captured but redacted first, use the `mask` hook. It runs
|
|
149
|
+
on every content-bearing field of every span before export, for every
|
|
150
|
+
exporter:
|
|
79
151
|
|
|
80
152
|
```typescript
|
|
81
153
|
init({ apiKey: 'rsk-...', traceContent: true, mask: (key, value) => value });
|
|
@@ -87,31 +159,91 @@ init({ apiKey: 'rsk-...', traceContent: true, mask: (key, value) => value });
|
|
|
87
159
|
- **12 LLM providers** — OpenAI, Anthropic, Google, Mistral, Groq, Cohere, Together, Ollama, HuggingFace, Cerebras, Bedrock, Vercel AI
|
|
88
160
|
- **4 framework integrations** — LangChain, LangGraph, Instructor, LlamaIndex
|
|
89
161
|
- **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
|
|
162
|
+
- **Evaluation scores** — Rate agent quality with `score()`
|
|
163
|
+
- **Streaming** — `tracedStream()` traces an async iterator (see "Streaming" below)
|
|
164
|
+
- **Context propagation** — Automatic across `async/await`, `Promise` and `setTimeout`. An `EventEmitter` listener runs in the context of the `emit()` call
|
|
93
165
|
- **Zero runtime dependencies** — No bloat in your node_modules
|
|
94
166
|
- **Dual CJS/ESM** — Works with `require()` and `import`
|
|
95
167
|
- **Full TypeScript** — Strict types and IntelliSense out of the box
|
|
96
|
-
- **
|
|
97
|
-
- **
|
|
168
|
+
- **Background export** — Async batch export with circuit breaker and retry
|
|
169
|
+
- **Low cost when disabled** — a frozen no-op span
|
|
98
170
|
|
|
99
171
|
## LLM Providers
|
|
100
172
|
|
|
101
173
|
```typescript
|
|
174
|
+
import OpenAI from 'openai';
|
|
102
175
|
import { patchOpenAI } from 'risicare/openai';
|
|
103
176
|
import { patchAnthropic } from 'risicare/anthropic';
|
|
104
|
-
import {
|
|
177
|
+
import { patchGoogleAI } from 'risicare/google';
|
|
105
178
|
// ... and 9 more
|
|
106
179
|
|
|
107
180
|
const openai = patchOpenAI(new OpenAI());
|
|
108
|
-
//
|
|
181
|
+
// chat.completions.create and embeddings.create are now traced
|
|
109
182
|
```
|
|
110
183
|
|
|
111
184
|
All 12 providers:
|
|
112
185
|
|
|
113
186
|
`openai` · `anthropic` · `google` · `mistral` · `groq` · `cohere` · `together` · `ollama` · `huggingface` · `cerebras` · `bedrock` · `vercel-ai`
|
|
114
187
|
|
|
188
|
+
`patchOpenAI` also traces an OpenAI-compatible host (`baseURL`). It sets the
|
|
189
|
+
provider name (`gen_ai.system`) from the host for DeepSeek, Together, Groq, xAI,
|
|
190
|
+
Fireworks, Baseten, Novita and BytePlus (`api.byteplus.com` and
|
|
191
|
+
`ark.cn-beijing.byteplus.com`). Any other host is named `openai`.
|
|
192
|
+
|
|
193
|
+
### Streaming
|
|
194
|
+
|
|
195
|
+
The caller gets the provider's own promise and stream objects. The SDK counts
|
|
196
|
+
only the chunks that the caller reads. It does not read ahead. The span of a
|
|
197
|
+
stream ends once, when the stream ends, with `stream.end_reason`:
|
|
198
|
+
|
|
199
|
+
| `stream.end_reason` | When | Status |
|
|
200
|
+
|---|---|---|
|
|
201
|
+
| `done` | The caller read the stream to its end. | ok |
|
|
202
|
+
| `return` | The caller stopped early (`break`, `return()`). | ok |
|
|
203
|
+
| `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 |
|
|
204
|
+
| `error` | An error reached the caller. The span records it. | error |
|
|
205
|
+
| `handoff` | The caller took the data another way: `tee()`, `getReader()`, `toReadableStream()`, `pipeTo()`, `pipeThrough()` or `asResponse()`. | ok |
|
|
206
|
+
| `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 |
|
|
207
|
+
| `shutdown` | `shutdown()` ends every stream span that is still open, and exports it. | ok |
|
|
208
|
+
|
|
209
|
+
The span has `stream.chunk_count`: the number of chunks that the caller read.
|
|
210
|
+
It has the token counts that the chunks gave: the usage chunk (OpenAI needs
|
|
211
|
+
`stream_options: { include_usage: true }`; also Groq, Together, Cerebras,
|
|
212
|
+
Hugging Face), `message_start` and `message_delta` (Anthropic), the last
|
|
213
|
+
`usageMetadata` (Google), the chunk `usage` (Mistral), the last chunk with
|
|
214
|
+
`done` (Ollama), `message-end` (Cohere). A count that the stream did not give
|
|
215
|
+
stays empty. The span does not capture the streamed completion text.
|
|
216
|
+
|
|
217
|
+
Call `shutdown()` before the process stops. A span that is still open is lost
|
|
218
|
+
if the process stops without it.
|
|
219
|
+
|
|
220
|
+
Limits:
|
|
221
|
+
|
|
222
|
+
- Cohere: `stream.controller.abort()` does not stop a Cohere stream, so it is
|
|
223
|
+
not an abort. The request option `abortSignal` stops it, and is an abort.
|
|
224
|
+
- Google, the request `signal`: the Google SDK changes the abort into a
|
|
225
|
+
`GoogleGenerativeAIError`. A read after the abort ends the span as `error`,
|
|
226
|
+
not `abort`. An abort with no read after it ends as `garbage` or
|
|
227
|
+
`shutdown`, status ok.
|
|
228
|
+
- Mistral, the request `signal` (`fetchOptions.signal`): a read after the
|
|
229
|
+
abort gets an `AbortError`, and the span ends as `abort`. The SDK cannot see
|
|
230
|
+
this signal, so an abort with no read after it ends as `garbage` or
|
|
231
|
+
`shutdown`, status ok.
|
|
232
|
+
- Google `result.response`: the Google SDK gives the aggregated response also
|
|
233
|
+
when nobody reads `result.stream`. If the caller never takes `result.stream`,
|
|
234
|
+
the span ends as `done` when `result.response` settles, with the tokens of
|
|
235
|
+
the aggregated response and `stream.chunk_count` = 0 (`error` if it
|
|
236
|
+
rejects). If the caller takes `result.stream`, the stream decides the end.
|
|
237
|
+
A stream that the caller takes after the span ended is not counted.
|
|
238
|
+
- `handoff`: the SDK does not see the chunks after the handoff, so the chunk
|
|
239
|
+
and token counts cover only the chunks read before it.
|
|
240
|
+
- Bedrock (`ConverseStreamCommand`): the SDK does not read the stream. The
|
|
241
|
+
span ends when `send()` returns. It has no token counts.
|
|
242
|
+
- Vercel AI (`tracedStreamText`): the span ends through the `streamText`
|
|
243
|
+
callbacks: `onFinish` (`done`, with the usage), `onAbort` (`abort`) or an
|
|
244
|
+
error chunk (`error`). With no callback, it ends as `garbage` or at
|
|
245
|
+
`shutdown()`.
|
|
246
|
+
|
|
115
247
|
## Framework Integrations
|
|
116
248
|
|
|
117
249
|
```typescript
|
|
@@ -130,13 +262,24 @@ const client = patchInstructor(instructor);
|
|
|
130
262
|
|
|
131
263
|
// LlamaIndex
|
|
132
264
|
import { RisicareLlamaIndexHandler } from 'risicare/llamaindex';
|
|
265
|
+
const liHandler = new RisicareLlamaIndexHandler();
|
|
266
|
+
for (const name of RisicareLlamaIndexHandler.EVENT_NAMES) {
|
|
267
|
+
Settings.callbackManager.on(name, (e) => liHandler.onEvent(e)); // Settings from 'llamaindex'
|
|
268
|
+
}
|
|
133
269
|
```
|
|
134
270
|
|
|
271
|
+
The LangChain and LlamaIndex handlers give one LLM span for each model call.
|
|
272
|
+
Use one handler: two handler instances on one call (for example one in the model
|
|
273
|
+
constructor and one in `invoke`) give two LLM spans. LangChain's `ChatOpenAI` and LlamaIndex's `OpenAI` make their own OpenAI client.
|
|
274
|
+
`patchOpenAI` changes only the client that you give to it, so it does not add a
|
|
275
|
+
second span to these calls. You need `withSuppression()` only when the same call
|
|
276
|
+
also goes through a client that you patched.
|
|
277
|
+
|
|
135
278
|
## Core API
|
|
136
279
|
|
|
137
280
|
```typescript
|
|
138
281
|
import {
|
|
139
|
-
init, shutdown,
|
|
282
|
+
init, flush, shutdown, // Lifecycle
|
|
140
283
|
agent, session, // Identity & grouping
|
|
141
284
|
traceThink, traceDecide, traceAct, // Decision phases
|
|
142
285
|
reportError, score, // Diagnosis & evaluation
|
|
@@ -144,48 +287,100 @@ import {
|
|
|
144
287
|
} from 'risicare';
|
|
145
288
|
|
|
146
289
|
init({ apiKey, endpoint }) // Initialize SDK
|
|
147
|
-
agent(
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
await
|
|
151
|
-
await
|
|
152
|
-
await
|
|
290
|
+
// agent(), session() and the trace* functions are WRAPPER FACTORIES:
|
|
291
|
+
// they return a function that you then call. Note the trailing ().
|
|
292
|
+
await agent({ name }, fn)() // Run fn with agent identity
|
|
293
|
+
await session({ sessionId, userId }, fn)() // Run fn in a user session
|
|
294
|
+
await traceThink('analyze', fn)()
|
|
295
|
+
await traceDecide('choose', fn)()
|
|
296
|
+
await traceAct('execute', fn)()
|
|
153
297
|
reportError(error) // Report caught errors for diagnosis
|
|
154
298
|
score(traceId, 'quality', 0.92) // Record evaluation score [0.0-1.0]
|
|
155
299
|
tracedStream(asyncIterable, 'stream') // Trace async iterators
|
|
156
|
-
await
|
|
300
|
+
await flush(5000) // Wait for delivery; false when a span or a score was lost
|
|
301
|
+
await shutdown(5000) // Deliver what it can in the time, then stop
|
|
157
302
|
```
|
|
158
303
|
|
|
304
|
+
## Delivery: flush, shutdown and metrics
|
|
305
|
+
|
|
306
|
+
- `await flush(timeoutMs?)` waits for the queued spans and the pending scores
|
|
307
|
+
(default 5000 ms). It returns `true` only when nothing is queued, no batch is
|
|
308
|
+
in flight, and no span was dropped or rejected and no score failed since the
|
|
309
|
+
previous `flush()` returned (or since `init()`, for the first call). A loss
|
|
310
|
+
makes the next `flush()` return `false` one time, also when it occurred while
|
|
311
|
+
no flush ran. It returns `false` at its deadline. `flush()` only waits. It
|
|
312
|
+
does not stop a request that is already sent. With more than one exporter,
|
|
313
|
+
a batch counts as delivered when the first exporter that succeeds takes it:
|
|
314
|
+
`flush()` can then return `true` while another exporter refused the batch.
|
|
315
|
+
- `await shutdown(timeoutMs?)` is the call that ends a process in a fixed time
|
|
316
|
+
(default 5000 ms). At the deadline it stops the export in flight. It counts
|
|
317
|
+
the spans that it did not deliver as `shutdown_residue`, with one WARNING.
|
|
318
|
+
- A timeout that is not a finite number means 5000 ms.
|
|
319
|
+
- `getMetrics()` gives `exportedSpans` (spans that the backend accepted),
|
|
320
|
+
`rejectedSpans`, `droppedSpans`, `droppedSpansByReason` (`queue_full`,
|
|
321
|
+
`transport_refused`, `shutdown_residue`, `unacknowledged`), `failedExports`,
|
|
322
|
+
`failedScores`, the queue numbers and `sdkState`. `unacknowledged` counts
|
|
323
|
+
spans that were sent, or that could not be serialized, and that the
|
|
324
|
+
backend's answer did not account for.
|
|
325
|
+
- `score()` stops its request after 2000 ms and does not follow a redirect. A
|
|
326
|
+
status of 300 or more, an error or a timeout adds 1 to `failedScores`. The
|
|
327
|
+
first failure writes one WARNING at once. Failures in the next 10 seconds
|
|
328
|
+
are counted, and the next WARNING gives their number.
|
|
329
|
+
At most 50 score requests run at one time. Up to 1,000 scores wait for a free
|
|
330
|
+
slot, with no timer: the 2000 ms bound starts when the request starts. A score
|
|
331
|
+
that comes when 1,000 already wait fails at once and is counted. When the bound
|
|
332
|
+
of `flush()` or `shutdown()` ends, the scores that still wait fail and are not
|
|
333
|
+
sent.
|
|
334
|
+
|
|
159
335
|
## Error Diagnosis
|
|
160
336
|
|
|
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.
|
|
337
|
+
> **Beta.** The Risicare service detects an error, diagnoses it and suggests a
|
|
338
|
+
> fix. The diagnosis runs on the service, with Together.AI Llama-3.3-70B.
|
|
339
|
+
> Suggested fixes land in your dashboard as `status=draft` for human review.
|
|
340
|
+
> Automatic deployment, A/B rollout and learning from outcomes are not
|
|
341
|
+
> available. Treat this as **AI-assisted error diagnosis**.
|
|
167
342
|
|
|
168
|
-
When your agent fails
|
|
343
|
+
When your agent fails:
|
|
169
344
|
|
|
170
|
-
1.
|
|
171
|
-
|
|
172
|
-
|
|
345
|
+
1. The SDK records the error on the span and gives it an error code
|
|
346
|
+
(`error.code`). The taxonomy has 154 codes in 10 modules (TOOL, MEMORY,
|
|
347
|
+
REASONING, OUTPUT and others). The SDK's own rules give 18 of them. An
|
|
348
|
+
error that no rule matches gets a 19th, `TOOL.EXECUTION.CRASHED`.
|
|
349
|
+
2. The Risicare service diagnoses the root cause.
|
|
350
|
+
3. The service writes a fix suggestion that you can review in the dashboard
|
|
351
|
+
and apply manually.
|
|
173
352
|
|
|
174
353
|
```typescript
|
|
175
354
|
try {
|
|
176
355
|
await myAgent(input);
|
|
177
356
|
} catch (error) {
|
|
178
|
-
reportError(error); //
|
|
357
|
+
reportError(error); // Records the error for diagnosis; the fix lands as a draft for review
|
|
179
358
|
}
|
|
180
359
|
```
|
|
181
360
|
|
|
182
361
|
## Fix application is off by default
|
|
183
362
|
|
|
184
|
-
**Since 0.7.0, FixRuntime starts only when you opt in.**
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
363
|
+
**Since 0.7.0, FixRuntime starts only when you opt in.** During the beta, the
|
|
364
|
+
Risicare service does not give fixes to customer projects, so FixRuntime has no
|
|
365
|
+
effect for them. Through 0.6.0, FixRuntime started automatically when you set an
|
|
366
|
+
API key.
|
|
367
|
+
|
|
368
|
+
When FixRuntime is on, it reads the active fixes for your project from Risicare.
|
|
369
|
+
The fix interceptor enforces guard fixes on these paths only: `interceptCall` and
|
|
370
|
+
`interceptResponse` on the runtime, and the input guards of the patched OpenAI
|
|
371
|
+
chat call. The guards do not run when a framework integration suppresses provider
|
|
372
|
+
instrumentation. A failed input guard throws `GuardRejectedError` before the LLM
|
|
373
|
+
call. The input guards check messages that have text content: a string, or the
|
|
374
|
+
`text` parts of a list. A guard pattern that is not usable (not a string, empty,
|
|
375
|
+
longer than 500 characters, or JavaScript cannot use it) rejects the call. The
|
|
376
|
+
provider path does not apply prompt, parameter or fallback fixes.
|
|
377
|
+
|
|
378
|
+
Each SDK uses its own regular-expression engine. These constructs can give a
|
|
379
|
+
different result in JavaScript and Python: `$` before a final newline, Unicode
|
|
380
|
+
case folding, `\d` and `\w` on non-ASCII text, and a `]` first in a class.
|
|
381
|
+
JavaScript rejects a pattern that contains `\N{...}` or `\U........`. A pattern
|
|
382
|
+
has no time bound: a pattern with nested repeats can take a very long time on a
|
|
383
|
+
long input.
|
|
189
384
|
|
|
190
385
|
When FixRuntime is off, the SDK does not request `/fixes/active`, and it does
|
|
191
386
|
not change your LLM calls. Tracing, error reporting and scores are not affected.
|
|
@@ -226,39 +421,63 @@ const myAgent = agent({ name: 'planner', role: 'coordinator' }, async (input) =>
|
|
|
226
421
|
|
|
227
422
|
## Sessions
|
|
228
423
|
|
|
229
|
-
Group traces from the same user conversation
|
|
424
|
+
Group traces from the same user conversation. `withSession` runs the callback
|
|
425
|
+
now and returns its result:
|
|
230
426
|
|
|
231
427
|
```typescript
|
|
232
|
-
|
|
428
|
+
import { withSession } from 'risicare';
|
|
429
|
+
|
|
430
|
+
const result = await withSession(
|
|
233
431
|
{ sessionId: 'sess-abc123', userId: 'user-456' },
|
|
234
432
|
() => myAgent(userMessage)
|
|
235
433
|
);
|
|
236
434
|
```
|
|
237
435
|
|
|
436
|
+
`session()` does not run the callback. It returns a wrapped function, which you
|
|
437
|
+
call later, for example once for each request.
|
|
438
|
+
|
|
238
439
|
## Known limitation — span loss during a backend outage
|
|
239
440
|
|
|
240
|
-
The SDK does **not**
|
|
241
|
-
|
|
242
|
-
|
|
441
|
+
The SDK does **not** keep spans through a long outage of the Risicare backend.
|
|
442
|
+
Nothing throws in your application. The SDK writes a WARNING, `flush()`
|
|
443
|
+
returns `false`, and `getMetrics()` counts the lost spans in
|
|
444
|
+
`droppedSpansByReason.transport_refused`.
|
|
243
445
|
|
|
244
446
|
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
|
-
|
|
447
|
+
calls** and holds it open for **60 seconds**. While it is open, an export
|
|
448
|
+
returns failure at once and does not use the network. A batch that fails is
|
|
449
|
+
put back in the queue at most 3 times. Against an open breaker these 3
|
|
450
|
+
attempts fail at once, so the spans are dropped. For the rest of the cooldown
|
|
451
|
+
the SDK does not send, also when your backend is healthy again.
|
|
452
|
+
|
|
453
|
+
The thresholds count **failed calls, not seconds**. When the 5th consecutive
|
|
454
|
+
failure occurs depends on your span rate and on how fast your endpoint fails.
|
|
455
|
+
A short failure that stays under 5 consecutive failed calls does not open the
|
|
456
|
+
breaker. Tracked as `F-SDKBLIP-001`.
|
|
457
|
+
|
|
458
|
+
One export call sends a batch at most 3 times. A 401 or 403 answer is sent
|
|
459
|
+
once in each export call: the endpoint refused the API key, and the same key
|
|
460
|
+
gets the same answer. At the first failed export of an outage (at most once in
|
|
461
|
+
5 minutes), the SDK writes the WARNING "spans are NOT reaching ...". It gives
|
|
462
|
+
the HTTP status of the last answer, or the error code when there was no answer.
|
|
463
|
+
For a 401 or 403 it tells you to check the API key. When the kind of failure
|
|
464
|
+
changes in one outage (for example a 401, then no answer), the SDK writes one more
|
|
465
|
+
WARNING. An endpoint URL with credentials (a user name or a password before the
|
|
466
|
+
host) is not supported: `fetch` does not send a request to it.
|
|
467
|
+
|
|
468
|
+
The SDK removes its API key from each text that it logs: in any case of letters,
|
|
469
|
+
and also when the key is percent-encoded. An endpoint is logged without its user
|
|
470
|
+
name, password and query. A secret that you put in another place of a URL (for
|
|
471
|
+
example in its path) is logged as you gave it.
|
|
258
472
|
|
|
259
473
|
## A note on running without an API key
|
|
260
474
|
|
|
261
|
-
If
|
|
475
|
+
If you give no API key, or an empty one, tracing is off. This applies when
|
|
476
|
+
you do not set tracing explicitly. The SDK then writes one WARNING to stderr.
|
|
477
|
+
The SDK sends no span.
|
|
478
|
+
|
|
479
|
+
If tracing is enabled explicitly (`enabled: true` or `RISICARE_TRACING=true`)
|
|
480
|
+
but no API key is configured, the SDK emits a one-time
|
|
262
481
|
`console.warn` and **drops** the spans. It deliberately does **not** print span
|
|
263
482
|
payloads to your console: the SDK performs no redaction of its own, so printing
|
|
264
483
|
would put prompts, completions and anything else in your attributes onto your
|