@handsforbots/semantic-event-observability 0.0.0-stage → 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 (55) hide show
  1. package/LICENSE.md +9 -0
  2. package/README.md +141 -2
  3. package/adapters/genericEventBus.js +20 -0
  4. package/adapters/instrumentChannel.js +22 -0
  5. package/core/CorrelationContext.js +49 -0
  6. package/core/EventBuffer.js +37 -0
  7. package/core/MetricsRegistry.js +200 -0
  8. package/core/PhaseTracker.js +143 -0
  9. package/core/Policy.js +87 -0
  10. package/core/SessionTracker.js +23 -0
  11. package/core/TraceContextBridge.js +74 -0
  12. package/core/TraceMapper.js +167 -0
  13. package/core/TurnMetricsCollector.js +19 -0
  14. package/core/TurnModel.js +87 -0
  15. package/core/baggage.d.ts +12 -0
  16. package/core/baggage.js +68 -0
  17. package/core/bucketEventName.js +11 -0
  18. package/core/createObservability.js +611 -0
  19. package/core/definePhaseModel.js +14 -0
  20. package/core/eventInstrumentation.js +21 -0
  21. package/core/isErrorEvent.js +9 -0
  22. package/core/telemetryAttributes.js +44 -0
  23. package/core/turnSpanNaming.js +73 -0
  24. package/docs/architecture.md +106 -0
  25. package/docs/custom-exporter.md +135 -0
  26. package/docs/exporters.md +180 -0
  27. package/docs/getting-started.md +192 -0
  28. package/docs/grafana-validation.md +71 -0
  29. package/docs/handsforbots-adapter.md +64 -0
  30. package/docs/handsforbots-roadmap.md +193 -0
  31. package/docs/metrics-roadmap.md +145 -0
  32. package/docs/publishing.md +55 -0
  33. package/docs/renaming.md +65 -0
  34. package/docs/roadmap.md +467 -0
  35. package/docs/tail-sampling.md +99 -0
  36. package/exporters/console.js +29 -0
  37. package/exporters/devPanel.js +204 -0
  38. package/exporters/faro.js +71 -0
  39. package/exporters/index.js +58 -0
  40. package/exporters/langfuse.js +161 -0
  41. package/exporters/langsmith.js +168 -0
  42. package/exporters/llmExporterState.js +84 -0
  43. package/exporters/memory.js +18 -0
  44. package/exporters/otel.js +236 -0
  45. package/exporters/otelTraceBackend.js +51 -0
  46. package/exporters/webVitals.js +73 -0
  47. package/grafana/semantic-event-observability.json +250 -0
  48. package/grafana/semantic-event-observability.lgtm.json +399 -0
  49. package/index.d.ts +312 -0
  50. package/index.js +31 -0
  51. package/package.json +80 -3
  52. package/packageIdentity.js +41 -0
  53. package/utils/id.js +10 -0
  54. package/utils/probeOptional.js +42 -0
  55. package/utils/safeJson.js +74 -0
package/core/Policy.js ADDED
@@ -0,0 +1,87 @@
1
+ import { summarizePayload, DEFAULT_DENYLIST } from '../utils/safeJson.js'
2
+
3
+ /**
4
+ * Sampling, redaction, and rate limiting for telemetry safety.
5
+ */
6
+ export default class Policy {
7
+ constructor(options = {}) {
8
+ this.enabled = options.enabled !== false
9
+ this.sampleRate = clampRate(options.sampleRate ?? 1)
10
+ this.maxEventsPerMinute = options.maxEventsPerMinute ?? 120
11
+ this.maxPayloadBytes = options.maxPayloadBytes ?? 2048
12
+ this.denylist = options.denylist || DEFAULT_DENYLIST
13
+ this.environment = options.environment || 'development'
14
+ this.onDrop = typeof options.onDrop === 'function' ? options.onDrop : null
15
+
16
+ this.windowStartedAt = Date.now()
17
+ this.eventsInWindow = 0
18
+ this.droppedTotal = 0
19
+ this.droppedByReason = {}
20
+ }
21
+
22
+ shouldEmit(eventType = 'bus.trigger') {
23
+ if (!this.enabled) {
24
+ this.recordDrop('disabled')
25
+ return false
26
+ }
27
+
28
+ if (!this.allowRate()) {
29
+ this.recordDrop('rate_limit')
30
+ return false
31
+ }
32
+
33
+ if (eventType.startsWith('turn.') || eventType.startsWith('phase.') || eventType.startsWith('session.') || eventType.startsWith('metric.')) {
34
+ return true
35
+ }
36
+
37
+ if (Math.random() > this.sampleRate) {
38
+ this.recordDrop('sampled_out')
39
+ return false
40
+ }
41
+
42
+ return true
43
+ }
44
+
45
+ allowRate() {
46
+ const now = Date.now()
47
+ if (now - this.windowStartedAt >= 60_000) {
48
+ this.windowStartedAt = now
49
+ this.eventsInWindow = 0
50
+ }
51
+
52
+ if (this.eventsInWindow >= this.maxEventsPerMinute) {
53
+ return false
54
+ }
55
+
56
+ this.eventsInWindow += 1
57
+ return true
58
+ }
59
+
60
+ sanitizePayload(payload) {
61
+ return summarizePayload(payload, {
62
+ denylist: this.denylist,
63
+ maxPayloadBytes: this.maxPayloadBytes,
64
+ })
65
+ }
66
+
67
+ recordDrop(reason) {
68
+ this.droppedTotal += 1
69
+ this.droppedByReason[reason] = (this.droppedByReason[reason] || 0) + 1
70
+ try { this.onDrop?.(reason) } catch { /* noop */ }
71
+ }
72
+
73
+ getStats() {
74
+ return {
75
+ droppedTotal: this.droppedTotal,
76
+ droppedByReason: { ...this.droppedByReason },
77
+ sampleRate: this.sampleRate,
78
+ maxEventsPerMinute: this.maxEventsPerMinute,
79
+ }
80
+ }
81
+ }
82
+
83
+ function clampRate(value) {
84
+ if (value <= 0) return 0
85
+ if (value >= 1) return 1
86
+ return value
87
+ }
@@ -0,0 +1,23 @@
1
+ /**
2
+ * Count turn outcomes within the current session for rollup metrics.
3
+ */
4
+ export function createSessionTracker() {
5
+ let completed = 0
6
+ let abandoned = 0
7
+
8
+ return {
9
+ recordTurn(status) {
10
+ if (status === 'completed') completed += 1
11
+ else if (status === 'abandoned') abandoned += 1
12
+ },
13
+
14
+ getCounts() {
15
+ return { completed, abandoned }
16
+ },
17
+
18
+ reset() {
19
+ completed = 0
20
+ abandoned = 0
21
+ },
22
+ }
23
+ }
@@ -0,0 +1,74 @@
1
+ import { mergeBaggage } from './baggage.js'
2
+
3
+ /**
4
+ * Propagate active turn trace context to fetch and other outbound calls.
5
+ */
6
+ export function createTraceContextBridge(options = {}) {
7
+ const getContext = options.getContext || (() => ({}))
8
+ const getBaggage = options.getBaggage || (() => null)
9
+ let injectHeaders = null
10
+
11
+ return {
12
+ setHeaderInjector(fn) {
13
+ injectHeaders = typeof fn === 'function' ? fn : null
14
+ },
15
+
16
+ getTraceHeaders() {
17
+ const headers = {}
18
+ const { traceId } = getContext()
19
+ if (traceId) headers['sevo-trace-id'] = traceId
20
+
21
+ if (injectHeaders) {
22
+ try {
23
+ const injected = injectHeaders()
24
+ if (injected && typeof injected === 'object') {
25
+ Object.assign(headers, injected)
26
+ }
27
+ } catch { /* noop */ }
28
+ }
29
+
30
+ const attributes = getBaggage()
31
+ if (attributes && Object.keys(attributes).length > 0) {
32
+ const existing = Object.keys(headers).find((key) => key.toLowerCase() === 'baggage')
33
+ const merged = mergeBaggage(existing ? headers[existing] : '', attributes)
34
+ if (existing) delete headers[existing]
35
+ if (merged) headers.baggage = merged
36
+ }
37
+
38
+ return headers
39
+ },
40
+
41
+ withTraceContext(input, init = {}) {
42
+ const headers = mergeHeaders(init.headers, this.getTraceHeaders())
43
+
44
+ if (typeof Request !== 'undefined' && input instanceof Request) {
45
+ return new Request(input, { ...init, headers })
46
+ }
47
+
48
+ return { ...init, headers }
49
+ },
50
+
51
+ withFetch(input, init = {}) {
52
+ const resolved = this.withTraceContext(input, init)
53
+ if (typeof resolved === 'object' && resolved.headers) {
54
+ return fetch(input, resolved)
55
+ }
56
+ return fetch(resolved)
57
+ },
58
+ }
59
+ }
60
+
61
+ function mergeHeaders(existing, injected) {
62
+ if (typeof Headers !== 'undefined' && existing instanceof Headers) {
63
+ const merged = new Headers(existing)
64
+ for (const [key, value] of Object.entries(injected)) {
65
+ merged.set(key, value)
66
+ }
67
+ return merged
68
+ }
69
+
70
+ return {
71
+ ...(existing && typeof existing === 'object' ? existing : {}),
72
+ ...injected,
73
+ }
74
+ }
@@ -0,0 +1,167 @@
1
+ import { isErrorEvent } from './isErrorEvent.js'
2
+ import { sevoAttributes } from './telemetryAttributes.js'
3
+ import { buildTurnRootSpan } from './turnSpanNaming.js'
4
+
5
+ /**
6
+ * Maps semantic events to a hierarchical span tree via an injected span backend.
7
+ * Backend-agnostic — OpenTelemetry adapter lives in exporters/otel.js.
8
+ */
9
+ export function createTraceMapper(options = {}) {
10
+ const isError = options.isError || isErrorEvent
11
+ const backend = options.backend
12
+ const onTurnContext = options.onTurnContext || null
13
+ const turnRootSpan = options.turnRootSpan
14
+ if (!backend) {
15
+ throw new Error('createTraceMapper requires a span backend')
16
+ }
17
+
18
+ /** @type {Map<string, TurnTraceState>} */
19
+ const turns = new Map()
20
+
21
+ return {
22
+ handleEvent(event) {
23
+ if (!event) return
24
+
25
+ switch (event.type) {
26
+ case 'turn.start':
27
+ startTurn(event)
28
+ break
29
+ case 'turn.end':
30
+ endTurn(event)
31
+ break
32
+ case 'phase.start':
33
+ startPhase(event)
34
+ break
35
+ case 'phase.end':
36
+ endPhase(event)
37
+ break
38
+ case 'bus.trigger':
39
+ if (event.turnId) recordBusEvent(event)
40
+ else recordOrphanEvent(event)
41
+ break
42
+ default:
43
+ break
44
+ }
45
+ },
46
+
47
+ destroy() {
48
+ for (const state of turns.values()) {
49
+ for (const phaseRef of state.phaseSpans.values()) {
50
+ try { backend.endSpan(phaseRef) } catch { /* noop */ }
51
+ }
52
+ try { backend.endSpan(state.rootSpan) } catch { /* noop */ }
53
+ }
54
+ turns.clear()
55
+ },
56
+ }
57
+
58
+ function startTurn(event) {
59
+ const root = buildTurnRootSpan(event, turnRootSpan)
60
+ const rootSpan = backend.startSpan(root.name, root.attributes, undefined, { kind: root.kind })
61
+ turns.set(event.turnId, {
62
+ rootSpan,
63
+ phaseSpans: new Map(),
64
+ lastPhaseEndedAt: null,
65
+ })
66
+ onTurnContext?.(event.turnId, backend.getPropagationContext?.(rootSpan))
67
+ }
68
+
69
+ function endTurn(event) {
70
+ const state = turns.get(event.turnId)
71
+ if (!state) return
72
+
73
+ for (const phaseRef of state.phaseSpans.values()) {
74
+ try { backend.endSpan(phaseRef) } catch { /* noop */ }
75
+ }
76
+ state.phaseSpans.clear()
77
+
78
+ if (event.durationMs != null) {
79
+ backend.setAttribute(state.rootSpan, 'turn.duration_ms', event.durationMs)
80
+ }
81
+
82
+ if (state.lastPhaseEndedAt != null) {
83
+ const renderMs = Math.max(0, Date.now() - state.lastPhaseEndedAt)
84
+ backend.setAttribute(state.rootSpan, 'phase.render_ms', renderMs)
85
+ }
86
+
87
+ backend.endSpan(state.rootSpan)
88
+ turns.delete(event.turnId)
89
+ onTurnContext?.(event.turnId, null)
90
+ }
91
+
92
+ function startPhase(event) {
93
+ const state = turns.get(event.turnId)
94
+ if (!state) return
95
+
96
+ const phaseSpan = backend.startSpan(
97
+ `phase:${event.phase}`,
98
+ {
99
+ ...sevoAttributes(event),
100
+ 'phase.name': event.phase,
101
+ 'phase.source': event.source,
102
+ },
103
+ state.rootSpan,
104
+ )
105
+ state.phaseSpans.set(event.phase, phaseSpan)
106
+ }
107
+
108
+ function endPhase(event) {
109
+ const state = turns.get(event.turnId)
110
+ if (!state) return
111
+
112
+ const phaseSpan = state.phaseSpans.get(event.phase)
113
+ if (!phaseSpan) return
114
+
115
+ if (event.durationMs != null) {
116
+ backend.setAttribute(state.rootSpan, `phase.${event.phase}_ms`, event.durationMs)
117
+ }
118
+
119
+ backend.endSpan(phaseSpan)
120
+ state.phaseSpans.delete(event.phase)
121
+ state.lastPhaseEndedAt = Date.now()
122
+ }
123
+
124
+ function recordBusEvent(event) {
125
+ const state = turns.get(event.turnId)
126
+ if (!state) {
127
+ recordOrphanEvent(event)
128
+ return
129
+ }
130
+
131
+ const eventSpan = backend.startSpan(
132
+ `event:${event.name}`,
133
+ {
134
+ ...sevoAttributes(event),
135
+ 'event.payload_preview': event.payloadSummary?.preview,
136
+ },
137
+ state.rootSpan,
138
+ )
139
+ backend.endSpan(eventSpan)
140
+ maybeMarkError(event, state.rootSpan)
141
+ }
142
+
143
+ function recordOrphanEvent(event) {
144
+ const eventSpan = backend.startSpan(
145
+ `event:${event.name}`,
146
+ {
147
+ ...sevoAttributes(event),
148
+ 'event.payload_preview': event.payloadSummary?.preview,
149
+ },
150
+ )
151
+ backend.endSpan(eventSpan)
152
+ }
153
+
154
+ function maybeMarkError(event, rootSpan) {
155
+ if (!isError(event)) return
156
+ backend.setError(rootSpan, event.name)
157
+ backend.setAttribute(rootSpan, 'turn.error_event', event.name)
158
+ backend.setAttribute(rootSpan, 'error.type', event.name)
159
+ }
160
+ }
161
+
162
+ /**
163
+ * @typedef {object} TurnTraceState
164
+ * @property {*} rootSpan
165
+ * @property {Map<string, *>} phaseSpans
166
+ * @property {number | null} lastPhaseEndedAt
167
+ */
@@ -0,0 +1,19 @@
1
+ import { createPhaseTracker } from './PhaseTracker.js'
2
+
3
+ /**
4
+ * @deprecated Use createPhaseTracker — kept for backwards compatibility.
5
+ */
6
+ export function createTurnMetricsCollector(options = {}) {
7
+ return createPhaseTracker({
8
+ phases: options.phases,
9
+ isError: options.isError,
10
+ onPhaseStart: () => {},
11
+ onPhaseEnd: ({ phase, durationMs, labels }) => {
12
+ options.onPhaseDuration?.(phase, durationMs, labels)
13
+ },
14
+ onRenderDuration: options.onRenderDuration,
15
+ onTurnStatus: options.onTurnStatus,
16
+ })
17
+ }
18
+
19
+ export { createPhaseTracker }
@@ -0,0 +1,87 @@
1
+ import { createId } from '../utils/id.js'
2
+
3
+ /**
4
+ * Normalize turn boundary configuration.
5
+ */
6
+ export function defineTurnModel(model = {}) {
7
+ const start = model.startEvents || model.start || []
8
+ const end = model.endEvents || model.end || []
9
+ return {
10
+ startEvents: [...new Set(start.map(String))],
11
+ endEvents: [...new Set(end.map(String))],
12
+ }
13
+ }
14
+
15
+ /**
16
+ * Turn boundary detection with abandonment support.
17
+ */
18
+ export default class TurnModel {
19
+ constructor(model = {}) {
20
+ const normalized = defineTurnModel(model)
21
+ this.startEvents = new Set(normalized.startEvents)
22
+ this.endEvents = new Set(normalized.endEvents)
23
+ this.currentTurnId = null
24
+ this.currentTraceId = null
25
+ this.turnStartedAt = null
26
+ this.completedTurns = 0
27
+ }
28
+
29
+ observeBusEvent(eventName) {
30
+ if (this.startEvents.has(eventName)) {
31
+ let abandoned = null
32
+ if (this.currentTurnId) {
33
+ abandoned = {
34
+ type: 'turn.abandoned',
35
+ turnId: this.currentTurnId,
36
+ traceId: this.currentTraceId,
37
+ }
38
+ }
39
+
40
+ this.currentTurnId = createId('turn')
41
+ this.currentTraceId = createId('trace')
42
+ this.turnStartedAt = Date.now()
43
+
44
+ const started = {
45
+ type: 'turn.start',
46
+ turnId: this.currentTurnId,
47
+ traceId: this.currentTraceId,
48
+ }
49
+
50
+ return abandoned ? { abandoned, started } : started
51
+ }
52
+
53
+ if (this.endEvents.has(eventName) && this.currentTurnId) {
54
+ const turnId = this.currentTurnId
55
+ const traceId = this.currentTraceId
56
+ const durationMs = this.turnStartedAt ? Date.now() - this.turnStartedAt : null
57
+ this.completedTurns += 1
58
+ this.currentTurnId = null
59
+ this.currentTraceId = null
60
+ this.turnStartedAt = null
61
+ return {
62
+ type: 'turn.end',
63
+ turnId,
64
+ traceId,
65
+ durationMs,
66
+ }
67
+ }
68
+
69
+ return null
70
+ }
71
+
72
+ getContext() {
73
+ return {
74
+ turnId: this.currentTurnId,
75
+ traceId: this.currentTraceId,
76
+ }
77
+ }
78
+
79
+ getActiveTurnAge() {
80
+ if (!this.turnStartedAt) return null
81
+ return Math.max(0, Date.now() - this.turnStartedAt)
82
+ }
83
+
84
+ getCompletedTurns() {
85
+ return this.completedTurns
86
+ }
87
+ }
@@ -0,0 +1,12 @@
1
+ export type BaggageValue = string | number | boolean
2
+
3
+ export const BAGGAGE_MAX_MEMBERS: 64
4
+ export const BAGGAGE_MAX_BYTES: 8192
5
+ /** Encodes attributes as a W3C baggage header value. */
6
+ export function encodeBaggage(attributes?: Readonly<Record<string, BaggageValue | null | undefined>>): string
7
+ /** Parses a W3C baggage header (string, Headers or headers object) into decoded strings. */
8
+ export function parseBaggage(
9
+ source: string | { get(name: string): string | null } | Record<string, string | string[] | undefined> | null | undefined,
10
+ ): Record<string, string>
11
+ /** Adds attributes to a baggage header value; the attributes win on the same key. */
12
+ export function mergeBaggage(existing: string | null | undefined, attributes?: Readonly<Record<string, BaggageValue>>): string
@@ -0,0 +1,68 @@
1
+ /**
2
+ * W3C Baggage (https://www.w3.org/TR/baggage/): `key=value` members separated
3
+ * by commas, values percent-encoded. Used to send conversation attributes to
4
+ * the backend next to `traceparent`.
5
+ */
6
+
7
+ /** Limits from the spec: 64 members and 8192 bytes per header. */
8
+ export const BAGGAGE_MAX_MEMBERS = 64
9
+ export const BAGGAGE_MAX_BYTES = 8192
10
+
11
+ const TOKEN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/
12
+
13
+ /** Encodes attributes as a baggage header value. Keys that are not tokens and `null` / `undefined` values are skipped. */
14
+ export function encodeBaggage(attributes = {}) {
15
+ const members = []
16
+ for (const [key, value] of Object.entries(attributes || {})) {
17
+ if (value == null || !TOKEN.test(key)) continue
18
+ members.push(`${key}=${encodeURIComponent(String(value))}`)
19
+ }
20
+ return members.join(',')
21
+ }
22
+
23
+ /**
24
+ * Parses a baggage header into `{ key: value }` (strings, decoded). Properties
25
+ * after `;` are ignored, as are malformed members. Accepts a string, a
26
+ * `Headers`, or a plain headers object (any case of `baggage`).
27
+ */
28
+ export function parseBaggage(source) {
29
+ const header = baggageHeader(source)
30
+ const result = {}
31
+ if (!header) return result
32
+ if (header.length > BAGGAGE_MAX_BYTES) return result
33
+ let count = 0
34
+ for (const raw of header.split(',')) {
35
+ if (++count > BAGGAGE_MAX_MEMBERS) break
36
+ const member = raw.split(';')[0].trim()
37
+ const eq = member.indexOf('=')
38
+ if (eq <= 0) continue
39
+ const key = member.slice(0, eq).trim()
40
+ if (!TOKEN.test(key)) continue
41
+ try {
42
+ result[key] = decodeURIComponent(member.slice(eq + 1).trim())
43
+ } catch { /* malformed percent-encoding */ }
44
+ }
45
+ return result
46
+ }
47
+
48
+ /** Adds `attributes` to an existing baggage header value; ours win on the same key. */
49
+ export function mergeBaggage(existing, attributes = {}) {
50
+ const ours = encodeBaggage(attributes)
51
+ if (!existing) return ours
52
+ const keys = new Set(ours ? ours.split(',').map((member) => member.split('=')[0]) : [])
53
+ const kept = String(existing)
54
+ .split(',')
55
+ .map((member) => member.trim())
56
+ .filter((member) => member && !keys.has(member.split(/[=;]/)[0].trim()))
57
+ return [...kept, ...(ours ? [ours] : [])].join(',')
58
+ }
59
+
60
+ function baggageHeader(source) {
61
+ if (!source) return ''
62
+ if (typeof source === 'string') return source
63
+ if (typeof source.get === 'function') return source.get('baggage') || ''
64
+ for (const [key, value] of Object.entries(source)) {
65
+ if (key.toLowerCase() === 'baggage') return Array.isArray(value) ? value.join(',') : String(value ?? '')
66
+ }
67
+ return ''
68
+ }
@@ -0,0 +1,11 @@
1
+ /**
2
+ * Reduce bus event name cardinality for metric labels.
3
+ */
4
+ export function bucketEventName(name) {
5
+ const normalized = String(name || 'unknown')
6
+ .replace(/\d{5,}/g, '*')
7
+ .replace(/[a-f0-9]{16,}/gi, '*')
8
+
9
+ if (normalized.length <= 64) return normalized
10
+ return `${normalized.slice(0, 61)}...`
11
+ }