@mainwave/cli 0.11.0 → 0.12.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 +168 -13
- package/dist/adapters/claude-code.js +3 -3
- package/dist/adapters/claude-desktop.js +35 -1
- package/dist/adapters/cursor.js +7 -2
- package/dist/adapters/kiro.js +13 -8
- package/dist/commands.js +217 -0
- package/dist/core/apply.js +3 -3
- package/dist/core/auth-commands.js +2 -1
- package/dist/core/codecs/kiro-hooks-json.js +1 -1
- package/dist/core/doctor.js +71 -8
- package/dist/core/entry-script.js +2 -3
- package/dist/core/format.js +0 -1
- package/dist/core/hook-copies.js +157 -0
- package/dist/core/install-hooks.js +144 -15
- package/dist/core/interview.js +8 -2
- package/dist/core/markers.js +86 -22
- package/dist/core/redaction.js +179 -0
- package/dist/core/skills.js +3 -11
- package/dist/core/status.js +21 -1
- package/dist/core/store.js +254 -4
- package/dist/core/wizard.js +91 -6
- package/dist/main.js +163 -162
- package/hooks/kiro-otlp.mjs +10 -1
- package/hooks/mainwave-hook.mjs +11 -1
- package/hooks/marker-core.mjs +56 -2
- package/hooks/matchers.json +1 -1
- package/hooks/redaction-data.mjs +201 -0
- package/hooks/redaction-json.mjs +215 -0
- package/hooks/redaction-pattern.mjs +503 -0
- package/hooks/redaction.d.mts +84 -0
- package/hooks/redaction.mjs +701 -0
- package/package.json +3 -1
- package/skills/mainwave-instrument/SKILL.md +24 -6
- package/skills/mainwave-instrument/reference/frameworks.md +4 -2
- package/skills/mainwave-instrument/reference/troubleshooting.md +4 -0
- package/skills/mainwave-instrument-node/SKILL.md +83 -38
- package/skills/mainwave-instrument-node/reference/api.md +16 -16
- package/skills/mainwave-instrument-node/reference/frameworks.md +42 -27
- package/skills/mainwave-instrument-node/reference/troubleshooting.md +11 -7
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mainwave/cli",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.12.0",
|
|
4
4
|
"description": "Setup wizard for connecting third-party coding tools to Mainwave AI.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
@@ -34,6 +34,7 @@
|
|
|
34
34
|
"lint:fix": "oxlint --fix .",
|
|
35
35
|
"format": "prettier --write .",
|
|
36
36
|
"format:check": "prettier --check .",
|
|
37
|
+
"knip": "knip",
|
|
37
38
|
"test": "vitest",
|
|
38
39
|
"test:run": "vitest run",
|
|
39
40
|
"test:hooks": "node tests/hooks/check-node.mjs && node --import ./tests/hooks/setup.mjs --test tests/hooks/*.test.mjs",
|
|
@@ -47,6 +48,7 @@
|
|
|
47
48
|
"devDependencies": {
|
|
48
49
|
"@hey-api/openapi-ts": "^0.99.0",
|
|
49
50
|
"@types/node": "22.20.5",
|
|
51
|
+
"knip": "6.41.0",
|
|
50
52
|
"lefthook": "2.2.1",
|
|
51
53
|
"oxlint": "1.87.0",
|
|
52
54
|
"prettier": "3.9.10",
|
|
@@ -39,9 +39,14 @@ Answer these from the codebase, not from assumption:
|
|
|
39
39
|
- **What is one "unit of work"?** A ticket triaged, a question answered, a
|
|
40
40
|
document processed. This becomes a run, and it is the level a business
|
|
41
41
|
operator reads results at — not one HTTP request, not one LLM call.
|
|
42
|
-
- **Is OpenTelemetry already set up?**
|
|
43
|
-
`TracerProvider`,
|
|
44
|
-
|
|
42
|
+
- **Is OpenTelemetry already set up?** Search for `set_tracer_provider`,
|
|
43
|
+
`TracerProvider`, `opentelemetry-instrument` in the start command,
|
|
44
|
+
Dockerfile, or Procfile, and `sentry_sdk.init` when Sentry runs on
|
|
45
|
+
OpenTelemetry. If the app registers its own provider, the SDK detects it and
|
|
46
|
+
runs in coexist mode. Do not remove their setup. Note where it runs, because
|
|
47
|
+
`init()` goes after it, as section 3 describes. The `opentelemetry-instrument`
|
|
48
|
+
launcher registers its provider before any app code runs, so an `init()` in
|
|
49
|
+
the app already comes after it.
|
|
45
50
|
|
|
46
51
|
## 2. Install with narrow extras
|
|
47
52
|
|
|
@@ -65,9 +70,22 @@ mainwave.init(service_name="support-triage")
|
|
|
65
70
|
```
|
|
66
71
|
|
|
67
72
|
`api_key` and `use_case_id` come from `MAINWAVE_API_KEY` and
|
|
68
|
-
`MAINWAVE_USE_CASE_ID` when not passed. Call it **
|
|
69
|
-
|
|
70
|
-
patch libraries
|
|
73
|
+
`MAINWAVE_USE_CASE_ID` when not passed. Call it **after** the app's own
|
|
74
|
+
OpenTelemetry setup and **before** the framework does its work. Instrumentors
|
|
75
|
+
patch libraries when `init()` wires them, so a framework that has already done
|
|
76
|
+
its work is not captured. With no OpenTelemetry setup in the app, that means
|
|
77
|
+
the top of the entry point, before the framework imports.
|
|
78
|
+
|
|
79
|
+
```python
|
|
80
|
+
trace.set_tracer_provider(provider) # the app's own setup, if it has one
|
|
81
|
+
mainwave.init(service_name="support-triage") # then Mainwave
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
Never put `init()` before the app's own provider is registered. `init()` would
|
|
85
|
+
install the SDK's provider as the global one, OpenTelemetry would refuse the
|
|
86
|
+
app's provider, and the app's own backend would stop receiving spans. The
|
|
87
|
+
only sign is an `Overriding of current TracerProvider is not allowed`
|
|
88
|
+
warning, which OpenTelemetry logs.
|
|
71
89
|
|
|
72
90
|
Rules that bite:
|
|
73
91
|
|
|
@@ -156,8 +156,10 @@ instead of installing one, and forwards spans under the host's resource
|
|
|
156
156
|
untouched.
|
|
157
157
|
|
|
158
158
|
Leave their setup alone. Do not remove their exporter, do not replace their
|
|
159
|
-
provider, do not
|
|
160
|
-
|
|
159
|
+
provider, and do not call `init()` before their `TracerProvider` is registered.
|
|
160
|
+
In that order OpenTelemetry keeps the SDK's provider and refuses theirs, and
|
|
161
|
+
their backend stops receiving spans. Called after their setup, `init()` leaves
|
|
162
|
+
their existing backend receiving everything it received before.
|
|
161
163
|
|
|
162
164
|
Only LLM-bearing traces are forwarded to Mainwave — the host's HTTP, database,
|
|
163
165
|
and background-job traces stay out. That filtering is what makes sharing a
|
|
@@ -34,6 +34,10 @@ the span.
|
|
|
34
34
|
a no-op that logs and returns. Check the deployment's env, not just the shell.
|
|
35
35
|
- In a web app, confirm `init()` is in the startup hook and that the hook
|
|
36
36
|
actually runs under the process manager in use.
|
|
37
|
+
- If the app has its own OpenTelemetry setup and its own backend stopped
|
|
38
|
+
receiving spans, `init()` ran before that setup. Look for an
|
|
39
|
+
`Overriding of current TracerProvider is not allowed` warning. Move `init()`
|
|
40
|
+
after the code that calls `trace.set_tracer_provider(...)`.
|
|
37
41
|
|
|
38
42
|
## 3. The process exited before the batch drained
|
|
39
43
|
|
|
@@ -25,19 +25,23 @@ Answer these from the codebase, not from assumption:
|
|
|
25
25
|
`ai` (with `@ai-sdk/otel`), `openai`, `@anthropic-ai/sdk`. More than one can
|
|
26
26
|
apply. Note the installed versions: eve `>=0.66.3 <0.70.0`, `ai` `^7` with
|
|
27
27
|
`@ai-sdk/otel` `^1`, `openai` `>=4.19.0 <8`, `@anthropic-ai/sdk`
|
|
28
|
-
`>=0.
|
|
29
|
-
not wire around it. `@anthropic-ai/sdk` 0.134.0
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
the app pins `@anthropic-ai/sdk` below 0.134.0.
|
|
28
|
+
`>=0.134.0`. A version outside its range is not instrumented: report it, do
|
|
29
|
+
not wire around it. An `@anthropic-ai/sdk` below 0.134.0 records no spans
|
|
30
|
+
at all: tell the user to upgrade it. From 0.134.0 the client records its own
|
|
31
|
+
spans, and Mainwave's middleware adds what they leave out (section 6).
|
|
33
32
|
- **Does the app already register OpenTelemetry?** Search for `@vercel/otel`
|
|
34
33
|
(`registerOTel`), `@opentelemetry/sdk-node` (`NodeSDK`),
|
|
35
|
-
`NodeTracerProvider`, a Next.js
|
|
36
|
-
`agent/instrumentation/` directory. If
|
|
37
|
-
provider, the app is a **host**: do not call
|
|
34
|
+
`NodeTracerProvider`, `@sentry/node` (`Sentry.init`), a Next.js
|
|
35
|
+
`instrumentation.ts`, or an eve `agent/instrumentation/` directory. If
|
|
36
|
+
something registers the tracer provider, the app is a **host**: do not call
|
|
37
|
+
`init()` into it. Note where that setup runs, because Mainwave joins it
|
|
38
|
+
through `createSpanProcessor()`, as section 5b describes.
|
|
38
39
|
- **Where does the process start?** The server entry, the worker bootstrap, the
|
|
39
40
|
script's first file, the Next.js `instrumentation.ts` `register()`. That is
|
|
40
|
-
where `init()` or the host wiring goes.
|
|
41
|
+
where `init()` or the host wiring goes. `init()` goes before the framework
|
|
42
|
+
does its work, because it patches libraries when it runs. Host wiring is
|
|
43
|
+
different: `createSpanProcessor()` installs no hooks, and section 6 says how
|
|
44
|
+
the clients attach.
|
|
41
45
|
- **ESM or CommonJS, bundled or not, and what runtime?** This picks the attach
|
|
42
46
|
path in section 6. Plain `node app.mjs` is not bundled; Vercel Functions,
|
|
43
47
|
Next.js, and anything built by a bundler are.
|
|
@@ -75,8 +79,9 @@ npm install @mainwave/sdk # or: pnpm add @mainwave/sdk / yarn add @mainwave
|
|
|
75
79
|
app already depends on another version of it, stop and report the conflict.
|
|
76
80
|
The framework and provider packages are optional peers the application already
|
|
77
81
|
installs; **install none of them for the user, and never install an
|
|
78
|
-
OpenInference or Traceloop package**: the SDK carries its own OpenAI
|
|
79
|
-
Anthropic
|
|
82
|
+
OpenInference or Traceloop package**: the SDK carries its own OpenAI
|
|
83
|
+
instrumentation and Anthropic middleware, and a second instrumentation traces
|
|
84
|
+
every call twice.
|
|
80
85
|
|
|
81
86
|
If the install fails with "package not found", report that
|
|
82
87
|
`@mainwave/sdk` is not yet published to npm and stop. Do not substitute another
|
|
@@ -171,10 +176,26 @@ A plain `NodeTracerProvider` takes
|
|
|
171
176
|
- An `init()` call that finds another provider registered, with no
|
|
172
177
|
`createSpanProcessor()` wired in, exports nothing and logs one warning.
|
|
173
178
|
Do not "fix" that by removing the host's provider.
|
|
179
|
+
- Mainwave joins the host's setup through `createSpanProcessor()` and never
|
|
180
|
+
registers ahead of it. An `init()` that runs first registers Mainwave's
|
|
181
|
+
provider as the global one. OpenTelemetry keeps the first global provider
|
|
182
|
+
and refuses the host's, so the host's own backend silently stops receiving
|
|
183
|
+
spans. The only sign is an
|
|
184
|
+
`@opentelemetry/api: Attempted duplicate registration of API: trace` error on
|
|
185
|
+
OpenTelemetry's diagnostic channel, and it prints only when the app has set a
|
|
186
|
+
diagnostic logger. Remove an `init()` that sits ahead of the host's setup and
|
|
187
|
+
wire `createSpanProcessor()` into the host instead.
|
|
188
|
+
- For a setup not shown above, such as `@sentry/node` or another monitoring
|
|
189
|
+
SDK that registers OpenTelemetry for you, pass `createSpanProcessor()`
|
|
190
|
+
wherever that setup accepts span processors. Check that setup's own
|
|
191
|
+
documentation for the option. If it accepts none, report that to the user
|
|
192
|
+
and do not call `init()`.
|
|
174
193
|
|
|
175
194
|
## 5c. Owned mode: `init()` at process start
|
|
176
195
|
|
|
177
|
-
For an application with no OpenTelemetry setup of its own
|
|
196
|
+
For an application with no OpenTelemetry setup of its own. If the survey
|
|
197
|
+
found one, use section 5b instead. `init()` here would register the global
|
|
198
|
+
provider ahead of it.
|
|
178
199
|
|
|
179
200
|
```ts
|
|
180
201
|
import { init } from '@mainwave/sdk'
|
|
@@ -240,11 +261,11 @@ passes `mainwaveTelemetry({ tracer })`.
|
|
|
240
261
|
**OpenAI (`openai`) and Anthropic (`@anthropic-ai/sdk`) called directly:** choose
|
|
241
262
|
by how the app starts.
|
|
242
263
|
|
|
243
|
-
| The app is | Attach
|
|
244
|
-
| --------------------------------------------------------------------- |
|
|
245
|
-
| A plain Node process you start (`node app.mjs`, a worker, a script) | `node --import @mainwave/sdk/register app.mjs`
|
|
246
|
-
| Bundled, or on Vercel Functions or Next.js, or the flag cannot be set | `instrument({ openai
|
|
247
|
-
| A host that registers its own OpenTelemetry instrumentations | `new OpenAIInstrumentation()`
|
|
264
|
+
| The app is | Attach |
|
|
265
|
+
| --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
266
|
+
| A plain Node process you start (`node app.mjs`, a worker, a script) | `node --import @mainwave/sdk/register app.mjs` |
|
|
267
|
+
| Bundled, or on Vercel Functions or Next.js, or the flag cannot be set | `instrument({ openai })`, and `mainwaveMiddleware()` in every Anthropic client, after the host wiring (host mode, no `init()`), or after `init()` (owned mode) |
|
|
268
|
+
| A host that registers its own OpenTelemetry instrumentations | `new OpenAIInstrumentation()` from `@mainwave/sdk/openai` via `registerInstrumentations`; `mainwaveMiddleware()` in every Anthropic client |
|
|
248
269
|
|
|
249
270
|
The loader flag covers static imports, dynamic `import()`, and `require()`,
|
|
250
271
|
for both clients in one process. Put it where the process starts (the
|
|
@@ -252,47 +273,71 @@ for both clients in one process. Put it where the process starts (the
|
|
|
252
273
|
@mainwave/sdk/register'`), and still initialize in the app: `init()` in owned
|
|
253
274
|
mode, or the `createSpanProcessor()` wiring from section 5b in host mode (no
|
|
254
275
|
`init()`). In owned mode, a CommonJS app that calls `init()` before its first
|
|
255
|
-
`require()` of
|
|
256
|
-
`
|
|
276
|
+
`require()` of `openai` needs no flag, and `init()` itself adds Mainwave's
|
|
277
|
+
middleware, last in the list, to every `Anthropic`, `AnthropicBedrock` and
|
|
278
|
+
`AnthropicVertex` client the app constructs after it, in ES module and
|
|
279
|
+
CommonJS apps alike. The flag also covers an Anthropic client constructed
|
|
280
|
+
before `init()`, such as one at the top level of a module the entry imports;
|
|
281
|
+
without it, give that client `mainwaveMiddleware()`. A host-mode app needs the
|
|
282
|
+
flag or the explicit path.
|
|
257
283
|
|
|
258
284
|
The explicit path, for bundled and serverless hosts (on Vercel Functions and in
|
|
259
|
-
bundled apps this is the supported way; do not use the flag there)
|
|
260
|
-
|
|
285
|
+
bundled apps this is the supported way; do not use the flag there): pass the
|
|
286
|
+
`openai` module to `instrument()`, and add `mainwaveMiddleware()` to the
|
|
287
|
+
`middleware` option of every `@anthropic-ai/sdk` client the app constructs.
|
|
288
|
+
Owned mode calls `init()` first:
|
|
261
289
|
|
|
262
290
|
```ts
|
|
263
|
-
import
|
|
291
|
+
import Anthropic from '@anthropic-ai/sdk'
|
|
264
292
|
import * as openai from 'openai'
|
|
265
293
|
import { init, instrument } from '@mainwave/sdk'
|
|
294
|
+
import { mainwaveMiddleware } from '@mainwave/sdk/anthropic'
|
|
266
295
|
|
|
267
296
|
init()
|
|
268
|
-
instrument({ openai
|
|
297
|
+
instrument({ openai })
|
|
298
|
+
const anthropic = new Anthropic({ middleware: [mainwaveMiddleware()] })
|
|
269
299
|
```
|
|
270
300
|
|
|
271
|
-
Host mode (Next.js with `@vercel/otel`, `NodeSDK`)
|
|
272
|
-
|
|
301
|
+
Host mode (Next.js with `@vercel/otel`, `NodeSDK`) attaches after the section
|
|
302
|
+
5b wiring and never calls `init()`:
|
|
273
303
|
|
|
274
304
|
```ts
|
|
275
|
-
import
|
|
305
|
+
import Anthropic from '@anthropic-ai/sdk'
|
|
276
306
|
import * as openai from 'openai'
|
|
277
307
|
import { instrument } from '@mainwave/sdk'
|
|
308
|
+
import { mainwaveMiddleware } from '@mainwave/sdk/anthropic'
|
|
278
309
|
|
|
279
310
|
// Runs after registerOTel(...) or sdk.start() has received createSpanProcessor().
|
|
280
|
-
instrument({ openai
|
|
311
|
+
instrument({ openai })
|
|
312
|
+
const anthropic = new Anthropic({ middleware: [mainwaveMiddleware()] })
|
|
281
313
|
```
|
|
282
314
|
|
|
283
|
-
|
|
315
|
+
If the app already passes its own `middleware` to an Anthropic client, put
|
|
316
|
+
`mainwaveMiddleware()` last in that list, so it records what the app's own
|
|
317
|
+
client-level middleware sends. Middleware passed to a single call
|
|
318
|
+
(`messages.create(body, { middleware })`) runs after Mainwave's has recorded:
|
|
319
|
+
if the app scrubs data there, move the scrubber to client level
|
|
320
|
+
(`new Anthropic({ middleware })` or `client.withOptions({ middleware })`) or
|
|
321
|
+
tell the user to use the SDK's redaction rules. Edit every place the app constructs
|
|
322
|
+
a client (`new Anthropic(...)`, `new AnthropicBedrock(...)`,
|
|
323
|
+
`new AnthropicVertex(...)`); a `withOptions()` copy keeps the middleware of the
|
|
324
|
+
client it copies. `instrument({ anthropic })` no longer exists: replace it with
|
|
325
|
+
the middleware when the app has it.
|
|
326
|
+
|
|
327
|
+
**Pass every `openai` module copy the app loads.** An ES module import and a
|
|
284
328
|
`require()` result are two different copies, and a copy that was not passed is
|
|
285
329
|
not traced: `instrument({ openai: [esm, required] })`. `instrument()` returns
|
|
286
|
-
`{ openai: 'patched' }`, `'already'` (attached before), `'
|
|
287
|
-
(
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
330
|
+
`{ openai: 'patched' }`, `'already'` (attached before), or `'unrecognized'`
|
|
331
|
+
(what it was given is not the module), and never throws. Read the result: an
|
|
332
|
+
`'unrecognized'` means the wiring is wrong, and a client missing from the spans
|
|
333
|
+
usually means the code calls a copy you did not pass.
|
|
334
|
+
|
|
335
|
+
An ES module app that uses neither the flag nor the explicit path gets no
|
|
336
|
+
spans from `openai`, and one not-attached warning naming both options. Its
|
|
337
|
+
`@anthropic-ai/sdk` clients constructed after `init()` get the middleware all
|
|
338
|
+
the same; one constructed before `init()` sends spans without the request
|
|
339
|
+
content, tool definitions and raw stream output, and the SDK logs one warning
|
|
340
|
+
when they arrive.
|
|
296
341
|
`init({ skipInstrumentations: ['openai'] })` turns the SDK's hooks off when
|
|
297
342
|
another instrumentation for that client is already running (it would trace
|
|
298
343
|
every call twice).
|
|
@@ -5,20 +5,20 @@ the package is internal: do not import from `dist/` paths.
|
|
|
5
5
|
|
|
6
6
|
## Root exports (`@mainwave/sdk`)
|
|
7
7
|
|
|
8
|
-
| Export | Use
|
|
9
|
-
| ---------------------------------------------------------------- |
|
|
10
|
-
| `init(options)` | Owned mode: build a tracer provider and export every LLM trace. Once per process. Throws `MainwaveConfigError` for a missing key
|
|
11
|
-
| `createSpanProcessor(options)` | Host mode: one processor to pass to the host's provider. Same options as `init()` except `mode`
|
|
12
|
-
| `run(runId, [options], fn)` | A run around a block; resolves with what `fn` returns
|
|
13
|
-
| `startRun(runId, [options])` | A run you end yourself; bind a block with `handle.with(fn)`; `handle.end({ status, description, reason, decision, iterations, cost })`
|
|
14
|
-
| `span(name, [{ attributes }], fn)` | A custom span; `fn` gets the OpenTelemetry `Span`
|
|
15
|
-
| `bindIdentity({ useCaseId, useCaseKey, agentName }, fn)` | Bind a use case and agent name to every span started inside `fn`
|
|
16
|
-
| `instrument({ openai
|
|
17
|
-
| `flush({ timeoutMs })` | Send everything buffered; resolves `true` when accepted, `false` otherwise; never rejects. Default 30,000 ms
|
|
18
|
-
| `shutdown()` | Flush, shut the provider or processor down, remove the SDK's listeners; safe to call twice
|
|
19
|
-
| `useCaseIdFor(key)` | The UUID a key derives to; throws `MainwaveConfigError` before `init()` or `createSpanProcessor()`, or when disabled
|
|
20
|
-
| `registerFramework(name, [version])`, `VERSION` | Record a framework name on exported spans (for a custom integration); package version
|
|
21
|
-
| `MainwaveError`, `MainwaveConfigError`, `MainwaveReinitConflict` | Error classes. Config errors are invalid caller input; reinit conflict is a second `init()` with a different configuration
|
|
8
|
+
| Export | Use |
|
|
9
|
+
| ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
|
|
10
|
+
| `init(options)` | Owned mode: build a tracer provider and export every LLM trace. Once per process. Throws `MainwaveConfigError` for a missing key |
|
|
11
|
+
| `createSpanProcessor(options)` | Host mode: one processor to pass to the host's provider. Same options as `init()` except `mode` |
|
|
12
|
+
| `run(runId, [options], fn)` | A run around a block; resolves with what `fn` returns |
|
|
13
|
+
| `startRun(runId, [options])` | A run you end yourself; bind a block with `handle.with(fn)`; `handle.end({ status, description, reason, decision, iterations, cost })` |
|
|
14
|
+
| `span(name, [{ attributes }], fn)` | A custom span; `fn` gets the OpenTelemetry `Span` |
|
|
15
|
+
| `bindIdentity({ useCaseId, useCaseKey, agentName }, fn)` | Bind a use case and agent name to every span started inside `fn` |
|
|
16
|
+
| `instrument({ openai })` | Attach to the module(s) passed; returns `'patched'`, `'already'` or `'unrecognized'`; never throws |
|
|
17
|
+
| `flush({ timeoutMs })` | Send everything buffered; resolves `true` when accepted, `false` otherwise; never rejects. Default 30,000 ms |
|
|
18
|
+
| `shutdown()` | Flush, shut the provider or processor down, remove the SDK's listeners; safe to call twice |
|
|
19
|
+
| `useCaseIdFor(key)` | The UUID a key derives to; throws `MainwaveConfigError` before `init()` or `createSpanProcessor()`, or when disabled |
|
|
20
|
+
| `registerFramework(name, [version])`, `VERSION` | Record a framework name on exported spans (for a custom integration); package version |
|
|
21
|
+
| `MainwaveError`, `MainwaveConfigError`, `MainwaveReinitConflict` | Error classes. Config errors are invalid caller input; reinit conflict is a second `init()` with a different configuration |
|
|
22
22
|
|
|
23
23
|
Before `init()` or `createSpanProcessor()`, `run()`, `startRun()`, `span()` and
|
|
24
24
|
`bindIdentity()` run their callbacks without telemetry and log one warning.
|
|
@@ -27,11 +27,11 @@ Before `init()` or `createSpanProcessor()`, `run()`, `startRun()`, `span()` and
|
|
|
27
27
|
|
|
28
28
|
| Import | Provides |
|
|
29
29
|
| ------------------------- | --------------------------------------------------------------------------------- |
|
|
30
|
-
| `@mainwave/sdk/register` | Loader hooks for `node --import`; patches `openai
|
|
30
|
+
| `@mainwave/sdk/register` | Loader hooks for `node --import`; patches `openai`, adds the Anthropic middleware |
|
|
31
31
|
| `@mainwave/sdk/eve` | `mainwave(options)`: the eve instrumentation destination |
|
|
32
32
|
| `@mainwave/sdk/ai-sdk` | `mainwaveTelemetry(options)`: the AI SDK v7 integration for `registerTelemetry` |
|
|
33
33
|
| `@mainwave/sdk/openai` | `OpenAIInstrumentation` class, for hosts that register their own instrumentations |
|
|
34
|
-
| `@mainwave/sdk/anthropic` | `
|
|
34
|
+
| `@mainwave/sdk/anthropic` | `mainwaveMiddleware()`, for `new Anthropic({ middleware: [...] })` |
|
|
35
35
|
| `@mainwave/sdk/testing` | `installInMemoryProvider(options)`, `reset()`: in-process span assertions |
|
|
36
36
|
|
|
37
37
|
## `init()` options
|
|
@@ -4,16 +4,16 @@ Supported ranges are the optional peer dependencies the application installs.
|
|
|
4
4
|
A version outside its range is not instrumented and logs one warning with the
|
|
5
5
|
package, version, and range: report it to the user instead of wiring around it.
|
|
6
6
|
|
|
7
|
-
| Framework | Range
|
|
8
|
-
| ------------- |
|
|
9
|
-
| eve | `>=0.66.3 <0.70.0`, Node 24+
|
|
10
|
-
| Vercel AI SDK | `ai` `^7` with `@ai-sdk/otel` `^1`
|
|
11
|
-
| OpenAI | `openai` `>=4.19.0 <8`
|
|
12
|
-
| Anthropic | `@anthropic-ai/sdk` `>=0.
|
|
7
|
+
| Framework | Range | Wiring |
|
|
8
|
+
| ------------- | ---------------------------------- | ---------------------------------------------------- |
|
|
9
|
+
| eve | `>=0.66.3 <0.70.0`, Node 24+ | `mainwave()` from `@mainwave/sdk/eve`; no `init()` |
|
|
10
|
+
| Vercel AI SDK | `ai` `^7` with `@ai-sdk/otel` `^1` | `registerTelemetry(mainwaveTelemetry())` |
|
|
11
|
+
| OpenAI | `openai` `>=4.19.0 <8` | loader flag, `instrument({ openai })`, or the class |
|
|
12
|
+
| Anthropic | `@anthropic-ai/sdk` `>=0.134.0` | `init()`, the loader flag, or `mainwaveMiddleware()` |
|
|
13
13
|
|
|
14
|
-
AI SDK v5 and v6 are not supported. `@anthropic-ai/sdk` 0.134.0
|
|
15
|
-
|
|
16
|
-
|
|
14
|
+
AI SDK v5 and v6 are not supported. An `@anthropic-ai/sdk` below 0.134.0
|
|
15
|
+
records no spans, so its calls reach Mainwave not at all; the SDK logs one
|
|
16
|
+
warning with its version and the range.
|
|
17
17
|
|
|
18
18
|
## eve
|
|
19
19
|
|
|
@@ -48,28 +48,43 @@ process restarts.
|
|
|
48
48
|
|
|
49
49
|
## Anthropic
|
|
50
50
|
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
`
|
|
54
|
-
`
|
|
55
|
-
|
|
51
|
+
The client records its own spans: one `anthropic.messages.create` span per
|
|
52
|
+
Messages API call (`messages.create()` with or without `stream: true`,
|
|
53
|
+
`messages.stream()`, `messages.parse()`, the beta methods, and each model turn
|
|
54
|
+
of `beta.messages.toolRunner()`, which also records an agent span and one span
|
|
55
|
+
per tool run). A trace of only `countTokens()`, batches, models or files spans
|
|
56
|
+
is not sent. Mainwave's middleware adds what those spans leave out, to
|
|
57
|
+
Mainwave's copy only: the request's messages, system prompt and tool
|
|
58
|
+
definitions, and the response, including a stream the app reads raw. A
|
|
59
|
+
redacted thinking block reaches Mainwave as `[redacted thinking]`. The app's
|
|
60
|
+
own exporters receive the client's spans unchanged. The Bedrock and Vertex
|
|
61
|
+
clients (`@anthropic-ai/bedrock-sdk`, `@anthropic-ai/vertex-sdk`) are covered
|
|
62
|
+
the same way, with the providers `aws.bedrock` and `gcp.vertex_ai`.
|
|
56
63
|
|
|
57
64
|
## Attach paths for OpenAI and Anthropic
|
|
58
65
|
|
|
59
66
|
1. `node --import @mainwave/sdk/register app.mjs` (or `NODE_OPTIONS`): static
|
|
60
|
-
imports, dynamic `import()`, and `require()`. For plain Node processes.
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
67
|
+
imports, dynamic `import()`, and `require()`. For plain Node processes. For
|
|
68
|
+
`@anthropic-ai/sdk` it adds Mainwave's middleware to every client the app
|
|
69
|
+
constructs. Without it, `init()` adds the middleware to every
|
|
70
|
+
`@anthropic-ai/sdk` client constructed after `init()`, in ES module and
|
|
71
|
+
CommonJS apps.
|
|
72
|
+
2. The explicit path, for bundled apps and serverless functions (Vercel
|
|
73
|
+
Functions, Next.js): `instrument({ openai })`, and
|
|
74
|
+
`new Anthropic({ middleware: [mainwaveMiddleware()] })` with
|
|
75
|
+
`mainwaveMiddleware` from `@mainwave/sdk/anthropic`. Attach after `init()`
|
|
76
|
+
in owned mode, or after the host wiring in host mode, where
|
|
77
|
+
`createSpanProcessor()` is the initialization and `init()` is not called (a
|
|
78
|
+
bare `init()` after it throws `MainwaveReinitConflict`). Pass every
|
|
79
|
+
`openai` copy the app loads; an ES module import and a `require()` result
|
|
80
|
+
are different copies.
|
|
81
|
+
3. The `OpenAIInstrumentation` class, for a host that calls
|
|
82
|
+
`registerInstrumentations`. ES module imports are then intercepted by the
|
|
83
|
+
host's own OpenTelemetry loader, registered before the application starts.
|
|
84
|
+
Anthropic clients there take the middleware as in 2.
|
|
85
|
+
|
|
86
|
+
A copy attached by two of these ways is instrumented once, and a client that
|
|
87
|
+
gets the Anthropic middleware both ways runs it once. Do not add an
|
|
73
88
|
OpenInference or Traceloop instrumentation for these clients: the SDK has its
|
|
74
89
|
own, and a second one traces every call twice. Where one is already installed
|
|
75
90
|
by the app, set `init({ skipInstrumentations: [...] })` for that client instead
|
|
@@ -27,10 +27,12 @@ the trace.
|
|
|
27
27
|
|
|
28
28
|
## 2. Nothing was attached for the provider client
|
|
29
29
|
|
|
30
|
-
An ES module app with `openai`
|
|
31
|
-
`--import @mainwave/sdk/register` nor `instrument()` gets no spans from
|
|
32
|
-
|
|
33
|
-
`
|
|
30
|
+
An ES module app with `openai` installed and neither
|
|
31
|
+
`--import @mainwave/sdk/register` nor `instrument()` gets no spans from it and
|
|
32
|
+
one warning naming both options. An `@anthropic-ai/sdk` client constructed
|
|
33
|
+
before `init()` without the flag or `mainwaveMiddleware()` sends its own spans
|
|
34
|
+
without the request content, tool definitions and raw stream output, with one
|
|
35
|
+
warning when they arrive; one constructed after `init()` gets the middleware. Fix per the attach table in `SKILL.md` section 6. If `instrument()` returned `'unrecognized'`, it was not
|
|
34
36
|
given the module itself (`import * as openai from 'openai'`). If a client is
|
|
35
37
|
traced in one file and not another, the second file loads a different copy:
|
|
36
38
|
pass every copy.
|
|
@@ -132,9 +134,11 @@ runtime`. Move the route to the Node.js runtime.
|
|
|
132
134
|
## 10. Every call appears twice
|
|
133
135
|
|
|
134
136
|
Another OpenAI or Anthropic instrumentation (OpenInference, Traceloop, a
|
|
135
|
-
host's own) is running beside the SDK's
|
|
136
|
-
|
|
137
|
-
|
|
137
|
+
host's own) is running beside the SDK's OpenAI instrumentation or the
|
|
138
|
+
Anthropic client's own spans. For `openai`, set
|
|
139
|
+
`init({ skipInstrumentations: ['openai'] })`; for `@anthropic-ai/sdk`, remove
|
|
140
|
+
the other instrumentation if the user agrees, since the client always records
|
|
141
|
+
its own spans.
|
|
138
142
|
|
|
139
143
|
## Proving instrumentation works without the network
|
|
140
144
|
|