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/src/config.ts
ADDED
|
@@ -0,0 +1,604 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Config schema and resolution for `dsh-observe`. Every tunable is a
|
|
3
|
+
* validated {@link Config} field changeable from cordis.yml; the resolution
|
|
4
|
+
* step validates numeric bounds, endpoint shapes, and backend credential
|
|
5
|
+
* presence so misconfiguration fails loud at mount — never silently skips
|
|
6
|
+
* or half-enables a backend. The plugin is off unless `enabled: true` AND at
|
|
7
|
+
* least one backend is configured: exporting observability data requires
|
|
8
|
+
* explicit opt-in (privacy default: off).
|
|
9
|
+
* @module dsh-observe/config
|
|
10
|
+
*/
|
|
11
|
+
|
|
12
|
+
import z from '@deepseek-ai/schemastery'
|
|
13
|
+
|
|
14
|
+
/** Whether capture of one span family is enabled. */
|
|
15
|
+
export interface CaptureConfig {
|
|
16
|
+
/** Turn lifecycle spans (start/end/reason). */
|
|
17
|
+
turns?: boolean
|
|
18
|
+
/** Step lifecycle spans, parented under their turn. */
|
|
19
|
+
steps?: boolean
|
|
20
|
+
/** Tool-call spans with duration, status, and sanitized arguments/results. */
|
|
21
|
+
tools?: boolean
|
|
22
|
+
/** LLM generation spans with sanitized prompt/completion and usage. */
|
|
23
|
+
llm?: boolean
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
/** Whether and how LLM prompt/completion bodies are captured. */
|
|
27
|
+
export interface LlmCaptureConfig {
|
|
28
|
+
/**
|
|
29
|
+
* Capture the sanitized request prompt (system prompt plus the session
|
|
30
|
+
* surface as of the request). `false` records only sizes and counts.
|
|
31
|
+
*/
|
|
32
|
+
prompt?: boolean
|
|
33
|
+
/** Capture the sanitized assistant completion. `false` records only sizes. */
|
|
34
|
+
completion?: boolean
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
/** Metadata capture switches; every one defaults to off except session identity. */
|
|
38
|
+
export interface MetadataCaptureConfig {
|
|
39
|
+
/** Session id (always exported as the trace identity; disabling it removes it from attribute values). */
|
|
40
|
+
sessionId?: boolean
|
|
41
|
+
/** Session working directory. Local path — off by default. */
|
|
42
|
+
cwd?: boolean
|
|
43
|
+
/** Agent preset id the session was composed from, when known. */
|
|
44
|
+
agentPreset?: boolean
|
|
45
|
+
/** Model and provider ids on step/llm/tool attributes. */
|
|
46
|
+
model?: boolean
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
/** Whether each metric family is exported. */
|
|
50
|
+
export interface MetricsCaptureConfig {
|
|
51
|
+
/** Token counters per provider/model from `assistant/message` usage. */
|
|
52
|
+
tokens?: boolean
|
|
53
|
+
/** Cost counter per provider/model when a {@link PricingRule} matches. */
|
|
54
|
+
cost?: boolean
|
|
55
|
+
/** Context-pressure gauge from `ctx.tokenMeter` at step end (needs the service). */
|
|
56
|
+
contextTokens?: boolean
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/**
|
|
60
|
+
* One pricing rule. A metric is priced by the FIRST rule in list order whose
|
|
61
|
+
* `model` (glob over the model id, e.g. `deepseek-chat`, `*`) and optional
|
|
62
|
+
* `provider` (exact route id) match the usage's attribution. Prices are USD
|
|
63
|
+
* per token. Cache fields are optional: an absent cache price charges cache
|
|
64
|
+
* traffic at the corresponding input price.
|
|
65
|
+
*/
|
|
66
|
+
export interface PricingRule {
|
|
67
|
+
/** Exact provider route id, or omitted to match every provider. */
|
|
68
|
+
provider?: string
|
|
69
|
+
/** Glob pattern over the model id; `*` matches any model. */
|
|
70
|
+
model: string
|
|
71
|
+
/** USD per uncached input token. */
|
|
72
|
+
inputPerToken: number
|
|
73
|
+
/** USD per output token. */
|
|
74
|
+
outputPerToken: number
|
|
75
|
+
/** USD per cache-read token; defaults to `inputPerToken` when absent. */
|
|
76
|
+
cacheReadPerToken?: number
|
|
77
|
+
/** USD per cache-write token; defaults to `inputPerToken` when absent. */
|
|
78
|
+
cacheWritePerToken?: number
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
/** The shared sanitization policy applied before any record is queued or spooled. */
|
|
82
|
+
export interface SanitizeConfig {
|
|
83
|
+
/** Master switch; when `false` only truncation applies (no redaction). */
|
|
84
|
+
enabled?: boolean
|
|
85
|
+
/**
|
|
86
|
+
* Key-name substrings (case-insensitive) whose values are replaced with
|
|
87
|
+
* `[REDACTED]` wherever they appear: `key`, `token`, `secret`, `password`,
|
|
88
|
+
* `authorization`, `credential`, `apiKey` are always included.
|
|
89
|
+
*/
|
|
90
|
+
redactKeys?: string[]
|
|
91
|
+
/**
|
|
92
|
+
* Additional regular expressions applied to string values; every match is
|
|
93
|
+
* replaced with `[REDACTED]`. Compiled once at mount; an invalid pattern
|
|
94
|
+
* fails the mount loudly. Beware of unbounded patterns (ReDoS): they run
|
|
95
|
+
* over every captured string.
|
|
96
|
+
*/
|
|
97
|
+
redactPatterns?: string[]
|
|
98
|
+
/** Prompt character budget (system prompt + surface projection). */
|
|
99
|
+
truncatePromptChars?: number
|
|
100
|
+
/** Completion character budget. */
|
|
101
|
+
truncateCompletionChars?: number
|
|
102
|
+
/** Tool argument character budget. */
|
|
103
|
+
truncateToolInputChars?: number
|
|
104
|
+
/** Tool result character budget. */
|
|
105
|
+
truncateToolOutputChars?: number
|
|
106
|
+
/** Cap on any single span attribute string value. */
|
|
107
|
+
truncateAttributeChars?: number
|
|
108
|
+
}
|
|
109
|
+
|
|
110
|
+
/** The shared batching policy for both backends. */
|
|
111
|
+
export interface BatchConfig {
|
|
112
|
+
/** Flush once the in-memory queue holds this many records. */
|
|
113
|
+
maxRecords?: number
|
|
114
|
+
/** Flush interval in milliseconds when the queue stays below `maxRecords`. */
|
|
115
|
+
flushIntervalMs?: number
|
|
116
|
+
/** Bound on the in-memory queue; excess spills to the offline buffer. */
|
|
117
|
+
maxQueueRecords?: number
|
|
118
|
+
/** Bound on the offline buffer in records; beyond it the oldest record is dropped. */
|
|
119
|
+
maxBufferRecords?: number
|
|
120
|
+
/** How often the offline buffer is retried, in milliseconds. */
|
|
121
|
+
bufferRetryIntervalMs?: number
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
/** The shared retry policy for network exports. */
|
|
125
|
+
export interface RetryConfig {
|
|
126
|
+
/** Attempts per batch, including the first try. */
|
|
127
|
+
maxAttempts?: number
|
|
128
|
+
/** First backoff delay in milliseconds. */
|
|
129
|
+
baseDelayMs?: number
|
|
130
|
+
/** Backoff multiplier per consecutive failure. */
|
|
131
|
+
factor?: number
|
|
132
|
+
/** Upper bound on the computed delay in milliseconds. */
|
|
133
|
+
maxDelayMs?: number
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
/** OpenTelemetry OTLP/HTTP backend (traces + metrics, JSON encoding). */
|
|
137
|
+
export interface OtlpConfig {
|
|
138
|
+
/** Base OTLP/HTTP endpoint, e.g. `http://localhost:4318`; `/v1/traces` and `/v1/metrics` are appended. */
|
|
139
|
+
endpoint: string
|
|
140
|
+
/** `service.name` resource attribute; defaults to `deepseek-harness`. */
|
|
141
|
+
serviceName?: string
|
|
142
|
+
/** `service.version` resource attribute, when set. */
|
|
143
|
+
serviceVersion?: string
|
|
144
|
+
/** Extra headers merged into every export request. */
|
|
145
|
+
headers?: Record<string, string>
|
|
146
|
+
/** Per-request timeout in milliseconds. */
|
|
147
|
+
timeoutMs?: number
|
|
148
|
+
}
|
|
149
|
+
|
|
150
|
+
/** Langfuse backend (LLM observability ingestion). */
|
|
151
|
+
export interface LangfuseConfig {
|
|
152
|
+
/** Langfuse base URL; defaults to the Langfuse Cloud endpoint. */
|
|
153
|
+
baseUrl?: string
|
|
154
|
+
/** Project public key. */
|
|
155
|
+
publicKey: string
|
|
156
|
+
/** Project secret key. */
|
|
157
|
+
secretKey: string
|
|
158
|
+
/** Release tag stamped onto traces. */
|
|
159
|
+
release?: string
|
|
160
|
+
/** Per-request timeout in milliseconds. */
|
|
161
|
+
timeoutMs?: number
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
/** Optional Typert remote service exposing the runtime kill switch to settings pages. */
|
|
165
|
+
export interface RemoteConfig {
|
|
166
|
+
/** Mount the `observe` Typert remote (`observe/status`, `observe/setEnabled`). */
|
|
167
|
+
enabled?: boolean
|
|
168
|
+
}
|
|
169
|
+
|
|
170
|
+
/** Raw plugin config — every field optional; {@link resolveConfig} supplies the defaults. */
|
|
171
|
+
export interface Config {
|
|
172
|
+
/** Master switch. Off by default: nothing is exported unless explicitly enabled. */
|
|
173
|
+
enabled?: boolean
|
|
174
|
+
/** OTLP backend; `null`/omitted disables it. */
|
|
175
|
+
otlp?: OtlpConfig | null
|
|
176
|
+
/** Langfuse backend; `null`/omitted disables it. */
|
|
177
|
+
langfuse?: LangfuseConfig | null
|
|
178
|
+
/** Span families to capture. */
|
|
179
|
+
capture?: CaptureConfig
|
|
180
|
+
/** LLM prompt/completion capture policy. */
|
|
181
|
+
llm?: LlmCaptureConfig
|
|
182
|
+
/** Metadata capture switches. */
|
|
183
|
+
metadata?: MetadataCaptureConfig
|
|
184
|
+
/** Metric families to export. */
|
|
185
|
+
metrics?: MetricsCaptureConfig
|
|
186
|
+
/** Pricing table for the cost metric; empty by default (no prices are hardcoded). */
|
|
187
|
+
pricing?: PricingRule[]
|
|
188
|
+
/** Pre-send sanitization policy. */
|
|
189
|
+
sanitize?: SanitizeConfig
|
|
190
|
+
/** Batching policy (shared by both backends). */
|
|
191
|
+
batch?: BatchConfig
|
|
192
|
+
/** Retry/backoff policy (shared by both backends). */
|
|
193
|
+
retry?: RetryConfig
|
|
194
|
+
/** Optional Typert remote surface. */
|
|
195
|
+
remote?: RemoteConfig
|
|
196
|
+
}
|
|
197
|
+
|
|
198
|
+
/** Fully resolved capture policy. */
|
|
199
|
+
export interface ResolvedCapture {
|
|
200
|
+
readonly turns: boolean
|
|
201
|
+
readonly steps: boolean
|
|
202
|
+
readonly tools: boolean
|
|
203
|
+
readonly llm: boolean
|
|
204
|
+
}
|
|
205
|
+
|
|
206
|
+
/** Fully resolved LLM capture policy. */
|
|
207
|
+
export interface ResolvedLlmCapture {
|
|
208
|
+
readonly prompt: boolean
|
|
209
|
+
readonly completion: boolean
|
|
210
|
+
}
|
|
211
|
+
|
|
212
|
+
/** Fully resolved metadata policy. */
|
|
213
|
+
export interface ResolvedMetadata {
|
|
214
|
+
readonly sessionId: boolean
|
|
215
|
+
readonly cwd: boolean
|
|
216
|
+
readonly agentPreset: boolean
|
|
217
|
+
readonly model: boolean
|
|
218
|
+
}
|
|
219
|
+
|
|
220
|
+
/** Fully resolved metric policy. */
|
|
221
|
+
export interface ResolvedMetrics {
|
|
222
|
+
readonly tokens: boolean
|
|
223
|
+
readonly cost: boolean
|
|
224
|
+
readonly contextTokens: boolean
|
|
225
|
+
}
|
|
226
|
+
|
|
227
|
+
/** Fully resolved sanitization policy. */
|
|
228
|
+
export interface ResolvedSanitize {
|
|
229
|
+
readonly enabled: boolean
|
|
230
|
+
readonly redactKeys: readonly string[]
|
|
231
|
+
readonly redactPatterns: readonly RegExp[]
|
|
232
|
+
readonly truncatePromptChars: number
|
|
233
|
+
readonly truncateCompletionChars: number
|
|
234
|
+
readonly truncateToolInputChars: number
|
|
235
|
+
readonly truncateToolOutputChars: number
|
|
236
|
+
readonly truncateAttributeChars: number
|
|
237
|
+
}
|
|
238
|
+
|
|
239
|
+
/** Fully resolved batching policy. */
|
|
240
|
+
export interface ResolvedBatch {
|
|
241
|
+
readonly maxRecords: number
|
|
242
|
+
readonly flushIntervalMs: number
|
|
243
|
+
readonly maxQueueRecords: number
|
|
244
|
+
readonly maxBufferRecords: number
|
|
245
|
+
readonly bufferRetryIntervalMs: number
|
|
246
|
+
}
|
|
247
|
+
|
|
248
|
+
/** Fully resolved retry policy. */
|
|
249
|
+
export interface ResolvedRetry {
|
|
250
|
+
readonly maxAttempts: number
|
|
251
|
+
readonly baseDelayMs: number
|
|
252
|
+
readonly factor: number
|
|
253
|
+
readonly maxDelayMs: number
|
|
254
|
+
}
|
|
255
|
+
|
|
256
|
+
/** Fully resolved OTLP backend. */
|
|
257
|
+
export interface ResolvedOtlp {
|
|
258
|
+
readonly endpoint: string
|
|
259
|
+
readonly serviceName: string
|
|
260
|
+
readonly serviceVersion: string | undefined
|
|
261
|
+
readonly headers: Readonly<Record<string, string>>
|
|
262
|
+
readonly timeoutMs: number
|
|
263
|
+
}
|
|
264
|
+
|
|
265
|
+
/** Fully resolved Langfuse backend. */
|
|
266
|
+
export interface ResolvedLangfuse {
|
|
267
|
+
readonly baseUrl: string
|
|
268
|
+
readonly publicKey: string
|
|
269
|
+
readonly secretKey: string
|
|
270
|
+
readonly release: string | undefined
|
|
271
|
+
readonly timeoutMs: number
|
|
272
|
+
}
|
|
273
|
+
|
|
274
|
+
/** The complete resolved config handed to the runtime. */
|
|
275
|
+
export interface ResolvedConfig {
|
|
276
|
+
readonly enabled: boolean
|
|
277
|
+
readonly otlp: ResolvedOtlp | undefined
|
|
278
|
+
readonly langfuse: ResolvedLangfuse | undefined
|
|
279
|
+
readonly capture: ResolvedCapture
|
|
280
|
+
readonly llm: ResolvedLlmCapture
|
|
281
|
+
readonly metadata: ResolvedMetadata
|
|
282
|
+
readonly metrics: ResolvedMetrics
|
|
283
|
+
readonly pricing: readonly PricingRule[]
|
|
284
|
+
readonly sanitize: ResolvedSanitize
|
|
285
|
+
readonly batch: ResolvedBatch
|
|
286
|
+
readonly retry: ResolvedRetry
|
|
287
|
+
readonly remote: boolean
|
|
288
|
+
}
|
|
289
|
+
|
|
290
|
+
/** Schemastery schema: the loader validates and fills defaults before `apply`. */
|
|
291
|
+
export const Config: z<Config> = z.object({
|
|
292
|
+
enabled: z.boolean().default(false),
|
|
293
|
+
otlp: z.union([z.object({
|
|
294
|
+
endpoint: z.string().required(),
|
|
295
|
+
serviceName: z.string().default('deepseek-harness'),
|
|
296
|
+
serviceVersion: z.string(),
|
|
297
|
+
headers: z.dict(z.string()).default({}),
|
|
298
|
+
timeoutMs: z.number().default(10_000),
|
|
299
|
+
}), z.const(null)]).default(null),
|
|
300
|
+
langfuse: z.union([z.object({
|
|
301
|
+
baseUrl: z.string().default('https://cloud.langfuse.com'),
|
|
302
|
+
publicKey: z.string().required(),
|
|
303
|
+
secretKey: z.string().required(),
|
|
304
|
+
release: z.string(),
|
|
305
|
+
timeoutMs: z.number().default(10_000),
|
|
306
|
+
}), z.const(null)]).default(null),
|
|
307
|
+
capture: z.object({
|
|
308
|
+
turns: z.boolean().default(true),
|
|
309
|
+
steps: z.boolean().default(true),
|
|
310
|
+
tools: z.boolean().default(true),
|
|
311
|
+
llm: z.boolean().default(true),
|
|
312
|
+
}).default({ turns: true, steps: true, tools: true, llm: true }),
|
|
313
|
+
llm: z.object({
|
|
314
|
+
prompt: z.boolean().default(true),
|
|
315
|
+
completion: z.boolean().default(true),
|
|
316
|
+
}).default({ prompt: true, completion: true }),
|
|
317
|
+
metadata: z.object({
|
|
318
|
+
sessionId: z.boolean().default(true),
|
|
319
|
+
cwd: z.boolean().default(false),
|
|
320
|
+
agentPreset: z.boolean().default(true),
|
|
321
|
+
model: z.boolean().default(true),
|
|
322
|
+
}).default({ sessionId: true, cwd: false, agentPreset: true, model: true }),
|
|
323
|
+
metrics: z.object({
|
|
324
|
+
tokens: z.boolean().default(true),
|
|
325
|
+
cost: z.boolean().default(true),
|
|
326
|
+
contextTokens: z.boolean().default(true),
|
|
327
|
+
}).default({ tokens: true, cost: true, contextTokens: true }),
|
|
328
|
+
pricing: z.array(z.object({
|
|
329
|
+
provider: z.string(),
|
|
330
|
+
model: z.string().required(),
|
|
331
|
+
inputPerToken: z.number().required(),
|
|
332
|
+
outputPerToken: z.number().required(),
|
|
333
|
+
cacheReadPerToken: z.number(),
|
|
334
|
+
cacheWritePerToken: z.number(),
|
|
335
|
+
})).default([]),
|
|
336
|
+
sanitize: z.object({
|
|
337
|
+
enabled: z.boolean().default(true),
|
|
338
|
+
redactKeys: z.array(z.string()).default([]),
|
|
339
|
+
redactPatterns: z.array(z.string()).default([]),
|
|
340
|
+
truncatePromptChars: z.number().default(4_000),
|
|
341
|
+
truncateCompletionChars: z.number().default(4_000),
|
|
342
|
+
truncateToolInputChars: z.number().default(2_000),
|
|
343
|
+
truncateToolOutputChars: z.number().default(2_000),
|
|
344
|
+
truncateAttributeChars: z.number().default(512),
|
|
345
|
+
}).default({
|
|
346
|
+
enabled: true,
|
|
347
|
+
redactKeys: [],
|
|
348
|
+
redactPatterns: [],
|
|
349
|
+
truncatePromptChars: 4_000,
|
|
350
|
+
truncateCompletionChars: 4_000,
|
|
351
|
+
truncateToolInputChars: 2_000,
|
|
352
|
+
truncateToolOutputChars: 2_000,
|
|
353
|
+
truncateAttributeChars: 512,
|
|
354
|
+
}),
|
|
355
|
+
batch: z.object({
|
|
356
|
+
maxRecords: z.number().default(256),
|
|
357
|
+
flushIntervalMs: z.number().default(5_000),
|
|
358
|
+
maxQueueRecords: z.number().default(2_000),
|
|
359
|
+
maxBufferRecords: z.number().default(10_000),
|
|
360
|
+
bufferRetryIntervalMs: z.number().default(30_000),
|
|
361
|
+
}).default({
|
|
362
|
+
maxRecords: 256,
|
|
363
|
+
flushIntervalMs: 5_000,
|
|
364
|
+
maxQueueRecords: 2_000,
|
|
365
|
+
maxBufferRecords: 10_000,
|
|
366
|
+
bufferRetryIntervalMs: 30_000,
|
|
367
|
+
}),
|
|
368
|
+
retry: z.object({
|
|
369
|
+
maxAttempts: z.number().default(5),
|
|
370
|
+
baseDelayMs: z.number().default(1_000),
|
|
371
|
+
factor: z.number().default(2),
|
|
372
|
+
maxDelayMs: z.number().default(60_000),
|
|
373
|
+
}).default({ maxAttempts: 5, baseDelayMs: 1_000, factor: 2, maxDelayMs: 60_000 }),
|
|
374
|
+
remote: z.object({
|
|
375
|
+
enabled: z.boolean().default(false),
|
|
376
|
+
}).default({ enabled: false }),
|
|
377
|
+
})
|
|
378
|
+
|
|
379
|
+
/** The redaction key substrings always applied, even with an empty `redactKeys`. */
|
|
380
|
+
const ALWAYS_REDACT_KEYS = ['key', 'token', 'secret', 'password', 'authorization', 'credential'] as const
|
|
381
|
+
|
|
382
|
+
/** Built-in secret patterns applied before the configured `redactPatterns`. */
|
|
383
|
+
const BUILTIN_REDACT_PATTERNS = [
|
|
384
|
+
/\bsk-[A-Za-z0-9]{16,}\b/u,
|
|
385
|
+
/\bghp_[A-Za-z0-9]{20,}\b/u,
|
|
386
|
+
/\bgho_[A-Za-z0-9]{20,}\b/u,
|
|
387
|
+
/\bAKIA[0-9A-Z]{16}\b/u,
|
|
388
|
+
/\bBearer\s+[A-Za-z0-9._~+/=-]{8,}\b/u,
|
|
389
|
+
/-----BEGIN [A-Z ]*PRIVATE KEY-----[A-Za-z0-9+/=\s]*-----END [A-Z ]*PRIVATE KEY-----/u,
|
|
390
|
+
] as const
|
|
391
|
+
|
|
392
|
+
/** Throw unless `value` is a non-negative safe integer. */
|
|
393
|
+
function assertNonNegativeInt(name: string, value: number): void {
|
|
394
|
+
if (!Number.isSafeInteger(value) || value < 0) {
|
|
395
|
+
throw new TypeError(`${name} must be a non-negative safe integer, got ${String(value)}`)
|
|
396
|
+
}
|
|
397
|
+
}
|
|
398
|
+
|
|
399
|
+
/** Throw unless `value` is a positive safe integer. */
|
|
400
|
+
function assertPositiveInt(name: string, value: number): void {
|
|
401
|
+
if (!Number.isSafeInteger(value) || value <= 0) {
|
|
402
|
+
throw new TypeError(`${name} must be a positive safe integer, got ${String(value)}`)
|
|
403
|
+
}
|
|
404
|
+
}
|
|
405
|
+
|
|
406
|
+
/** Throw unless `value` is a finite number in `[min, max]`. */
|
|
407
|
+
function assertFiniteRange(name: string, value: number, min: number, max: number): void {
|
|
408
|
+
if (typeof value !== 'number' || !Number.isFinite(value) || value < min || value > max) {
|
|
409
|
+
throw new TypeError(`${name} must be a finite number in [${min}, ${max}], got ${String(value)}`)
|
|
410
|
+
}
|
|
411
|
+
}
|
|
412
|
+
|
|
413
|
+
/**
|
|
414
|
+
* Validate an http(s) URL string and normalize it to a clean base (no query,
|
|
415
|
+
* no fragment, no trailing slash).
|
|
416
|
+
* @param name - config key, for the error message.
|
|
417
|
+
* @param value - raw URL value.
|
|
418
|
+
* @returns the normalized base URL.
|
|
419
|
+
*/
|
|
420
|
+
export function normalizeBaseUrl(name: string, value: string): string {
|
|
421
|
+
let parsed: URL
|
|
422
|
+
try {
|
|
423
|
+
parsed = new URL(value)
|
|
424
|
+
} catch (error) {
|
|
425
|
+
throw new TypeError(`${name} must be a valid URL, got ${JSON.stringify(value)} (${error instanceof Error ? error.message : 'invalid URL'})`)
|
|
426
|
+
}
|
|
427
|
+
if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
|
|
428
|
+
throw new TypeError(`${name} must use http(s), got ${JSON.stringify(parsed.protocol)}`)
|
|
429
|
+
}
|
|
430
|
+
parsed.search = ''
|
|
431
|
+
parsed.hash = ''
|
|
432
|
+
const text = parsed.href.replace(/\/+$/u, '')
|
|
433
|
+
return text
|
|
434
|
+
}
|
|
435
|
+
|
|
436
|
+
/**
|
|
437
|
+
* Validate raw values and fill explicit defaults. Invalid enums, numeric
|
|
438
|
+
* bounds, endpoints, or credentials throw here — misconfiguration fails loud
|
|
439
|
+
* at mount even when the plugin is mounted without the Schemastery loader.
|
|
440
|
+
* `enabled: true` with no backend also throws: an enabled exporter with
|
|
441
|
+
* nowhere to send is a silent black hole, not a valid configuration.
|
|
442
|
+
* @param config - raw (possibly partial) plugin config.
|
|
443
|
+
* @returns the fully resolved config.
|
|
444
|
+
*/
|
|
445
|
+
export function resolveConfig(config: Config = {}): ResolvedConfig {
|
|
446
|
+
const enabled = config.enabled ?? false
|
|
447
|
+
|
|
448
|
+
const otlpRaw = config.otlp ?? null
|
|
449
|
+
const langfuseRaw = config.langfuse ?? null
|
|
450
|
+
if (enabled && otlpRaw === null && langfuseRaw === null) {
|
|
451
|
+
throw new TypeError('enabled: true requires at least one backend (otlp or langfuse)')
|
|
452
|
+
}
|
|
453
|
+
|
|
454
|
+
const otlp: ResolvedOtlp | undefined = otlpRaw === null ? undefined : (() => {
|
|
455
|
+
const endpoint = normalizeBaseUrl('otlp.endpoint', otlpRaw.endpoint)
|
|
456
|
+
if (endpoint.endsWith('/v1/traces') || endpoint.endsWith('/v1/metrics')) {
|
|
457
|
+
throw new TypeError('otlp.endpoint must be the OTLP base URL (e.g. http://localhost:4318); /v1/traces and /v1/metrics are appended')
|
|
458
|
+
}
|
|
459
|
+
if ((otlpRaw.serviceName ?? 'deepseek-harness').trim().length === 0) {
|
|
460
|
+
throw new TypeError('otlp.serviceName must be a non-empty string')
|
|
461
|
+
}
|
|
462
|
+
const timeoutMs = otlpRaw.timeoutMs ?? 10_000
|
|
463
|
+
assertPositiveInt('otlp.timeoutMs', timeoutMs)
|
|
464
|
+
return {
|
|
465
|
+
endpoint,
|
|
466
|
+
serviceName: (otlpRaw.serviceName ?? 'deepseek-harness').trim(),
|
|
467
|
+
serviceVersion: otlpRaw.serviceVersion === undefined ? undefined : otlpRaw.serviceVersion,
|
|
468
|
+
headers: { ...otlpRaw.headers },
|
|
469
|
+
timeoutMs,
|
|
470
|
+
}
|
|
471
|
+
})()
|
|
472
|
+
|
|
473
|
+
const langfuse: ResolvedLangfuse | undefined = langfuseRaw === null ? undefined : (() => {
|
|
474
|
+
const baseUrl = normalizeBaseUrl('langfuse.baseUrl', langfuseRaw.baseUrl ?? 'https://cloud.langfuse.com')
|
|
475
|
+
if (langfuseRaw.publicKey.trim().length === 0) {
|
|
476
|
+
throw new TypeError('langfuse.publicKey must be a non-empty string')
|
|
477
|
+
}
|
|
478
|
+
if (langfuseRaw.secretKey.trim().length === 0) {
|
|
479
|
+
throw new TypeError('langfuse.secretKey must be a non-empty string')
|
|
480
|
+
}
|
|
481
|
+
const timeoutMs = langfuseRaw.timeoutMs ?? 10_000
|
|
482
|
+
assertPositiveInt('langfuse.timeoutMs', timeoutMs)
|
|
483
|
+
return {
|
|
484
|
+
baseUrl,
|
|
485
|
+
publicKey: langfuseRaw.publicKey.trim(),
|
|
486
|
+
secretKey: langfuseRaw.secretKey.trim(),
|
|
487
|
+
release: langfuseRaw.release === undefined ? undefined : langfuseRaw.release,
|
|
488
|
+
timeoutMs,
|
|
489
|
+
}
|
|
490
|
+
})()
|
|
491
|
+
|
|
492
|
+
const captureRaw = config.capture ?? {}
|
|
493
|
+
const llmRaw = config.llm ?? {}
|
|
494
|
+
const metadataRaw = config.metadata ?? {}
|
|
495
|
+
const metricsRaw = config.metrics ?? {}
|
|
496
|
+
|
|
497
|
+
const batchRaw = config.batch ?? {}
|
|
498
|
+
const batch = {
|
|
499
|
+
maxRecords: batchRaw.maxRecords ?? 256,
|
|
500
|
+
flushIntervalMs: batchRaw.flushIntervalMs ?? 5_000,
|
|
501
|
+
maxQueueRecords: batchRaw.maxQueueRecords ?? 2_000,
|
|
502
|
+
maxBufferRecords: batchRaw.maxBufferRecords ?? 10_000,
|
|
503
|
+
bufferRetryIntervalMs: batchRaw.bufferRetryIntervalMs ?? 30_000,
|
|
504
|
+
}
|
|
505
|
+
assertPositiveInt('batch.maxRecords', batch.maxRecords)
|
|
506
|
+
assertPositiveInt('batch.flushIntervalMs', batch.flushIntervalMs)
|
|
507
|
+
assertPositiveInt('batch.maxQueueRecords', batch.maxQueueRecords)
|
|
508
|
+
assertPositiveInt('batch.maxBufferRecords', batch.maxBufferRecords)
|
|
509
|
+
assertPositiveInt('batch.bufferRetryIntervalMs', batch.bufferRetryIntervalMs)
|
|
510
|
+
|
|
511
|
+
const retryRaw = config.retry ?? {}
|
|
512
|
+
const retry = {
|
|
513
|
+
maxAttempts: retryRaw.maxAttempts ?? 5,
|
|
514
|
+
baseDelayMs: retryRaw.baseDelayMs ?? 1_000,
|
|
515
|
+
maxDelayMs: retryRaw.maxDelayMs ?? 60_000,
|
|
516
|
+
}
|
|
517
|
+
assertPositiveInt('retry.maxAttempts', retry.maxAttempts)
|
|
518
|
+
assertPositiveInt('retry.baseDelayMs', retry.baseDelayMs)
|
|
519
|
+
assertPositiveInt('retry.maxDelayMs', retry.maxDelayMs)
|
|
520
|
+
assertFiniteRange('retry.factor', retryRaw.factor ?? 2, 1, 1_000)
|
|
521
|
+
|
|
522
|
+
const sanitizeRaw = config.sanitize ?? {}
|
|
523
|
+
const sanitize = {
|
|
524
|
+
enabled: sanitizeRaw.enabled ?? true,
|
|
525
|
+
redactKeys: [...ALWAYS_REDACT_KEYS, ...(sanitizeRaw.redactKeys ?? [])],
|
|
526
|
+
redactPatterns: compilePatterns([
|
|
527
|
+
...BUILTIN_REDACT_PATTERNS.map(pattern => pattern.source),
|
|
528
|
+
...(sanitizeRaw.redactPatterns ?? []),
|
|
529
|
+
]),
|
|
530
|
+
truncatePromptChars: sanitizeRaw.truncatePromptChars ?? 4_000,
|
|
531
|
+
truncateCompletionChars: sanitizeRaw.truncateCompletionChars ?? 4_000,
|
|
532
|
+
truncateToolInputChars: sanitizeRaw.truncateToolInputChars ?? 2_000,
|
|
533
|
+
truncateToolOutputChars: sanitizeRaw.truncateToolOutputChars ?? 2_000,
|
|
534
|
+
truncateAttributeChars: sanitizeRaw.truncateAttributeChars ?? 512,
|
|
535
|
+
}
|
|
536
|
+
assertNonNegativeInt('sanitize.truncatePromptChars', sanitize.truncatePromptChars)
|
|
537
|
+
assertNonNegativeInt('sanitize.truncateCompletionChars', sanitize.truncateCompletionChars)
|
|
538
|
+
assertNonNegativeInt('sanitize.truncateToolInputChars', sanitize.truncateToolInputChars)
|
|
539
|
+
assertNonNegativeInt('sanitize.truncateToolOutputChars', sanitize.truncateToolOutputChars)
|
|
540
|
+
assertPositiveInt('sanitize.truncateAttributeChars', sanitize.truncateAttributeChars)
|
|
541
|
+
|
|
542
|
+
const pricing = (config.pricing ?? []).map((rule, index) => {
|
|
543
|
+
if (typeof rule.model !== 'string' || rule.model.trim().length === 0) {
|
|
544
|
+
throw new TypeError(`pricing[${index}].model must be a non-empty string`)
|
|
545
|
+
}
|
|
546
|
+
if (typeof rule.inputPerToken !== 'number' || !Number.isFinite(rule.inputPerToken) || rule.inputPerToken < 0) {
|
|
547
|
+
throw new TypeError(`pricing[${index}].inputPerToken must be a non-negative finite number`)
|
|
548
|
+
}
|
|
549
|
+
if (typeof rule.outputPerToken !== 'number' || !Number.isFinite(rule.outputPerToken) || rule.outputPerToken < 0) {
|
|
550
|
+
throw new TypeError(`pricing[${index}].outputPerToken must be a non-negative finite number`)
|
|
551
|
+
}
|
|
552
|
+
return {
|
|
553
|
+
...(rule.provider === undefined ? {} : { provider: rule.provider }),
|
|
554
|
+
model: rule.model.trim(),
|
|
555
|
+
inputPerToken: rule.inputPerToken,
|
|
556
|
+
outputPerToken: rule.outputPerToken,
|
|
557
|
+
...(rule.cacheReadPerToken === undefined ? {} : { cacheReadPerToken: rule.cacheReadPerToken }),
|
|
558
|
+
...(rule.cacheWritePerToken === undefined ? {} : { cacheWritePerToken: rule.cacheWritePerToken }),
|
|
559
|
+
}
|
|
560
|
+
})
|
|
561
|
+
|
|
562
|
+
return {
|
|
563
|
+
enabled,
|
|
564
|
+
otlp,
|
|
565
|
+
langfuse,
|
|
566
|
+
capture: {
|
|
567
|
+
turns: captureRaw.turns ?? true,
|
|
568
|
+
steps: captureRaw.steps ?? true,
|
|
569
|
+
tools: captureRaw.tools ?? true,
|
|
570
|
+
llm: captureRaw.llm ?? true,
|
|
571
|
+
},
|
|
572
|
+
llm: {
|
|
573
|
+
prompt: llmRaw.prompt ?? true,
|
|
574
|
+
completion: llmRaw.completion ?? true,
|
|
575
|
+
},
|
|
576
|
+
metadata: {
|
|
577
|
+
sessionId: metadataRaw.sessionId ?? true,
|
|
578
|
+
cwd: metadataRaw.cwd ?? false,
|
|
579
|
+
agentPreset: metadataRaw.agentPreset ?? true,
|
|
580
|
+
model: metadataRaw.model ?? true,
|
|
581
|
+
},
|
|
582
|
+
metrics: {
|
|
583
|
+
tokens: metricsRaw.tokens ?? true,
|
|
584
|
+
cost: metricsRaw.cost ?? true,
|
|
585
|
+
contextTokens: metricsRaw.contextTokens ?? true,
|
|
586
|
+
},
|
|
587
|
+
pricing,
|
|
588
|
+
sanitize,
|
|
589
|
+
batch,
|
|
590
|
+
retry: { ...retry, factor: retryRaw.factor ?? 2 },
|
|
591
|
+
remote: config.remote?.enabled ?? false,
|
|
592
|
+
}
|
|
593
|
+
}
|
|
594
|
+
|
|
595
|
+
/** Compile user regexes at mount; an invalid pattern fails loud before any export runs. */
|
|
596
|
+
function compilePatterns(patterns: readonly string[]): RegExp[] {
|
|
597
|
+
return patterns.map((pattern, index) => {
|
|
598
|
+
try {
|
|
599
|
+
return new RegExp(pattern, 'gu')
|
|
600
|
+
} catch (error) {
|
|
601
|
+
throw new TypeError(`sanitize.redactPatterns[${index}] is not a valid regular expression: ${error instanceof Error ? error.message : String(error)}`)
|
|
602
|
+
}
|
|
603
|
+
})
|
|
604
|
+
}
|
package/src/ids.ts
ADDED
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Deterministic span and trace ids. Ids are SHA-256 digests of the session
|
|
3
|
+
* identity plus structural keys, truncated to the widths each backend
|
|
4
|
+
* requires (OTel: 16-byte trace ids / 8-byte span ids; Langfuse: 32-hex
|
|
5
|
+
* observation and trace ids). Determinism is a feature: replaying the same
|
|
6
|
+
* session log produces the same ids, so backends deduplicate re-exports
|
|
7
|
+
* instead of double-counting.
|
|
8
|
+
* @module dsh-observe/ids
|
|
9
|
+
*/
|
|
10
|
+
|
|
11
|
+
import { createHash } from 'node:crypto'
|
|
12
|
+
|
|
13
|
+
/**
|
|
14
|
+
* Digest joined structural parts to a fixed hex string.
|
|
15
|
+
* @param parts - the structural identity parts.
|
|
16
|
+
* @param bytes - digest length in bytes.
|
|
17
|
+
* @returns lowercase hex, `bytes * 2` characters.
|
|
18
|
+
*/
|
|
19
|
+
export function digest(parts: readonly (string | number)[], bytes: number): string {
|
|
20
|
+
const hash = createHash('sha256')
|
|
21
|
+
for (const part of parts) {
|
|
22
|
+
hash.update('|')
|
|
23
|
+
// The runtime type rides the digest: structural parts `1` (number) and
|
|
24
|
+
// `'1'` (string) must never collide into one id.
|
|
25
|
+
hash.update(typeof part)
|
|
26
|
+
hash.update('=')
|
|
27
|
+
hash.update(String(part))
|
|
28
|
+
}
|
|
29
|
+
return hash.digest('hex').slice(0, bytes * 2)
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
/**
|
|
33
|
+
* OTel trace id for one session turn (16 bytes, 32 hex chars).
|
|
34
|
+
* @param sessionId - the session identity.
|
|
35
|
+
* @param turn - the turn number.
|
|
36
|
+
* @returns the trace id.
|
|
37
|
+
*/
|
|
38
|
+
export function otelTraceId(sessionId: string, turn: number): string {
|
|
39
|
+
return digest(['trace', sessionId, turn], 16)
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
/**
|
|
43
|
+
* OTel span id for one span (8 bytes, 16 hex chars).
|
|
44
|
+
* @param parts - the span's structural identity.
|
|
45
|
+
* @returns the span id.
|
|
46
|
+
*/
|
|
47
|
+
export function otelSpanId(...parts: readonly (string | number)[]): string {
|
|
48
|
+
return digest(['span', ...parts], 8)
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
/**
|
|
52
|
+
* Langfuse trace id for one session turn (32 hex chars).
|
|
53
|
+
* @param sessionId - the session identity.
|
|
54
|
+
* @param turn - the turn number.
|
|
55
|
+
* @returns the trace id.
|
|
56
|
+
*/
|
|
57
|
+
export function langfuseTraceId(sessionId: string, turn: number): string {
|
|
58
|
+
return digest(['langfuse-trace', sessionId, turn], 16)
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
/**
|
|
62
|
+
* Langfuse observation or event id (32 hex chars).
|
|
63
|
+
* @param parts - the observation's structural identity.
|
|
64
|
+
* @returns the id.
|
|
65
|
+
*/
|
|
66
|
+
export function langfuseId(...parts: readonly (string | number)[]): string {
|
|
67
|
+
return digest(['langfuse', ...parts], 16)
|
|
68
|
+
}
|