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