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/index.ts
ADDED
|
@@ -0,0 +1,186 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `dsh-observe` — the observability exporter for DeepSeek Harness: turns
|
|
3
|
+
* the `session/event` stream into OTLP/HTTP traces + metrics and Langfuse
|
|
4
|
+
* observations. Turn/step lifecycle spans, tool-call spans (duration,
|
|
5
|
+
* status, derived retries), LLM generation spans with sanitized
|
|
6
|
+
* prompt/completion, and per-model token and cost metrics; async batching,
|
|
7
|
+
* a bounded durable offline buffer (storage-domain), retry with backoff,
|
|
8
|
+
* and a pre-send sanitization layer. Off by default — `enabled: true` plus
|
|
9
|
+
* at least one backend is an explicit opt-in.
|
|
10
|
+
*
|
|
11
|
+
* Function plugin — no default export (the Loader unwraps
|
|
12
|
+
* `exports.default ?? exports`, and a stray default would discard
|
|
13
|
+
* `name`/`inject`/`Config`/`apply`).
|
|
14
|
+
* @module dsh-observe
|
|
15
|
+
*/
|
|
16
|
+
|
|
17
|
+
import type { Context } from '@deepseek-ai/cordis'
|
|
18
|
+
import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
|
|
19
|
+
import { Config, resolveConfig } from './config.ts'
|
|
20
|
+
import type { ExportRecord, MetricRecord, SpanRecord } from './model.ts'
|
|
21
|
+
import { observeDomainSpec, openSpool } from './spool.ts'
|
|
22
|
+
import { OtlpSink, LangfuseSink } from './sinks.ts'
|
|
23
|
+
import { Pipeline } from './pipeline.ts'
|
|
24
|
+
import { Collector } from './collector.ts'
|
|
25
|
+
import type { TokenMeterService } from './collector.ts'
|
|
26
|
+
import { observeRemotePlugin } from './remote.ts'
|
|
27
|
+
import type { ObserveStatus } from './wire.ts'
|
|
28
|
+
|
|
29
|
+
export const name = 'observe'
|
|
30
|
+
/** The durable offline buffer needs the host's storage-domain facility. */
|
|
31
|
+
export const inject = ['storageDomain']
|
|
32
|
+
|
|
33
|
+
export { Config, resolveConfig } from './config.ts'
|
|
34
|
+
export type { ResolvedConfig, PricingRule, SanitizeConfig, BatchConfig, RetryConfig, OtlpConfig, LangfuseConfig } from './config.ts'
|
|
35
|
+
export { VERSION } from './version.ts'
|
|
36
|
+
export { REDACTED, sanitizeJson, sanitizeJsonText, sanitizeText, truncate } from './sanitize.ts'
|
|
37
|
+
export type { SpanRecord, MetricRecord, ExportRecord, TokenCounts, SpanKind } from './model.ts'
|
|
38
|
+
export type { ObserveStatus, ObserveSetEnabledResult } from './wire.ts'
|
|
39
|
+
|
|
40
|
+
/**
|
|
41
|
+
* Mount the exporter. The resolved config is validated first (fail loud);
|
|
42
|
+
* with `enabled: false` the plugin registers nothing and stays inert.
|
|
43
|
+
* @param ctx - the plugin context (host).
|
|
44
|
+
* @param config - raw plugin config.
|
|
45
|
+
* @returns resolution after the offline-buffer domain is open.
|
|
46
|
+
*/
|
|
47
|
+
export async function apply(ctx: Context, config: Config = {}): Promise<void> {
|
|
48
|
+
const resolved = resolveConfig(config)
|
|
49
|
+
const logger = ctx.logger('observe')
|
|
50
|
+
if (!resolved.enabled) {
|
|
51
|
+
logger.info('disabled: enabled is false — no session data is captured or exported')
|
|
52
|
+
return
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
// The runtime kill switch, flippable through the optional Typert remote.
|
|
56
|
+
let enabled = true
|
|
57
|
+
const isEnabled = () => enabled
|
|
58
|
+
|
|
59
|
+
const otlpSink = resolved.otlp === undefined ? undefined : new OtlpSink(resolved.otlp, logger)
|
|
60
|
+
const recordMetric = (metric: MetricRecord): void => {
|
|
61
|
+
if (isEnabled()) otlpSink?.recordMetric(metric)
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
const domain = await ctx.storageDomain.open(observeDomainSpec)
|
|
65
|
+
const spool = openSpool(
|
|
66
|
+
domain,
|
|
67
|
+
resolved.batch.maxBufferRecords,
|
|
68
|
+
count => recordMetric({
|
|
69
|
+
name: 'observe.dropped',
|
|
70
|
+
kind: 'counter',
|
|
71
|
+
unit: 'records',
|
|
72
|
+
value: count,
|
|
73
|
+
attributes: { reason: 'buffer_overflow' },
|
|
74
|
+
}),
|
|
75
|
+
count => {
|
|
76
|
+
logger.warn(`spool: ${count} stored record(s) failed validation and were dropped`)
|
|
77
|
+
},
|
|
78
|
+
)
|
|
79
|
+
|
|
80
|
+
const pipelines: Pipeline[] = []
|
|
81
|
+
if (otlpSink !== undefined) {
|
|
82
|
+
pipelines.push(new Pipeline({
|
|
83
|
+
name: 'otlp',
|
|
84
|
+
sink: otlpSink,
|
|
85
|
+
spool,
|
|
86
|
+
batch: resolved.batch,
|
|
87
|
+
retry: resolved.retry,
|
|
88
|
+
logger,
|
|
89
|
+
isEnabled,
|
|
90
|
+
onMetric: recordMetric,
|
|
91
|
+
}))
|
|
92
|
+
}
|
|
93
|
+
if (resolved.langfuse !== undefined) {
|
|
94
|
+
pipelines.push(new Pipeline({
|
|
95
|
+
name: 'langfuse',
|
|
96
|
+
sink: new LangfuseSink(resolved.langfuse, logger),
|
|
97
|
+
spool,
|
|
98
|
+
batch: resolved.batch,
|
|
99
|
+
retry: resolved.retry,
|
|
100
|
+
logger,
|
|
101
|
+
isEnabled,
|
|
102
|
+
onMetric: recordMetric,
|
|
103
|
+
}))
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
const onSpan = (span: SpanRecord): void => {
|
|
107
|
+
const record: ExportRecord = { kind: 'span', span }
|
|
108
|
+
for (const pipeline of pipelines) pipeline.push(record)
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
const collector = new Collector(
|
|
112
|
+
resolved,
|
|
113
|
+
() => ctx.get('tokenMeter') as unknown as TokenMeterService | undefined,
|
|
114
|
+
onSpan,
|
|
115
|
+
recordMetric,
|
|
116
|
+
logger,
|
|
117
|
+
)
|
|
118
|
+
|
|
119
|
+
// One effect owns every timer and the teardown order: stop the timers,
|
|
120
|
+
// final-flush the pipelines (spilling failures to the durable buffer),
|
|
121
|
+
// then close the domain.
|
|
122
|
+
ctx.effect(() => {
|
|
123
|
+
const timers: ReturnType<typeof setInterval>[] = [
|
|
124
|
+
setInterval(() => {
|
|
125
|
+
for (const pipeline of pipelines) void pipeline.tick()
|
|
126
|
+
}, resolved.batch.flushIntervalMs),
|
|
127
|
+
setInterval(() => {
|
|
128
|
+
for (const pipeline of pipelines) void pipeline.drainSpool()
|
|
129
|
+
}, resolved.batch.bufferRetryIntervalMs),
|
|
130
|
+
...(otlpSink === undefined
|
|
131
|
+
? []
|
|
132
|
+
: [setInterval(() => { void otlpSink.flushMetrics() }, resolved.batch.flushIntervalMs)]),
|
|
133
|
+
]
|
|
134
|
+
return async () => {
|
|
135
|
+
for (const timer of timers) clearInterval(timer)
|
|
136
|
+
await Promise.all(pipelines.map(pipeline => pipeline.dispose()))
|
|
137
|
+
await domain.close()
|
|
138
|
+
}
|
|
139
|
+
})
|
|
140
|
+
|
|
141
|
+
ctx.on('session/event', (session: Session, event: SessionEvent) => {
|
|
142
|
+
try {
|
|
143
|
+
collector.handleEvent(session, event)
|
|
144
|
+
} catch (error) {
|
|
145
|
+
logger.warn(`session "${session.id}": event handling failed: ${error instanceof Error ? error.message : String(error)}`)
|
|
146
|
+
}
|
|
147
|
+
})
|
|
148
|
+
|
|
149
|
+
// Best-effort kick: the session-flush durability checkpoint must not wait
|
|
150
|
+
// on a remote observability backend, so exports run in the background.
|
|
151
|
+
ctx.on('session/flush', () => {
|
|
152
|
+
for (const pipeline of pipelines) pipeline.kick()
|
|
153
|
+
})
|
|
154
|
+
|
|
155
|
+
ctx.on('session/disposed', (session: Session) => {
|
|
156
|
+
try {
|
|
157
|
+
collector.handleSessionDisposed(session)
|
|
158
|
+
} catch (error) {
|
|
159
|
+
logger.warn(`session "${session.id}": disposal handling failed: ${error instanceof Error ? error.message : String(error)}`)
|
|
160
|
+
}
|
|
161
|
+
for (const pipeline of pipelines) pipeline.kick()
|
|
162
|
+
})
|
|
163
|
+
|
|
164
|
+
if (resolved.remote) {
|
|
165
|
+
const depthOf = (backend: 'otlp' | 'langfuse'): number =>
|
|
166
|
+
pipelines.find(pipeline => pipeline.name === backend)?.depth ?? 0
|
|
167
|
+
await ctx.plugin(observeRemotePlugin({
|
|
168
|
+
getStatus: (): ObserveStatus => ({
|
|
169
|
+
enabled,
|
|
170
|
+
backends: {
|
|
171
|
+
otlp: resolved.otlp !== undefined,
|
|
172
|
+
langfuse: resolved.langfuse !== undefined,
|
|
173
|
+
},
|
|
174
|
+
queueDepth: { otlp: depthOf('otlp'), langfuse: depthOf('langfuse') },
|
|
175
|
+
spool: spool.counts(),
|
|
176
|
+
}),
|
|
177
|
+
setEnabled: (value: boolean) => {
|
|
178
|
+
enabled = value
|
|
179
|
+
logger.info(value ? 'exporting re-enabled' : 'exporting disabled (kill switch): new records are dropped until re-enabled')
|
|
180
|
+
if (value) {
|
|
181
|
+
for (const pipeline of pipelines) pipeline.kick()
|
|
182
|
+
}
|
|
183
|
+
},
|
|
184
|
+
}))
|
|
185
|
+
}
|
|
186
|
+
}
|
package/src/model.ts
ADDED
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Owned JSON record model shared by both export backends. Everything here
|
|
3
|
+
* is plain data, already sanitized, and fully detached from live harness
|
|
4
|
+
* objects — records are the only thing that ever crosses the plugin's
|
|
5
|
+
* process boundary, so no Cordis/Session reference can leak into a payload.
|
|
6
|
+
* @module dsh-observe/model
|
|
7
|
+
*/
|
|
8
|
+
|
|
9
|
+
/** JSON-scalar attribute values. */
|
|
10
|
+
export type JsonScalar = string | number | boolean
|
|
11
|
+
|
|
12
|
+
/** Normalized token accounting for one LLM call. */
|
|
13
|
+
export interface TokenCounts {
|
|
14
|
+
input: number
|
|
15
|
+
output: number
|
|
16
|
+
cacheRead: number
|
|
17
|
+
cacheWrite: number
|
|
18
|
+
reasoning: number
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
/** Tool-specific span payload (sanitized at capture). */
|
|
22
|
+
export interface ToolSpanInfo {
|
|
23
|
+
name: string
|
|
24
|
+
status: 'ok' | 'error'
|
|
25
|
+
errorName?: string
|
|
26
|
+
errorCode?: string
|
|
27
|
+
input?: string
|
|
28
|
+
output?: string
|
|
29
|
+
/** 1-based occurrence of this exact (name, arguments) pair within the step. */
|
|
30
|
+
attempt: number
|
|
31
|
+
/** `attempt - 1` — earlier identical calls in the same step are retries. */
|
|
32
|
+
retries: number
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
/** LLM-specific span payload (sanitized at capture). */
|
|
36
|
+
export interface LlmSpanInfo {
|
|
37
|
+
model?: string
|
|
38
|
+
provider?: string
|
|
39
|
+
usage?: TokenCounts
|
|
40
|
+
finishReason?: string
|
|
41
|
+
ttftMs?: number
|
|
42
|
+
input?: string
|
|
43
|
+
output?: string
|
|
44
|
+
costUsd?: number
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
/** The span families. */
|
|
48
|
+
export type SpanKind = 'turn' | 'step' | 'tool' | 'llm'
|
|
49
|
+
|
|
50
|
+
/** One closed span, ready for export. */
|
|
51
|
+
export interface SpanRecord {
|
|
52
|
+
kind: SpanKind
|
|
53
|
+
sessionId: string
|
|
54
|
+
turn: number
|
|
55
|
+
/** Present for step/tool/llm spans; absent for turn spans. */
|
|
56
|
+
step?: number
|
|
57
|
+
/** The tool call id (tool spans only) — anchors the deterministic span id. */
|
|
58
|
+
callId?: string
|
|
59
|
+
startUnixNano: number
|
|
60
|
+
endUnixNano: number
|
|
61
|
+
attributes: Record<string, JsonScalar>
|
|
62
|
+
status: 'ok' | 'error'
|
|
63
|
+
tool?: ToolSpanInfo
|
|
64
|
+
llm?: LlmSpanInfo
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
/**
|
|
68
|
+
* One metric sample. Counters carry deltas (the OTLP sink aggregates them
|
|
69
|
+
* into cumulative sums); gauges carry absolute values (last write wins).
|
|
70
|
+
*/
|
|
71
|
+
export interface MetricRecord {
|
|
72
|
+
name: string
|
|
73
|
+
kind: 'counter' | 'gauge'
|
|
74
|
+
unit: string
|
|
75
|
+
value: number
|
|
76
|
+
attributes: Record<string, string>
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
/** The record union that flows through pipelines, spool, and sinks. */
|
|
80
|
+
export type ExportRecord =
|
|
81
|
+
| { kind: 'span'; span: SpanRecord }
|
|
82
|
+
| { kind: 'metric'; metric: MetricRecord }
|
|
83
|
+
|
|
84
|
+
/**
|
|
85
|
+
* Validate a value read back from the durable spool: it must look like an
|
|
86
|
+
* export record. The spool is a durable boundary, so hostile or hand-edited
|
|
87
|
+
* values are rejected here instead of reaching a sink.
|
|
88
|
+
* @param value - the stored value.
|
|
89
|
+
* @returns true when the value is an {@link ExportRecord}.
|
|
90
|
+
*/
|
|
91
|
+
export function isExportRecord(value: unknown): value is ExportRecord {
|
|
92
|
+
if (typeof value !== 'object' || value === null) return false
|
|
93
|
+
const record = value as { kind?: unknown; span?: unknown; metric?: unknown }
|
|
94
|
+
if (record.kind === 'span') return typeof record.span === 'object' && record.span !== null
|
|
95
|
+
if (record.kind === 'metric') return typeof record.metric === 'object' && record.metric !== null
|
|
96
|
+
return false
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
/** The two export backends. */
|
|
100
|
+
export type BackendName = 'otlp' | 'langfuse'
|
package/src/pipeline.ts
ADDED
|
@@ -0,0 +1,205 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The per-backend delivery pipeline: an in-memory queue, periodic and
|
|
3
|
+
* size-triggered flushes, retry with exponential backoff, and spill-over
|
|
4
|
+
* into the durable offline buffer (both when the queue bound is hit and
|
|
5
|
+
* when retries are exhausted). Spool draining runs on its own cycle.
|
|
6
|
+
* @module dsh-observe/pipeline
|
|
7
|
+
*/
|
|
8
|
+
|
|
9
|
+
import type { ResolvedBatch, ResolvedRetry } from './config.ts'
|
|
10
|
+
import type { BackendName, ExportRecord, MetricRecord } from './model.ts'
|
|
11
|
+
import { backoffDelayMs } from './backoff.ts'
|
|
12
|
+
import type { ObserveLogger, SpanSink } from './sinks.ts'
|
|
13
|
+
import type { Spool } from './spool.ts'
|
|
14
|
+
|
|
15
|
+
/** Everything one pipeline needs. */
|
|
16
|
+
export interface PipelineOptions {
|
|
17
|
+
name: BackendName
|
|
18
|
+
sink: SpanSink
|
|
19
|
+
spool: Spool
|
|
20
|
+
batch: ResolvedBatch
|
|
21
|
+
retry: ResolvedRetry
|
|
22
|
+
logger: ObserveLogger
|
|
23
|
+
/** The runtime kill switch; when off, pushed records are dropped and counted. */
|
|
24
|
+
isEnabled: () => boolean
|
|
25
|
+
/** Operational metric sink (OTLP aggregation). */
|
|
26
|
+
onMetric: (metric: MetricRecord) => void
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
/**
|
|
30
|
+
* One backend's delivery pipeline. Push is synchronous (the session event
|
|
31
|
+
* hot path); all network work happens on timers or in the background.
|
|
32
|
+
*/
|
|
33
|
+
export class Pipeline {
|
|
34
|
+
private queue: ExportRecord[] = []
|
|
35
|
+
private pending: ExportRecord[] | undefined
|
|
36
|
+
private inFlight = false
|
|
37
|
+
private consecutiveFailures = 0
|
|
38
|
+
private retryTimer: ReturnType<typeof setTimeout> | undefined
|
|
39
|
+
private disposed = false
|
|
40
|
+
|
|
41
|
+
/**
|
|
42
|
+
* @param options - the pipeline options (copied, never mutated).
|
|
43
|
+
*/
|
|
44
|
+
constructor(private readonly options: PipelineOptions) {}
|
|
45
|
+
|
|
46
|
+
/** Records currently queued or awaiting retry. */
|
|
47
|
+
get depth(): number {
|
|
48
|
+
return this.queue.length + (this.pending?.length ?? 0)
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
/** The backend this pipeline delivers to (`otlp` / `langfuse`). */
|
|
52
|
+
get name(): BackendName {
|
|
53
|
+
return this.options.name
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
/**
|
|
57
|
+
* Queue one record. A disabled runtime drops it (counted); a full queue
|
|
58
|
+
* spills it straight into the durable buffer (bounded; oldest records
|
|
59
|
+
* there are evicted first).
|
|
60
|
+
* @param record - the owned, sanitized record.
|
|
61
|
+
*/
|
|
62
|
+
push(record: ExportRecord): void {
|
|
63
|
+
if (this.disposed) return
|
|
64
|
+
if (!this.options.isEnabled()) {
|
|
65
|
+
this.options.onMetric({
|
|
66
|
+
name: 'observe.dropped',
|
|
67
|
+
kind: 'counter',
|
|
68
|
+
unit: 'records',
|
|
69
|
+
value: 1,
|
|
70
|
+
attributes: { reason: 'disabled', backend: this.options.name },
|
|
71
|
+
})
|
|
72
|
+
return
|
|
73
|
+
}
|
|
74
|
+
if (this.queue.length < this.options.batch.maxQueueRecords) {
|
|
75
|
+
this.queue.push(record)
|
|
76
|
+
if (this.queue.length >= this.options.batch.maxRecords) this.kick()
|
|
77
|
+
return
|
|
78
|
+
}
|
|
79
|
+
void this.options.spool.push(this.options.name, [record]).catch((error: unknown) => {
|
|
80
|
+
this.options.logger.warn(`${this.options.name}: buffer spill failed: ${error instanceof Error ? error.message : String(error)}`)
|
|
81
|
+
})
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
/** Start a flush immediately when no flush is already running or scheduled. */
|
|
85
|
+
kick(): void {
|
|
86
|
+
if (this.retryTimer !== undefined || this.inFlight) return
|
|
87
|
+
void this.flushOnce()
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
/** The periodic flush entry point. */
|
|
91
|
+
async tick(): Promise<void> {
|
|
92
|
+
await this.flushOnce()
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
/** One flush attempt: pending retry batch first, otherwise the queue head. */
|
|
96
|
+
private async flushOnce(): Promise<void> {
|
|
97
|
+
if (this.inFlight || this.disposed) return
|
|
98
|
+
const batch = this.pending ?? this.queue.splice(0, this.options.batch.maxRecords)
|
|
99
|
+
if (batch.length === 0) return
|
|
100
|
+
this.inFlight = true
|
|
101
|
+
try {
|
|
102
|
+
await this.options.sink.exportSpans(batch)
|
|
103
|
+
this.consecutiveFailures = 0
|
|
104
|
+
this.pending = undefined
|
|
105
|
+
} catch (error) {
|
|
106
|
+
this.consecutiveFailures += 1
|
|
107
|
+
this.pending = batch
|
|
108
|
+
if (this.consecutiveFailures >= this.options.retry.maxAttempts) {
|
|
109
|
+
this.pending = undefined
|
|
110
|
+
this.consecutiveFailures = 0
|
|
111
|
+
await this.options.spool.push(this.options.name, batch)
|
|
112
|
+
this.options.onMetric({
|
|
113
|
+
name: 'observe.spooled',
|
|
114
|
+
kind: 'counter',
|
|
115
|
+
unit: 'records',
|
|
116
|
+
value: batch.length,
|
|
117
|
+
attributes: { backend: this.options.name },
|
|
118
|
+
})
|
|
119
|
+
} else {
|
|
120
|
+
this.scheduleRetry()
|
|
121
|
+
}
|
|
122
|
+
this.options.onMetric({
|
|
123
|
+
name: 'observe.export_failures',
|
|
124
|
+
kind: 'counter',
|
|
125
|
+
unit: 'requests',
|
|
126
|
+
value: 1,
|
|
127
|
+
attributes: { backend: this.options.name },
|
|
128
|
+
})
|
|
129
|
+
this.options.logger.warn(
|
|
130
|
+
`${this.options.name}: export attempt ${this.consecutiveFailures} failed: ${error instanceof Error ? error.message : String(error)}`,
|
|
131
|
+
)
|
|
132
|
+
} finally {
|
|
133
|
+
this.inFlight = false
|
|
134
|
+
}
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
/** Schedule the backoff retry for the pending batch. */
|
|
138
|
+
private scheduleRetry(): void {
|
|
139
|
+
if (this.disposed || this.retryTimer !== undefined) return
|
|
140
|
+
const delay = backoffDelayMs(this.consecutiveFailures, this.options.retry)
|
|
141
|
+
this.retryTimer = setTimeout(() => {
|
|
142
|
+
this.retryTimer = undefined
|
|
143
|
+
void this.flushOnce()
|
|
144
|
+
}, delay)
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
/**
|
|
148
|
+
* Try the oldest buffered batches once. Batches that fail stay in the
|
|
149
|
+
* buffer for the next cycle; success deletes them.
|
|
150
|
+
*/
|
|
151
|
+
async drainSpool(): Promise<void> {
|
|
152
|
+
if (this.inFlight || this.disposed) return
|
|
153
|
+
const { batches, records } = this.options.spool.peek(this.options.name, this.options.batch.maxRecords)
|
|
154
|
+
if (records.length === 0) return
|
|
155
|
+
this.inFlight = true
|
|
156
|
+
try {
|
|
157
|
+
await this.options.sink.exportSpans(records)
|
|
158
|
+
await this.options.spool.remove(batches)
|
|
159
|
+
this.consecutiveFailures = 0
|
|
160
|
+
this.options.onMetric({
|
|
161
|
+
name: 'observe.spool_flushed',
|
|
162
|
+
kind: 'counter',
|
|
163
|
+
unit: 'records',
|
|
164
|
+
value: records.length,
|
|
165
|
+
attributes: { backend: this.options.name },
|
|
166
|
+
})
|
|
167
|
+
} catch (error) {
|
|
168
|
+
this.options.onMetric({
|
|
169
|
+
name: 'observe.export_failures',
|
|
170
|
+
kind: 'counter',
|
|
171
|
+
unit: 'requests',
|
|
172
|
+
value: 1,
|
|
173
|
+
attributes: { backend: this.options.name, kind: 'buffer' },
|
|
174
|
+
})
|
|
175
|
+
this.options.logger.warn(`${this.options.name}: buffer drain failed: ${error instanceof Error ? error.message : String(error)}`)
|
|
176
|
+
} finally {
|
|
177
|
+
this.inFlight = false
|
|
178
|
+
}
|
|
179
|
+
}
|
|
180
|
+
|
|
181
|
+
/**
|
|
182
|
+
* Final flush on unload: one best-effort export of everything queued;
|
|
183
|
+
* whatever fails goes to the durable buffer for the next process run.
|
|
184
|
+
*/
|
|
185
|
+
async dispose(): Promise<void> {
|
|
186
|
+
this.disposed = true
|
|
187
|
+
if (this.retryTimer !== undefined) {
|
|
188
|
+
clearTimeout(this.retryTimer)
|
|
189
|
+
this.retryTimer = undefined
|
|
190
|
+
}
|
|
191
|
+
const batch = [...(this.pending ?? []), ...this.queue]
|
|
192
|
+
this.queue = []
|
|
193
|
+
this.pending = undefined
|
|
194
|
+
if (batch.length === 0) return
|
|
195
|
+
try {
|
|
196
|
+
await this.options.sink.exportSpans(batch)
|
|
197
|
+
} catch {
|
|
198
|
+
try {
|
|
199
|
+
await this.options.spool.push(this.options.name, batch)
|
|
200
|
+
} catch (error) {
|
|
201
|
+
this.options.logger.warn(`${this.options.name}: final buffer spill failed: ${error instanceof Error ? error.message : String(error)}`)
|
|
202
|
+
}
|
|
203
|
+
}
|
|
204
|
+
}
|
|
205
|
+
}
|
package/src/pricing.ts
ADDED
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Cost pricing: match a model's token usage against the configured pricing
|
|
3
|
+
* table and compute the call cost. No prices are hardcoded — an empty table
|
|
4
|
+
* simply means the cost metric stays silent for that model.
|
|
5
|
+
* @module dsh-observe/pricing
|
|
6
|
+
*/
|
|
7
|
+
|
|
8
|
+
import type { PricingRule } from './config.ts'
|
|
9
|
+
import type { TokenCounts } from './model.ts'
|
|
10
|
+
|
|
11
|
+
/**
|
|
12
|
+
* Compile a glob pattern (only `*` is special) to an anchored regular
|
|
13
|
+
* expression.
|
|
14
|
+
* @param pattern - the glob pattern over a model id.
|
|
15
|
+
* @returns the compiled matcher.
|
|
16
|
+
*/
|
|
17
|
+
export function globToRegExp(pattern: string): RegExp {
|
|
18
|
+
const escaped = pattern.replace(/[.+?^${}()|[\]\\]/gu, '\\$&').replaceAll('*', '.*')
|
|
19
|
+
return new RegExp(`^${escaped}$`, 'u')
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
/**
|
|
23
|
+
* Find the first pricing rule matching the attribution: `provider` matches
|
|
24
|
+
* exactly when set, `model` matches as a glob.
|
|
25
|
+
* @param pricing - the configured pricing table, in priority order.
|
|
26
|
+
* @param provider - the provider route id.
|
|
27
|
+
* @param model - the model id.
|
|
28
|
+
* @returns the first matching rule, or undefined.
|
|
29
|
+
*/
|
|
30
|
+
export function findPrice(
|
|
31
|
+
pricing: readonly PricingRule[],
|
|
32
|
+
provider: string,
|
|
33
|
+
model: string,
|
|
34
|
+
): PricingRule | undefined {
|
|
35
|
+
return pricing.find(rule =>
|
|
36
|
+
(rule.provider === undefined || rule.provider === provider)
|
|
37
|
+
&& globToRegExp(rule.model).test(model))
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
/**
|
|
41
|
+
* Compute the USD cost of one call under a matched rule. Cache-read and
|
|
42
|
+
* cache-write traffic falls back to the input price when the rule does not
|
|
43
|
+
* price them separately.
|
|
44
|
+
* @param rule - the matched pricing rule.
|
|
45
|
+
* @param usage - the normalized token counts.
|
|
46
|
+
* @returns the cost in USD.
|
|
47
|
+
*/
|
|
48
|
+
export function costUsd(rule: PricingRule, usage: TokenCounts): number {
|
|
49
|
+
const cacheRead = usage.cacheRead * (rule.cacheReadPerToken ?? rule.inputPerToken)
|
|
50
|
+
const cacheWrite = usage.cacheWrite * (rule.cacheWritePerToken ?? rule.inputPerToken)
|
|
51
|
+
return usage.input * rule.inputPerToken
|
|
52
|
+
+ usage.output * rule.outputPerToken
|
|
53
|
+
+ cacheRead
|
|
54
|
+
+ cacheWrite
|
|
55
|
+
}
|
package/src/project.ts
ADDED
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Text projection of model-visible messages and content blocks. Used to
|
|
3
|
+
* turn logged messages into the sanitized prompt/completion strings exported
|
|
4
|
+
* to observability backends; every projection stays reconstructable from the
|
|
5
|
+
* session log (the model-visible ⟺ logged invariant holds — no extra
|
|
6
|
+
* information enters the export).
|
|
7
|
+
* @module dsh-observe/project
|
|
8
|
+
*/
|
|
9
|
+
|
|
10
|
+
import type { ContentBlock, Message } from '@deepseek-ai/dsh-llm'
|
|
11
|
+
|
|
12
|
+
/**
|
|
13
|
+
* Project content blocks to one compact plain-text string. Text and
|
|
14
|
+
* reasoning deltas pass through verbatim; tool calls render as
|
|
15
|
+
* `<tool-call name(arguments)>`; images render as `[image]`; tool results
|
|
16
|
+
* recurse. Unknown block types (merge-extensible) are skipped — they carry
|
|
17
|
+
* no projectable text.
|
|
18
|
+
* @param blocks - the model-facing content blocks.
|
|
19
|
+
* @returns the joined projection.
|
|
20
|
+
*/
|
|
21
|
+
export function projectContent(blocks: readonly ContentBlock[]): string {
|
|
22
|
+
const parts: string[] = []
|
|
23
|
+
for (const block of blocks) {
|
|
24
|
+
switch (block.type) {
|
|
25
|
+
case 'text':
|
|
26
|
+
parts.push(block.text)
|
|
27
|
+
break
|
|
28
|
+
case 'reasoning':
|
|
29
|
+
parts.push(block.text)
|
|
30
|
+
break
|
|
31
|
+
case 'tool-call':
|
|
32
|
+
parts.push(`<tool-call ${block.name}(${block.arguments})>`)
|
|
33
|
+
break
|
|
34
|
+
case 'image':
|
|
35
|
+
parts.push('[image]')
|
|
36
|
+
break
|
|
37
|
+
case 'tool-result':
|
|
38
|
+
parts.push(projectContent(block.content) + (block.isError === true ? ' [error]' : ''))
|
|
39
|
+
break
|
|
40
|
+
default:
|
|
41
|
+
// Unknown content block types carry no projectable text.
|
|
42
|
+
break
|
|
43
|
+
}
|
|
44
|
+
}
|
|
45
|
+
return parts.join('\n')
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
/**
|
|
49
|
+
* Project one message with its role prefix.
|
|
50
|
+
* @param message - the logged message.
|
|
51
|
+
* @returns `[role] content` on one logical line.
|
|
52
|
+
*/
|
|
53
|
+
export function projectMessage(message: Message): string {
|
|
54
|
+
return `[${message.role}] ${projectContent(message.content)}`
|
|
55
|
+
}
|
package/src/remote.ts
ADDED
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The optional Typert remote surface: a small `observe` service exposing
|
|
3
|
+
* `observe/status` and `observe/setEnabled` to settings pages and other
|
|
4
|
+
* remote consumers. `setEnabled` is the runtime kill switch — it stops
|
|
5
|
+
* (or resumes) exporting without unmounting the plugin. Mounted only when
|
|
6
|
+
* `remote.enabled: true`; the service itself never exports data.
|
|
7
|
+
*
|
|
8
|
+
* **No `@Remote` method decorators**: the rc.6 typert loader binds the
|
|
9
|
+
* `./typert` manifest invocations (src/typert.host.ts) to same-named public
|
|
10
|
+
* methods, and decorator syntax breaks both the vitest transform pipeline
|
|
11
|
+
* and the plain-Node build output (the dsh-mcp-panel precedent).
|
|
12
|
+
*
|
|
13
|
+
* @module dsh-observe/remote
|
|
14
|
+
*/
|
|
15
|
+
|
|
16
|
+
import type { Context, Plugin } from '@deepseek-ai/cordis'
|
|
17
|
+
import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol'
|
|
18
|
+
import type { ObserveStatus } from './wire.ts'
|
|
19
|
+
|
|
20
|
+
/** Bindings the remote service reads from the runtime. */
|
|
21
|
+
export interface ObserveRemoteOptions {
|
|
22
|
+
getStatus: () => ObserveStatus
|
|
23
|
+
setEnabled: (enabled: boolean) => void
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
/**
|
|
27
|
+
* Build the `observe` Typert remote service as a Cordis plugin class.
|
|
28
|
+
* @param options - the runtime bindings.
|
|
29
|
+
* @returns the service plugin (mount with `ctx.plugin`).
|
|
30
|
+
*/
|
|
31
|
+
export function observeRemotePlugin(options: ObserveRemoteOptions): Plugin {
|
|
32
|
+
class ObserveRemoteService extends TypertRemoteService {
|
|
33
|
+
/**
|
|
34
|
+
* @param ctx - the mounting context.
|
|
35
|
+
*/
|
|
36
|
+
constructor(ctx: Context) {
|
|
37
|
+
super(ctx, 'observe')
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
/** The read-only status snapshot (bound as `observe/status`). */
|
|
41
|
+
status(): ObserveStatus {
|
|
42
|
+
return options.getStatus()
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
/** The runtime kill switch (bound as `observe/setEnabled`). */
|
|
46
|
+
setEnabled(request: { enabled: boolean }): { enabled: boolean } {
|
|
47
|
+
const value: unknown = request?.enabled
|
|
48
|
+
if (typeof value !== 'boolean') {
|
|
49
|
+
throw new TypeError('observe.setEnabled requires { enabled: boolean }')
|
|
50
|
+
}
|
|
51
|
+
options.setEnabled(value)
|
|
52
|
+
return { enabled: options.getStatus().enabled }
|
|
53
|
+
}
|
|
54
|
+
}
|
|
55
|
+
return ObserveRemoteService as unknown as Plugin
|
|
56
|
+
}
|