metergraph 0.6.10 → 0.6.14
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 +34 -4
- package/dist/capture.d.ts +1 -0
- package/dist/capture.js +56 -0
- package/dist/context.d.ts +3 -0
- package/dist/context.js +1 -0
- package/dist/index.js +9 -1
- package/dist/model-evidence.d.ts +15 -0
- package/dist/model-evidence.js +105 -0
- package/dist/template.js +13 -2
- package/dist/vercel-ai.js +3 -0
- package/dist/version.d.ts +1 -1
- package/dist/version.js +1 -1
- package/dist/wrap.d.ts +2 -0
- package/dist/wrap.js +165 -7
- package/package.json +18 -6
package/README.md
CHANGED
|
@@ -1,8 +1,19 @@
|
|
|
1
1
|
# metergraph (TypeScript)
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
3
|
+
See where your agentic AI application's LLM spend comes from. Attribute usage
|
|
4
|
+
to functions, agents, and workflows without changing provider call sites, then
|
|
5
|
+
send it to Metergraph Cloud or your self-hosted Metergraph server.
|
|
6
|
+
|
|
7
|
+
[Metergraph](https://www.metergraph.dev/) helps teams understand and optimize
|
|
8
|
+
agentic AI applications. This open-source, zero-runtime-dependency package
|
|
9
|
+
provides function-level LLM cost attribution for OpenAI, Anthropic, and Gemini
|
|
10
|
+
clients plus provider-independent Vercel AI SDK language models. Paid
|
|
11
|
+
Metergraph builds on that attribution with experimentation and optimization
|
|
12
|
+
across models, prompts, tools, retrieval, context, batching, and caching. This
|
|
13
|
+
package captures and attributes usage; it does not run experiments or optimize
|
|
14
|
+
your application.
|
|
15
|
+
|
|
16
|
+
The package runs on Node 18+, including AWS Lambda. Worker-style `waitUntil` hooks are present but are not part of the v1
|
|
6
17
|
public-package qualification contract.
|
|
7
18
|
|
|
8
19
|
Metergraph supports OpenAI JavaScript SDK majors 4 through 7. The current
|
|
@@ -176,6 +187,21 @@ inference while iterating a wrapped `client.messages.batches.results()` result.
|
|
|
176
187
|
Consume results inside `route()` so the asynchronous batch retains its product
|
|
177
188
|
route. Job-management polls are deliberately not counted as model calls.
|
|
178
189
|
|
|
190
|
+
OpenAI Responses created with `background: true` are recorded once, when a
|
|
191
|
+
wrapped `client.responses.retrieve()` or `cancel()` first returns a terminal
|
|
192
|
+
status (`completed`, `failed`, `cancelled` or `incomplete`), with that
|
|
193
|
+
response's usage and output. A `retrieve(id, { stream: true })` or
|
|
194
|
+
`responses.stream({ response_id })` resume is observed through its terminal
|
|
195
|
+
`response.*` event when the stream is iterated directly; `tee()` and
|
|
196
|
+
`toReadableStream()` copies are not observed. Polls that still report
|
|
197
|
+
`queued` or `in_progress` add no rows, and latency runs from `create` to the
|
|
198
|
+
observed terminal response. A background response whose terminal status the
|
|
199
|
+
process never observes is recorded at `shutdown()` with status `abandoned`
|
|
200
|
+
and unknown usage, never as a completed call with zero tokens. Only retrieves
|
|
201
|
+
made through the same wrapped client in the same process are observed; a
|
|
202
|
+
client derived with `withOptions()` or polling from a different process leaves
|
|
203
|
+
the call to be recorded as `abandoned`.
|
|
204
|
+
|
|
179
205
|
## Batch-first execution (opt-in)
|
|
180
206
|
|
|
181
207
|
`batchFirst()` is a separate, explicitly opt-in code path from `wrap()`/capture: submit one request through a provider's Batch API, wait up to a caller-chosen deadline, and fall back to exactly one direct call if the batch hasn't finished in time.
|
|
@@ -220,7 +246,7 @@ codebase you want instrumented:
|
|
|
220
246
|
|
|
221
247
|
```text
|
|
222
248
|
Instrument this codebase's LLM API costs with the `metergraph` npm package
|
|
223
|
-
(https://github.com/
|
|
249
|
+
(https://github.com/metergraph/metergraphsdk): npm install metergraph,
|
|
224
250
|
then wrap every new OpenAI(), new Anthropic(), and new GoogleGenAI()
|
|
225
251
|
construction in place, e.g. const client = mg.wrap(new OpenAI()) after
|
|
226
252
|
import * as mg from "metergraph". wrap() returns the same client and
|
|
@@ -247,3 +273,7 @@ mg.vercelAISDKMiddleware() }); do not also wrap its internal provider transport.
|
|
|
247
273
|
When done, list every client and AI SDK model you instrumented, and flag LLM
|
|
248
274
|
calls made outside these supported paths.
|
|
249
275
|
```
|
|
276
|
+
|
|
277
|
+
### Service tier evidence
|
|
278
|
+
|
|
279
|
+
Calls record `service_tier` separately from `requested_service_tier`: requesting Flex does not prove it was served. Capture reads OpenAI's response tier, Anthropic's usage tier, and Google's usage tier or traffic type, retaining evidence across trailing stream events. Successful Batch API results record `batch` from the transport, without inventing a requested tier. Missing response evidence stays unknown.
|
package/dist/capture.d.ts
CHANGED
package/dist/capture.js
CHANGED
|
@@ -2,6 +2,7 @@
|
|
|
2
2
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
3
|
exports.CaptureRuntime = exports.DEFAULT_TEXT_MAX_BYTES = void 0;
|
|
4
4
|
exports.chunkText = chunkText;
|
|
5
|
+
const model_evidence_js_1 = require("./model-evidence.js");
|
|
5
6
|
const node_crypto_1 = require("node:crypto");
|
|
6
7
|
const context_js_1 = require("./context.js");
|
|
7
8
|
const gateway_js_1 = require("./gateway.js");
|
|
@@ -12,6 +13,54 @@ exports.DEFAULT_TEXT_MAX_BYTES = 1024 * 1024;
|
|
|
12
13
|
function get(value, key) {
|
|
13
14
|
return value && typeof value === "object" ? value[key] : undefined;
|
|
14
15
|
}
|
|
16
|
+
function tierString(value) {
|
|
17
|
+
return typeof value === "string" && value.trim() ? value.trim() : undefined;
|
|
18
|
+
}
|
|
19
|
+
function serviceTier(value) {
|
|
20
|
+
return tierString(get(value, "service_tier") ?? get(value, "serviceTier"));
|
|
21
|
+
}
|
|
22
|
+
function responseTier(value) {
|
|
23
|
+
const direct = serviceTier(value) ?? serviceTier(get(value, "usage"));
|
|
24
|
+
if (direct !== undefined)
|
|
25
|
+
return direct;
|
|
26
|
+
const usage = get(value, "usageMetadata") ?? get(value, "usage_metadata");
|
|
27
|
+
const nativeTier = serviceTier(usage);
|
|
28
|
+
if (nativeTier !== undefined)
|
|
29
|
+
return nativeTier;
|
|
30
|
+
const traffic = tierString(get(usage, "trafficType") ?? get(usage, "traffic_type"));
|
|
31
|
+
if (traffic === "ON_DEMAND_FLEX")
|
|
32
|
+
return "flex";
|
|
33
|
+
if (traffic === "ON_DEMAND")
|
|
34
|
+
return "standard";
|
|
35
|
+
if (traffic === "ON_DEMAND_PRIORITY")
|
|
36
|
+
return "priority";
|
|
37
|
+
return traffic;
|
|
38
|
+
}
|
|
39
|
+
function servedServiceTier(response, chunks = []) {
|
|
40
|
+
const read = (value) => responseTier(value)
|
|
41
|
+
?? responseTier(get(value, "response")) ?? responseTier(get(value, "message"));
|
|
42
|
+
const direct = read(response);
|
|
43
|
+
if (direct !== undefined)
|
|
44
|
+
return direct;
|
|
45
|
+
// A trailing event need not repeat the provider's tier.
|
|
46
|
+
for (let i = chunks.length - 1; i >= 0; i--) {
|
|
47
|
+
const tier = read(chunks[i]);
|
|
48
|
+
if (tier !== undefined)
|
|
49
|
+
return tier;
|
|
50
|
+
}
|
|
51
|
+
return undefined;
|
|
52
|
+
}
|
|
53
|
+
function requestedServiceTier(request) {
|
|
54
|
+
const config = get(request, "config");
|
|
55
|
+
const explicit = serviceTier(request) ?? serviceTier(config);
|
|
56
|
+
if (explicit !== undefined)
|
|
57
|
+
return explicit;
|
|
58
|
+
const http = get(config, "httpOptions") ?? get(config, "http_options");
|
|
59
|
+
const headers = get(http, "headers");
|
|
60
|
+
if (!headers || typeof headers !== "object")
|
|
61
|
+
return undefined;
|
|
62
|
+
return tierString(Object.entries(headers).find(([key]) => key.toLowerCase() === "x-vertex-ai-llm-shared-request-type")?.[1]);
|
|
63
|
+
}
|
|
15
64
|
function first(value) {
|
|
16
65
|
return Array.isArray(value) ? value[0] : undefined;
|
|
17
66
|
}
|
|
@@ -767,12 +816,19 @@ class CaptureRuntime {
|
|
|
767
816
|
provider: state.provider,
|
|
768
817
|
model: state.request.model,
|
|
769
818
|
...usage(response),
|
|
819
|
+
// The Batch API confirms billing even when its body reports a default tier.
|
|
820
|
+
service_tier: state.endpoint.startsWith("batch.") && response != null
|
|
821
|
+
&& !extra.error && extra.status !== "error"
|
|
822
|
+
? "batch" : servedServiceTier(response, extra.responseChunks),
|
|
823
|
+
requested_service_tier: requestedServiceTier(state.request),
|
|
770
824
|
...(0, gateway_js_1.gatewayEvidence)(state.gateway, state.endpoint, response),
|
|
771
825
|
latency_ms: Math.round(performance.now() - state.started),
|
|
772
826
|
status,
|
|
773
827
|
status_code: statusCode,
|
|
774
828
|
finish_reason: finishReason,
|
|
775
829
|
finish_reason_raw: finishReasonRaw,
|
|
830
|
+
...(0, model_evidence_js_1.modelEvidence)({ response, error: extra.error, refusalSignal: state.context.refusalSignal,
|
|
831
|
+
stream_chunks: extra.evidenceChunks ?? extra.responseChunks, stream_complete: extra.stream === true && extra.error === undefined && extra.status !== "error" && extra.status !== "abandoned" }),
|
|
776
832
|
session_id: state.context.sessionId,
|
|
777
833
|
conversation_id: state.context.sessionId,
|
|
778
834
|
trace_id: state.traceId,
|
package/dist/context.d.ts
CHANGED
|
@@ -7,6 +7,7 @@ export interface CaptureContext {
|
|
|
7
7
|
unitName?: string;
|
|
8
8
|
unitCount?: number;
|
|
9
9
|
captureText?: boolean;
|
|
10
|
+
refusalSignal?: boolean;
|
|
10
11
|
funcName?: string;
|
|
11
12
|
traceId?: string;
|
|
12
13
|
traceName?: string;
|
|
@@ -24,6 +25,8 @@ export interface TraceOptions {
|
|
|
24
25
|
captureText?: boolean;
|
|
25
26
|
}
|
|
26
27
|
export interface ContextOptions {
|
|
28
|
+
/** Scoped observation; an explicit native refusal takes precedence. */
|
|
29
|
+
refusalSignal?: boolean;
|
|
27
30
|
sessionId?: string;
|
|
28
31
|
tags?: Record<string, unknown>;
|
|
29
32
|
}
|
package/dist/context.js
CHANGED
|
@@ -31,6 +31,7 @@ function withContext(options, fn) {
|
|
|
31
31
|
const child = {
|
|
32
32
|
...parent,
|
|
33
33
|
sessionId: options.sessionId ?? parent.sessionId,
|
|
34
|
+
refusalSignal: options.refusalSignal ?? parent.refusalSignal,
|
|
34
35
|
tags: { ...parent.tags, ...normalizeTags(options.tags ?? {}) },
|
|
35
36
|
};
|
|
36
37
|
return storage.run(child, fn);
|
package/dist/index.js
CHANGED
|
@@ -93,7 +93,7 @@ function init(options = {}) {
|
|
|
93
93
|
initialized = true;
|
|
94
94
|
if (!repoConfig && !warnedNoRepository) {
|
|
95
95
|
warnedNoRepository = true;
|
|
96
|
-
console.warn("Metergraph
|
|
96
|
+
console.warn("Metergraph is capturing calls normally. Repository identity is optional and not set, so traces are not linked to a source repository. To link them, commit .metergraph/config.json containing {\"repository\": \"owner/name\"}, set METERGRAPH_REPOSITORY=owner/name, pass init({ repository: \"owner/name\" }), or run `metergraph setup` in the project.");
|
|
97
97
|
}
|
|
98
98
|
sessionManager = repoConfig
|
|
99
99
|
? new session_js_1.SessionManager(token, ingestUrl, repoConfig.repository, version_js_1.SDK_VERSION)
|
|
@@ -179,6 +179,14 @@ async function flush(timeoutMs = 3_000) {
|
|
|
179
179
|
return transport?.flush(timeoutMs) ?? true;
|
|
180
180
|
}
|
|
181
181
|
async function shutdown() {
|
|
182
|
+
// Background responses whose final result was never retrieved are recorded
|
|
183
|
+
// as abandoned before the transport drains, never as zero usage.
|
|
184
|
+
try {
|
|
185
|
+
(0, wrap_js_1.finishBackgroundCalls)();
|
|
186
|
+
}
|
|
187
|
+
catch {
|
|
188
|
+
// fail-open
|
|
189
|
+
}
|
|
182
190
|
config?.stop();
|
|
183
191
|
config = undefined;
|
|
184
192
|
await transport?.shutdown();
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
export declare function modelEvidence(input: {
|
|
2
|
+
response?: unknown;
|
|
3
|
+
error?: unknown;
|
|
4
|
+
stream_chunks?: unknown[];
|
|
5
|
+
stream_complete?: boolean;
|
|
6
|
+
refusalSignal?: boolean;
|
|
7
|
+
}): {
|
|
8
|
+
otel?: {
|
|
9
|
+
finish_reasons: string[];
|
|
10
|
+
} | undefined;
|
|
11
|
+
http_status_code: number | null;
|
|
12
|
+
error_code: string | null;
|
|
13
|
+
refusal_signal: boolean | null;
|
|
14
|
+
response_received: boolean | null;
|
|
15
|
+
};
|
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.modelEvidence = modelEvidence;
|
|
4
|
+
/** Content-free native facts; receivers own outcome classification. */
|
|
5
|
+
function get(value, key) {
|
|
6
|
+
return value && typeof value === "object" ? value[key] : undefined;
|
|
7
|
+
}
|
|
8
|
+
function items(value) { return Array.isArray(value) ? value : []; }
|
|
9
|
+
function text(value) { return typeof value === "string" && value.trim().length > 0 && value.length <= 256; }
|
|
10
|
+
function inspect(value) {
|
|
11
|
+
const reasons = [], coverage = [];
|
|
12
|
+
let positive = false, received = false;
|
|
13
|
+
const reason = (raw) => { if (text(raw))
|
|
14
|
+
reasons.push(raw); };
|
|
15
|
+
reason(get(value, "finish_reason"));
|
|
16
|
+
reason(get(value, "stop_reason"));
|
|
17
|
+
const camelFinish = get(value, "finishReason");
|
|
18
|
+
reason(get(camelFinish, "raw") ?? get(camelFinish, "unified") ?? camelFinish);
|
|
19
|
+
if (["refusal", "response.refusal.delta", "response.refusal.done"].includes(String(get(value, "type"))))
|
|
20
|
+
positive = true;
|
|
21
|
+
for (const part of [get(value, "part"), get(value, "content_block")])
|
|
22
|
+
positive ||= get(part, "type") === "refusal";
|
|
23
|
+
const delta = get(value, "delta");
|
|
24
|
+
reason(get(delta, "stop_reason"));
|
|
25
|
+
positive ||= Boolean(get(delta, "refusal"));
|
|
26
|
+
const choices = get(value, "choices");
|
|
27
|
+
if (Array.isArray(choices)) {
|
|
28
|
+
received = true;
|
|
29
|
+
for (const choice of choices) {
|
|
30
|
+
const finish = get(choice, "finish_reason"), message = get(choice, "message");
|
|
31
|
+
reason(finish);
|
|
32
|
+
positive ||= Boolean(get(message, "refusal")) || Boolean(get(get(choice, "delta"), "refusal")) || items(get(message, "content")).some(part => get(part, "type") === "refusal");
|
|
33
|
+
coverage.push(message != null && text(finish) && (get(message, "content") != null || get(message, "tool_calls") != null || typeof message === "object" && "refusal" in message));
|
|
34
|
+
}
|
|
35
|
+
}
|
|
36
|
+
const content = get(value, "content");
|
|
37
|
+
if (Array.isArray(content)) {
|
|
38
|
+
positive ||= content.some(part => get(part, "type") === "refusal");
|
|
39
|
+
if (text(get(value, "stop_reason"))) {
|
|
40
|
+
received = true;
|
|
41
|
+
coverage.push(content.length > 0 && content.every(part => ["text", "thinking", "redacted_thinking", "tool_use", "refusal"].includes(String(get(part, "type")))));
|
|
42
|
+
}
|
|
43
|
+
}
|
|
44
|
+
const output = get(value, "output");
|
|
45
|
+
if (Array.isArray(output)) {
|
|
46
|
+
received = true;
|
|
47
|
+
for (const item of output) {
|
|
48
|
+
const parts = items(get(item, "content"));
|
|
49
|
+
positive ||= get(item, "type") === "refusal" || parts.some(part => get(part, "type") === "refusal");
|
|
50
|
+
coverage.push(["completed", "incomplete"].includes(String(get(value, "status"))) && (get(item, "type") === "message" && parts.length > 0 && parts.every(part => ["output_text", "refusal"].includes(String(get(part, "type")))) ||
|
|
51
|
+
["function_call", "reasoning"].includes(String(get(item, "type")))));
|
|
52
|
+
}
|
|
53
|
+
}
|
|
54
|
+
reason(get(get(value, "incomplete_details"), "reason"));
|
|
55
|
+
const feedback = get(value, "promptFeedback") ?? get(value, "prompt_feedback");
|
|
56
|
+
if (feedback != null) {
|
|
57
|
+
received = true;
|
|
58
|
+
reason(get(feedback, "blockReason") ?? get(feedback, "block_reason"));
|
|
59
|
+
}
|
|
60
|
+
const candidates = get(value, "candidates");
|
|
61
|
+
if (Array.isArray(candidates)) {
|
|
62
|
+
received = true;
|
|
63
|
+
for (const candidate of candidates) {
|
|
64
|
+
const finish = get(candidate, "finishReason") ?? get(candidate, "finish_reason");
|
|
65
|
+
reason(finish);
|
|
66
|
+
const parts = items(get(get(candidate, "content"), "parts"));
|
|
67
|
+
positive ||= parts.some(part => get(part, "type") === "refusal");
|
|
68
|
+
coverage.push(text(finish) && parts.length > 0);
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
return { positive, complete: coverage.length > 0 && coverage.every(Boolean), received, reasons };
|
|
72
|
+
}
|
|
73
|
+
function modelEvidence(input) {
|
|
74
|
+
const { response, error } = input;
|
|
75
|
+
const raw = get(error, "status_code") ?? get(error, "status") ?? get(error, "statusCode")
|
|
76
|
+
?? get(get(error, "response"), "status_code") ?? get(response, "status_code");
|
|
77
|
+
const status = typeof raw === "number" && Number.isInteger(raw) && raw >= 100 && raw <= 599 ? raw : null;
|
|
78
|
+
let payload = get(error, "error") ?? get(error, "body") ?? error;
|
|
79
|
+
payload = get(payload, "error") ?? payload;
|
|
80
|
+
const code = get(payload, "code") ?? get(error, "code");
|
|
81
|
+
const safeInspect = (value) => {
|
|
82
|
+
try {
|
|
83
|
+
return inspect(value);
|
|
84
|
+
}
|
|
85
|
+
catch {
|
|
86
|
+
return { positive: false, complete: false, received: false, reasons: [] };
|
|
87
|
+
}
|
|
88
|
+
};
|
|
89
|
+
const native = safeInspect(response);
|
|
90
|
+
for (const chunk of input.stream_chunks ?? []) {
|
|
91
|
+
for (const value of [chunk, get(chunk, "response")]) {
|
|
92
|
+
const inspected = safeInspect(value);
|
|
93
|
+
native.positive ||= inspected.positive;
|
|
94
|
+
native.received ||= inspected.received;
|
|
95
|
+
native.reasons.push(...inspected.reasons);
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
const signal = native.positive ? true : typeof input.refusalSignal === "boolean" ? input.refusalSignal :
|
|
99
|
+
native.complete && (input.stream_chunks === undefined || input.stream_complete) ? false : null;
|
|
100
|
+
return {
|
|
101
|
+
http_status_code: status, error_code: text(code) ? code : null,
|
|
102
|
+
refusal_signal: signal, response_received: native.received || native.positive ? true : null,
|
|
103
|
+
...(native.reasons.length ? { otel: { finish_reasons: native.reasons } } : {}),
|
|
104
|
+
};
|
|
105
|
+
}
|
package/dist/template.js
CHANGED
|
@@ -82,10 +82,21 @@ function normalized(value) {
|
|
|
82
82
|
}
|
|
83
83
|
if (typeof value !== "string")
|
|
84
84
|
return value;
|
|
85
|
+
// Every pattern here must run in time linear in the text: a request can
|
|
86
|
+
// carry megabytes in one string (an inline image) and this runs inside the
|
|
87
|
+
// wrapped call. The email local part is capped at 64 characters, the most
|
|
88
|
+
// RFC 5321 allows, and the domain commits to its first dot instead of
|
|
89
|
+
// retrying from every dot. It matches the same strings as the former
|
|
90
|
+
// `[^\s@]+@[^\s@]+\.[^\s@]+\b`, which rescanned a run with no whitespace
|
|
91
|
+
// or "@" from every word boundary and was quadratic on a base64 image.
|
|
92
|
+
// Inline images differ on every call, so for fingerprinting they are a URL.
|
|
93
|
+
// The data URL's media type is bounded and may not hold ":", which a media
|
|
94
|
+
// type never does, so a "data:" that is not a data URL fails within a few
|
|
95
|
+
// characters instead of scanning the rest of the string from every "data:".
|
|
85
96
|
return value
|
|
86
97
|
.replace(/\b[0-9a-f]{8}-[0-9a-f-]{27,}\b/gi, "<uuid>")
|
|
87
|
-
.replace(/\b[^\s@]
|
|
88
|
-
.replace(/\
|
|
98
|
+
.replace(/\b[^\s@]{1,64}@[^\s@][^\s@.]*\.[^\s@]+\b/g, "<email>")
|
|
99
|
+
.replace(/\b(?:https?:\/\/|data:[^\s,:]{0,255};base64,)\S+/g, "<url>")
|
|
89
100
|
.replace(/\b[A-Za-z0-9_-]{24,}\b/g, "<token>")
|
|
90
101
|
.replace(/(^|[^A-Za-z])[-+]?\d+(?:\.\d+)?(?=$|[^A-Za-z])/g, "$1<n>")
|
|
91
102
|
.replace(/\s+/g, " ")
|
package/dist/vercel-ai.js
CHANGED
|
@@ -81,10 +81,12 @@ function wrapStreamResult(result, capture, state, started) {
|
|
|
81
81
|
let finishPart;
|
|
82
82
|
let streamError;
|
|
83
83
|
const content = [];
|
|
84
|
+
const evidenceChunks = [];
|
|
84
85
|
const responseMetadata = {};
|
|
85
86
|
// Telemetry inspection of one part. Reads part fields, so callers run it
|
|
86
87
|
// fail-open; a fault must not block delivery or become a stream error.
|
|
87
88
|
const observe = (part) => {
|
|
89
|
+
evidenceChunks.push(part);
|
|
88
90
|
if (firstOutputAt === undefined && outputChunk(part))
|
|
89
91
|
firstOutputAt = performance.now();
|
|
90
92
|
const delta = (0, capture_js_1.chunkText)(part);
|
|
@@ -137,6 +139,7 @@ function wrapStreamResult(result, capture, state, started) {
|
|
|
137
139
|
status,
|
|
138
140
|
stream: true,
|
|
139
141
|
responseText: text,
|
|
142
|
+
evidenceChunks,
|
|
140
143
|
ttftMs: firstOutputAt === undefined ? undefined : Math.round(firstOutputAt - started),
|
|
141
144
|
});
|
|
142
145
|
};
|
package/dist/version.d.ts
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
export declare const SDK_VERSION = "0.6.
|
|
1
|
+
export declare const SDK_VERSION = "0.6.14";
|
package/dist/version.js
CHANGED
package/dist/wrap.d.ts
CHANGED
|
@@ -3,6 +3,8 @@ type AnyRecord = Record<PropertyKey, any>;
|
|
|
3
3
|
export declare function setCaptureRuntime(value?: CaptureRuntime): void;
|
|
4
4
|
/** @internal Used by optional framework adapters without adding runtime dependencies. */
|
|
5
5
|
export declare function getCaptureRuntime(): CaptureRuntime | undefined;
|
|
6
|
+
/** Record every held background call whose final result was never observed. */
|
|
7
|
+
export declare function finishBackgroundCalls(status?: string): number;
|
|
6
8
|
export interface Seam {
|
|
7
9
|
path: string;
|
|
8
10
|
method: string;
|
package/dist/wrap.js
CHANGED
|
@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
|
|
|
3
3
|
exports.wrapClient = exports.SEAM_TABLES = exports.GOOGLE_SEAMS = exports.ANTHROPIC_SEAMS = exports.OPENAI_SEAMS = void 0;
|
|
4
4
|
exports.setCaptureRuntime = setCaptureRuntime;
|
|
5
5
|
exports.getCaptureRuntime = getCaptureRuntime;
|
|
6
|
+
exports.finishBackgroundCalls = finishBackgroundCalls;
|
|
6
7
|
exports.wrap = wrap;
|
|
7
8
|
const capture_js_1 = require("./capture.js");
|
|
8
9
|
const context_js_1 = require("./context.js");
|
|
@@ -77,7 +78,6 @@ function captureOpenAIBatchItem(capture, item, sourceId, context, stack) {
|
|
|
77
78
|
const request = {
|
|
78
79
|
model: get(body, "model"),
|
|
79
80
|
batch: true,
|
|
80
|
-
service_tier: "batch",
|
|
81
81
|
batch_custom_id: customId || undefined,
|
|
82
82
|
batch_item_id: itemId || undefined,
|
|
83
83
|
};
|
|
@@ -150,7 +150,6 @@ function captureAnthropicBatchItem(capture, item, batchId, context, stack) {
|
|
|
150
150
|
const state = capture.start("anthropic", "batch.messages", {
|
|
151
151
|
model: get(message, "model"),
|
|
152
152
|
batch: true,
|
|
153
|
-
service_tier: "batch",
|
|
154
153
|
batch_custom_id: customId || undefined,
|
|
155
154
|
batch_id: batchId || undefined,
|
|
156
155
|
}, stack, context);
|
|
@@ -278,7 +277,7 @@ function streamProxy(stream, state, capture, suppressUsageOnly) {
|
|
|
278
277
|
stream.on("error", (error) => finish(last, error));
|
|
279
278
|
}
|
|
280
279
|
return new Proxy(stream, {
|
|
281
|
-
get(target, property
|
|
280
|
+
get(target, property) {
|
|
282
281
|
if (property === Symbol.asyncIterator && typeof target[Symbol.asyncIterator] === "function") {
|
|
283
282
|
return async function* () {
|
|
284
283
|
try {
|
|
@@ -337,7 +336,7 @@ function streamProxy(stream, state, capture, suppressUsageOnly) {
|
|
|
337
336
|
};
|
|
338
337
|
}
|
|
339
338
|
if (property === "close" || property === "abort") {
|
|
340
|
-
const original = Reflect.get(target, property
|
|
339
|
+
const original = Reflect.get(target, property);
|
|
341
340
|
if (typeof original !== "function")
|
|
342
341
|
return original;
|
|
343
342
|
return (...args) => {
|
|
@@ -357,7 +356,7 @@ function streamProxy(stream, state, capture, suppressUsageOnly) {
|
|
|
357
356
|
return returned;
|
|
358
357
|
};
|
|
359
358
|
}
|
|
360
|
-
const value = Reflect.get(target, property
|
|
359
|
+
const value = Reflect.get(target, property);
|
|
361
360
|
return typeof value === "function" ? value.bind(target) : value;
|
|
362
361
|
},
|
|
363
362
|
});
|
|
@@ -405,6 +404,153 @@ function preserveProviderPromise(target, complete, fail) {
|
|
|
405
404
|
},
|
|
406
405
|
});
|
|
407
406
|
}
|
|
407
|
+
// Background Responses ({ background: true }) return a queued or in-progress
|
|
408
|
+
// response from create(); output and usage arrive on a later retrieve() or
|
|
409
|
+
// cancel(). The capture is held until the client observes a terminal status,
|
|
410
|
+
// then recorded once from that response. A held call the client never sees
|
|
411
|
+
// finish is recorded as "abandoned" at shutdown (or when the bound is
|
|
412
|
+
// exceeded), so it is never stored as a completed call with zero usage.
|
|
413
|
+
const BACKGROUND_PENDING = new Set(["queued", "in_progress"]);
|
|
414
|
+
const BACKGROUND_TERMINAL = new Set(["completed", "failed", "cancelled", "incomplete"]);
|
|
415
|
+
const BACKGROUND_MAX_PENDING = 1024;
|
|
416
|
+
const backgroundCalls = new Map();
|
|
417
|
+
function shouldHoldBackground(endpoint, request, response) {
|
|
418
|
+
try {
|
|
419
|
+
return (endpoint === "responses" || endpoint === "responses.parse")
|
|
420
|
+
&& BACKGROUND_PENDING.has(get(response, "status"))
|
|
421
|
+
&& (request.background === true || get(response, "background") === true)
|
|
422
|
+
&& typeof get(response, "id") === "string"
|
|
423
|
+
&& get(response, "id") !== "";
|
|
424
|
+
}
|
|
425
|
+
catch {
|
|
426
|
+
return false;
|
|
427
|
+
}
|
|
428
|
+
}
|
|
429
|
+
function holdBackground(capture, state, response) {
|
|
430
|
+
const id = get(response, "id");
|
|
431
|
+
backgroundCalls.delete(id);
|
|
432
|
+
backgroundCalls.set(id, { capture, state, last: response });
|
|
433
|
+
while (backgroundCalls.size > BACKGROUND_MAX_PENDING) {
|
|
434
|
+
const [oldest, held] = backgroundCalls.entries().next().value;
|
|
435
|
+
backgroundCalls.delete(oldest);
|
|
436
|
+
finishCapture(held.capture, held.state, held.last, { status: "abandoned" });
|
|
437
|
+
}
|
|
438
|
+
}
|
|
439
|
+
function observeBackground(response) {
|
|
440
|
+
try {
|
|
441
|
+
const id = get(response, "id");
|
|
442
|
+
if (typeof id !== "string")
|
|
443
|
+
return;
|
|
444
|
+
const held = backgroundCalls.get(id);
|
|
445
|
+
if (!held)
|
|
446
|
+
return;
|
|
447
|
+
const status = get(response, "status");
|
|
448
|
+
if (BACKGROUND_PENDING.has(status)) {
|
|
449
|
+
held.last = response;
|
|
450
|
+
return;
|
|
451
|
+
}
|
|
452
|
+
if (!BACKGROUND_TERMINAL.has(status))
|
|
453
|
+
return;
|
|
454
|
+
backgroundCalls.delete(id);
|
|
455
|
+
finishCapture(held.capture, held.state, response);
|
|
456
|
+
}
|
|
457
|
+
catch {
|
|
458
|
+
// Observation is telemetry-only and fail-open.
|
|
459
|
+
}
|
|
460
|
+
}
|
|
461
|
+
function observeBackgroundEvent(event) {
|
|
462
|
+
try {
|
|
463
|
+
const type = get(event, "type");
|
|
464
|
+
if (typeof type === "string" && type.startsWith("response.")) {
|
|
465
|
+
const response = get(event, "response");
|
|
466
|
+
if (response)
|
|
467
|
+
observeBackground(response);
|
|
468
|
+
}
|
|
469
|
+
}
|
|
470
|
+
catch {
|
|
471
|
+
// fail-open
|
|
472
|
+
}
|
|
473
|
+
}
|
|
474
|
+
// Pass a resumed background stream through unchanged, observing its response
|
|
475
|
+
// events so the terminal one finishes the held call.
|
|
476
|
+
function observedBackgroundStream(stream) {
|
|
477
|
+
return new Proxy(stream, {
|
|
478
|
+
get(target, property, receiver) {
|
|
479
|
+
if (property === Symbol.asyncIterator) {
|
|
480
|
+
return async function* () {
|
|
481
|
+
for await (const event of target) {
|
|
482
|
+
observeBackgroundEvent(event);
|
|
483
|
+
yield event;
|
|
484
|
+
}
|
|
485
|
+
};
|
|
486
|
+
}
|
|
487
|
+
const value = Reflect.get(target, property, receiver);
|
|
488
|
+
return typeof value === "function" ? value.bind(target) : value;
|
|
489
|
+
},
|
|
490
|
+
});
|
|
491
|
+
}
|
|
492
|
+
/** Record every held background call whose final result was never observed. */
|
|
493
|
+
function finishBackgroundCalls(status = "abandoned") {
|
|
494
|
+
const held = [...backgroundCalls.values()];
|
|
495
|
+
backgroundCalls.clear();
|
|
496
|
+
for (const call of held)
|
|
497
|
+
finishCapture(call.capture, call.state, call.last, { status });
|
|
498
|
+
return held.length;
|
|
499
|
+
}
|
|
500
|
+
function patchBackgroundObserver(owner, method) {
|
|
501
|
+
if (!owner || typeof owner[method] !== "function")
|
|
502
|
+
return false;
|
|
503
|
+
if (owner[method].__metergraph__)
|
|
504
|
+
return true;
|
|
505
|
+
const original = owner[method];
|
|
506
|
+
const wrapped = function (...args) {
|
|
507
|
+
const result = original.apply(owner, args);
|
|
508
|
+
// retrieve(id, { stream: true }) resumes a background response as a stream.
|
|
509
|
+
let streamed = false;
|
|
510
|
+
try {
|
|
511
|
+
streamed = get(args[1], "stream") === true;
|
|
512
|
+
}
|
|
513
|
+
catch {
|
|
514
|
+
// fail-open
|
|
515
|
+
}
|
|
516
|
+
const observe = (value) => {
|
|
517
|
+
if (streamed) {
|
|
518
|
+
try {
|
|
519
|
+
return value && value[Symbol.asyncIterator] ? observedBackgroundStream(value) : value;
|
|
520
|
+
}
|
|
521
|
+
catch {
|
|
522
|
+
return value;
|
|
523
|
+
}
|
|
524
|
+
}
|
|
525
|
+
observeBackground(value);
|
|
526
|
+
return value;
|
|
527
|
+
};
|
|
528
|
+
if (result && typeof result.then === "function") {
|
|
529
|
+
return preserveProviderPromise(result, observe, (error) => {
|
|
530
|
+
throw error;
|
|
531
|
+
});
|
|
532
|
+
}
|
|
533
|
+
return observe(result);
|
|
534
|
+
};
|
|
535
|
+
wrapped.__metergraph__ = true;
|
|
536
|
+
owner[method] = wrapped;
|
|
537
|
+
return true;
|
|
538
|
+
}
|
|
539
|
+
function applyBackgroundObservers(client) {
|
|
540
|
+
let patched = 0;
|
|
541
|
+
for (const path of ["responses", "beta.responses"]) {
|
|
542
|
+
let owner;
|
|
543
|
+
try {
|
|
544
|
+
owner = resolveSeam(client, path);
|
|
545
|
+
}
|
|
546
|
+
catch {
|
|
547
|
+
continue;
|
|
548
|
+
}
|
|
549
|
+
for (const method of ["retrieve", "cancel"])
|
|
550
|
+
patched += Number(patchBackgroundObserver(owner, method));
|
|
551
|
+
}
|
|
552
|
+
return patched;
|
|
553
|
+
}
|
|
408
554
|
function patch(owner, method, provider, endpoint, gatewayName) {
|
|
409
555
|
if (!owner || typeof owner[method] !== "function")
|
|
410
556
|
return false;
|
|
@@ -433,6 +579,12 @@ function patch(owner, method, provider, endpoint, gatewayName) {
|
|
|
433
579
|
return original.apply(owner, args);
|
|
434
580
|
}
|
|
435
581
|
const incoming = requestFrom(args);
|
|
582
|
+
if (endpoint === "responses.stream" && incoming.response_id != null) {
|
|
583
|
+
// Resuming an existing (background) response is not a new model call:
|
|
584
|
+
// it retrieves with stream: true, and the retrieve observer records the
|
|
585
|
+
// held create once from its terminal event.
|
|
586
|
+
return original.apply(owner, args);
|
|
587
|
+
}
|
|
436
588
|
const patchUsage = typeof process === "undefined"
|
|
437
589
|
|| process.env.METERGRAPH_PATCH_STREAM_USAGE !== "0";
|
|
438
590
|
let injectedUsage = false;
|
|
@@ -482,7 +634,12 @@ function patch(owner, method, provider, endpoint, gatewayName) {
|
|
|
482
634
|
}
|
|
483
635
|
if (!settled) {
|
|
484
636
|
settled = true;
|
|
485
|
-
|
|
637
|
+
if (shouldHoldBackground(endpoint, request, response)) {
|
|
638
|
+
holdBackground(capture, state, response);
|
|
639
|
+
}
|
|
640
|
+
else {
|
|
641
|
+
finishCapture(capture, state, response);
|
|
642
|
+
}
|
|
486
643
|
}
|
|
487
644
|
return response;
|
|
488
645
|
};
|
|
@@ -613,7 +770,8 @@ function wrap(client, providerOrOptions) {
|
|
|
613
770
|
const name = provider ?? detectProvider(client);
|
|
614
771
|
const gatewayName = overrideGateway ?? (name === "openai" ? (0, gateway_js_1.detectGateway)(client) : undefined);
|
|
615
772
|
const patched = applySeams(client, name, gatewayName);
|
|
616
|
-
const patchedCount = patched.length + applyBatchExtras(client, name)
|
|
773
|
+
const patchedCount = patched.length + applyBatchExtras(client, name)
|
|
774
|
+
+ (name === "openai" ? applyBackgroundObservers(client) : 0);
|
|
617
775
|
const label = gatewayName ? `${gatewayName} gateway via ${name}` : name;
|
|
618
776
|
if (!patchedCount) {
|
|
619
777
|
console.warn(`Metergraph found no supported methods on ${label} client`);
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "metergraph",
|
|
3
|
-
"version": "0.6.
|
|
4
|
-
"description": "
|
|
3
|
+
"version": "0.6.14",
|
|
4
|
+
"description": "Zero-dependency TypeScript SDK for function-level LLM cost attribution across major LLM providers and frameworks, including OpenAI, Anthropic, Gemini, and Vercel AI SDK.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./dist/index.js",
|
|
7
7
|
"module": "./dist/index.mjs",
|
|
@@ -29,17 +29,29 @@
|
|
|
29
29
|
"node": ">=18"
|
|
30
30
|
},
|
|
31
31
|
"license": "Apache-2.0",
|
|
32
|
-
"author": "
|
|
32
|
+
"author": "Metergraph",
|
|
33
33
|
"homepage": "https://www.metergraph.dev/",
|
|
34
34
|
"repository": {
|
|
35
35
|
"type": "git",
|
|
36
|
-
"url": "git+https://github.com/
|
|
36
|
+
"url": "git+https://github.com/metergraph/metergraphsdk.git",
|
|
37
37
|
"directory": "typescript"
|
|
38
38
|
},
|
|
39
39
|
"bugs": {
|
|
40
|
-
"url": "https://github.com/
|
|
40
|
+
"url": "https://github.com/metergraph/metergraphsdk/issues"
|
|
41
41
|
},
|
|
42
|
-
"keywords": [
|
|
42
|
+
"keywords": [
|
|
43
|
+
"llm",
|
|
44
|
+
"llm-cost",
|
|
45
|
+
"llm-observability",
|
|
46
|
+
"cost-attribution",
|
|
47
|
+
"ai-agents",
|
|
48
|
+
"openai",
|
|
49
|
+
"anthropic",
|
|
50
|
+
"gemini",
|
|
51
|
+
"vercel-ai-sdk",
|
|
52
|
+
"opentelemetry",
|
|
53
|
+
"self-hosted"
|
|
54
|
+
],
|
|
43
55
|
"dependencies": {},
|
|
44
56
|
"devDependencies": {
|
|
45
57
|
"@ai-sdk/anthropic": "^4.0.39",
|