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.
Files changed (92) hide show
  1. package/CHANGELOG.md +25 -0
  2. package/LICENSE +201 -0
  3. package/README.es.md +198 -0
  4. package/README.hi.md +198 -0
  5. package/README.md +198 -0
  6. package/README.pt.md +198 -0
  7. package/README.zh.md +198 -0
  8. package/THIRD_PARTY_NOTICES.md +21 -0
  9. package/cordis.patch.yml +86 -0
  10. package/lib/index.js +1947 -0
  11. package/lib/typert.host.js +109 -0
  12. package/lib/types/backoff.d.ts +17 -0
  13. package/lib/types/backoff.d.ts.map +1 -0
  14. package/lib/types/backoff.js +17 -0
  15. package/lib/types/backoff.js.map +1 -0
  16. package/lib/types/collector.d.ts +83 -0
  17. package/lib/types/collector.d.ts.map +1 -0
  18. package/lib/types/collector.js +506 -0
  19. package/lib/types/collector.js.map +1 -0
  20. package/lib/types/config.d.ts +286 -0
  21. package/lib/types/config.d.ts.map +1 -0
  22. package/lib/types/config.js +312 -0
  23. package/lib/types/config.js.map +1 -0
  24. package/lib/types/ids.d.ts +43 -0
  25. package/lib/types/ids.d.ts.map +1 -0
  26. package/lib/types/ids.js +63 -0
  27. package/lib/types/ids.js.map +1 -0
  28. package/lib/types/index.d.ts +35 -0
  29. package/lib/types/index.d.ts.map +1 -0
  30. package/lib/types/index.js +162 -0
  31. package/lib/types/index.js.map +1 -0
  32. package/lib/types/model.d.ts +89 -0
  33. package/lib/types/model.d.ts.map +1 -0
  34. package/lib/types/model.js +25 -0
  35. package/lib/types/model.js.map +1 -0
  36. package/lib/types/pipeline.d.ts +71 -0
  37. package/lib/types/pipeline.d.ts.map +1 -0
  38. package/lib/types/pipeline.js +193 -0
  39. package/lib/types/pipeline.js.map +1 -0
  40. package/lib/types/pricing.d.ts +34 -0
  41. package/lib/types/pricing.d.ts.map +1 -0
  42. package/lib/types/pricing.js +45 -0
  43. package/lib/types/pricing.js.map +1 -0
  44. package/lib/types/project.d.ts +26 -0
  45. package/lib/types/project.d.ts.map +1 -0
  46. package/lib/types/project.js +52 -0
  47. package/lib/types/project.js.map +1 -0
  48. package/lib/types/remote.d.ts +28 -0
  49. package/lib/types/remote.d.ts.map +1 -0
  50. package/lib/types/remote.js +45 -0
  51. package/lib/types/remote.js.map +1 -0
  52. package/lib/types/sanitize.d.ts +78 -0
  53. package/lib/types/sanitize.d.ts.map +1 -0
  54. package/lib/types/sanitize.js +132 -0
  55. package/lib/types/sanitize.js.map +1 -0
  56. package/lib/types/sinks.d.ts +84 -0
  57. package/lib/types/sinks.d.ts.map +1 -0
  58. package/lib/types/sinks.js +434 -0
  59. package/lib/types/sinks.js.map +1 -0
  60. package/lib/types/spool.d.ts +113 -0
  61. package/lib/types/spool.d.ts.map +1 -0
  62. package/lib/types/spool.js +167 -0
  63. package/lib/types/spool.js.map +1 -0
  64. package/lib/types/typert.host.d.ts +93 -0
  65. package/lib/types/typert.host.d.ts.map +1 -0
  66. package/lib/types/typert.host.js +23 -0
  67. package/lib/types/typert.host.js.map +1 -0
  68. package/lib/types/version.d.ts +10 -0
  69. package/lib/types/version.d.ts.map +1 -0
  70. package/lib/types/version.js +10 -0
  71. package/lib/types/version.js.map +1 -0
  72. package/lib/types/wire.d.ts +206 -0
  73. package/lib/types/wire.d.ts.map +1 -0
  74. package/lib/types/wire.js +71 -0
  75. package/lib/types/wire.js.map +1 -0
  76. package/package.json +147 -0
  77. package/src/backoff.ts +20 -0
  78. package/src/collector.ts +561 -0
  79. package/src/config.ts +604 -0
  80. package/src/ids.ts +68 -0
  81. package/src/index.ts +186 -0
  82. package/src/model.ts +100 -0
  83. package/src/pipeline.ts +205 -0
  84. package/src/pricing.ts +55 -0
  85. package/src/project.ts +55 -0
  86. package/src/remote.ts +56 -0
  87. package/src/sanitize.ts +132 -0
  88. package/src/sinks.ts +471 -0
  89. package/src/spool.ts +196 -0
  90. package/src/typert.host.ts +24 -0
  91. package/src/version.ts +10 -0
  92. package/src/wire.ts +97 -0
@@ -0,0 +1,132 @@
1
+ /**
2
+ * The pre-send sanitization layer. Every string or JSON value that could
3
+ * reach an observability backend passes through these pure functions before
4
+ * it is queued, batched, or spooled: key-name redaction and pattern
5
+ * redaction remove secrets and credentials, and per-surface character
6
+ * budgets truncate bodies. Sanitization is pure and deterministic so a
7
+ * replayed session log produces byte-identical exports.
8
+ * @module dsh-observe/sanitize
9
+ */
10
+
11
+ import type { ResolvedSanitize } from './config.ts'
12
+
13
+ /** The placeholder replacing any redacted value. */
14
+ export const REDACTED = '[REDACTED]'
15
+
16
+ /**
17
+ * Truncate text to a character budget, appending an ellipsis marker when
18
+ * content is cut. A budget of zero yields the empty string.
19
+ * @param text - the text to bound.
20
+ * @param budget - maximum character count (marker included).
21
+ * @returns the bounded text.
22
+ */
23
+ export function truncate(text: string, budget: number): string {
24
+ if (text.length <= budget) return text
25
+ if (budget <= 0) return ''
26
+ if (budget === 1) return '…'
27
+ return `${text.slice(0, budget - 1)}…`
28
+ }
29
+
30
+ /**
31
+ * Apply pattern redaction to one text value: every match of every
32
+ * configured pattern (built-in secret patterns plus the user patterns) is
33
+ * replaced with {@link REDACTED}.
34
+ * @param text - the text to scan.
35
+ * @param policy - the resolved sanitization policy.
36
+ * @returns the redacted text.
37
+ */
38
+ export function redactText(text: string, policy: ResolvedSanitize): string {
39
+ if (!policy.enabled) return text
40
+ let out = text
41
+ for (const pattern of policy.redactPatterns) {
42
+ out = out.replace(pattern, REDACTED)
43
+ }
44
+ return out
45
+ }
46
+
47
+ /**
48
+ * Split a key name into its words (snake_case, kebab-case, and camelCase
49
+ * boundaries) for structural key redaction.
50
+ * @param key - the raw key name.
51
+ * @returns lowercase word tokens.
52
+ */
53
+ export function tokenizeKey(key: string): string[] {
54
+ return key
55
+ .replace(/([a-z0-9])([A-Z])/gu, '$1 $2')
56
+ .split(/[^a-zA-Z0-9]+/u)
57
+ .map(token => token.toLowerCase())
58
+ .filter(token => token.length > 0)
59
+ }
60
+
61
+ /**
62
+ * Whether a structural key name is redacted under the policy: any word
63
+ * token matches one of the redaction key names.
64
+ * @param key - the raw key name.
65
+ * @param policy - the resolved sanitization policy.
66
+ * @returns true when the key's value must be replaced.
67
+ */
68
+ export function isRedactedKey(key: string, policy: ResolvedSanitize): boolean {
69
+ if (!policy.enabled) return false
70
+ const tokens = tokenizeKey(key)
71
+ const lowerKey = key.toLowerCase()
72
+ return tokens.some(token => policy.redactKeys.some(name => token === name || lowerKey.includes(name)))
73
+ }
74
+
75
+ /**
76
+ * Deep-clone an arbitrary JSON value while redacting: object keys matching
77
+ * the policy are replaced with {@link REDACTED} (their children are not
78
+ * walked), and every string value is pattern-scanned. Non-JSON exotic
79
+ * values (functions, symbols, class instances) normalize to `null` — the
80
+ * session log guarantees JSON inputs, so that branch exists only as
81
+ * containment for data crossing an untrusted boundary.
82
+ * @param value - the value to sanitize.
83
+ * @param policy - the resolved sanitization policy.
84
+ * @returns a JSON-safe sanitized clone.
85
+ */
86
+ export function sanitizeJson(value: unknown, policy: ResolvedSanitize): unknown {
87
+ if (typeof value === 'string') return redactText(value, policy)
88
+ if (typeof value === 'number' || typeof value === 'boolean' || value === null) return value
89
+ if (Array.isArray(value)) return value.map(item => sanitizeJson(item, policy))
90
+ if (typeof value === 'object') {
91
+ const out: Record<string, unknown> = {}
92
+ for (const [key, child] of Object.entries(value)) {
93
+ out[key] = isRedactedKey(key, policy) ? REDACTED : sanitizeJson(child, policy)
94
+ }
95
+ return out
96
+ }
97
+ return null
98
+ }
99
+
100
+ /**
101
+ * Sanitize and bound one text body: pattern redaction first, then the
102
+ * character budget.
103
+ * @param text - the text to sanitize.
104
+ * @param budget - character budget.
105
+ * @param policy - the resolved sanitization policy.
106
+ * @returns the sanitized, bounded text.
107
+ */
108
+ export function sanitizeText(text: string, budget: number, policy: ResolvedSanitize): string {
109
+ return truncate(redactText(text, policy), budget)
110
+ }
111
+
112
+ /**
113
+ * Sanitize a value that is either JSON text (parsed for structural key
114
+ * redaction, then re-serialized) or free-form text: a valid JSON parse gets
115
+ * the structural walk, anything else is pattern-scanned as text. Both paths
116
+ * end inside the character budget.
117
+ * @param value - the raw value (typically a tool arguments string).
118
+ * @param budget - character budget.
119
+ * @param policy - the resolved sanitization policy.
120
+ * @returns the sanitized value: re-serialized JSON when the input parsed,
121
+ * plain text otherwise.
122
+ */
123
+ export function sanitizeJsonText(value: string, budget: number, policy: ResolvedSanitize): string {
124
+ try {
125
+ const parsed: unknown = JSON.parse(value)
126
+ const cleaned = sanitizeJson(parsed, policy)
127
+ return truncate(JSON.stringify(cleaned), budget)
128
+ } catch {
129
+ // Not JSON: fall through to plain-text redaction.
130
+ return sanitizeText(value, budget, policy)
131
+ }
132
+ }
package/src/sinks.ts ADDED
@@ -0,0 +1,471 @@
1
+ /**
2
+ * Export sinks: the OTLP/HTTP backend (traces + metrics, JSON encoding)
3
+ * and the Langfuse ingestion backend. Sinks receive only owned, sanitized
4
+ * {@link ExportRecord}s and translate them to wire payloads; they own no
5
+ * harness state.
6
+ * @module dsh-observe/sinks
7
+ */
8
+
9
+ import type { Logger } from '@deepseek-ai/cordis'
10
+ import type { ResolvedLangfuse, ResolvedOtlp } from './config.ts'
11
+ import type { ExportRecord, JsonScalar, MetricRecord, SpanRecord, TokenCounts } from './model.ts'
12
+ import { langfuseId, langfuseTraceId, otelSpanId, otelTraceId } from './ids.ts'
13
+ import { VERSION } from './version.ts'
14
+
15
+ /** The observable logging surface consumed by sinks, pipelines, and the collector. */
16
+ export type ObserveLogger = Pick<Logger, 'info' | 'warn' | 'error'>
17
+
18
+ /** One span sink: consumes span records and delivers them to its backend. */
19
+ export interface SpanSink {
20
+ readonly name: 'otlp' | 'langfuse'
21
+ exportSpans(records: readonly ExportRecord[]): Promise<void>
22
+ }
23
+
24
+ /** POST a JSON body with a timeout; throws on non-2xx. */
25
+ async function postJson(
26
+ url: string,
27
+ headers: Record<string, string>,
28
+ body: unknown,
29
+ timeoutMs: number,
30
+ ): Promise<void> {
31
+ const response = await fetch(url, {
32
+ method: 'POST',
33
+ headers: { 'content-type': 'application/json', ...headers },
34
+ body: JSON.stringify(body),
35
+ signal: AbortSignal.timeout(timeoutMs),
36
+ })
37
+ if (!response.ok) {
38
+ throw new Error(`${url} responded ${response.status} ${response.statusText}`)
39
+ }
40
+ }
41
+
42
+ /** Encode one attribute value in OTLP/JSON form. */
43
+ function otlpValue(value: JsonScalar): Record<string, unknown> {
44
+ if (typeof value === 'string') return { stringValue: value }
45
+ if (typeof value === 'boolean') return { boolValue: value }
46
+ if (Number.isInteger(value)) return { intValue: String(value) }
47
+ return { doubleValue: value }
48
+ }
49
+
50
+ /** Encode one key/value pair as an OTLP/JSON attribute. */
51
+ function otlpAttribute(key: string, value: JsonScalar): Record<string, unknown> {
52
+ return { key, value: otlpValue(value) }
53
+ }
54
+
55
+ /** OTel span status code. */
56
+ const STATUS_CODE_OK = 1
57
+ const STATUS_CODE_ERROR = 2
58
+
59
+ /** OTel span kind: INTERNAL. */
60
+ const SPAN_KIND_INTERNAL = 1
61
+
62
+ /** Name of one span record, shared by both backends. */
63
+ function spanName(span: SpanRecord): string {
64
+ switch (span.kind) {
65
+ case 'turn': return `turn ${span.turn}`
66
+ case 'step': return `step ${span.turn}.${String(span.step)}`
67
+ case 'tool': return `tool ${span.tool?.name ?? 'unknown'}`
68
+ case 'llm': return 'llm.request'
69
+ }
70
+ }
71
+
72
+ /** OTel span id of one span record. */
73
+ function spanIdOf(span: SpanRecord): string {
74
+ switch (span.kind) {
75
+ case 'turn': return otelSpanId(span.sessionId, span.turn, 'turn')
76
+ case 'step': return otelSpanId(span.sessionId, span.turn, span.step ?? -1, 'step')
77
+ case 'tool': return otelSpanId(span.sessionId, span.turn, span.step ?? -1, span.callId ?? 'tool')
78
+ case 'llm': return otelSpanId(span.sessionId, span.turn, span.step ?? -1, 'llm')
79
+ }
80
+ }
81
+
82
+ /** Parent OTel span id of one span record (step/tool/llm parent under their step span). */
83
+ function parentSpanIdOf(span: SpanRecord): string | undefined {
84
+ if (span.kind === 'turn') return undefined
85
+ return otelSpanId(span.sessionId, span.turn, span.step ?? -1, 'step')
86
+ }
87
+
88
+ /** ISO-8601 timestamp of Unix nanoseconds (Langfuse wire format). */
89
+ function isoTimestamp(unixNano: number): string {
90
+ return new Date(Math.floor(unixNano / 1_000_000)).toISOString()
91
+ }
92
+
93
+ /** One span in OTLP/JSON wire form. */
94
+ function otlpSpan(span: SpanRecord): Record<string, unknown> {
95
+ const attributes = Object.entries(span.attributes).map(([key, value]) => otlpAttribute(key, value))
96
+ if (span.tool !== undefined) {
97
+ attributes.push(otlpAttribute('tool.name', span.tool.name))
98
+ attributes.push(otlpAttribute('tool.status', span.tool.status))
99
+ attributes.push(otlpAttribute('tool.attempt', span.tool.attempt))
100
+ attributes.push(otlpAttribute('tool.retries', span.tool.retries))
101
+ if (span.tool.input !== undefined) attributes.push(otlpAttribute('tool.input', span.tool.input))
102
+ if (span.tool.output !== undefined) attributes.push(otlpAttribute('tool.output', span.tool.output))
103
+ if (span.tool.errorName !== undefined) attributes.push(otlpAttribute('tool.error.name', span.tool.errorName))
104
+ if (span.tool.errorCode !== undefined) attributes.push(otlpAttribute('tool.error.code', span.tool.errorCode))
105
+ }
106
+ if (span.llm !== undefined) {
107
+ if (span.llm.model !== undefined) attributes.push(otlpAttribute('llm.model', span.llm.model))
108
+ if (span.llm.provider !== undefined) attributes.push(otlpAttribute('llm.provider', span.llm.provider))
109
+ if (span.llm.finishReason !== undefined) attributes.push(otlpAttribute('llm.finish_reason', span.llm.finishReason))
110
+ if (span.llm.ttftMs !== undefined) attributes.push(otlpAttribute('llm.ttft_ms', span.llm.ttftMs))
111
+ if (span.llm.costUsd !== undefined) attributes.push(otlpAttribute('llm.cost_usd', span.llm.costUsd))
112
+ for (const [key, value] of usageAttributes(span.llm.usage)) {
113
+ attributes.push(otlpAttribute(key, value))
114
+ }
115
+ }
116
+ const events = []
117
+ if (span.llm?.input !== undefined) {
118
+ events.push({ name: 'gen_ai.prompt', attributes: [otlpAttribute('gen_ai.prompt', span.llm.input)] })
119
+ }
120
+ if (span.llm?.output !== undefined) {
121
+ events.push({ name: 'gen_ai.completion', attributes: [otlpAttribute('gen_ai.completion', span.llm.output)] })
122
+ }
123
+ const error = span.status === 'error'
124
+ return {
125
+ traceId: otelTraceId(span.sessionId, span.turn),
126
+ spanId: spanIdOf(span),
127
+ ...(parentSpanIdOf(span) === undefined ? {} : { parentSpanId: parentSpanIdOf(span) }),
128
+ name: spanName(span),
129
+ kind: SPAN_KIND_INTERNAL,
130
+ startTimeUnixNano: String(span.startUnixNano),
131
+ endTimeUnixNano: String(span.endUnixNano),
132
+ attributes,
133
+ events,
134
+ status: { code: error ? STATUS_CODE_ERROR : STATUS_CODE_OK, message: error ? spanError(span) : '' },
135
+ }
136
+ }
137
+
138
+ /** Flatten usage counts to `usage.*` attributes. */
139
+ function usageAttributes(usage: TokenCounts | undefined): [string, number][] {
140
+ if (usage === undefined) return []
141
+ return [
142
+ ['usage.input_tokens', usage.input],
143
+ ['usage.output_tokens', usage.output],
144
+ ['usage.cache_read_tokens', usage.cacheRead],
145
+ ['usage.cache_write_tokens', usage.cacheWrite],
146
+ ['usage.reasoning_tokens', usage.reasoning],
147
+ ]
148
+ }
149
+
150
+ /** Error message for a failed span's status. */
151
+ function spanError(span: SpanRecord): string {
152
+ if (span.tool?.errorCode !== undefined) return `tool ${span.tool.name}: ${span.tool.errorCode}`
153
+ if (span.tool !== undefined) return `tool ${span.tool.name}: aborted`
154
+ return 'span closed with error status'
155
+ }
156
+
157
+ /** A stable key for one metric aggregation: JSON over name + sorted attributes. */
158
+ function metricKey(metric: MetricRecord): string {
159
+ const attributes = Object.fromEntries(Object.entries(metric.attributes).sort(([left], [right]) => left.localeCompare(right)))
160
+ return JSON.stringify({ name: metric.name, attributes })
161
+ }
162
+
163
+ /** Parse a metric aggregation key back into name + attributes. */
164
+ function parseMetricKey(key: string): { name: string; attributes: Record<string, string> } {
165
+ const parsed = JSON.parse(key) as { name: string; attributes: Record<string, string> }
166
+ return { name: parsed.name, attributes: parsed.attributes }
167
+ }
168
+
169
+ /** An OTLP/JSON metric attribute (string values only). */
170
+ function otlpMetricAttributes(attributes: Record<string, string>): Record<string, unknown>[] {
171
+ return Object.entries(attributes).map(([key, value]) => otlpAttribute(key, value))
172
+ }
173
+
174
+ /** OTel aggregation temporality: cumulative. */
175
+ const AGGREGATION_TEMPORALITY_CUMULATIVE = 2
176
+
177
+ /**
178
+ * The OTLP/HTTP backend. Spans POST to `{endpoint}/v1/traces`; metrics are
179
+ * aggregated here into cumulative counters (and last-write-wins gauges) and
180
+ * POSTed to `{endpoint}/v1/metrics` by a periodic flush. Cumulative
181
+ * counters make a lost metric flush self-healing — the next flush carries
182
+ * the totals — which is why metrics intentionally bypass the retry/spool
183
+ * pipeline that protects spans.
184
+ */
185
+ export class OtlpSink implements SpanSink {
186
+ readonly name = 'otlp' as const
187
+
188
+ private readonly counters = new Map<string, { startUnixNano: number; value: number }>()
189
+ private readonly gauges = new Map<string, number>()
190
+ private metricsDirty = false
191
+
192
+ /**
193
+ * @param config - the resolved OTLP backend config.
194
+ * @param logger - the plugin logger.
195
+ */
196
+ constructor(
197
+ private readonly config: ResolvedOtlp,
198
+ private readonly logger: ObserveLogger,
199
+ ) {}
200
+
201
+ /**
202
+ * Fold one metric sample into the aggregation state. Counters accumulate
203
+ * deltas from the first-seen timestamp; gauges replace per key.
204
+ * @param metric - the sample.
205
+ */
206
+ recordMetric(metric: MetricRecord): void {
207
+ if (metric.kind === 'counter') {
208
+ const key = metricKey(metric)
209
+ const entry = this.counters.get(key)
210
+ if (entry === undefined) {
211
+ this.counters.set(key, { startUnixNano: Date.now() * 1_000_000, value: metric.value })
212
+ } else {
213
+ entry.value += metric.value
214
+ }
215
+ } else {
216
+ this.gauges.set(metricKey(metric), metric.value)
217
+ }
218
+ this.metricsDirty = true
219
+ }
220
+
221
+ /**
222
+ * Send the aggregated metrics if anything changed since the last flush.
223
+ * A failed flush re-flags the state through the failure counter, so the
224
+ * next cycle retries with the cumulative totals.
225
+ * @returns resolution after the POST (or immediately when clean).
226
+ */
227
+ async flushMetrics(): Promise<void> {
228
+ if (!this.metricsDirty) return
229
+ this.metricsDirty = false
230
+ const timeUnixNano = Date.now() * 1_000_000
231
+ const metrics: Record<string, unknown>[] = []
232
+ for (const [key, entry] of this.counters) {
233
+ const { name, attributes } = parseMetricKey(key)
234
+ metrics.push({
235
+ name,
236
+ unit: unitOf(name),
237
+ sum: {
238
+ dataPoints: [{
239
+ attributes: otlpMetricAttributes(attributes),
240
+ startTimeUnixNano: String(entry.startUnixNano),
241
+ timeUnixNano: String(timeUnixNano),
242
+ ...(Number.isInteger(entry.value) ? { asInt: String(entry.value) } : { asDouble: entry.value }),
243
+ }],
244
+ aggregationTemporality: AGGREGATION_TEMPORALITY_CUMULATIVE,
245
+ isMonotonic: true,
246
+ },
247
+ })
248
+ }
249
+ for (const [key, value] of this.gauges) {
250
+ const { name, attributes } = parseMetricKey(key)
251
+ metrics.push({
252
+ name,
253
+ unit: unitOf(name),
254
+ gauge: {
255
+ dataPoints: [{
256
+ attributes: otlpMetricAttributes(attributes),
257
+ startTimeUnixNano: String(timeUnixNano),
258
+ timeUnixNano: String(timeUnixNano),
259
+ ...(Number.isInteger(value) ? { asInt: String(value) } : { asDouble: value }),
260
+ }],
261
+ },
262
+ })
263
+ }
264
+ try {
265
+ await postJson(
266
+ `${this.config.endpoint}/v1/metrics`,
267
+ this.config.headers,
268
+ { resourceMetrics: [{ resource: this.resource(), scopeMetrics: [{ scope: this.scope(), metrics }] }] },
269
+ this.config.timeoutMs,
270
+ )
271
+ } catch (error) {
272
+ this.logger.warn(`otlp: metrics flush failed: ${error instanceof Error ? error.message : String(error)}`)
273
+ this.recordMetric({
274
+ name: 'observe.export_failures',
275
+ kind: 'counter',
276
+ unit: 'requests',
277
+ value: 1,
278
+ attributes: { backend: 'otlp', kind: 'metrics' },
279
+ })
280
+ }
281
+ }
282
+
283
+ async exportSpans(records: readonly ExportRecord[]): Promise<void> {
284
+ const spans = records.flatMap(record => record.kind === 'span' ? [record.span] : [])
285
+ if (spans.length === 0) return
286
+ await postJson(
287
+ `${this.config.endpoint}/v1/traces`,
288
+ this.config.headers,
289
+ {
290
+ resourceSpans: [{
291
+ resource: this.resource(),
292
+ scopeSpans: [{ scope: this.scope(), spans: spans.map(otlpSpan) }],
293
+ }],
294
+ },
295
+ this.config.timeoutMs,
296
+ )
297
+ }
298
+
299
+ /** The OTel resource (service identity). */
300
+ private resource(): Record<string, unknown> {
301
+ const attributes = [
302
+ otlpAttribute('service.name', this.config.serviceName),
303
+ ...(this.config.serviceVersion === undefined
304
+ ? []
305
+ : [otlpAttribute('service.version', this.config.serviceVersion)]),
306
+ ]
307
+ return { attributes }
308
+ }
309
+
310
+ /** The instrumentation scope. */
311
+ private scope(): Record<string, unknown> {
312
+ return { name: 'dsh-observe', version: VERSION }
313
+ }
314
+ }
315
+
316
+ /** Parse a metric aggregation key back into name + attributes. */
317
+
318
+ /** Metric units. */
319
+ function unitOf(name: string): string {
320
+ if (name === 'observe.cost') return 'USD'
321
+ if (name === 'observe.export_failures' || name === 'observe.spool_flushed') return 'requests'
322
+ return 'records'
323
+ }
324
+
325
+ /** One Langfuse ingestion event. */
326
+ interface LangfuseEvent {
327
+ id: string
328
+ timestamp: string
329
+ type: string
330
+ body: Record<string, unknown>
331
+ }
332
+
333
+ /**
334
+ * The Langfuse backend. Each export batch is one ingestion POST; the trace
335
+ * each observation belongs to is created (once per trace id, remembered
336
+ * after a successful POST) inside the same batch, so a batch is always
337
+ * self-contained and retries stay idempotent — Langfuse upserts on event
338
+ * ids.
339
+ */
340
+ export class LangfuseSink implements SpanSink {
341
+ readonly name = 'langfuse' as const
342
+
343
+ private readonly seenTraces = new Set<string>()
344
+
345
+ /**
346
+ * @param config - the resolved Langfuse backend config.
347
+ * @param logger - the plugin logger.
348
+ */
349
+ constructor(
350
+ private readonly config: ResolvedLangfuse,
351
+ private readonly logger: ObserveLogger,
352
+ ) {}
353
+
354
+ async exportSpans(records: readonly ExportRecord[]): Promise<void> {
355
+ const spans = records.flatMap(record => record.kind === 'span' ? [record.span] : [])
356
+ if (spans.length === 0) return
357
+ const events: LangfuseEvent[] = []
358
+ const ensured: string[] = []
359
+ // One batch may carry several spans of the same trace: remember the
360
+ // in-batch creations too, so a single trace-create event rides each POST.
361
+ const ensuredInBatch = new Set<string>()
362
+ for (const span of spans) {
363
+ const traceId = langfuseTraceId(span.sessionId, span.turn)
364
+ if (!this.seenTraces.has(traceId) && !ensuredInBatch.has(traceId)) {
365
+ ensuredInBatch.add(traceId)
366
+ ensured.push(traceId)
367
+ events.push(this.traceEvent(traceId, span))
368
+ }
369
+ events.push(this.observationEvent(traceId, span))
370
+ }
371
+ try {
372
+ await this.post({ batch: events })
373
+ for (const traceId of ensured) this.seenTraces.add(traceId)
374
+ } catch (error) {
375
+ this.logger.warn(`langfuse: export failed: ${error instanceof Error ? error.message : String(error)}`)
376
+ throw error
377
+ }
378
+ }
379
+
380
+ /** The `trace-create` event for one turn span. */
381
+ private traceEvent(traceId: string, span: SpanRecord): LangfuseEvent {
382
+ const metadata: Record<string, unknown> = { ...span.attributes }
383
+ if (span.kind === 'turn') metadata['observe.span.kind'] = 'turn'
384
+ return {
385
+ id: langfuseId('trace-event', traceId),
386
+ timestamp: isoTimestamp(span.startUnixNano),
387
+ type: 'trace-create',
388
+ body: {
389
+ id: traceId,
390
+ name: `session ${span.sessionId} turn ${span.turn}`,
391
+ sessionId: span.sessionId,
392
+ timestamp: isoTimestamp(span.startUnixNano),
393
+ metadata,
394
+ ...(this.config.release === undefined ? {} : { release: this.config.release }),
395
+ },
396
+ }
397
+ }
398
+
399
+ /** The observation event for one span (span-create or generation-create). */
400
+ private observationEvent(traceId: string, span: SpanRecord): LangfuseEvent {
401
+ if (span.llm !== undefined) return this.generationEvent(traceId, span)
402
+ const id = span.kind === 'step'
403
+ ? langfuseId('step', span.sessionId, span.turn, span.step ?? -1)
404
+ : langfuseId('tool', span.sessionId, span.turn, span.step ?? -1, span.callId ?? span.tool?.name ?? 'tool')
405
+ return {
406
+ id: langfuseId('span-event', id),
407
+ timestamp: isoTimestamp(span.startUnixNano),
408
+ type: 'span-create',
409
+ body: {
410
+ id,
411
+ traceId,
412
+ name: spanName(span),
413
+ startTime: isoTimestamp(span.startUnixNano),
414
+ endTime: isoTimestamp(span.endUnixNano),
415
+ metadata: { ...span.attributes, ...(span.tool === undefined ? {} : { 'tool.status': span.tool.status }) },
416
+ ...(span.tool?.input === undefined ? {} : { input: span.tool.input }),
417
+ ...(span.tool?.output === undefined ? {} : { output: span.tool.output }),
418
+ level: span.status === 'error' ? 'ERROR' : 'DEFAULT',
419
+ },
420
+ }
421
+ }
422
+
423
+ /** The `generation-create` event for one LLM span. */
424
+ private generationEvent(traceId: string, span: SpanRecord): LangfuseEvent {
425
+ const id = langfuseId('generation', span.sessionId, span.turn, span.step ?? -1)
426
+ const usage = span.llm?.usage
427
+ return {
428
+ id: langfuseId('generation-event', id),
429
+ timestamp: isoTimestamp(span.startUnixNano),
430
+ type: 'generation-create',
431
+ body: {
432
+ id,
433
+ traceId,
434
+ name: 'llm.request',
435
+ startTime: isoTimestamp(span.startUnixNano),
436
+ endTime: isoTimestamp(span.endUnixNano),
437
+ ...(span.llm?.model === undefined ? {} : { model: span.llm.model }),
438
+ metadata: { ...span.attributes, ...(span.llm?.costUsd === undefined ? {} : { costUsd: span.llm.costUsd }) },
439
+ ...(span.llm?.input === undefined ? {} : { input: span.llm.input }),
440
+ ...(span.llm?.output === undefined ? {} : { output: span.llm.output }),
441
+ ...(usage === undefined ? {} : {
442
+ usage: { input: usage.input + usage.cacheRead + usage.cacheWrite, output: usage.output, total: usage.input + usage.cacheRead + usage.cacheWrite + usage.output, unit: 'TOKENS' },
443
+ }),
444
+ level: span.status === 'error' ? 'ERROR' : 'DEFAULT',
445
+ },
446
+ }
447
+ }
448
+
449
+ /** POST one ingestion batch with Basic auth. */
450
+ private async post(body: unknown): Promise<void> {
451
+ const authorization = Buffer.from(`${this.config.publicKey}:${this.config.secretKey}`, 'utf8').toString('base64')
452
+ const response = await fetch(`${this.config.baseUrl}/api/public/ingestion`, {
453
+ method: 'POST',
454
+ headers: {
455
+ 'content-type': 'application/json',
456
+ authorization: `Basic ${authorization}`,
457
+ },
458
+ body: JSON.stringify(body),
459
+ signal: AbortSignal.timeout(this.config.timeoutMs),
460
+ })
461
+ if (!response.ok) {
462
+ throw new Error(`langfuse ingestion responded ${response.status} ${response.statusText}`)
463
+ }
464
+ // 2xx with per-event errors still means some records failed: treat it as
465
+ // a retryable failure (Langfuse upserts by id, so retries are safe).
466
+ const result = await response.json() as { errors?: unknown[] }
467
+ if (Array.isArray(result.errors) && result.errors.length > 0) {
468
+ throw new Error(`langfuse ingestion reported ${result.errors.length} event error(s)`)
469
+ }
470
+ }
471
+ }