dsh-observe 0.1.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/CHANGELOG.md +25 -0
- package/LICENSE +201 -0
- package/README.es.md +198 -0
- package/README.hi.md +198 -0
- package/README.md +198 -0
- package/README.pt.md +198 -0
- package/README.zh.md +198 -0
- package/THIRD_PARTY_NOTICES.md +21 -0
- package/cordis.patch.yml +86 -0
- package/lib/index.js +1947 -0
- package/lib/typert.host.js +109 -0
- package/lib/types/backoff.d.ts +17 -0
- package/lib/types/backoff.d.ts.map +1 -0
- package/lib/types/backoff.js +17 -0
- package/lib/types/backoff.js.map +1 -0
- package/lib/types/collector.d.ts +83 -0
- package/lib/types/collector.d.ts.map +1 -0
- package/lib/types/collector.js +506 -0
- package/lib/types/collector.js.map +1 -0
- package/lib/types/config.d.ts +286 -0
- package/lib/types/config.d.ts.map +1 -0
- package/lib/types/config.js +312 -0
- package/lib/types/config.js.map +1 -0
- package/lib/types/ids.d.ts +43 -0
- package/lib/types/ids.d.ts.map +1 -0
- package/lib/types/ids.js +63 -0
- package/lib/types/ids.js.map +1 -0
- package/lib/types/index.d.ts +35 -0
- package/lib/types/index.d.ts.map +1 -0
- package/lib/types/index.js +162 -0
- package/lib/types/index.js.map +1 -0
- package/lib/types/model.d.ts +89 -0
- package/lib/types/model.d.ts.map +1 -0
- package/lib/types/model.js +25 -0
- package/lib/types/model.js.map +1 -0
- package/lib/types/pipeline.d.ts +71 -0
- package/lib/types/pipeline.d.ts.map +1 -0
- package/lib/types/pipeline.js +193 -0
- package/lib/types/pipeline.js.map +1 -0
- package/lib/types/pricing.d.ts +34 -0
- package/lib/types/pricing.d.ts.map +1 -0
- package/lib/types/pricing.js +45 -0
- package/lib/types/pricing.js.map +1 -0
- package/lib/types/project.d.ts +26 -0
- package/lib/types/project.d.ts.map +1 -0
- package/lib/types/project.js +52 -0
- package/lib/types/project.js.map +1 -0
- package/lib/types/remote.d.ts +28 -0
- package/lib/types/remote.d.ts.map +1 -0
- package/lib/types/remote.js +45 -0
- package/lib/types/remote.js.map +1 -0
- package/lib/types/sanitize.d.ts +78 -0
- package/lib/types/sanitize.d.ts.map +1 -0
- package/lib/types/sanitize.js +132 -0
- package/lib/types/sanitize.js.map +1 -0
- package/lib/types/sinks.d.ts +84 -0
- package/lib/types/sinks.d.ts.map +1 -0
- package/lib/types/sinks.js +434 -0
- package/lib/types/sinks.js.map +1 -0
- package/lib/types/spool.d.ts +113 -0
- package/lib/types/spool.d.ts.map +1 -0
- package/lib/types/spool.js +167 -0
- package/lib/types/spool.js.map +1 -0
- package/lib/types/typert.host.d.ts +93 -0
- package/lib/types/typert.host.d.ts.map +1 -0
- package/lib/types/typert.host.js +23 -0
- package/lib/types/typert.host.js.map +1 -0
- package/lib/types/version.d.ts +10 -0
- package/lib/types/version.d.ts.map +1 -0
- package/lib/types/version.js +10 -0
- package/lib/types/version.js.map +1 -0
- package/lib/types/wire.d.ts +206 -0
- package/lib/types/wire.d.ts.map +1 -0
- package/lib/types/wire.js +71 -0
- package/lib/types/wire.js.map +1 -0
- package/package.json +147 -0
- package/src/backoff.ts +20 -0
- package/src/collector.ts +561 -0
- package/src/config.ts +604 -0
- package/src/ids.ts +68 -0
- package/src/index.ts +186 -0
- package/src/model.ts +100 -0
- package/src/pipeline.ts +205 -0
- package/src/pricing.ts +55 -0
- package/src/project.ts +55 -0
- package/src/remote.ts +56 -0
- package/src/sanitize.ts +132 -0
- package/src/sinks.ts +471 -0
- package/src/spool.ts +196 -0
- package/src/typert.host.ts +24 -0
- package/src/version.ts +10 -0
- package/src/wire.ts +97 -0
package/lib/index.js
ADDED
|
@@ -0,0 +1,1947 @@
|
|
|
1
|
+
import z from "@deepseek-ai/schemastery";
|
|
2
|
+
import { defineDomain } from "@deepseek-ai/dsh-storage-domain";
|
|
3
|
+
import { z as z$1 } from "zod";
|
|
4
|
+
import { createHash } from "node:crypto";
|
|
5
|
+
import { isTokenDelta } from "@deepseek-ai/dsh-llm/message";
|
|
6
|
+
import { deriveEventMessage } from "@deepseek-ai/dsh-session";
|
|
7
|
+
import { TypertRemoteService } from "@deepseek-ai/dsh-typert-protocol";
|
|
8
|
+
//#region src/config.ts
|
|
9
|
+
/**
|
|
10
|
+
* Config schema and resolution for `dsh-observe`. Every tunable is a
|
|
11
|
+
* validated {@link Config} field changeable from cordis.yml; the resolution
|
|
12
|
+
* step validates numeric bounds, endpoint shapes, and backend credential
|
|
13
|
+
* presence so misconfiguration fails loud at mount — never silently skips
|
|
14
|
+
* or half-enables a backend. The plugin is off unless `enabled: true` AND at
|
|
15
|
+
* least one backend is configured: exporting observability data requires
|
|
16
|
+
* explicit opt-in (privacy default: off).
|
|
17
|
+
* @module dsh-observe/config
|
|
18
|
+
*/
|
|
19
|
+
/** Schemastery schema: the loader validates and fills defaults before `apply`. */
|
|
20
|
+
const Config = z.object({
|
|
21
|
+
enabled: z.boolean().default(false),
|
|
22
|
+
otlp: z.union([z.object({
|
|
23
|
+
endpoint: z.string().required(),
|
|
24
|
+
serviceName: z.string().default("deepseek-harness"),
|
|
25
|
+
serviceVersion: z.string(),
|
|
26
|
+
headers: z.dict(z.string()).default({}),
|
|
27
|
+
timeoutMs: z.number().default(1e4)
|
|
28
|
+
}), z.const(null)]).default(null),
|
|
29
|
+
langfuse: z.union([z.object({
|
|
30
|
+
baseUrl: z.string().default("https://cloud.langfuse.com"),
|
|
31
|
+
publicKey: z.string().required(),
|
|
32
|
+
secretKey: z.string().required(),
|
|
33
|
+
release: z.string(),
|
|
34
|
+
timeoutMs: z.number().default(1e4)
|
|
35
|
+
}), z.const(null)]).default(null),
|
|
36
|
+
capture: z.object({
|
|
37
|
+
turns: z.boolean().default(true),
|
|
38
|
+
steps: z.boolean().default(true),
|
|
39
|
+
tools: z.boolean().default(true),
|
|
40
|
+
llm: z.boolean().default(true)
|
|
41
|
+
}).default({
|
|
42
|
+
turns: true,
|
|
43
|
+
steps: true,
|
|
44
|
+
tools: true,
|
|
45
|
+
llm: true
|
|
46
|
+
}),
|
|
47
|
+
llm: z.object({
|
|
48
|
+
prompt: z.boolean().default(true),
|
|
49
|
+
completion: z.boolean().default(true)
|
|
50
|
+
}).default({
|
|
51
|
+
prompt: true,
|
|
52
|
+
completion: true
|
|
53
|
+
}),
|
|
54
|
+
metadata: z.object({
|
|
55
|
+
sessionId: z.boolean().default(true),
|
|
56
|
+
cwd: z.boolean().default(false),
|
|
57
|
+
agentPreset: z.boolean().default(true),
|
|
58
|
+
model: z.boolean().default(true)
|
|
59
|
+
}).default({
|
|
60
|
+
sessionId: true,
|
|
61
|
+
cwd: false,
|
|
62
|
+
agentPreset: true,
|
|
63
|
+
model: true
|
|
64
|
+
}),
|
|
65
|
+
metrics: z.object({
|
|
66
|
+
tokens: z.boolean().default(true),
|
|
67
|
+
cost: z.boolean().default(true),
|
|
68
|
+
contextTokens: z.boolean().default(true)
|
|
69
|
+
}).default({
|
|
70
|
+
tokens: true,
|
|
71
|
+
cost: true,
|
|
72
|
+
contextTokens: true
|
|
73
|
+
}),
|
|
74
|
+
pricing: z.array(z.object({
|
|
75
|
+
provider: z.string(),
|
|
76
|
+
model: z.string().required(),
|
|
77
|
+
inputPerToken: z.number().required(),
|
|
78
|
+
outputPerToken: z.number().required(),
|
|
79
|
+
cacheReadPerToken: z.number(),
|
|
80
|
+
cacheWritePerToken: z.number()
|
|
81
|
+
})).default([]),
|
|
82
|
+
sanitize: z.object({
|
|
83
|
+
enabled: z.boolean().default(true),
|
|
84
|
+
redactKeys: z.array(z.string()).default([]),
|
|
85
|
+
redactPatterns: z.array(z.string()).default([]),
|
|
86
|
+
truncatePromptChars: z.number().default(4e3),
|
|
87
|
+
truncateCompletionChars: z.number().default(4e3),
|
|
88
|
+
truncateToolInputChars: z.number().default(2e3),
|
|
89
|
+
truncateToolOutputChars: z.number().default(2e3),
|
|
90
|
+
truncateAttributeChars: z.number().default(512)
|
|
91
|
+
}).default({
|
|
92
|
+
enabled: true,
|
|
93
|
+
redactKeys: [],
|
|
94
|
+
redactPatterns: [],
|
|
95
|
+
truncatePromptChars: 4e3,
|
|
96
|
+
truncateCompletionChars: 4e3,
|
|
97
|
+
truncateToolInputChars: 2e3,
|
|
98
|
+
truncateToolOutputChars: 2e3,
|
|
99
|
+
truncateAttributeChars: 512
|
|
100
|
+
}),
|
|
101
|
+
batch: z.object({
|
|
102
|
+
maxRecords: z.number().default(256),
|
|
103
|
+
flushIntervalMs: z.number().default(5e3),
|
|
104
|
+
maxQueueRecords: z.number().default(2e3),
|
|
105
|
+
maxBufferRecords: z.number().default(1e4),
|
|
106
|
+
bufferRetryIntervalMs: z.number().default(3e4)
|
|
107
|
+
}).default({
|
|
108
|
+
maxRecords: 256,
|
|
109
|
+
flushIntervalMs: 5e3,
|
|
110
|
+
maxQueueRecords: 2e3,
|
|
111
|
+
maxBufferRecords: 1e4,
|
|
112
|
+
bufferRetryIntervalMs: 3e4
|
|
113
|
+
}),
|
|
114
|
+
retry: z.object({
|
|
115
|
+
maxAttempts: z.number().default(5),
|
|
116
|
+
baseDelayMs: z.number().default(1e3),
|
|
117
|
+
factor: z.number().default(2),
|
|
118
|
+
maxDelayMs: z.number().default(6e4)
|
|
119
|
+
}).default({
|
|
120
|
+
maxAttempts: 5,
|
|
121
|
+
baseDelayMs: 1e3,
|
|
122
|
+
factor: 2,
|
|
123
|
+
maxDelayMs: 6e4
|
|
124
|
+
}),
|
|
125
|
+
remote: z.object({ enabled: z.boolean().default(false) }).default({ enabled: false })
|
|
126
|
+
});
|
|
127
|
+
/** The redaction key substrings always applied, even with an empty `redactKeys`. */
|
|
128
|
+
const ALWAYS_REDACT_KEYS = [
|
|
129
|
+
"key",
|
|
130
|
+
"token",
|
|
131
|
+
"secret",
|
|
132
|
+
"password",
|
|
133
|
+
"authorization",
|
|
134
|
+
"credential"
|
|
135
|
+
];
|
|
136
|
+
/** Built-in secret patterns applied before the configured `redactPatterns`. */
|
|
137
|
+
const BUILTIN_REDACT_PATTERNS = [
|
|
138
|
+
/\bsk-[A-Za-z0-9]{16,}\b/u,
|
|
139
|
+
/\bghp_[A-Za-z0-9]{20,}\b/u,
|
|
140
|
+
/\bgho_[A-Za-z0-9]{20,}\b/u,
|
|
141
|
+
/\bAKIA[0-9A-Z]{16}\b/u,
|
|
142
|
+
/\bBearer\s+[A-Za-z0-9._~+/=-]{8,}\b/u,
|
|
143
|
+
/-----BEGIN [A-Z ]*PRIVATE KEY-----[A-Za-z0-9+/=\s]*-----END [A-Z ]*PRIVATE KEY-----/u
|
|
144
|
+
];
|
|
145
|
+
/** Throw unless `value` is a non-negative safe integer. */
|
|
146
|
+
function assertNonNegativeInt(name, value) {
|
|
147
|
+
if (!Number.isSafeInteger(value) || value < 0) throw new TypeError(`${name} must be a non-negative safe integer, got ${String(value)}`);
|
|
148
|
+
}
|
|
149
|
+
/** Throw unless `value` is a positive safe integer. */
|
|
150
|
+
function assertPositiveInt(name, value) {
|
|
151
|
+
if (!Number.isSafeInteger(value) || value <= 0) throw new TypeError(`${name} must be a positive safe integer, got ${String(value)}`);
|
|
152
|
+
}
|
|
153
|
+
/** Throw unless `value` is a finite number in `[min, max]`. */
|
|
154
|
+
function assertFiniteRange(name, value, min, max) {
|
|
155
|
+
if (typeof value !== "number" || !Number.isFinite(value) || value < min || value > max) throw new TypeError(`${name} must be a finite number in [${min}, ${max}], got ${String(value)}`);
|
|
156
|
+
}
|
|
157
|
+
/**
|
|
158
|
+
* Validate an http(s) URL string and normalize it to a clean base (no query,
|
|
159
|
+
* no fragment, no trailing slash).
|
|
160
|
+
* @param name - config key, for the error message.
|
|
161
|
+
* @param value - raw URL value.
|
|
162
|
+
* @returns the normalized base URL.
|
|
163
|
+
*/
|
|
164
|
+
function normalizeBaseUrl(name, value) {
|
|
165
|
+
let parsed;
|
|
166
|
+
try {
|
|
167
|
+
parsed = new URL(value);
|
|
168
|
+
} catch (error) {
|
|
169
|
+
throw new TypeError(`${name} must be a valid URL, got ${JSON.stringify(value)} (${error instanceof Error ? error.message : "invalid URL"})`);
|
|
170
|
+
}
|
|
171
|
+
if (parsed.protocol !== "http:" && parsed.protocol !== "https:") throw new TypeError(`${name} must use http(s), got ${JSON.stringify(parsed.protocol)}`);
|
|
172
|
+
parsed.search = "";
|
|
173
|
+
parsed.hash = "";
|
|
174
|
+
return parsed.href.replace(/\/+$/u, "");
|
|
175
|
+
}
|
|
176
|
+
/**
|
|
177
|
+
* Validate raw values and fill explicit defaults. Invalid enums, numeric
|
|
178
|
+
* bounds, endpoints, or credentials throw here — misconfiguration fails loud
|
|
179
|
+
* at mount even when the plugin is mounted without the Schemastery loader.
|
|
180
|
+
* `enabled: true` with no backend also throws: an enabled exporter with
|
|
181
|
+
* nowhere to send is a silent black hole, not a valid configuration.
|
|
182
|
+
* @param config - raw (possibly partial) plugin config.
|
|
183
|
+
* @returns the fully resolved config.
|
|
184
|
+
*/
|
|
185
|
+
function resolveConfig(config = {}) {
|
|
186
|
+
const enabled = config.enabled ?? false;
|
|
187
|
+
const otlpRaw = config.otlp ?? null;
|
|
188
|
+
const langfuseRaw = config.langfuse ?? null;
|
|
189
|
+
if (enabled && otlpRaw === null && langfuseRaw === null) throw new TypeError("enabled: true requires at least one backend (otlp or langfuse)");
|
|
190
|
+
const otlp = otlpRaw === null ? void 0 : (() => {
|
|
191
|
+
const endpoint = normalizeBaseUrl("otlp.endpoint", otlpRaw.endpoint);
|
|
192
|
+
if (endpoint.endsWith("/v1/traces") || endpoint.endsWith("/v1/metrics")) throw new TypeError("otlp.endpoint must be the OTLP base URL (e.g. http://localhost:4318); /v1/traces and /v1/metrics are appended");
|
|
193
|
+
if ((otlpRaw.serviceName ?? "deepseek-harness").trim().length === 0) throw new TypeError("otlp.serviceName must be a non-empty string");
|
|
194
|
+
const timeoutMs = otlpRaw.timeoutMs ?? 1e4;
|
|
195
|
+
assertPositiveInt("otlp.timeoutMs", timeoutMs);
|
|
196
|
+
return {
|
|
197
|
+
endpoint,
|
|
198
|
+
serviceName: (otlpRaw.serviceName ?? "deepseek-harness").trim(),
|
|
199
|
+
serviceVersion: otlpRaw.serviceVersion === void 0 ? void 0 : otlpRaw.serviceVersion,
|
|
200
|
+
headers: { ...otlpRaw.headers },
|
|
201
|
+
timeoutMs
|
|
202
|
+
};
|
|
203
|
+
})();
|
|
204
|
+
const langfuse = langfuseRaw === null ? void 0 : (() => {
|
|
205
|
+
const baseUrl = normalizeBaseUrl("langfuse.baseUrl", langfuseRaw.baseUrl ?? "https://cloud.langfuse.com");
|
|
206
|
+
if (langfuseRaw.publicKey.trim().length === 0) throw new TypeError("langfuse.publicKey must be a non-empty string");
|
|
207
|
+
if (langfuseRaw.secretKey.trim().length === 0) throw new TypeError("langfuse.secretKey must be a non-empty string");
|
|
208
|
+
const timeoutMs = langfuseRaw.timeoutMs ?? 1e4;
|
|
209
|
+
assertPositiveInt("langfuse.timeoutMs", timeoutMs);
|
|
210
|
+
return {
|
|
211
|
+
baseUrl,
|
|
212
|
+
publicKey: langfuseRaw.publicKey.trim(),
|
|
213
|
+
secretKey: langfuseRaw.secretKey.trim(),
|
|
214
|
+
release: langfuseRaw.release === void 0 ? void 0 : langfuseRaw.release,
|
|
215
|
+
timeoutMs
|
|
216
|
+
};
|
|
217
|
+
})();
|
|
218
|
+
const captureRaw = config.capture ?? {};
|
|
219
|
+
const llmRaw = config.llm ?? {};
|
|
220
|
+
const metadataRaw = config.metadata ?? {};
|
|
221
|
+
const metricsRaw = config.metrics ?? {};
|
|
222
|
+
const batchRaw = config.batch ?? {};
|
|
223
|
+
const batch = {
|
|
224
|
+
maxRecords: batchRaw.maxRecords ?? 256,
|
|
225
|
+
flushIntervalMs: batchRaw.flushIntervalMs ?? 5e3,
|
|
226
|
+
maxQueueRecords: batchRaw.maxQueueRecords ?? 2e3,
|
|
227
|
+
maxBufferRecords: batchRaw.maxBufferRecords ?? 1e4,
|
|
228
|
+
bufferRetryIntervalMs: batchRaw.bufferRetryIntervalMs ?? 3e4
|
|
229
|
+
};
|
|
230
|
+
assertPositiveInt("batch.maxRecords", batch.maxRecords);
|
|
231
|
+
assertPositiveInt("batch.flushIntervalMs", batch.flushIntervalMs);
|
|
232
|
+
assertPositiveInt("batch.maxQueueRecords", batch.maxQueueRecords);
|
|
233
|
+
assertPositiveInt("batch.maxBufferRecords", batch.maxBufferRecords);
|
|
234
|
+
assertPositiveInt("batch.bufferRetryIntervalMs", batch.bufferRetryIntervalMs);
|
|
235
|
+
const retryRaw = config.retry ?? {};
|
|
236
|
+
const retry = {
|
|
237
|
+
maxAttempts: retryRaw.maxAttempts ?? 5,
|
|
238
|
+
baseDelayMs: retryRaw.baseDelayMs ?? 1e3,
|
|
239
|
+
maxDelayMs: retryRaw.maxDelayMs ?? 6e4
|
|
240
|
+
};
|
|
241
|
+
assertPositiveInt("retry.maxAttempts", retry.maxAttempts);
|
|
242
|
+
assertPositiveInt("retry.baseDelayMs", retry.baseDelayMs);
|
|
243
|
+
assertPositiveInt("retry.maxDelayMs", retry.maxDelayMs);
|
|
244
|
+
assertFiniteRange("retry.factor", retryRaw.factor ?? 2, 1, 1e3);
|
|
245
|
+
const sanitizeRaw = config.sanitize ?? {};
|
|
246
|
+
const sanitize = {
|
|
247
|
+
enabled: sanitizeRaw.enabled ?? true,
|
|
248
|
+
redactKeys: [...ALWAYS_REDACT_KEYS, ...sanitizeRaw.redactKeys ?? []],
|
|
249
|
+
redactPatterns: compilePatterns([...BUILTIN_REDACT_PATTERNS.map((pattern) => pattern.source), ...sanitizeRaw.redactPatterns ?? []]),
|
|
250
|
+
truncatePromptChars: sanitizeRaw.truncatePromptChars ?? 4e3,
|
|
251
|
+
truncateCompletionChars: sanitizeRaw.truncateCompletionChars ?? 4e3,
|
|
252
|
+
truncateToolInputChars: sanitizeRaw.truncateToolInputChars ?? 2e3,
|
|
253
|
+
truncateToolOutputChars: sanitizeRaw.truncateToolOutputChars ?? 2e3,
|
|
254
|
+
truncateAttributeChars: sanitizeRaw.truncateAttributeChars ?? 512
|
|
255
|
+
};
|
|
256
|
+
assertNonNegativeInt("sanitize.truncatePromptChars", sanitize.truncatePromptChars);
|
|
257
|
+
assertNonNegativeInt("sanitize.truncateCompletionChars", sanitize.truncateCompletionChars);
|
|
258
|
+
assertNonNegativeInt("sanitize.truncateToolInputChars", sanitize.truncateToolInputChars);
|
|
259
|
+
assertNonNegativeInt("sanitize.truncateToolOutputChars", sanitize.truncateToolOutputChars);
|
|
260
|
+
assertPositiveInt("sanitize.truncateAttributeChars", sanitize.truncateAttributeChars);
|
|
261
|
+
const pricing = (config.pricing ?? []).map((rule, index) => {
|
|
262
|
+
if (typeof rule.model !== "string" || rule.model.trim().length === 0) throw new TypeError(`pricing[${index}].model must be a non-empty string`);
|
|
263
|
+
if (typeof rule.inputPerToken !== "number" || !Number.isFinite(rule.inputPerToken) || rule.inputPerToken < 0) throw new TypeError(`pricing[${index}].inputPerToken must be a non-negative finite number`);
|
|
264
|
+
if (typeof rule.outputPerToken !== "number" || !Number.isFinite(rule.outputPerToken) || rule.outputPerToken < 0) throw new TypeError(`pricing[${index}].outputPerToken must be a non-negative finite number`);
|
|
265
|
+
return {
|
|
266
|
+
...rule.provider === void 0 ? {} : { provider: rule.provider },
|
|
267
|
+
model: rule.model.trim(),
|
|
268
|
+
inputPerToken: rule.inputPerToken,
|
|
269
|
+
outputPerToken: rule.outputPerToken,
|
|
270
|
+
...rule.cacheReadPerToken === void 0 ? {} : { cacheReadPerToken: rule.cacheReadPerToken },
|
|
271
|
+
...rule.cacheWritePerToken === void 0 ? {} : { cacheWritePerToken: rule.cacheWritePerToken }
|
|
272
|
+
};
|
|
273
|
+
});
|
|
274
|
+
return {
|
|
275
|
+
enabled,
|
|
276
|
+
otlp,
|
|
277
|
+
langfuse,
|
|
278
|
+
capture: {
|
|
279
|
+
turns: captureRaw.turns ?? true,
|
|
280
|
+
steps: captureRaw.steps ?? true,
|
|
281
|
+
tools: captureRaw.tools ?? true,
|
|
282
|
+
llm: captureRaw.llm ?? true
|
|
283
|
+
},
|
|
284
|
+
llm: {
|
|
285
|
+
prompt: llmRaw.prompt ?? true,
|
|
286
|
+
completion: llmRaw.completion ?? true
|
|
287
|
+
},
|
|
288
|
+
metadata: {
|
|
289
|
+
sessionId: metadataRaw.sessionId ?? true,
|
|
290
|
+
cwd: metadataRaw.cwd ?? false,
|
|
291
|
+
agentPreset: metadataRaw.agentPreset ?? true,
|
|
292
|
+
model: metadataRaw.model ?? true
|
|
293
|
+
},
|
|
294
|
+
metrics: {
|
|
295
|
+
tokens: metricsRaw.tokens ?? true,
|
|
296
|
+
cost: metricsRaw.cost ?? true,
|
|
297
|
+
contextTokens: metricsRaw.contextTokens ?? true
|
|
298
|
+
},
|
|
299
|
+
pricing,
|
|
300
|
+
sanitize,
|
|
301
|
+
batch,
|
|
302
|
+
retry: {
|
|
303
|
+
...retry,
|
|
304
|
+
factor: retryRaw.factor ?? 2
|
|
305
|
+
},
|
|
306
|
+
remote: config.remote?.enabled ?? false
|
|
307
|
+
};
|
|
308
|
+
}
|
|
309
|
+
/** Compile user regexes at mount; an invalid pattern fails loud before any export runs. */
|
|
310
|
+
function compilePatterns(patterns) {
|
|
311
|
+
return patterns.map((pattern, index) => {
|
|
312
|
+
try {
|
|
313
|
+
return new RegExp(pattern, "gu");
|
|
314
|
+
} catch (error) {
|
|
315
|
+
throw new TypeError(`sanitize.redactPatterns[${index}] is not a valid regular expression: ${error instanceof Error ? error.message : String(error)}`);
|
|
316
|
+
}
|
|
317
|
+
});
|
|
318
|
+
}
|
|
319
|
+
//#endregion
|
|
320
|
+
//#region src/model.ts
|
|
321
|
+
/**
|
|
322
|
+
* Validate a value read back from the durable spool: it must look like an
|
|
323
|
+
* export record. The spool is a durable boundary, so hostile or hand-edited
|
|
324
|
+
* values are rejected here instead of reaching a sink.
|
|
325
|
+
* @param value - the stored value.
|
|
326
|
+
* @returns true when the value is an {@link ExportRecord}.
|
|
327
|
+
*/
|
|
328
|
+
function isExportRecord(value) {
|
|
329
|
+
if (typeof value !== "object" || value === null) return false;
|
|
330
|
+
const record = value;
|
|
331
|
+
if (record.kind === "span") return typeof record.span === "object" && record.span !== null;
|
|
332
|
+
if (record.kind === "metric") return typeof record.metric === "object" && record.metric !== null;
|
|
333
|
+
return false;
|
|
334
|
+
}
|
|
335
|
+
//#endregion
|
|
336
|
+
//#region src/spool.ts
|
|
337
|
+
/** One stored batch: creation time plus sanitized export records. */
|
|
338
|
+
const spoolBatchSchema = z$1.object({
|
|
339
|
+
createdAt: z$1.number().int().nonnegative(),
|
|
340
|
+
records: z$1.array(z$1.unknown())
|
|
341
|
+
});
|
|
342
|
+
/** The dsh-observe storage domain declaration. */
|
|
343
|
+
const observeDomainSpec = defineDomain({
|
|
344
|
+
name: "observe",
|
|
345
|
+
version: 1,
|
|
346
|
+
tables: { spool: { valueSchema: spoolBatchSchema } }
|
|
347
|
+
});
|
|
348
|
+
/** A monotonic, zero-padded key for lexicographically ordered batches. */
|
|
349
|
+
function batchKey(backend, seq) {
|
|
350
|
+
return `${backend}:${String(seq).padStart(16, "0")}`;
|
|
351
|
+
}
|
|
352
|
+
/**
|
|
353
|
+
* The offline buffer over one storage-domain table. The domain itself is
|
|
354
|
+
* opened and closed by the runtime; the spool only owns the table handle.
|
|
355
|
+
*/
|
|
356
|
+
var Spool = class {
|
|
357
|
+
table;
|
|
358
|
+
maxBufferRecords;
|
|
359
|
+
onDropped;
|
|
360
|
+
onInvalid;
|
|
361
|
+
nextSeq = 0;
|
|
362
|
+
bufferedRecords = 0;
|
|
363
|
+
/**
|
|
364
|
+
* @param table - the domain `spool` table handle.
|
|
365
|
+
* @param maxBufferRecords - total record bound across all backends.
|
|
366
|
+
* @param onDropped - receives the count of records dropped by bound eviction.
|
|
367
|
+
* @param onInvalid - receives the count of stored records rejected by validation.
|
|
368
|
+
*/
|
|
369
|
+
constructor(table, maxBufferRecords, onDropped, onInvalid) {
|
|
370
|
+
this.table = table;
|
|
371
|
+
this.maxBufferRecords = maxBufferRecords;
|
|
372
|
+
this.onDropped = onDropped;
|
|
373
|
+
this.onInvalid = onInvalid;
|
|
374
|
+
for (const [key, value] of this.table.entries()) {
|
|
375
|
+
const match = /^[a-z]+:(\d+)$/u.exec(key);
|
|
376
|
+
if (match !== null && match[1] !== void 0) this.nextSeq = Math.max(this.nextSeq, Number(match[1]) + 1);
|
|
377
|
+
this.bufferedRecords += value.records.length;
|
|
378
|
+
}
|
|
379
|
+
}
|
|
380
|
+
/** All batches in chronological write order (createdAt, then key). */
|
|
381
|
+
ordered() {
|
|
382
|
+
return [...this.table.entries()].sort((left, right) => left[1].createdAt - right[1].createdAt || left[0].localeCompare(right[0]));
|
|
383
|
+
}
|
|
384
|
+
/**
|
|
385
|
+
* Spill one batch into the buffer, enforcing the record bound: when the
|
|
386
|
+
* batch alone exceeds the bound only its newest records are kept, and
|
|
387
|
+
* otherwise the oldest stored batches are evicted until it fits. Drops
|
|
388
|
+
* are reported through {@link onDropped}.
|
|
389
|
+
* @param backend - the owning backend.
|
|
390
|
+
* @param records - sanitized records to persist.
|
|
391
|
+
* @returns resolution after the write and any evictions.
|
|
392
|
+
*/
|
|
393
|
+
async push(backend, records) {
|
|
394
|
+
if (records.length === 0) return;
|
|
395
|
+
let kept = records;
|
|
396
|
+
let dropped = 0;
|
|
397
|
+
if (kept.length > this.maxBufferRecords) {
|
|
398
|
+
dropped += kept.length - this.maxBufferRecords;
|
|
399
|
+
kept = kept.slice(kept.length - this.maxBufferRecords);
|
|
400
|
+
}
|
|
401
|
+
while (this.bufferedRecords + kept.length > this.maxBufferRecords) {
|
|
402
|
+
const oldest = this.ordered()[0];
|
|
403
|
+
if (oldest === void 0) break;
|
|
404
|
+
await this.table.delete(oldest[0]);
|
|
405
|
+
this.bufferedRecords -= oldest[1].records.length;
|
|
406
|
+
dropped += oldest[1].records.length;
|
|
407
|
+
}
|
|
408
|
+
const key = batchKey(backend, this.nextSeq);
|
|
409
|
+
this.nextSeq += 1;
|
|
410
|
+
await this.table.put(key, {
|
|
411
|
+
createdAt: Date.now(),
|
|
412
|
+
records: kept
|
|
413
|
+
});
|
|
414
|
+
this.bufferedRecords += kept.length;
|
|
415
|
+
if (dropped > 0) this.onDropped(dropped);
|
|
416
|
+
}
|
|
417
|
+
/**
|
|
418
|
+
* Read the oldest batches of one backend, up to a record budget. Stored
|
|
419
|
+
* records that fail {@link isExportRecord} are dropped from the returned
|
|
420
|
+
* set (and reported through {@link onInvalid}) but stay on disk until a
|
|
421
|
+
* later `remove` deletes their batch.
|
|
422
|
+
* @param backend - the backend to read.
|
|
423
|
+
* @param maxRecords - record budget for one drain cycle.
|
|
424
|
+
* @returns the batches (fully consumed, delete as a unit) and their records.
|
|
425
|
+
*/
|
|
426
|
+
peek(backend, maxRecords) {
|
|
427
|
+
const prefix = `${backend}:`;
|
|
428
|
+
const batches = [];
|
|
429
|
+
const records = [];
|
|
430
|
+
for (const [key, value] of this.ordered()) {
|
|
431
|
+
if (!key.startsWith(prefix)) continue;
|
|
432
|
+
const valid = [];
|
|
433
|
+
for (const record of value.records) if (isExportRecord(record)) valid.push(record);
|
|
434
|
+
if (valid.length !== value.records.length) this.onInvalid(value.records.length - valid.length);
|
|
435
|
+
batches.push({
|
|
436
|
+
backend,
|
|
437
|
+
key,
|
|
438
|
+
createdAt: value.createdAt,
|
|
439
|
+
records: valid
|
|
440
|
+
});
|
|
441
|
+
records.push(...valid);
|
|
442
|
+
if (records.length >= maxRecords) break;
|
|
443
|
+
}
|
|
444
|
+
return {
|
|
445
|
+
batches,
|
|
446
|
+
records
|
|
447
|
+
};
|
|
448
|
+
}
|
|
449
|
+
/**
|
|
450
|
+
* Delete delivered batches.
|
|
451
|
+
* @param batches - the batches that were exported successfully.
|
|
452
|
+
* @returns resolution after every delete.
|
|
453
|
+
*/
|
|
454
|
+
async remove(batches) {
|
|
455
|
+
await Promise.all(batches.map((batch) => this.table.delete(batch.key)));
|
|
456
|
+
for (const batch of batches) this.bufferedRecords -= batch.records.length;
|
|
457
|
+
}
|
|
458
|
+
/**
|
|
459
|
+
* Per-backend occupancy.
|
|
460
|
+
* @returns batch and record counts per backend.
|
|
461
|
+
*/
|
|
462
|
+
counts() {
|
|
463
|
+
const counts = {
|
|
464
|
+
otlp: {
|
|
465
|
+
batches: 0,
|
|
466
|
+
records: 0
|
|
467
|
+
},
|
|
468
|
+
langfuse: {
|
|
469
|
+
batches: 0,
|
|
470
|
+
records: 0
|
|
471
|
+
}
|
|
472
|
+
};
|
|
473
|
+
for (const [key, value] of this.table.entries()) {
|
|
474
|
+
const backend = key.startsWith("otlp:") ? "otlp" : "langfuse";
|
|
475
|
+
counts[backend].batches += 1;
|
|
476
|
+
counts[backend].records += value.records.length;
|
|
477
|
+
}
|
|
478
|
+
return counts;
|
|
479
|
+
}
|
|
480
|
+
};
|
|
481
|
+
/**
|
|
482
|
+
* Open the offline buffer over an already-opened domain.
|
|
483
|
+
* @param domain - the opened `observe` domain.
|
|
484
|
+
* @param maxBufferRecords - total record bound.
|
|
485
|
+
* @param onDropped - drop callback (bound eviction).
|
|
486
|
+
* @param onInvalid - invalid-record callback (durable-boundary validation).
|
|
487
|
+
* @returns the spool handle.
|
|
488
|
+
*/
|
|
489
|
+
function openSpool(domain, maxBufferRecords, onDropped, onInvalid) {
|
|
490
|
+
return new Spool(domain.table("spool"), maxBufferRecords, onDropped, onInvalid);
|
|
491
|
+
}
|
|
492
|
+
//#endregion
|
|
493
|
+
//#region src/ids.ts
|
|
494
|
+
/**
|
|
495
|
+
* Deterministic span and trace ids. Ids are SHA-256 digests of the session
|
|
496
|
+
* identity plus structural keys, truncated to the widths each backend
|
|
497
|
+
* requires (OTel: 16-byte trace ids / 8-byte span ids; Langfuse: 32-hex
|
|
498
|
+
* observation and trace ids). Determinism is a feature: replaying the same
|
|
499
|
+
* session log produces the same ids, so backends deduplicate re-exports
|
|
500
|
+
* instead of double-counting.
|
|
501
|
+
* @module dsh-observe/ids
|
|
502
|
+
*/
|
|
503
|
+
/**
|
|
504
|
+
* Digest joined structural parts to a fixed hex string.
|
|
505
|
+
* @param parts - the structural identity parts.
|
|
506
|
+
* @param bytes - digest length in bytes.
|
|
507
|
+
* @returns lowercase hex, `bytes * 2` characters.
|
|
508
|
+
*/
|
|
509
|
+
function digest(parts, bytes) {
|
|
510
|
+
const hash = createHash("sha256");
|
|
511
|
+
for (const part of parts) {
|
|
512
|
+
hash.update("|");
|
|
513
|
+
hash.update(typeof part);
|
|
514
|
+
hash.update("=");
|
|
515
|
+
hash.update(String(part));
|
|
516
|
+
}
|
|
517
|
+
return hash.digest("hex").slice(0, bytes * 2);
|
|
518
|
+
}
|
|
519
|
+
/**
|
|
520
|
+
* OTel trace id for one session turn (16 bytes, 32 hex chars).
|
|
521
|
+
* @param sessionId - the session identity.
|
|
522
|
+
* @param turn - the turn number.
|
|
523
|
+
* @returns the trace id.
|
|
524
|
+
*/
|
|
525
|
+
function otelTraceId(sessionId, turn) {
|
|
526
|
+
return digest([
|
|
527
|
+
"trace",
|
|
528
|
+
sessionId,
|
|
529
|
+
turn
|
|
530
|
+
], 16);
|
|
531
|
+
}
|
|
532
|
+
/**
|
|
533
|
+
* OTel span id for one span (8 bytes, 16 hex chars).
|
|
534
|
+
* @param parts - the span's structural identity.
|
|
535
|
+
* @returns the span id.
|
|
536
|
+
*/
|
|
537
|
+
function otelSpanId(...parts) {
|
|
538
|
+
return digest(["span", ...parts], 8);
|
|
539
|
+
}
|
|
540
|
+
/**
|
|
541
|
+
* Langfuse trace id for one session turn (32 hex chars).
|
|
542
|
+
* @param sessionId - the session identity.
|
|
543
|
+
* @param turn - the turn number.
|
|
544
|
+
* @returns the trace id.
|
|
545
|
+
*/
|
|
546
|
+
function langfuseTraceId(sessionId, turn) {
|
|
547
|
+
return digest([
|
|
548
|
+
"langfuse-trace",
|
|
549
|
+
sessionId,
|
|
550
|
+
turn
|
|
551
|
+
], 16);
|
|
552
|
+
}
|
|
553
|
+
/**
|
|
554
|
+
* Langfuse observation or event id (32 hex chars).
|
|
555
|
+
* @param parts - the observation's structural identity.
|
|
556
|
+
* @returns the id.
|
|
557
|
+
*/
|
|
558
|
+
function langfuseId(...parts) {
|
|
559
|
+
return digest(["langfuse", ...parts], 16);
|
|
560
|
+
}
|
|
561
|
+
//#endregion
|
|
562
|
+
//#region src/version.ts
|
|
563
|
+
/**
|
|
564
|
+
* Package version stamp shared by build artifacts (OTLP instrumentation
|
|
565
|
+
* scope) and the release script. `scripts/release.mjs` bumps this string
|
|
566
|
+
* together with package.json; tests/version.spec.ts trips when the two
|
|
567
|
+
* drift apart.
|
|
568
|
+
* @module dsh-observe/version
|
|
569
|
+
*/
|
|
570
|
+
/** The dsh-observe package version, kept in sync with package.json. */
|
|
571
|
+
const VERSION = "0.1.0";
|
|
572
|
+
//#endregion
|
|
573
|
+
//#region src/sinks.ts
|
|
574
|
+
/** POST a JSON body with a timeout; throws on non-2xx. */
|
|
575
|
+
async function postJson(url, headers, body, timeoutMs) {
|
|
576
|
+
const response = await fetch(url, {
|
|
577
|
+
method: "POST",
|
|
578
|
+
headers: {
|
|
579
|
+
"content-type": "application/json",
|
|
580
|
+
...headers
|
|
581
|
+
},
|
|
582
|
+
body: JSON.stringify(body),
|
|
583
|
+
signal: AbortSignal.timeout(timeoutMs)
|
|
584
|
+
});
|
|
585
|
+
if (!response.ok) throw new Error(`${url} responded ${response.status} ${response.statusText}`);
|
|
586
|
+
}
|
|
587
|
+
/** Encode one attribute value in OTLP/JSON form. */
|
|
588
|
+
function otlpValue(value) {
|
|
589
|
+
if (typeof value === "string") return { stringValue: value };
|
|
590
|
+
if (typeof value === "boolean") return { boolValue: value };
|
|
591
|
+
if (Number.isInteger(value)) return { intValue: String(value) };
|
|
592
|
+
return { doubleValue: value };
|
|
593
|
+
}
|
|
594
|
+
/** Encode one key/value pair as an OTLP/JSON attribute. */
|
|
595
|
+
function otlpAttribute(key, value) {
|
|
596
|
+
return {
|
|
597
|
+
key,
|
|
598
|
+
value: otlpValue(value)
|
|
599
|
+
};
|
|
600
|
+
}
|
|
601
|
+
/** OTel span status code. */
|
|
602
|
+
const STATUS_CODE_OK = 1;
|
|
603
|
+
const STATUS_CODE_ERROR = 2;
|
|
604
|
+
/** OTel span kind: INTERNAL. */
|
|
605
|
+
const SPAN_KIND_INTERNAL = 1;
|
|
606
|
+
/** Name of one span record, shared by both backends. */
|
|
607
|
+
function spanName(span) {
|
|
608
|
+
switch (span.kind) {
|
|
609
|
+
case "turn": return `turn ${span.turn}`;
|
|
610
|
+
case "step": return `step ${span.turn}.${String(span.step)}`;
|
|
611
|
+
case "tool": return `tool ${span.tool?.name ?? "unknown"}`;
|
|
612
|
+
case "llm": return "llm.request";
|
|
613
|
+
}
|
|
614
|
+
}
|
|
615
|
+
/** OTel span id of one span record. */
|
|
616
|
+
function spanIdOf(span) {
|
|
617
|
+
switch (span.kind) {
|
|
618
|
+
case "turn": return otelSpanId(span.sessionId, span.turn, "turn");
|
|
619
|
+
case "step": return otelSpanId(span.sessionId, span.turn, span.step ?? -1, "step");
|
|
620
|
+
case "tool": return otelSpanId(span.sessionId, span.turn, span.step ?? -1, span.callId ?? "tool");
|
|
621
|
+
case "llm": return otelSpanId(span.sessionId, span.turn, span.step ?? -1, "llm");
|
|
622
|
+
}
|
|
623
|
+
}
|
|
624
|
+
/** Parent OTel span id of one span record (step/tool/llm parent under their step span). */
|
|
625
|
+
function parentSpanIdOf(span) {
|
|
626
|
+
if (span.kind === "turn") return void 0;
|
|
627
|
+
return otelSpanId(span.sessionId, span.turn, span.step ?? -1, "step");
|
|
628
|
+
}
|
|
629
|
+
/** ISO-8601 timestamp of Unix nanoseconds (Langfuse wire format). */
|
|
630
|
+
function isoTimestamp(unixNano) {
|
|
631
|
+
return new Date(Math.floor(unixNano / 1e6)).toISOString();
|
|
632
|
+
}
|
|
633
|
+
/** One span in OTLP/JSON wire form. */
|
|
634
|
+
function otlpSpan(span) {
|
|
635
|
+
const attributes = Object.entries(span.attributes).map(([key, value]) => otlpAttribute(key, value));
|
|
636
|
+
if (span.tool !== void 0) {
|
|
637
|
+
attributes.push(otlpAttribute("tool.name", span.tool.name));
|
|
638
|
+
attributes.push(otlpAttribute("tool.status", span.tool.status));
|
|
639
|
+
attributes.push(otlpAttribute("tool.attempt", span.tool.attempt));
|
|
640
|
+
attributes.push(otlpAttribute("tool.retries", span.tool.retries));
|
|
641
|
+
if (span.tool.input !== void 0) attributes.push(otlpAttribute("tool.input", span.tool.input));
|
|
642
|
+
if (span.tool.output !== void 0) attributes.push(otlpAttribute("tool.output", span.tool.output));
|
|
643
|
+
if (span.tool.errorName !== void 0) attributes.push(otlpAttribute("tool.error.name", span.tool.errorName));
|
|
644
|
+
if (span.tool.errorCode !== void 0) attributes.push(otlpAttribute("tool.error.code", span.tool.errorCode));
|
|
645
|
+
}
|
|
646
|
+
if (span.llm !== void 0) {
|
|
647
|
+
if (span.llm.model !== void 0) attributes.push(otlpAttribute("llm.model", span.llm.model));
|
|
648
|
+
if (span.llm.provider !== void 0) attributes.push(otlpAttribute("llm.provider", span.llm.provider));
|
|
649
|
+
if (span.llm.finishReason !== void 0) attributes.push(otlpAttribute("llm.finish_reason", span.llm.finishReason));
|
|
650
|
+
if (span.llm.ttftMs !== void 0) attributes.push(otlpAttribute("llm.ttft_ms", span.llm.ttftMs));
|
|
651
|
+
if (span.llm.costUsd !== void 0) attributes.push(otlpAttribute("llm.cost_usd", span.llm.costUsd));
|
|
652
|
+
for (const [key, value] of usageAttributes(span.llm.usage)) attributes.push(otlpAttribute(key, value));
|
|
653
|
+
}
|
|
654
|
+
const events = [];
|
|
655
|
+
if (span.llm?.input !== void 0) events.push({
|
|
656
|
+
name: "gen_ai.prompt",
|
|
657
|
+
attributes: [otlpAttribute("gen_ai.prompt", span.llm.input)]
|
|
658
|
+
});
|
|
659
|
+
if (span.llm?.output !== void 0) events.push({
|
|
660
|
+
name: "gen_ai.completion",
|
|
661
|
+
attributes: [otlpAttribute("gen_ai.completion", span.llm.output)]
|
|
662
|
+
});
|
|
663
|
+
const error = span.status === "error";
|
|
664
|
+
return {
|
|
665
|
+
traceId: otelTraceId(span.sessionId, span.turn),
|
|
666
|
+
spanId: spanIdOf(span),
|
|
667
|
+
...parentSpanIdOf(span) === void 0 ? {} : { parentSpanId: parentSpanIdOf(span) },
|
|
668
|
+
name: spanName(span),
|
|
669
|
+
kind: SPAN_KIND_INTERNAL,
|
|
670
|
+
startTimeUnixNano: String(span.startUnixNano),
|
|
671
|
+
endTimeUnixNano: String(span.endUnixNano),
|
|
672
|
+
attributes,
|
|
673
|
+
events,
|
|
674
|
+
status: {
|
|
675
|
+
code: error ? STATUS_CODE_ERROR : STATUS_CODE_OK,
|
|
676
|
+
message: error ? spanError(span) : ""
|
|
677
|
+
}
|
|
678
|
+
};
|
|
679
|
+
}
|
|
680
|
+
/** Flatten usage counts to `usage.*` attributes. */
|
|
681
|
+
function usageAttributes(usage) {
|
|
682
|
+
if (usage === void 0) return [];
|
|
683
|
+
return [
|
|
684
|
+
["usage.input_tokens", usage.input],
|
|
685
|
+
["usage.output_tokens", usage.output],
|
|
686
|
+
["usage.cache_read_tokens", usage.cacheRead],
|
|
687
|
+
["usage.cache_write_tokens", usage.cacheWrite],
|
|
688
|
+
["usage.reasoning_tokens", usage.reasoning]
|
|
689
|
+
];
|
|
690
|
+
}
|
|
691
|
+
/** Error message for a failed span's status. */
|
|
692
|
+
function spanError(span) {
|
|
693
|
+
if (span.tool?.errorCode !== void 0) return `tool ${span.tool.name}: ${span.tool.errorCode}`;
|
|
694
|
+
if (span.tool !== void 0) return `tool ${span.tool.name}: aborted`;
|
|
695
|
+
return "span closed with error status";
|
|
696
|
+
}
|
|
697
|
+
/** A stable key for one metric aggregation: JSON over name + sorted attributes. */
|
|
698
|
+
function metricKey(metric) {
|
|
699
|
+
const attributes = Object.fromEntries(Object.entries(metric.attributes).sort(([left], [right]) => left.localeCompare(right)));
|
|
700
|
+
return JSON.stringify({
|
|
701
|
+
name: metric.name,
|
|
702
|
+
attributes
|
|
703
|
+
});
|
|
704
|
+
}
|
|
705
|
+
/** Parse a metric aggregation key back into name + attributes. */
|
|
706
|
+
function parseMetricKey(key) {
|
|
707
|
+
const parsed = JSON.parse(key);
|
|
708
|
+
return {
|
|
709
|
+
name: parsed.name,
|
|
710
|
+
attributes: parsed.attributes
|
|
711
|
+
};
|
|
712
|
+
}
|
|
713
|
+
/** An OTLP/JSON metric attribute (string values only). */
|
|
714
|
+
function otlpMetricAttributes(attributes) {
|
|
715
|
+
return Object.entries(attributes).map(([key, value]) => otlpAttribute(key, value));
|
|
716
|
+
}
|
|
717
|
+
/** OTel aggregation temporality: cumulative. */
|
|
718
|
+
const AGGREGATION_TEMPORALITY_CUMULATIVE = 2;
|
|
719
|
+
/**
|
|
720
|
+
* The OTLP/HTTP backend. Spans POST to `{endpoint}/v1/traces`; metrics are
|
|
721
|
+
* aggregated here into cumulative counters (and last-write-wins gauges) and
|
|
722
|
+
* POSTed to `{endpoint}/v1/metrics` by a periodic flush. Cumulative
|
|
723
|
+
* counters make a lost metric flush self-healing — the next flush carries
|
|
724
|
+
* the totals — which is why metrics intentionally bypass the retry/spool
|
|
725
|
+
* pipeline that protects spans.
|
|
726
|
+
*/
|
|
727
|
+
var OtlpSink = class {
|
|
728
|
+
config;
|
|
729
|
+
logger;
|
|
730
|
+
name = "otlp";
|
|
731
|
+
counters = /* @__PURE__ */ new Map();
|
|
732
|
+
gauges = /* @__PURE__ */ new Map();
|
|
733
|
+
metricsDirty = false;
|
|
734
|
+
/**
|
|
735
|
+
* @param config - the resolved OTLP backend config.
|
|
736
|
+
* @param logger - the plugin logger.
|
|
737
|
+
*/
|
|
738
|
+
constructor(config, logger) {
|
|
739
|
+
this.config = config;
|
|
740
|
+
this.logger = logger;
|
|
741
|
+
}
|
|
742
|
+
/**
|
|
743
|
+
* Fold one metric sample into the aggregation state. Counters accumulate
|
|
744
|
+
* deltas from the first-seen timestamp; gauges replace per key.
|
|
745
|
+
* @param metric - the sample.
|
|
746
|
+
*/
|
|
747
|
+
recordMetric(metric) {
|
|
748
|
+
if (metric.kind === "counter") {
|
|
749
|
+
const key = metricKey(metric);
|
|
750
|
+
const entry = this.counters.get(key);
|
|
751
|
+
if (entry === void 0) this.counters.set(key, {
|
|
752
|
+
startUnixNano: Date.now() * 1e6,
|
|
753
|
+
value: metric.value
|
|
754
|
+
});
|
|
755
|
+
else entry.value += metric.value;
|
|
756
|
+
} else this.gauges.set(metricKey(metric), metric.value);
|
|
757
|
+
this.metricsDirty = true;
|
|
758
|
+
}
|
|
759
|
+
/**
|
|
760
|
+
* Send the aggregated metrics if anything changed since the last flush.
|
|
761
|
+
* A failed flush re-flags the state through the failure counter, so the
|
|
762
|
+
* next cycle retries with the cumulative totals.
|
|
763
|
+
* @returns resolution after the POST (or immediately when clean).
|
|
764
|
+
*/
|
|
765
|
+
async flushMetrics() {
|
|
766
|
+
if (!this.metricsDirty) return;
|
|
767
|
+
this.metricsDirty = false;
|
|
768
|
+
const timeUnixNano = Date.now() * 1e6;
|
|
769
|
+
const metrics = [];
|
|
770
|
+
for (const [key, entry] of this.counters) {
|
|
771
|
+
const { name, attributes } = parseMetricKey(key);
|
|
772
|
+
metrics.push({
|
|
773
|
+
name,
|
|
774
|
+
unit: unitOf(name),
|
|
775
|
+
sum: {
|
|
776
|
+
dataPoints: [{
|
|
777
|
+
attributes: otlpMetricAttributes(attributes),
|
|
778
|
+
startTimeUnixNano: String(entry.startUnixNano),
|
|
779
|
+
timeUnixNano: String(timeUnixNano),
|
|
780
|
+
...Number.isInteger(entry.value) ? { asInt: String(entry.value) } : { asDouble: entry.value }
|
|
781
|
+
}],
|
|
782
|
+
aggregationTemporality: AGGREGATION_TEMPORALITY_CUMULATIVE,
|
|
783
|
+
isMonotonic: true
|
|
784
|
+
}
|
|
785
|
+
});
|
|
786
|
+
}
|
|
787
|
+
for (const [key, value] of this.gauges) {
|
|
788
|
+
const { name, attributes } = parseMetricKey(key);
|
|
789
|
+
metrics.push({
|
|
790
|
+
name,
|
|
791
|
+
unit: unitOf(name),
|
|
792
|
+
gauge: { dataPoints: [{
|
|
793
|
+
attributes: otlpMetricAttributes(attributes),
|
|
794
|
+
startTimeUnixNano: String(timeUnixNano),
|
|
795
|
+
timeUnixNano: String(timeUnixNano),
|
|
796
|
+
...Number.isInteger(value) ? { asInt: String(value) } : { asDouble: value }
|
|
797
|
+
}] }
|
|
798
|
+
});
|
|
799
|
+
}
|
|
800
|
+
try {
|
|
801
|
+
await postJson(`${this.config.endpoint}/v1/metrics`, this.config.headers, { resourceMetrics: [{
|
|
802
|
+
resource: this.resource(),
|
|
803
|
+
scopeMetrics: [{
|
|
804
|
+
scope: this.scope(),
|
|
805
|
+
metrics
|
|
806
|
+
}]
|
|
807
|
+
}] }, this.config.timeoutMs);
|
|
808
|
+
} catch (error) {
|
|
809
|
+
this.logger.warn(`otlp: metrics flush failed: ${error instanceof Error ? error.message : String(error)}`);
|
|
810
|
+
this.recordMetric({
|
|
811
|
+
name: "observe.export_failures",
|
|
812
|
+
kind: "counter",
|
|
813
|
+
unit: "requests",
|
|
814
|
+
value: 1,
|
|
815
|
+
attributes: {
|
|
816
|
+
backend: "otlp",
|
|
817
|
+
kind: "metrics"
|
|
818
|
+
}
|
|
819
|
+
});
|
|
820
|
+
}
|
|
821
|
+
}
|
|
822
|
+
async exportSpans(records) {
|
|
823
|
+
const spans = records.flatMap((record) => record.kind === "span" ? [record.span] : []);
|
|
824
|
+
if (spans.length === 0) return;
|
|
825
|
+
await postJson(`${this.config.endpoint}/v1/traces`, this.config.headers, { resourceSpans: [{
|
|
826
|
+
resource: this.resource(),
|
|
827
|
+
scopeSpans: [{
|
|
828
|
+
scope: this.scope(),
|
|
829
|
+
spans: spans.map(otlpSpan)
|
|
830
|
+
}]
|
|
831
|
+
}] }, this.config.timeoutMs);
|
|
832
|
+
}
|
|
833
|
+
/** The OTel resource (service identity). */
|
|
834
|
+
resource() {
|
|
835
|
+
return { attributes: [otlpAttribute("service.name", this.config.serviceName), ...this.config.serviceVersion === void 0 ? [] : [otlpAttribute("service.version", this.config.serviceVersion)]] };
|
|
836
|
+
}
|
|
837
|
+
/** The instrumentation scope. */
|
|
838
|
+
scope() {
|
|
839
|
+
return {
|
|
840
|
+
name: "dsh-observe",
|
|
841
|
+
version: VERSION
|
|
842
|
+
};
|
|
843
|
+
}
|
|
844
|
+
};
|
|
845
|
+
/** Parse a metric aggregation key back into name + attributes. */
|
|
846
|
+
/** Metric units. */
|
|
847
|
+
function unitOf(name) {
|
|
848
|
+
if (name === "observe.cost") return "USD";
|
|
849
|
+
if (name === "observe.export_failures" || name === "observe.spool_flushed") return "requests";
|
|
850
|
+
return "records";
|
|
851
|
+
}
|
|
852
|
+
/**
|
|
853
|
+
* The Langfuse backend. Each export batch is one ingestion POST; the trace
|
|
854
|
+
* each observation belongs to is created (once per trace id, remembered
|
|
855
|
+
* after a successful POST) inside the same batch, so a batch is always
|
|
856
|
+
* self-contained and retries stay idempotent — Langfuse upserts on event
|
|
857
|
+
* ids.
|
|
858
|
+
*/
|
|
859
|
+
var LangfuseSink = class {
|
|
860
|
+
config;
|
|
861
|
+
logger;
|
|
862
|
+
name = "langfuse";
|
|
863
|
+
seenTraces = /* @__PURE__ */ new Set();
|
|
864
|
+
/**
|
|
865
|
+
* @param config - the resolved Langfuse backend config.
|
|
866
|
+
* @param logger - the plugin logger.
|
|
867
|
+
*/
|
|
868
|
+
constructor(config, logger) {
|
|
869
|
+
this.config = config;
|
|
870
|
+
this.logger = logger;
|
|
871
|
+
}
|
|
872
|
+
async exportSpans(records) {
|
|
873
|
+
const spans = records.flatMap((record) => record.kind === "span" ? [record.span] : []);
|
|
874
|
+
if (spans.length === 0) return;
|
|
875
|
+
const events = [];
|
|
876
|
+
const ensured = [];
|
|
877
|
+
const ensuredInBatch = /* @__PURE__ */ new Set();
|
|
878
|
+
for (const span of spans) {
|
|
879
|
+
const traceId = langfuseTraceId(span.sessionId, span.turn);
|
|
880
|
+
if (!this.seenTraces.has(traceId) && !ensuredInBatch.has(traceId)) {
|
|
881
|
+
ensuredInBatch.add(traceId);
|
|
882
|
+
ensured.push(traceId);
|
|
883
|
+
events.push(this.traceEvent(traceId, span));
|
|
884
|
+
}
|
|
885
|
+
events.push(this.observationEvent(traceId, span));
|
|
886
|
+
}
|
|
887
|
+
try {
|
|
888
|
+
await this.post({ batch: events });
|
|
889
|
+
for (const traceId of ensured) this.seenTraces.add(traceId);
|
|
890
|
+
} catch (error) {
|
|
891
|
+
this.logger.warn(`langfuse: export failed: ${error instanceof Error ? error.message : String(error)}`);
|
|
892
|
+
throw error;
|
|
893
|
+
}
|
|
894
|
+
}
|
|
895
|
+
/** The `trace-create` event for one turn span. */
|
|
896
|
+
traceEvent(traceId, span) {
|
|
897
|
+
const metadata = { ...span.attributes };
|
|
898
|
+
if (span.kind === "turn") metadata["observe.span.kind"] = "turn";
|
|
899
|
+
return {
|
|
900
|
+
id: langfuseId("trace-event", traceId),
|
|
901
|
+
timestamp: isoTimestamp(span.startUnixNano),
|
|
902
|
+
type: "trace-create",
|
|
903
|
+
body: {
|
|
904
|
+
id: traceId,
|
|
905
|
+
name: `session ${span.sessionId} turn ${span.turn}`,
|
|
906
|
+
sessionId: span.sessionId,
|
|
907
|
+
timestamp: isoTimestamp(span.startUnixNano),
|
|
908
|
+
metadata,
|
|
909
|
+
...this.config.release === void 0 ? {} : { release: this.config.release }
|
|
910
|
+
}
|
|
911
|
+
};
|
|
912
|
+
}
|
|
913
|
+
/** The observation event for one span (span-create or generation-create). */
|
|
914
|
+
observationEvent(traceId, span) {
|
|
915
|
+
if (span.llm !== void 0) return this.generationEvent(traceId, span);
|
|
916
|
+
const id = span.kind === "step" ? langfuseId("step", span.sessionId, span.turn, span.step ?? -1) : langfuseId("tool", span.sessionId, span.turn, span.step ?? -1, span.callId ?? span.tool?.name ?? "tool");
|
|
917
|
+
return {
|
|
918
|
+
id: langfuseId("span-event", id),
|
|
919
|
+
timestamp: isoTimestamp(span.startUnixNano),
|
|
920
|
+
type: "span-create",
|
|
921
|
+
body: {
|
|
922
|
+
id,
|
|
923
|
+
traceId,
|
|
924
|
+
name: spanName(span),
|
|
925
|
+
startTime: isoTimestamp(span.startUnixNano),
|
|
926
|
+
endTime: isoTimestamp(span.endUnixNano),
|
|
927
|
+
metadata: {
|
|
928
|
+
...span.attributes,
|
|
929
|
+
...span.tool === void 0 ? {} : { "tool.status": span.tool.status }
|
|
930
|
+
},
|
|
931
|
+
...span.tool?.input === void 0 ? {} : { input: span.tool.input },
|
|
932
|
+
...span.tool?.output === void 0 ? {} : { output: span.tool.output },
|
|
933
|
+
level: span.status === "error" ? "ERROR" : "DEFAULT"
|
|
934
|
+
}
|
|
935
|
+
};
|
|
936
|
+
}
|
|
937
|
+
/** The `generation-create` event for one LLM span. */
|
|
938
|
+
generationEvent(traceId, span) {
|
|
939
|
+
const id = langfuseId("generation", span.sessionId, span.turn, span.step ?? -1);
|
|
940
|
+
const usage = span.llm?.usage;
|
|
941
|
+
return {
|
|
942
|
+
id: langfuseId("generation-event", id),
|
|
943
|
+
timestamp: isoTimestamp(span.startUnixNano),
|
|
944
|
+
type: "generation-create",
|
|
945
|
+
body: {
|
|
946
|
+
id,
|
|
947
|
+
traceId,
|
|
948
|
+
name: "llm.request",
|
|
949
|
+
startTime: isoTimestamp(span.startUnixNano),
|
|
950
|
+
endTime: isoTimestamp(span.endUnixNano),
|
|
951
|
+
...span.llm?.model === void 0 ? {} : { model: span.llm.model },
|
|
952
|
+
metadata: {
|
|
953
|
+
...span.attributes,
|
|
954
|
+
...span.llm?.costUsd === void 0 ? {} : { costUsd: span.llm.costUsd }
|
|
955
|
+
},
|
|
956
|
+
...span.llm?.input === void 0 ? {} : { input: span.llm.input },
|
|
957
|
+
...span.llm?.output === void 0 ? {} : { output: span.llm.output },
|
|
958
|
+
...usage === void 0 ? {} : { usage: {
|
|
959
|
+
input: usage.input + usage.cacheRead + usage.cacheWrite,
|
|
960
|
+
output: usage.output,
|
|
961
|
+
total: usage.input + usage.cacheRead + usage.cacheWrite + usage.output,
|
|
962
|
+
unit: "TOKENS"
|
|
963
|
+
} },
|
|
964
|
+
level: span.status === "error" ? "ERROR" : "DEFAULT"
|
|
965
|
+
}
|
|
966
|
+
};
|
|
967
|
+
}
|
|
968
|
+
/** POST one ingestion batch with Basic auth. */
|
|
969
|
+
async post(body) {
|
|
970
|
+
const authorization = Buffer.from(`${this.config.publicKey}:${this.config.secretKey}`, "utf8").toString("base64");
|
|
971
|
+
const response = await fetch(`${this.config.baseUrl}/api/public/ingestion`, {
|
|
972
|
+
method: "POST",
|
|
973
|
+
headers: {
|
|
974
|
+
"content-type": "application/json",
|
|
975
|
+
authorization: `Basic ${authorization}`
|
|
976
|
+
},
|
|
977
|
+
body: JSON.stringify(body),
|
|
978
|
+
signal: AbortSignal.timeout(this.config.timeoutMs)
|
|
979
|
+
});
|
|
980
|
+
if (!response.ok) throw new Error(`langfuse ingestion responded ${response.status} ${response.statusText}`);
|
|
981
|
+
const result = await response.json();
|
|
982
|
+
if (Array.isArray(result.errors) && result.errors.length > 0) throw new Error(`langfuse ingestion reported ${result.errors.length} event error(s)`);
|
|
983
|
+
}
|
|
984
|
+
};
|
|
985
|
+
//#endregion
|
|
986
|
+
//#region src/backoff.ts
|
|
987
|
+
/**
|
|
988
|
+
* Backoff delay computation for export retries: deterministic exponential
|
|
989
|
+
* backoff (no jitter — tests and replays stay reproducible).
|
|
990
|
+
* @module dsh-observe/backoff
|
|
991
|
+
*/
|
|
992
|
+
/**
|
|
993
|
+
* Compute the delay before the next retry attempt.
|
|
994
|
+
* @param consecutiveFailures - failures so far (1 = first retry).
|
|
995
|
+
* @param policy - the resolved retry policy.
|
|
996
|
+
* @returns the delay in milliseconds, capped at `maxDelayMs`.
|
|
997
|
+
*/
|
|
998
|
+
function backoffDelayMs(consecutiveFailures, policy) {
|
|
999
|
+
const exponent = Math.min(consecutiveFailures, 30);
|
|
1000
|
+
const delay = policy.baseDelayMs * policy.factor ** exponent;
|
|
1001
|
+
return Math.min(delay, policy.maxDelayMs);
|
|
1002
|
+
}
|
|
1003
|
+
//#endregion
|
|
1004
|
+
//#region src/pipeline.ts
|
|
1005
|
+
/**
|
|
1006
|
+
* One backend's delivery pipeline. Push is synchronous (the session event
|
|
1007
|
+
* hot path); all network work happens on timers or in the background.
|
|
1008
|
+
*/
|
|
1009
|
+
var Pipeline = class {
|
|
1010
|
+
options;
|
|
1011
|
+
queue = [];
|
|
1012
|
+
pending;
|
|
1013
|
+
inFlight = false;
|
|
1014
|
+
consecutiveFailures = 0;
|
|
1015
|
+
retryTimer;
|
|
1016
|
+
disposed = false;
|
|
1017
|
+
/**
|
|
1018
|
+
* @param options - the pipeline options (copied, never mutated).
|
|
1019
|
+
*/
|
|
1020
|
+
constructor(options) {
|
|
1021
|
+
this.options = options;
|
|
1022
|
+
}
|
|
1023
|
+
/** Records currently queued or awaiting retry. */
|
|
1024
|
+
get depth() {
|
|
1025
|
+
return this.queue.length + (this.pending?.length ?? 0);
|
|
1026
|
+
}
|
|
1027
|
+
/** The backend this pipeline delivers to (`otlp` / `langfuse`). */
|
|
1028
|
+
get name() {
|
|
1029
|
+
return this.options.name;
|
|
1030
|
+
}
|
|
1031
|
+
/**
|
|
1032
|
+
* Queue one record. A disabled runtime drops it (counted); a full queue
|
|
1033
|
+
* spills it straight into the durable buffer (bounded; oldest records
|
|
1034
|
+
* there are evicted first).
|
|
1035
|
+
* @param record - the owned, sanitized record.
|
|
1036
|
+
*/
|
|
1037
|
+
push(record) {
|
|
1038
|
+
if (this.disposed) return;
|
|
1039
|
+
if (!this.options.isEnabled()) {
|
|
1040
|
+
this.options.onMetric({
|
|
1041
|
+
name: "observe.dropped",
|
|
1042
|
+
kind: "counter",
|
|
1043
|
+
unit: "records",
|
|
1044
|
+
value: 1,
|
|
1045
|
+
attributes: {
|
|
1046
|
+
reason: "disabled",
|
|
1047
|
+
backend: this.options.name
|
|
1048
|
+
}
|
|
1049
|
+
});
|
|
1050
|
+
return;
|
|
1051
|
+
}
|
|
1052
|
+
if (this.queue.length < this.options.batch.maxQueueRecords) {
|
|
1053
|
+
this.queue.push(record);
|
|
1054
|
+
if (this.queue.length >= this.options.batch.maxRecords) this.kick();
|
|
1055
|
+
return;
|
|
1056
|
+
}
|
|
1057
|
+
this.options.spool.push(this.options.name, [record]).catch((error) => {
|
|
1058
|
+
this.options.logger.warn(`${this.options.name}: buffer spill failed: ${error instanceof Error ? error.message : String(error)}`);
|
|
1059
|
+
});
|
|
1060
|
+
}
|
|
1061
|
+
/** Start a flush immediately when no flush is already running or scheduled. */
|
|
1062
|
+
kick() {
|
|
1063
|
+
if (this.retryTimer !== void 0 || this.inFlight) return;
|
|
1064
|
+
this.flushOnce();
|
|
1065
|
+
}
|
|
1066
|
+
/** The periodic flush entry point. */
|
|
1067
|
+
async tick() {
|
|
1068
|
+
await this.flushOnce();
|
|
1069
|
+
}
|
|
1070
|
+
/** One flush attempt: pending retry batch first, otherwise the queue head. */
|
|
1071
|
+
async flushOnce() {
|
|
1072
|
+
if (this.inFlight || this.disposed) return;
|
|
1073
|
+
const batch = this.pending ?? this.queue.splice(0, this.options.batch.maxRecords);
|
|
1074
|
+
if (batch.length === 0) return;
|
|
1075
|
+
this.inFlight = true;
|
|
1076
|
+
try {
|
|
1077
|
+
await this.options.sink.exportSpans(batch);
|
|
1078
|
+
this.consecutiveFailures = 0;
|
|
1079
|
+
this.pending = void 0;
|
|
1080
|
+
} catch (error) {
|
|
1081
|
+
this.consecutiveFailures += 1;
|
|
1082
|
+
this.pending = batch;
|
|
1083
|
+
if (this.consecutiveFailures >= this.options.retry.maxAttempts) {
|
|
1084
|
+
this.pending = void 0;
|
|
1085
|
+
this.consecutiveFailures = 0;
|
|
1086
|
+
await this.options.spool.push(this.options.name, batch);
|
|
1087
|
+
this.options.onMetric({
|
|
1088
|
+
name: "observe.spooled",
|
|
1089
|
+
kind: "counter",
|
|
1090
|
+
unit: "records",
|
|
1091
|
+
value: batch.length,
|
|
1092
|
+
attributes: { backend: this.options.name }
|
|
1093
|
+
});
|
|
1094
|
+
} else this.scheduleRetry();
|
|
1095
|
+
this.options.onMetric({
|
|
1096
|
+
name: "observe.export_failures",
|
|
1097
|
+
kind: "counter",
|
|
1098
|
+
unit: "requests",
|
|
1099
|
+
value: 1,
|
|
1100
|
+
attributes: { backend: this.options.name }
|
|
1101
|
+
});
|
|
1102
|
+
this.options.logger.warn(`${this.options.name}: export attempt ${this.consecutiveFailures} failed: ${error instanceof Error ? error.message : String(error)}`);
|
|
1103
|
+
} finally {
|
|
1104
|
+
this.inFlight = false;
|
|
1105
|
+
}
|
|
1106
|
+
}
|
|
1107
|
+
/** Schedule the backoff retry for the pending batch. */
|
|
1108
|
+
scheduleRetry() {
|
|
1109
|
+
if (this.disposed || this.retryTimer !== void 0) return;
|
|
1110
|
+
const delay = backoffDelayMs(this.consecutiveFailures, this.options.retry);
|
|
1111
|
+
this.retryTimer = setTimeout(() => {
|
|
1112
|
+
this.retryTimer = void 0;
|
|
1113
|
+
this.flushOnce();
|
|
1114
|
+
}, delay);
|
|
1115
|
+
}
|
|
1116
|
+
/**
|
|
1117
|
+
* Try the oldest buffered batches once. Batches that fail stay in the
|
|
1118
|
+
* buffer for the next cycle; success deletes them.
|
|
1119
|
+
*/
|
|
1120
|
+
async drainSpool() {
|
|
1121
|
+
if (this.inFlight || this.disposed) return;
|
|
1122
|
+
const { batches, records } = this.options.spool.peek(this.options.name, this.options.batch.maxRecords);
|
|
1123
|
+
if (records.length === 0) return;
|
|
1124
|
+
this.inFlight = true;
|
|
1125
|
+
try {
|
|
1126
|
+
await this.options.sink.exportSpans(records);
|
|
1127
|
+
await this.options.spool.remove(batches);
|
|
1128
|
+
this.consecutiveFailures = 0;
|
|
1129
|
+
this.options.onMetric({
|
|
1130
|
+
name: "observe.spool_flushed",
|
|
1131
|
+
kind: "counter",
|
|
1132
|
+
unit: "records",
|
|
1133
|
+
value: records.length,
|
|
1134
|
+
attributes: { backend: this.options.name }
|
|
1135
|
+
});
|
|
1136
|
+
} catch (error) {
|
|
1137
|
+
this.options.onMetric({
|
|
1138
|
+
name: "observe.export_failures",
|
|
1139
|
+
kind: "counter",
|
|
1140
|
+
unit: "requests",
|
|
1141
|
+
value: 1,
|
|
1142
|
+
attributes: {
|
|
1143
|
+
backend: this.options.name,
|
|
1144
|
+
kind: "buffer"
|
|
1145
|
+
}
|
|
1146
|
+
});
|
|
1147
|
+
this.options.logger.warn(`${this.options.name}: buffer drain failed: ${error instanceof Error ? error.message : String(error)}`);
|
|
1148
|
+
} finally {
|
|
1149
|
+
this.inFlight = false;
|
|
1150
|
+
}
|
|
1151
|
+
}
|
|
1152
|
+
/**
|
|
1153
|
+
* Final flush on unload: one best-effort export of everything queued;
|
|
1154
|
+
* whatever fails goes to the durable buffer for the next process run.
|
|
1155
|
+
*/
|
|
1156
|
+
async dispose() {
|
|
1157
|
+
this.disposed = true;
|
|
1158
|
+
if (this.retryTimer !== void 0) {
|
|
1159
|
+
clearTimeout(this.retryTimer);
|
|
1160
|
+
this.retryTimer = void 0;
|
|
1161
|
+
}
|
|
1162
|
+
const batch = [...this.pending ?? [], ...this.queue];
|
|
1163
|
+
this.queue = [];
|
|
1164
|
+
this.pending = void 0;
|
|
1165
|
+
if (batch.length === 0) return;
|
|
1166
|
+
try {
|
|
1167
|
+
await this.options.sink.exportSpans(batch);
|
|
1168
|
+
} catch {
|
|
1169
|
+
try {
|
|
1170
|
+
await this.options.spool.push(this.options.name, batch);
|
|
1171
|
+
} catch (error) {
|
|
1172
|
+
this.options.logger.warn(`${this.options.name}: final buffer spill failed: ${error instanceof Error ? error.message : String(error)}`);
|
|
1173
|
+
}
|
|
1174
|
+
}
|
|
1175
|
+
}
|
|
1176
|
+
};
|
|
1177
|
+
//#endregion
|
|
1178
|
+
//#region src/pricing.ts
|
|
1179
|
+
/**
|
|
1180
|
+
* Compile a glob pattern (only `*` is special) to an anchored regular
|
|
1181
|
+
* expression.
|
|
1182
|
+
* @param pattern - the glob pattern over a model id.
|
|
1183
|
+
* @returns the compiled matcher.
|
|
1184
|
+
*/
|
|
1185
|
+
function globToRegExp(pattern) {
|
|
1186
|
+
const escaped = pattern.replace(/[.+?^${}()|[\]\\]/gu, "\\$&").replaceAll("*", ".*");
|
|
1187
|
+
return new RegExp(`^${escaped}$`, "u");
|
|
1188
|
+
}
|
|
1189
|
+
/**
|
|
1190
|
+
* Find the first pricing rule matching the attribution: `provider` matches
|
|
1191
|
+
* exactly when set, `model` matches as a glob.
|
|
1192
|
+
* @param pricing - the configured pricing table, in priority order.
|
|
1193
|
+
* @param provider - the provider route id.
|
|
1194
|
+
* @param model - the model id.
|
|
1195
|
+
* @returns the first matching rule, or undefined.
|
|
1196
|
+
*/
|
|
1197
|
+
function findPrice(pricing, provider, model) {
|
|
1198
|
+
return pricing.find((rule) => (rule.provider === void 0 || rule.provider === provider) && globToRegExp(rule.model).test(model));
|
|
1199
|
+
}
|
|
1200
|
+
/**
|
|
1201
|
+
* Compute the USD cost of one call under a matched rule. Cache-read and
|
|
1202
|
+
* cache-write traffic falls back to the input price when the rule does not
|
|
1203
|
+
* price them separately.
|
|
1204
|
+
* @param rule - the matched pricing rule.
|
|
1205
|
+
* @param usage - the normalized token counts.
|
|
1206
|
+
* @returns the cost in USD.
|
|
1207
|
+
*/
|
|
1208
|
+
function costUsd(rule, usage) {
|
|
1209
|
+
const cacheRead = usage.cacheRead * (rule.cacheReadPerToken ?? rule.inputPerToken);
|
|
1210
|
+
const cacheWrite = usage.cacheWrite * (rule.cacheWritePerToken ?? rule.inputPerToken);
|
|
1211
|
+
return usage.input * rule.inputPerToken + usage.output * rule.outputPerToken + cacheRead + cacheWrite;
|
|
1212
|
+
}
|
|
1213
|
+
//#endregion
|
|
1214
|
+
//#region src/project.ts
|
|
1215
|
+
/**
|
|
1216
|
+
* Project content blocks to one compact plain-text string. Text and
|
|
1217
|
+
* reasoning deltas pass through verbatim; tool calls render as
|
|
1218
|
+
* `<tool-call name(arguments)>`; images render as `[image]`; tool results
|
|
1219
|
+
* recurse. Unknown block types (merge-extensible) are skipped — they carry
|
|
1220
|
+
* no projectable text.
|
|
1221
|
+
* @param blocks - the model-facing content blocks.
|
|
1222
|
+
* @returns the joined projection.
|
|
1223
|
+
*/
|
|
1224
|
+
function projectContent(blocks) {
|
|
1225
|
+
const parts = [];
|
|
1226
|
+
for (const block of blocks) switch (block.type) {
|
|
1227
|
+
case "text":
|
|
1228
|
+
parts.push(block.text);
|
|
1229
|
+
break;
|
|
1230
|
+
case "reasoning":
|
|
1231
|
+
parts.push(block.text);
|
|
1232
|
+
break;
|
|
1233
|
+
case "tool-call":
|
|
1234
|
+
parts.push(`<tool-call ${block.name}(${block.arguments})>`);
|
|
1235
|
+
break;
|
|
1236
|
+
case "image":
|
|
1237
|
+
parts.push("[image]");
|
|
1238
|
+
break;
|
|
1239
|
+
case "tool-result": parts.push(projectContent(block.content) + (block.isError === true ? " [error]" : ""));
|
|
1240
|
+
}
|
|
1241
|
+
return parts.join("\n");
|
|
1242
|
+
}
|
|
1243
|
+
/**
|
|
1244
|
+
* Project one message with its role prefix.
|
|
1245
|
+
* @param message - the logged message.
|
|
1246
|
+
* @returns `[role] content` on one logical line.
|
|
1247
|
+
*/
|
|
1248
|
+
function projectMessage(message) {
|
|
1249
|
+
return `[${message.role}] ${projectContent(message.content)}`;
|
|
1250
|
+
}
|
|
1251
|
+
//#endregion
|
|
1252
|
+
//#region src/sanitize.ts
|
|
1253
|
+
/** The placeholder replacing any redacted value. */
|
|
1254
|
+
const REDACTED = "[REDACTED]";
|
|
1255
|
+
/**
|
|
1256
|
+
* Truncate text to a character budget, appending an ellipsis marker when
|
|
1257
|
+
* content is cut. A budget of zero yields the empty string.
|
|
1258
|
+
* @param text - the text to bound.
|
|
1259
|
+
* @param budget - maximum character count (marker included).
|
|
1260
|
+
* @returns the bounded text.
|
|
1261
|
+
*/
|
|
1262
|
+
function truncate(text, budget) {
|
|
1263
|
+
if (text.length <= budget) return text;
|
|
1264
|
+
if (budget <= 0) return "";
|
|
1265
|
+
if (budget === 1) return "…";
|
|
1266
|
+
return `${text.slice(0, budget - 1)}…`;
|
|
1267
|
+
}
|
|
1268
|
+
/**
|
|
1269
|
+
* Apply pattern redaction to one text value: every match of every
|
|
1270
|
+
* configured pattern (built-in secret patterns plus the user patterns) is
|
|
1271
|
+
* replaced with {@link REDACTED}.
|
|
1272
|
+
* @param text - the text to scan.
|
|
1273
|
+
* @param policy - the resolved sanitization policy.
|
|
1274
|
+
* @returns the redacted text.
|
|
1275
|
+
*/
|
|
1276
|
+
function redactText(text, policy) {
|
|
1277
|
+
if (!policy.enabled) return text;
|
|
1278
|
+
let out = text;
|
|
1279
|
+
for (const pattern of policy.redactPatterns) out = out.replace(pattern, REDACTED);
|
|
1280
|
+
return out;
|
|
1281
|
+
}
|
|
1282
|
+
/**
|
|
1283
|
+
* Split a key name into its words (snake_case, kebab-case, and camelCase
|
|
1284
|
+
* boundaries) for structural key redaction.
|
|
1285
|
+
* @param key - the raw key name.
|
|
1286
|
+
* @returns lowercase word tokens.
|
|
1287
|
+
*/
|
|
1288
|
+
function tokenizeKey(key) {
|
|
1289
|
+
return key.replace(/([a-z0-9])([A-Z])/gu, "$1 $2").split(/[^a-zA-Z0-9]+/u).map((token) => token.toLowerCase()).filter((token) => token.length > 0);
|
|
1290
|
+
}
|
|
1291
|
+
/**
|
|
1292
|
+
* Whether a structural key name is redacted under the policy: any word
|
|
1293
|
+
* token matches one of the redaction key names.
|
|
1294
|
+
* @param key - the raw key name.
|
|
1295
|
+
* @param policy - the resolved sanitization policy.
|
|
1296
|
+
* @returns true when the key's value must be replaced.
|
|
1297
|
+
*/
|
|
1298
|
+
function isRedactedKey(key, policy) {
|
|
1299
|
+
if (!policy.enabled) return false;
|
|
1300
|
+
const tokens = tokenizeKey(key);
|
|
1301
|
+
const lowerKey = key.toLowerCase();
|
|
1302
|
+
return tokens.some((token) => policy.redactKeys.some((name) => token === name || lowerKey.includes(name)));
|
|
1303
|
+
}
|
|
1304
|
+
/**
|
|
1305
|
+
* Deep-clone an arbitrary JSON value while redacting: object keys matching
|
|
1306
|
+
* the policy are replaced with {@link REDACTED} (their children are not
|
|
1307
|
+
* walked), and every string value is pattern-scanned. Non-JSON exotic
|
|
1308
|
+
* values (functions, symbols, class instances) normalize to `null` — the
|
|
1309
|
+
* session log guarantees JSON inputs, so that branch exists only as
|
|
1310
|
+
* containment for data crossing an untrusted boundary.
|
|
1311
|
+
* @param value - the value to sanitize.
|
|
1312
|
+
* @param policy - the resolved sanitization policy.
|
|
1313
|
+
* @returns a JSON-safe sanitized clone.
|
|
1314
|
+
*/
|
|
1315
|
+
function sanitizeJson(value, policy) {
|
|
1316
|
+
if (typeof value === "string") return redactText(value, policy);
|
|
1317
|
+
if (typeof value === "number" || typeof value === "boolean" || value === null) return value;
|
|
1318
|
+
if (Array.isArray(value)) return value.map((item) => sanitizeJson(item, policy));
|
|
1319
|
+
if (typeof value === "object") {
|
|
1320
|
+
const out = {};
|
|
1321
|
+
for (const [key, child] of Object.entries(value)) out[key] = isRedactedKey(key, policy) ? REDACTED : sanitizeJson(child, policy);
|
|
1322
|
+
return out;
|
|
1323
|
+
}
|
|
1324
|
+
return null;
|
|
1325
|
+
}
|
|
1326
|
+
/**
|
|
1327
|
+
* Sanitize and bound one text body: pattern redaction first, then the
|
|
1328
|
+
* character budget.
|
|
1329
|
+
* @param text - the text to sanitize.
|
|
1330
|
+
* @param budget - character budget.
|
|
1331
|
+
* @param policy - the resolved sanitization policy.
|
|
1332
|
+
* @returns the sanitized, bounded text.
|
|
1333
|
+
*/
|
|
1334
|
+
function sanitizeText(text, budget, policy) {
|
|
1335
|
+
return truncate(redactText(text, policy), budget);
|
|
1336
|
+
}
|
|
1337
|
+
/**
|
|
1338
|
+
* Sanitize a value that is either JSON text (parsed for structural key
|
|
1339
|
+
* redaction, then re-serialized) or free-form text: a valid JSON parse gets
|
|
1340
|
+
* the structural walk, anything else is pattern-scanned as text. Both paths
|
|
1341
|
+
* end inside the character budget.
|
|
1342
|
+
* @param value - the raw value (typically a tool arguments string).
|
|
1343
|
+
* @param budget - character budget.
|
|
1344
|
+
* @param policy - the resolved sanitization policy.
|
|
1345
|
+
* @returns the sanitized value: re-serialized JSON when the input parsed,
|
|
1346
|
+
* plain text otherwise.
|
|
1347
|
+
*/
|
|
1348
|
+
function sanitizeJsonText(value, budget, policy) {
|
|
1349
|
+
try {
|
|
1350
|
+
const cleaned = sanitizeJson(JSON.parse(value), policy);
|
|
1351
|
+
return truncate(JSON.stringify(cleaned), budget);
|
|
1352
|
+
} catch {
|
|
1353
|
+
return sanitizeText(value, budget, policy);
|
|
1354
|
+
}
|
|
1355
|
+
}
|
|
1356
|
+
//#endregion
|
|
1357
|
+
//#region src/collector.ts
|
|
1358
|
+
/** Milliseconds → Unix nanoseconds. */
|
|
1359
|
+
const NANO = 1e6;
|
|
1360
|
+
/** Normalize provider usage to the export-facing token counts. */
|
|
1361
|
+
function normalizeUsage(usage) {
|
|
1362
|
+
if (usage === void 0) return void 0;
|
|
1363
|
+
return {
|
|
1364
|
+
input: usage.inputTokens,
|
|
1365
|
+
output: usage.outputTokens,
|
|
1366
|
+
cacheRead: usage.cacheReadTokens ?? 0,
|
|
1367
|
+
cacheWrite: usage.cacheWriteTokens ?? 0,
|
|
1368
|
+
reasoning: usage.reasoningTokens ?? 0
|
|
1369
|
+
};
|
|
1370
|
+
}
|
|
1371
|
+
/**
|
|
1372
|
+
* The event → span/metric collector. State lives in a WeakMap keyed by the
|
|
1373
|
+
* live Session, so sessions the plugin stops seeing are garbage-collected.
|
|
1374
|
+
*/
|
|
1375
|
+
var Collector = class {
|
|
1376
|
+
config;
|
|
1377
|
+
tokenMeter;
|
|
1378
|
+
onSpan;
|
|
1379
|
+
onMetric;
|
|
1380
|
+
logger;
|
|
1381
|
+
states = /* @__PURE__ */ new WeakMap();
|
|
1382
|
+
/**
|
|
1383
|
+
* @param config - the resolved plugin config.
|
|
1384
|
+
* @param tokenMeter - lazy lookup of the optional token meter service.
|
|
1385
|
+
* @param onSpan - span sink (both pipelines).
|
|
1386
|
+
* @param onMetric - metric sink (OTLP aggregation).
|
|
1387
|
+
* @param logger - the plugin logger.
|
|
1388
|
+
*/
|
|
1389
|
+
constructor(config, tokenMeter, onSpan, onMetric, logger) {
|
|
1390
|
+
this.config = config;
|
|
1391
|
+
this.tokenMeter = tokenMeter;
|
|
1392
|
+
this.onSpan = onSpan;
|
|
1393
|
+
this.onMetric = onMetric;
|
|
1394
|
+
this.logger = logger;
|
|
1395
|
+
}
|
|
1396
|
+
/**
|
|
1397
|
+
* Fold one appended session event.
|
|
1398
|
+
* @param session - the session the event belongs to.
|
|
1399
|
+
* @param event - the appended event.
|
|
1400
|
+
*/
|
|
1401
|
+
handleEvent(session, event) {
|
|
1402
|
+
const state = this.stateOf(session);
|
|
1403
|
+
state.lastEventUnixNano = event.time * NANO;
|
|
1404
|
+
switch (event.type) {
|
|
1405
|
+
case "turn/start":
|
|
1406
|
+
this.turnStart(session, state, event);
|
|
1407
|
+
break;
|
|
1408
|
+
case "step/start":
|
|
1409
|
+
this.stepStart(session, state, event);
|
|
1410
|
+
break;
|
|
1411
|
+
case "request/header":
|
|
1412
|
+
state.header = event.data.header;
|
|
1413
|
+
if (this.config.capture.llm && this.config.llm.prompt && state.step !== void 0 && state.step.requestStartUnixNano === void 0) {
|
|
1414
|
+
state.step.requestStartUnixNano = event.time * NANO;
|
|
1415
|
+
state.step.prompt = this.capturePrompt(session, event.data.header);
|
|
1416
|
+
}
|
|
1417
|
+
break;
|
|
1418
|
+
case "request/context":
|
|
1419
|
+
state.context = event.data;
|
|
1420
|
+
break;
|
|
1421
|
+
case "assistant/chunk":
|
|
1422
|
+
if (state.step !== void 0) {
|
|
1423
|
+
if (event.data.chunk.type === "finish") state.step.finishReason = event.data.chunk.reason.kind;
|
|
1424
|
+
else if (state.step.firstChunkUnixNano === void 0 && isTokenDelta(event.data.chunk)) state.step.firstChunkUnixNano = event.time * NANO;
|
|
1425
|
+
}
|
|
1426
|
+
break;
|
|
1427
|
+
case "assistant/message":
|
|
1428
|
+
this.assistantMessage(session, state, event);
|
|
1429
|
+
break;
|
|
1430
|
+
case "tool/call":
|
|
1431
|
+
this.toolCall(session, state, event);
|
|
1432
|
+
break;
|
|
1433
|
+
case "tool/result":
|
|
1434
|
+
this.toolResult(session, state, event);
|
|
1435
|
+
break;
|
|
1436
|
+
case "step/end":
|
|
1437
|
+
this.stepEnd(session, state, event);
|
|
1438
|
+
break;
|
|
1439
|
+
case "turn/end": this.turnEnd(session, state, event);
|
|
1440
|
+
}
|
|
1441
|
+
}
|
|
1442
|
+
/**
|
|
1443
|
+
* Close every open span for a session leaving the store.
|
|
1444
|
+
* @param session - the disposed session.
|
|
1445
|
+
*/
|
|
1446
|
+
handleSessionDisposed(session) {
|
|
1447
|
+
const state = this.states.get(session);
|
|
1448
|
+
if (state === void 0) return;
|
|
1449
|
+
const end = state.lastEventUnixNano;
|
|
1450
|
+
if (state.step !== void 0) this.closeStep(session, state, state.step, end, true);
|
|
1451
|
+
if (state.turn !== void 0 && this.config.capture.turns) {
|
|
1452
|
+
const attributes = this.baseAttributes(session, state.turn.turn);
|
|
1453
|
+
attributes["turn.reason"] = "disposed";
|
|
1454
|
+
this.onSpan({
|
|
1455
|
+
kind: "turn",
|
|
1456
|
+
sessionId: session.id,
|
|
1457
|
+
turn: state.turn.turn,
|
|
1458
|
+
startUnixNano: state.turn.startUnixNano,
|
|
1459
|
+
endUnixNano: end,
|
|
1460
|
+
attributes,
|
|
1461
|
+
status: "error"
|
|
1462
|
+
});
|
|
1463
|
+
}
|
|
1464
|
+
this.states.delete(session);
|
|
1465
|
+
}
|
|
1466
|
+
stateOf(session) {
|
|
1467
|
+
const existing = this.states.get(session);
|
|
1468
|
+
if (existing !== void 0) return existing;
|
|
1469
|
+
const state = {
|
|
1470
|
+
turn: void 0,
|
|
1471
|
+
step: void 0,
|
|
1472
|
+
tools: /* @__PURE__ */ new Map(),
|
|
1473
|
+
header: void 0,
|
|
1474
|
+
context: void 0,
|
|
1475
|
+
lastEventUnixNano: Date.now() * NANO
|
|
1476
|
+
};
|
|
1477
|
+
this.states.set(session, state);
|
|
1478
|
+
return state;
|
|
1479
|
+
}
|
|
1480
|
+
turnStart(session, state, event) {
|
|
1481
|
+
if (state.step !== void 0) this.closeStep(session, state, state.step, event.time * NANO, true);
|
|
1482
|
+
if (state.turn !== void 0 && this.config.capture.turns) {
|
|
1483
|
+
const attributes = this.baseAttributes(session, state.turn.turn);
|
|
1484
|
+
attributes["turn.reason"] = "aborted";
|
|
1485
|
+
this.onSpan({
|
|
1486
|
+
kind: "turn",
|
|
1487
|
+
sessionId: session.id,
|
|
1488
|
+
turn: state.turn.turn,
|
|
1489
|
+
startUnixNano: state.turn.startUnixNano,
|
|
1490
|
+
endUnixNano: event.time * NANO,
|
|
1491
|
+
attributes,
|
|
1492
|
+
status: "error"
|
|
1493
|
+
});
|
|
1494
|
+
}
|
|
1495
|
+
state.turn = {
|
|
1496
|
+
turn: event.data.turn,
|
|
1497
|
+
startUnixNano: event.time * NANO
|
|
1498
|
+
};
|
|
1499
|
+
}
|
|
1500
|
+
stepStart(session, state, event) {
|
|
1501
|
+
if (state.step !== void 0) this.closeStep(session, state, state.step, event.time * NANO, true);
|
|
1502
|
+
state.step = {
|
|
1503
|
+
turn: event.data.turn,
|
|
1504
|
+
step: event.data.step,
|
|
1505
|
+
startUnixNano: event.time * NANO,
|
|
1506
|
+
requestStartUnixNano: void 0,
|
|
1507
|
+
firstChunkUnixNano: void 0,
|
|
1508
|
+
finishReason: void 0,
|
|
1509
|
+
llmClosed: false,
|
|
1510
|
+
prompt: void 0,
|
|
1511
|
+
toolCounts: /* @__PURE__ */ new Map()
|
|
1512
|
+
};
|
|
1513
|
+
}
|
|
1514
|
+
assistantMessage(session, state, event) {
|
|
1515
|
+
const step = state.step;
|
|
1516
|
+
if (step === void 0 || step.turn !== event.data.turn || step.step !== event.data.step) {
|
|
1517
|
+
this.logger.warn(`session "${session.id}": assistant/message at seq ${event.seq} has no matching open step; llm span skipped`);
|
|
1518
|
+
return;
|
|
1519
|
+
}
|
|
1520
|
+
if (this.config.capture.llm) {
|
|
1521
|
+
const start = step.requestStartUnixNano ?? step.startUnixNano;
|
|
1522
|
+
const end = event.time * NANO;
|
|
1523
|
+
const { provider, model } = this.modelOf(state);
|
|
1524
|
+
const usage = normalizeUsage(event.data.usage);
|
|
1525
|
+
const price = usage !== void 0 && provider !== void 0 && model !== void 0 ? findPrice(this.config.pricing, provider, model) : void 0;
|
|
1526
|
+
const cost = usage !== void 0 && price !== void 0 ? costUsd(price, usage) : void 0;
|
|
1527
|
+
const output = this.config.llm.completion ? sanitizeText(projectContent(event.data.message.content), this.config.sanitize.truncateCompletionChars, this.config.sanitize) : void 0;
|
|
1528
|
+
this.onSpan({
|
|
1529
|
+
kind: "llm",
|
|
1530
|
+
sessionId: session.id,
|
|
1531
|
+
turn: step.turn,
|
|
1532
|
+
step: step.step,
|
|
1533
|
+
startUnixNano: start,
|
|
1534
|
+
endUnixNano: end,
|
|
1535
|
+
attributes: this.baseAttributes(session, step.turn, step.step),
|
|
1536
|
+
status: "ok",
|
|
1537
|
+
llm: {
|
|
1538
|
+
...this.config.metadata.model && model !== void 0 ? { model } : {},
|
|
1539
|
+
...this.config.metadata.model && provider !== void 0 ? { provider } : {},
|
|
1540
|
+
...usage === void 0 ? {} : { usage },
|
|
1541
|
+
...step.finishReason === void 0 ? {} : { finishReason: step.finishReason },
|
|
1542
|
+
...step.firstChunkUnixNano === void 0 ? {} : { ttftMs: Math.max(0, Math.round((step.firstChunkUnixNano - start) / NANO)) },
|
|
1543
|
+
...step.prompt === void 0 ? {} : { input: step.prompt },
|
|
1544
|
+
...output === void 0 ? {} : { output },
|
|
1545
|
+
...cost === void 0 ? {} : { costUsd: cost }
|
|
1546
|
+
}
|
|
1547
|
+
});
|
|
1548
|
+
step.llmClosed = true;
|
|
1549
|
+
if (usage !== void 0) this.emitUsageMetrics(provider, model, usage, cost);
|
|
1550
|
+
}
|
|
1551
|
+
}
|
|
1552
|
+
toolCall(_session, state, event) {
|
|
1553
|
+
const step = state.step;
|
|
1554
|
+
if (step === void 0 || step.turn !== event.data.turn || step.step !== event.data.step) return;
|
|
1555
|
+
if (!this.config.capture.tools) return;
|
|
1556
|
+
const key = `${event.data.name}\u0000${event.data.arguments}`;
|
|
1557
|
+
const attempt = (step.toolCounts.get(key) ?? 0) + 1;
|
|
1558
|
+
step.toolCounts.set(key, attempt);
|
|
1559
|
+
state.tools.set(event.data.callId, {
|
|
1560
|
+
turn: step.turn,
|
|
1561
|
+
step: step.step,
|
|
1562
|
+
name: event.data.name,
|
|
1563
|
+
arguments: event.data.arguments,
|
|
1564
|
+
startUnixNano: event.time * NANO,
|
|
1565
|
+
attempt
|
|
1566
|
+
});
|
|
1567
|
+
}
|
|
1568
|
+
toolResult(session, state, event) {
|
|
1569
|
+
const callId = event.data.message.source.callId;
|
|
1570
|
+
const open = state.tools.get(callId);
|
|
1571
|
+
if (open === void 0) return;
|
|
1572
|
+
state.tools.delete(callId);
|
|
1573
|
+
const status = event.data.error === void 0 ? "ok" : "error";
|
|
1574
|
+
const attributes = this.baseAttributes(session, open.turn, open.step);
|
|
1575
|
+
attributes["tool.status"] = status;
|
|
1576
|
+
attributes["tool.attempt"] = open.attempt;
|
|
1577
|
+
attributes["tool.retries"] = open.attempt - 1;
|
|
1578
|
+
if (event.data.error !== void 0) {
|
|
1579
|
+
attributes["tool.error.name"] = this.attr(event.data.error.name);
|
|
1580
|
+
attributes["tool.error.code"] = this.attr(event.data.error.code);
|
|
1581
|
+
}
|
|
1582
|
+
const input = sanitizeJsonText(open.arguments, this.config.sanitize.truncateToolInputChars, this.config.sanitize);
|
|
1583
|
+
const output = sanitizeText(projectContent(event.data.message.content), this.config.sanitize.truncateToolOutputChars, this.config.sanitize);
|
|
1584
|
+
this.onSpan({
|
|
1585
|
+
kind: "tool",
|
|
1586
|
+
sessionId: session.id,
|
|
1587
|
+
turn: open.turn,
|
|
1588
|
+
step: open.step,
|
|
1589
|
+
callId,
|
|
1590
|
+
startUnixNano: open.startUnixNano,
|
|
1591
|
+
endUnixNano: event.time * NANO,
|
|
1592
|
+
attributes,
|
|
1593
|
+
status,
|
|
1594
|
+
tool: {
|
|
1595
|
+
name: open.name,
|
|
1596
|
+
status,
|
|
1597
|
+
...event.data.error === void 0 ? {} : {
|
|
1598
|
+
errorName: this.attr(event.data.error.name),
|
|
1599
|
+
errorCode: this.attr(event.data.error.code)
|
|
1600
|
+
},
|
|
1601
|
+
input,
|
|
1602
|
+
output,
|
|
1603
|
+
attempt: open.attempt,
|
|
1604
|
+
retries: open.attempt - 1
|
|
1605
|
+
}
|
|
1606
|
+
});
|
|
1607
|
+
}
|
|
1608
|
+
stepEnd(session, state, event) {
|
|
1609
|
+
const step = state.step;
|
|
1610
|
+
if (step === void 0 || step.turn !== event.data.turn || step.step !== event.data.step) return;
|
|
1611
|
+
this.closeStep(session, state, step, event.time * NANO, false);
|
|
1612
|
+
}
|
|
1613
|
+
turnEnd(session, state, event) {
|
|
1614
|
+
const turn = state.turn;
|
|
1615
|
+
if (turn === void 0 || turn.turn !== event.data.turn) return;
|
|
1616
|
+
const end = event.time * NANO;
|
|
1617
|
+
if (state.step !== void 0 && state.step.turn === turn.turn) this.closeStep(session, state, state.step, end, true);
|
|
1618
|
+
if (this.config.capture.turns) {
|
|
1619
|
+
const attributes = this.baseAttributes(session, turn.turn);
|
|
1620
|
+
attributes["turn.reason"] = event.data.reason.kind;
|
|
1621
|
+
if (event.data.reason.kind === "error") {
|
|
1622
|
+
attributes["turn.error.code"] = this.attr(event.data.reason.error.code);
|
|
1623
|
+
attributes["turn.error.message"] = this.attr(event.data.reason.error.message);
|
|
1624
|
+
} else if (event.data.reason.kind === "aborted") attributes["turn.cancel.kind"] = event.data.reason.reason.kind;
|
|
1625
|
+
this.onSpan({
|
|
1626
|
+
kind: "turn",
|
|
1627
|
+
sessionId: session.id,
|
|
1628
|
+
turn: turn.turn,
|
|
1629
|
+
startUnixNano: turn.startUnixNano,
|
|
1630
|
+
endUnixNano: end,
|
|
1631
|
+
attributes,
|
|
1632
|
+
status: event.data.reason.kind === "error" ? "error" : "ok"
|
|
1633
|
+
});
|
|
1634
|
+
}
|
|
1635
|
+
state.turn = void 0;
|
|
1636
|
+
}
|
|
1637
|
+
/** Close one step: dangling LLM span, dangling tool spans, the step span, and the context gauge. */
|
|
1638
|
+
closeStep(session, state, step, endUnixNano, forced) {
|
|
1639
|
+
if (this.config.capture.llm && !step.llmClosed && step.requestStartUnixNano !== void 0) {
|
|
1640
|
+
const attributes = this.baseAttributes(session, step.turn, step.step);
|
|
1641
|
+
attributes["observe.incomplete"] = true;
|
|
1642
|
+
this.onSpan({
|
|
1643
|
+
kind: "llm",
|
|
1644
|
+
sessionId: session.id,
|
|
1645
|
+
turn: step.turn,
|
|
1646
|
+
step: step.step,
|
|
1647
|
+
startUnixNano: step.requestStartUnixNano,
|
|
1648
|
+
endUnixNano,
|
|
1649
|
+
attributes,
|
|
1650
|
+
status: "error",
|
|
1651
|
+
llm: { ...step.finishReason === void 0 ? {} : { finishReason: step.finishReason } }
|
|
1652
|
+
});
|
|
1653
|
+
step.llmClosed = true;
|
|
1654
|
+
}
|
|
1655
|
+
for (const [callId, open] of [...state.tools]) {
|
|
1656
|
+
if (open.turn !== step.turn || open.step !== step.step) continue;
|
|
1657
|
+
state.tools.delete(callId);
|
|
1658
|
+
const attributes = this.baseAttributes(session, open.turn, open.step);
|
|
1659
|
+
attributes["tool.status"] = "error";
|
|
1660
|
+
attributes["tool.attempt"] = open.attempt;
|
|
1661
|
+
attributes["tool.retries"] = open.attempt - 1;
|
|
1662
|
+
attributes["tool.error.code"] = "ABORTED";
|
|
1663
|
+
attributes["observe.incomplete"] = true;
|
|
1664
|
+
this.onSpan({
|
|
1665
|
+
kind: "tool",
|
|
1666
|
+
sessionId: session.id,
|
|
1667
|
+
turn: open.turn,
|
|
1668
|
+
step: open.step,
|
|
1669
|
+
callId,
|
|
1670
|
+
startUnixNano: open.startUnixNano,
|
|
1671
|
+
endUnixNano,
|
|
1672
|
+
attributes,
|
|
1673
|
+
status: "error",
|
|
1674
|
+
tool: {
|
|
1675
|
+
name: open.name,
|
|
1676
|
+
status: "error",
|
|
1677
|
+
errorCode: "ABORTED",
|
|
1678
|
+
attempt: open.attempt,
|
|
1679
|
+
retries: open.attempt - 1
|
|
1680
|
+
}
|
|
1681
|
+
});
|
|
1682
|
+
}
|
|
1683
|
+
if (this.config.capture.steps) {
|
|
1684
|
+
const attributes = this.baseAttributes(session, step.turn, step.step);
|
|
1685
|
+
if (forced) attributes["observe.aborted"] = true;
|
|
1686
|
+
const { provider, model } = this.modelOf(state);
|
|
1687
|
+
if (this.config.metadata.model) {
|
|
1688
|
+
if (provider !== void 0) attributes.provider = provider;
|
|
1689
|
+
if (model !== void 0) attributes.model = model;
|
|
1690
|
+
}
|
|
1691
|
+
this.onSpan({
|
|
1692
|
+
kind: "step",
|
|
1693
|
+
sessionId: session.id,
|
|
1694
|
+
turn: step.turn,
|
|
1695
|
+
step: step.step,
|
|
1696
|
+
startUnixNano: step.startUnixNano,
|
|
1697
|
+
endUnixNano,
|
|
1698
|
+
attributes,
|
|
1699
|
+
status: "ok"
|
|
1700
|
+
});
|
|
1701
|
+
}
|
|
1702
|
+
this.emitContextGauge(session, state);
|
|
1703
|
+
state.step = void 0;
|
|
1704
|
+
}
|
|
1705
|
+
/** The context-pressure gauge from the optional token meter (contained). */
|
|
1706
|
+
emitContextGauge(session, state) {
|
|
1707
|
+
if (!this.config.metrics.contextTokens) return;
|
|
1708
|
+
const meter = this.tokenMeter();
|
|
1709
|
+
if (meter === void 0) return;
|
|
1710
|
+
try {
|
|
1711
|
+
const measurement = meter.measure(session);
|
|
1712
|
+
const attributes = {};
|
|
1713
|
+
const { provider, model } = this.modelOf(state);
|
|
1714
|
+
if (provider !== void 0) attributes.provider = provider;
|
|
1715
|
+
if (model !== void 0) attributes.model = model;
|
|
1716
|
+
attributes.baseline = measurement.baseline?.kind ?? "unknown";
|
|
1717
|
+
this.onMetric({
|
|
1718
|
+
name: "observe.context_tokens",
|
|
1719
|
+
kind: "gauge",
|
|
1720
|
+
unit: "tokens",
|
|
1721
|
+
value: measurement.totalTokens,
|
|
1722
|
+
attributes
|
|
1723
|
+
});
|
|
1724
|
+
} catch (error) {
|
|
1725
|
+
this.logger.warn(`session "${session.id}": token meter measurement failed: ${error instanceof Error ? error.message : String(error)}`);
|
|
1726
|
+
}
|
|
1727
|
+
}
|
|
1728
|
+
/** Token and cost counters for one LLM call. */
|
|
1729
|
+
emitUsageMetrics(provider, model, usage, cost) {
|
|
1730
|
+
if (this.config.metrics.tokens && provider !== void 0 && model !== void 0) {
|
|
1731
|
+
const kinds = [
|
|
1732
|
+
["input", usage.input],
|
|
1733
|
+
["output", usage.output],
|
|
1734
|
+
["cache_read", usage.cacheRead],
|
|
1735
|
+
["cache_write", usage.cacheWrite],
|
|
1736
|
+
["reasoning", usage.reasoning]
|
|
1737
|
+
];
|
|
1738
|
+
for (const [kind, value] of kinds) if (value > 0) this.onMetric({
|
|
1739
|
+
name: "observe.tokens",
|
|
1740
|
+
kind: "counter",
|
|
1741
|
+
unit: "tokens",
|
|
1742
|
+
value,
|
|
1743
|
+
attributes: {
|
|
1744
|
+
provider,
|
|
1745
|
+
model,
|
|
1746
|
+
kind
|
|
1747
|
+
}
|
|
1748
|
+
});
|
|
1749
|
+
}
|
|
1750
|
+
if (this.config.metrics.cost && cost !== void 0 && provider !== void 0 && model !== void 0) this.onMetric({
|
|
1751
|
+
name: "observe.cost",
|
|
1752
|
+
kind: "counter",
|
|
1753
|
+
unit: "USD",
|
|
1754
|
+
value: cost,
|
|
1755
|
+
attributes: {
|
|
1756
|
+
provider,
|
|
1757
|
+
model
|
|
1758
|
+
}
|
|
1759
|
+
});
|
|
1760
|
+
}
|
|
1761
|
+
/** The sanitized prompt snapshot: logged system prompt plus the current session surface. */
|
|
1762
|
+
capturePrompt(session, header) {
|
|
1763
|
+
const parts = [];
|
|
1764
|
+
if (header?.system !== void 0) parts.push(header.system);
|
|
1765
|
+
for (const seq of session.surface.nodes) {
|
|
1766
|
+
const event = session.events[seq];
|
|
1767
|
+
if (event === void 0) continue;
|
|
1768
|
+
const message = deriveEventMessage(event);
|
|
1769
|
+
if (message !== null) parts.push(projectMessage(message));
|
|
1770
|
+
}
|
|
1771
|
+
return sanitizeText(parts.join("\n"), this.config.sanitize.truncatePromptChars, this.config.sanitize);
|
|
1772
|
+
}
|
|
1773
|
+
/** The current provider/model attribution: request context first, then the logged header. */
|
|
1774
|
+
modelOf(state) {
|
|
1775
|
+
return {
|
|
1776
|
+
provider: state.context?.provider ?? state.header?.config.provider,
|
|
1777
|
+
model: state.context?.model ?? state.header?.config.model
|
|
1778
|
+
};
|
|
1779
|
+
}
|
|
1780
|
+
/** Common span attributes (sanitized and budgeted). */
|
|
1781
|
+
baseAttributes(session, turn, step) {
|
|
1782
|
+
const attributes = { turn };
|
|
1783
|
+
if (step !== void 0) attributes.step = step;
|
|
1784
|
+
if (this.config.metadata.sessionId) attributes["session.id"] = session.id;
|
|
1785
|
+
if (this.config.metadata.cwd && session.header.cwd !== void 0) attributes["session.cwd"] = this.attr(session.header.cwd);
|
|
1786
|
+
if (this.config.metadata.agentPreset && session.header.agentPreset !== void 0) attributes["agent.preset"] = this.attr(session.header.agentPreset);
|
|
1787
|
+
return attributes;
|
|
1788
|
+
}
|
|
1789
|
+
/** Sanitize and bound one attribute string. */
|
|
1790
|
+
attr(value) {
|
|
1791
|
+
return sanitizeText(value, this.config.sanitize.truncateAttributeChars, this.config.sanitize);
|
|
1792
|
+
}
|
|
1793
|
+
};
|
|
1794
|
+
//#endregion
|
|
1795
|
+
//#region src/remote.ts
|
|
1796
|
+
/**
|
|
1797
|
+
* Build the `observe` Typert remote service as a Cordis plugin class.
|
|
1798
|
+
* @param options - the runtime bindings.
|
|
1799
|
+
* @returns the service plugin (mount with `ctx.plugin`).
|
|
1800
|
+
*/
|
|
1801
|
+
function observeRemotePlugin(options) {
|
|
1802
|
+
class ObserveRemoteService extends TypertRemoteService {
|
|
1803
|
+
/**
|
|
1804
|
+
* @param ctx - the mounting context.
|
|
1805
|
+
*/
|
|
1806
|
+
constructor(ctx) {
|
|
1807
|
+
super(ctx, "observe");
|
|
1808
|
+
}
|
|
1809
|
+
/** The read-only status snapshot (bound as `observe/status`). */
|
|
1810
|
+
status() {
|
|
1811
|
+
return options.getStatus();
|
|
1812
|
+
}
|
|
1813
|
+
/** The runtime kill switch (bound as `observe/setEnabled`). */
|
|
1814
|
+
setEnabled(request) {
|
|
1815
|
+
const value = request?.enabled;
|
|
1816
|
+
if (typeof value !== "boolean") throw new TypeError("observe.setEnabled requires { enabled: boolean }");
|
|
1817
|
+
options.setEnabled(value);
|
|
1818
|
+
return { enabled: options.getStatus().enabled };
|
|
1819
|
+
}
|
|
1820
|
+
}
|
|
1821
|
+
return ObserveRemoteService;
|
|
1822
|
+
}
|
|
1823
|
+
//#endregion
|
|
1824
|
+
//#region src/index.ts
|
|
1825
|
+
const name = "observe";
|
|
1826
|
+
/** The durable offline buffer needs the host's storage-domain facility. */
|
|
1827
|
+
const inject = ["storageDomain"];
|
|
1828
|
+
/**
|
|
1829
|
+
* Mount the exporter. The resolved config is validated first (fail loud);
|
|
1830
|
+
* with `enabled: false` the plugin registers nothing and stays inert.
|
|
1831
|
+
* @param ctx - the plugin context (host).
|
|
1832
|
+
* @param config - raw plugin config.
|
|
1833
|
+
* @returns resolution after the offline-buffer domain is open.
|
|
1834
|
+
*/
|
|
1835
|
+
async function apply(ctx, config = {}) {
|
|
1836
|
+
const resolved = resolveConfig(config);
|
|
1837
|
+
const logger = ctx.logger("observe");
|
|
1838
|
+
if (!resolved.enabled) {
|
|
1839
|
+
logger.info("disabled: enabled is false — no session data is captured or exported");
|
|
1840
|
+
return;
|
|
1841
|
+
}
|
|
1842
|
+
let enabled = true;
|
|
1843
|
+
const isEnabled = () => enabled;
|
|
1844
|
+
const otlpSink = resolved.otlp === void 0 ? void 0 : new OtlpSink(resolved.otlp, logger);
|
|
1845
|
+
const recordMetric = (metric) => {
|
|
1846
|
+
if (isEnabled()) otlpSink?.recordMetric(metric);
|
|
1847
|
+
};
|
|
1848
|
+
const domain = await ctx.storageDomain.open(observeDomainSpec);
|
|
1849
|
+
const spool = openSpool(domain, resolved.batch.maxBufferRecords, (count) => recordMetric({
|
|
1850
|
+
name: "observe.dropped",
|
|
1851
|
+
kind: "counter",
|
|
1852
|
+
unit: "records",
|
|
1853
|
+
value: count,
|
|
1854
|
+
attributes: { reason: "buffer_overflow" }
|
|
1855
|
+
}), (count) => {
|
|
1856
|
+
logger.warn(`spool: ${count} stored record(s) failed validation and were dropped`);
|
|
1857
|
+
});
|
|
1858
|
+
const pipelines = [];
|
|
1859
|
+
if (otlpSink !== void 0) pipelines.push(new Pipeline({
|
|
1860
|
+
name: "otlp",
|
|
1861
|
+
sink: otlpSink,
|
|
1862
|
+
spool,
|
|
1863
|
+
batch: resolved.batch,
|
|
1864
|
+
retry: resolved.retry,
|
|
1865
|
+
logger,
|
|
1866
|
+
isEnabled,
|
|
1867
|
+
onMetric: recordMetric
|
|
1868
|
+
}));
|
|
1869
|
+
if (resolved.langfuse !== void 0) pipelines.push(new Pipeline({
|
|
1870
|
+
name: "langfuse",
|
|
1871
|
+
sink: new LangfuseSink(resolved.langfuse, logger),
|
|
1872
|
+
spool,
|
|
1873
|
+
batch: resolved.batch,
|
|
1874
|
+
retry: resolved.retry,
|
|
1875
|
+
logger,
|
|
1876
|
+
isEnabled,
|
|
1877
|
+
onMetric: recordMetric
|
|
1878
|
+
}));
|
|
1879
|
+
const onSpan = (span) => {
|
|
1880
|
+
const record = {
|
|
1881
|
+
kind: "span",
|
|
1882
|
+
span
|
|
1883
|
+
};
|
|
1884
|
+
for (const pipeline of pipelines) pipeline.push(record);
|
|
1885
|
+
};
|
|
1886
|
+
const collector = new Collector(resolved, () => ctx.get("tokenMeter"), onSpan, recordMetric, logger);
|
|
1887
|
+
ctx.effect(() => {
|
|
1888
|
+
const timers = [
|
|
1889
|
+
setInterval(() => {
|
|
1890
|
+
for (const pipeline of pipelines) pipeline.tick();
|
|
1891
|
+
}, resolved.batch.flushIntervalMs),
|
|
1892
|
+
setInterval(() => {
|
|
1893
|
+
for (const pipeline of pipelines) pipeline.drainSpool();
|
|
1894
|
+
}, resolved.batch.bufferRetryIntervalMs),
|
|
1895
|
+
...otlpSink === void 0 ? [] : [setInterval(() => {
|
|
1896
|
+
otlpSink.flushMetrics();
|
|
1897
|
+
}, resolved.batch.flushIntervalMs)]
|
|
1898
|
+
];
|
|
1899
|
+
return async () => {
|
|
1900
|
+
for (const timer of timers) clearInterval(timer);
|
|
1901
|
+
await Promise.all(pipelines.map((pipeline) => pipeline.dispose()));
|
|
1902
|
+
await domain.close();
|
|
1903
|
+
};
|
|
1904
|
+
});
|
|
1905
|
+
ctx.on("session/event", (session, event) => {
|
|
1906
|
+
try {
|
|
1907
|
+
collector.handleEvent(session, event);
|
|
1908
|
+
} catch (error) {
|
|
1909
|
+
logger.warn(`session "${session.id}": event handling failed: ${error instanceof Error ? error.message : String(error)}`);
|
|
1910
|
+
}
|
|
1911
|
+
});
|
|
1912
|
+
ctx.on("session/flush", () => {
|
|
1913
|
+
for (const pipeline of pipelines) pipeline.kick();
|
|
1914
|
+
});
|
|
1915
|
+
ctx.on("session/disposed", (session) => {
|
|
1916
|
+
try {
|
|
1917
|
+
collector.handleSessionDisposed(session);
|
|
1918
|
+
} catch (error) {
|
|
1919
|
+
logger.warn(`session "${session.id}": disposal handling failed: ${error instanceof Error ? error.message : String(error)}`);
|
|
1920
|
+
}
|
|
1921
|
+
for (const pipeline of pipelines) pipeline.kick();
|
|
1922
|
+
});
|
|
1923
|
+
if (resolved.remote) {
|
|
1924
|
+
const depthOf = (backend) => pipelines.find((pipeline) => pipeline.name === backend)?.depth ?? 0;
|
|
1925
|
+
await ctx.plugin(observeRemotePlugin({
|
|
1926
|
+
getStatus: () => ({
|
|
1927
|
+
enabled,
|
|
1928
|
+
backends: {
|
|
1929
|
+
otlp: resolved.otlp !== void 0,
|
|
1930
|
+
langfuse: resolved.langfuse !== void 0
|
|
1931
|
+
},
|
|
1932
|
+
queueDepth: {
|
|
1933
|
+
otlp: depthOf("otlp"),
|
|
1934
|
+
langfuse: depthOf("langfuse")
|
|
1935
|
+
},
|
|
1936
|
+
spool: spool.counts()
|
|
1937
|
+
}),
|
|
1938
|
+
setEnabled: (value) => {
|
|
1939
|
+
enabled = value;
|
|
1940
|
+
logger.info(value ? "exporting re-enabled" : "exporting disabled (kill switch): new records are dropped until re-enabled");
|
|
1941
|
+
if (value) for (const pipeline of pipelines) pipeline.kick();
|
|
1942
|
+
}
|
|
1943
|
+
}));
|
|
1944
|
+
}
|
|
1945
|
+
}
|
|
1946
|
+
//#endregion
|
|
1947
|
+
export { Config, REDACTED, VERSION, apply, inject, name, resolveConfig, sanitizeJson, sanitizeJsonText, sanitizeText, truncate };
|