@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
@@ -0,0 +1,611 @@
1
+ import { getPackageIdentity } from '../packageIdentity.js'
2
+ import CorrelationContext from './CorrelationContext.js'
3
+ import Policy from './Policy.js'
4
+ import EventBuffer from './EventBuffer.js'
5
+ import { createMetricsRegistry } from './MetricsRegistry.js'
6
+ import { createPhaseTracker } from './PhaseTracker.js'
7
+ import { definePhaseModel } from './definePhaseModel.js'
8
+ import { defineTurnModel } from './TurnModel.js'
9
+ import { createTraceContextBridge } from './TraceContextBridge.js'
10
+ import { createEventInstrumentation } from './eventInstrumentation.js'
11
+ import { createSessionTracker } from './SessionTracker.js'
12
+ import { isErrorEvent } from './isErrorEvent.js'
13
+ import { bucketEventName } from './bucketEventName.js'
14
+ import { createExporters, initExporters } from '../exporters/index.js'
15
+ import { createId } from '../utils/id.js'
16
+
17
+ const DEFAULT_EXPORTERS = ['memory']
18
+
19
+ /**
20
+ * Create a semantic observability instance for async event systems.
21
+ */
22
+ export function createObservability(options = {}) {
23
+ const identity = getPackageIdentity(options.identity)
24
+ const environment = options.environment || 'development'
25
+ const phases = definePhaseModel(options.phases || [])
26
+ const isError = options.isError || isErrorEvent
27
+ const eventInstrumentation = createEventInstrumentation({
28
+ eventFilter: options.eventFilter,
29
+ eventAllowlist: options.eventAllowlist,
30
+ })
31
+ const metricsRegistry = createMetricsRegistry({ environment })
32
+
33
+ const policy = new Policy({
34
+ enabled: options.enabled !== false,
35
+ sampleRate: options.sampleRate,
36
+ maxEventsPerMinute: options.maxEventsPerMinute,
37
+ maxPayloadBytes: options.maxPayloadBytes,
38
+ denylist: options.denylist,
39
+ environment,
40
+ onDrop: (reason) => metricsRegistry.recordEventDropped(reason),
41
+ })
42
+
43
+ const correlation = new CorrelationContext({
44
+ sessionId: options.sessionId,
45
+ turnModel: options.turn || defineTurnModel({
46
+ startEvents: options.turnStartEvents,
47
+ endEvents: options.turnEndEvents,
48
+ }),
49
+ turnStartEvents: options.turnStartEvents || [],
50
+ turnEndEvents: options.turnEndEvents || [],
51
+ })
52
+
53
+ const traceContextBridge = createTraceContextBridge({
54
+ getContext: () => correlation.getContext(),
55
+ getBaggage: () => (policy.enabled ? api.attributes : null),
56
+ })
57
+
58
+ const sessionEndEvents = new Set((options.sessionEndEvents || []).map(String))
59
+ const customMetricAllowlist = options.customMetricAllowlist
60
+ ? new Set(options.customMetricAllowlist.map(String))
61
+ : null
62
+ const sessionTracker = createSessionTracker()
63
+ const turnRootSpan = options.turnRootSpan
64
+
65
+ const buffer = new EventBuffer(options.bufferSize || 200)
66
+ let exporters = []
67
+ let exporterStatus = []
68
+ let stateProvider = null
69
+ let initialized = false
70
+ let initPromise = null
71
+
72
+ const api = {
73
+ identity,
74
+ policy,
75
+ correlation,
76
+ buffer,
77
+ metricsRegistry,
78
+ phases,
79
+ isError,
80
+ eventInstrumentation,
81
+ traceContextBridge,
82
+ sessionTracker,
83
+ sessionEndEvents,
84
+ exporters: [],
85
+ /** Attributes on every event and span, sent as `baggage` (see setAttributes). */
86
+ attributes: Object.freeze({}),
87
+ }
88
+
89
+ const phaseTracker = createPhaseTracker({
90
+ phases,
91
+ isError,
92
+ onPhaseStart: (data) => {
93
+ emitEvent(api, buildPhaseEvent(api, 'phase.start', data))
94
+ },
95
+ onPhaseWait: (data) => {
96
+ metricsRegistry.recordPhaseWait(data.phase, data.waitMs, data.labels)
97
+ },
98
+ onPhaseEnd: (data) => {
99
+ metricsRegistry.recordPhaseDuration(data.phase, data.durationMs, data.labels)
100
+ const event = buildPhaseEvent(api, 'phase.end', data)
101
+ emitEvent(api, event)
102
+ dispatchPhaseEnd(api, event)
103
+ },
104
+ onRenderDuration: (durationMs, labels) => {
105
+ metricsRegistry.recordPhaseDuration('render', durationMs, labels)
106
+ const ctx = correlation.getContext()
107
+ if (!ctx.turnId) return
108
+ const event = buildPhaseEvent(api, 'phase.end', {
109
+ turnId: ctx.turnId,
110
+ phase: 'render',
111
+ durationMs,
112
+ source: 'computed',
113
+ labels,
114
+ })
115
+ emitEvent(api, event)
116
+ dispatchPhaseEnd(api, event)
117
+ },
118
+ onTurnStatus: (status, labels) => {
119
+ metricsRegistry.recordTurnStatus(status, labels)
120
+ },
121
+ })
122
+
123
+ api.phaseTracker = phaseTracker
124
+ api.traceContext = traceContextBridge
125
+ api.sessionTracker = sessionTracker
126
+
127
+ metricsRegistry.subscribe((metric) => {
128
+ buffer.pushMetric(metric)
129
+ for (const exporter of exporters) {
130
+ dispatchMetric(exporter, metric, metricsRegistry)
131
+ }
132
+ })
133
+
134
+ Object.assign(api, {
135
+ async init() {
136
+ if (initialized) return exporterStatus
137
+ if (initPromise) return initPromise
138
+
139
+ initPromise = (async () => {
140
+ const requested = options.exporters || DEFAULT_EXPORTERS
141
+ exporters = await createExporters(requested, options.exporterConfig || {})
142
+ if (Array.isArray(options.customExporters)) {
143
+ exporters.push(...options.customExporters)
144
+ }
145
+ api.exporters = exporters
146
+ exporterStatus = await initExporters(exporters, createContext())
147
+ initialized = true
148
+ publishGlobal(api, identity)
149
+ return exporterStatus
150
+ })()
151
+
152
+ return initPromise
153
+ },
154
+
155
+ instrument(bus, instrumentOptions = {}) {
156
+ stateProvider = instrumentOptions.stateProvider || null
157
+ api.stateProvider = stateProvider
158
+
159
+ if (!bus || typeof bus.trigger !== 'function' || typeof bus.on !== 'function') {
160
+ throw new Error('instrument() expects an event bus with on() and trigger()')
161
+ }
162
+
163
+ const originalTrigger = bus.trigger.bind(bus)
164
+ bus.trigger = function instrumentedTrigger(name, args) {
165
+ recordBusEvent(api, name, args, 'bus.trigger')
166
+ return originalTrigger(name, args)
167
+ }
168
+
169
+ if (instrumentOptions.wrapListeners === true) {
170
+ const originalOn = bus.on.bind(bus)
171
+ bus.on = function instrumentedOn(names, callback) {
172
+ const wrapped = function wrappedCallback(...listenerArgs) {
173
+ const started = Date.now()
174
+ try {
175
+ recordBusEvent(api, names, listenerArgs, 'bus.listener')
176
+ return callback.apply(this, listenerArgs)
177
+ } finally {
178
+ api.metricsRegistry.recordListenerDuration(Date.now() - started, {
179
+ event: bucketEventName(normalizeEventName(names)),
180
+ })
181
+ }
182
+ }
183
+ return originalOn(names, wrapped)
184
+ }
185
+ }
186
+
187
+ return bus
188
+ },
189
+
190
+ record(name, payload = {}, meta = {}) {
191
+ emit(api, {
192
+ type: meta.type || 'custom',
193
+ name,
194
+ payload,
195
+ })
196
+ },
197
+
198
+ recordMetric(name, value, labels = {}) {
199
+ if (!policy.shouldEmit('metric.gauge')) return
200
+
201
+ const metric = {
202
+ name,
203
+ value,
204
+ labels: { environment, ...labels },
205
+ type: 'gauge',
206
+ timestamp: new Date().toISOString(),
207
+ sessionId: correlation.sessionId,
208
+ }
209
+
210
+ buffer.pushMetric(metric)
211
+ for (const exporter of api.exporters) {
212
+ dispatchMetric(exporter, metric, metricsRegistry)
213
+ }
214
+
215
+ if (customMetricAllowlist?.has(String(name))) {
216
+ metricsRegistry.recordCustomMetric(String(name), labels)
217
+ }
218
+ },
219
+
220
+ /**
221
+ * Replaces the attributes that go on every event and span and, as W3C
222
+ * `baggage`, in getTraceHeaders(). Values: strings, numbers, booleans.
223
+ */
224
+ setAttributes(attributes = {}) {
225
+ const next = {}
226
+ for (const [key, value] of Object.entries(attributes || {})) {
227
+ if (typeof value === 'string' || typeof value === 'boolean' || (typeof value === 'number' && Number.isFinite(value))) {
228
+ next[key] = value
229
+ }
230
+ }
231
+ api.attributes = Object.freeze(next)
232
+ },
233
+
234
+ getAttributes() {
235
+ return api.attributes
236
+ },
237
+
238
+ /**
239
+ * Adds to a counter (an OpenTelemetry Counter in the otel exporter, created
240
+ * on first use). Counters are never sampled nor rate-limited: use them for
241
+ * totals that must add up (exposures, conversions). Labels are kept as given.
242
+ */
243
+ recordCounter(name, value = 1, labels = {}) {
244
+ if (!policy.enabled) return
245
+ const metric = {
246
+ name: String(name),
247
+ value,
248
+ labels: { environment, ...labels },
249
+ type: 'counter',
250
+ custom: true,
251
+ timestamp: new Date().toISOString(),
252
+ sessionId: correlation.sessionId,
253
+ }
254
+ buffer.pushMetric(metric)
255
+ for (const exporter of api.exporters) {
256
+ dispatchMetric(exporter, metric, metricsRegistry)
257
+ }
258
+ },
259
+
260
+ startPhase(phaseId, labels = {}) {
261
+ const { turnId } = correlation.getContext()
262
+ if (!turnId) return false
263
+ return phaseTracker.startPhase(turnId, phaseId, {
264
+ environment,
265
+ ...labels,
266
+ })
267
+ },
268
+
269
+ endPhase(phaseId, labels = {}) {
270
+ const { turnId } = correlation.getContext()
271
+ if (!turnId) return false
272
+ return phaseTracker.endPhase(turnId, phaseId, {
273
+ environment,
274
+ ...labels,
275
+ })
276
+ },
277
+
278
+ getTraceHeaders() {
279
+ return traceContextBridge.getTraceHeaders()
280
+ },
281
+
282
+ withTraceContext(input, init = {}) {
283
+ return traceContextBridge.withTraceContext(input, init)
284
+ },
285
+
286
+ withFetch(input, init = {}) {
287
+ return traceContextBridge.withFetch(input, init)
288
+ },
289
+
290
+ async registerExporter(exporter) {
291
+ if (!exporter?.id) {
292
+ throw new Error('registerExporter expects an exporter with id')
293
+ }
294
+
295
+ exporters.push(exporter)
296
+ api.exporters = exporters
297
+
298
+ try {
299
+ await exporter.init?.(createContext())
300
+ const status = {
301
+ id: exporter.id,
302
+ available: exporter.available !== false,
303
+ description: exporter.description,
304
+ }
305
+ exporterStatus.push(status)
306
+ return status
307
+ } catch (error) {
308
+ const status = {
309
+ id: exporter.id,
310
+ available: false,
311
+ error: error?.message || String(error),
312
+ }
313
+ exporterStatus.push(status)
314
+ return status
315
+ }
316
+ },
317
+
318
+ endSession(reason = 'manual') {
319
+ return finalizeSession(api, sessionTracker, reason)
320
+ },
321
+
322
+ getTimeline(limit) {
323
+ return buffer.getTimeline(limit)
324
+ },
325
+
326
+ getMetrics(limit) {
327
+ return buffer.getMetrics(limit)
328
+ },
329
+
330
+ getPolicyStats() {
331
+ return policy.getStats()
332
+ },
333
+
334
+ getExporterStatus() {
335
+ return exporterStatus
336
+ },
337
+
338
+ destroy() {
339
+ for (const exporter of api.exporters) {
340
+ try { exporter.destroy?.() } catch { /* noop */ }
341
+ }
342
+ exporters = []
343
+ api.exporters = []
344
+ phaseTracker.clear()
345
+ buffer.clear()
346
+ removeGlobal(identity)
347
+ },
348
+ })
349
+
350
+ function createContext() {
351
+ return {
352
+ identity,
353
+ buffer,
354
+ phases,
355
+ metricsRegistry,
356
+ isError,
357
+ traceContextBridge,
358
+ turnRootSpan,
359
+ getTimeline: api.getTimeline,
360
+ getMetrics: api.getMetrics,
361
+ getPolicyStats: api.getPolicyStats,
362
+ }
363
+ }
364
+
365
+ api.init().catch(() => {})
366
+
367
+ return api
368
+ }
369
+
370
+ function buildPhaseEvent(api, type, data) {
371
+ const ctx = api.correlation.getContext()
372
+ return {
373
+ type,
374
+ name: `phase:${data.phase}`,
375
+ phase: data.phase,
376
+ source: data.source,
377
+ durationMs: data.durationMs,
378
+ sessionId: ctx.sessionId,
379
+ turnId: data.turnId || ctx.turnId,
380
+ traceId: ctx.traceId,
381
+ turnMetadata: ctx.turnMetadata,
382
+ }
383
+ }
384
+
385
+ function recordBusEvent(api, name, args, type) {
386
+ const eventName = normalizeEventName(name)
387
+ const payload = Array.isArray(args) ? args[0] : args
388
+
389
+ if (type === 'bus.trigger') {
390
+ api.metricsRegistry.recordBusEvent(bucketEventName(eventName))
391
+ }
392
+
393
+ emit(api, { type, name: eventName, payload })
394
+ }
395
+
396
+ function emit(api, partial) {
397
+ const { correlation } = api
398
+
399
+ if (partial.type !== 'bus.trigger') {
400
+ emitEvent(api, { ...partial, ...correlation.getContext() })
401
+ return
402
+ }
403
+
404
+ const snapshotBefore = correlation.getContext()
405
+ const correlationChange = correlation.observeBusEvent(partial.name)
406
+
407
+ if (api.sessionEndEvents?.has(partial.name)) {
408
+ finalizeSession(api, api.sessionTracker, partial.name)
409
+ }
410
+
411
+ if (correlationChange?.abandoned) {
412
+ handleTurnAbandoned(api, correlationChange.abandoned)
413
+ handleTurnStart(api, partial, correlationChange.started)
414
+ if (api.eventInstrumentation.shouldRecord(partial.name)) {
415
+ emitEvent(api, { ...partial, ...correlation.getContext() })
416
+ }
417
+ return
418
+ }
419
+
420
+ if (correlationChange?.type === 'turn.start') {
421
+ handleTurnStart(api, partial, correlationChange)
422
+ if (api.eventInstrumentation.shouldRecord(partial.name)) {
423
+ emitEvent(api, { ...partial, ...correlation.getContext() })
424
+ }
425
+ return
426
+ }
427
+
428
+ if (correlationChange?.type === 'turn.end') {
429
+ if (api.eventInstrumentation.shouldRecord(partial.name)) {
430
+ emitEvent(api, { ...partial, ...snapshotBefore })
431
+ }
432
+ handleTurnEnd(api, partial, snapshotBefore, correlationChange.durationMs)
433
+ return
434
+ }
435
+
436
+ if (!api.eventInstrumentation.shouldRecord(partial.name)) {
437
+ return
438
+ }
439
+
440
+ emitEvent(api, { ...partial, ...correlation.getContext() })
441
+ }
442
+
443
+ function finalizeSession(api, sessionTracker, reason) {
444
+ const counts = sessionTracker.getCounts()
445
+ const endedSessionId = api.correlation.sessionId
446
+
447
+ api.metricsRegistry.recordSessionTurnsRollup(counts, {
448
+ reason: reason || 'manual',
449
+ })
450
+ sessionTracker.reset()
451
+ api.correlation.startSession()
452
+
453
+ emitEvent(api, {
454
+ type: 'session.end',
455
+ name: String(reason || 'session.end'),
456
+ sessionId: endedSessionId,
457
+ payloadSummary: { completed: counts.completed, abandoned: counts.abandoned },
458
+ })
459
+
460
+ return counts
461
+ }
462
+
463
+ function handleTurnAbandoned(api, abandoned) {
464
+ const labels = metricLabels(api, abandoned)
465
+ api.metricsRegistry.recordTurnStatus('abandoned', labels)
466
+ api.sessionTracker?.recordTurn('abandoned')
467
+ api.phaseTracker.onTurnAbandoned(abandoned)
468
+ emitEvent(api, {
469
+ type: 'turn.abandoned',
470
+ name: 'turn.abandoned',
471
+ ...abandoned,
472
+ sessionId: api.correlation.sessionId,
473
+ })
474
+ }
475
+
476
+ function handleTurnStart(api, partial, started) {
477
+ const plugin = extractPluginFromPayload(partial.payload)
478
+ if (plugin) api.correlation.setTurnMetadata({ input_plugin: plugin })
479
+
480
+ api.metricsRegistry.recordActiveTurns(1)
481
+ api.phaseTracker.onTurnStart({ ...started, name: partial.name })
482
+ emitEvent(api, {
483
+ type: 'turn.start',
484
+ name: partial.name,
485
+ ...started,
486
+ sessionId: api.correlation.sessionId,
487
+ })
488
+ }
489
+
490
+ function handleTurnEnd(api, partial, snapshot, durationMs) {
491
+ const labels = metricLabels(api, {
492
+ ...snapshot,
493
+ name: partial.name,
494
+ turnMetadata: snapshot.turnMetadata,
495
+ })
496
+ api.metricsRegistry.recordTurnDuration(durationMs, labels)
497
+ api.metricsRegistry.recordActiveTurns(0)
498
+ api.sessionTracker?.recordTurn('completed')
499
+ api.phaseTracker.onTurnEnd({ ...snapshot, name: partial.name, durationMs }, labels)
500
+ emitEvent(api, {
501
+ type: 'turn.end',
502
+ name: partial.name,
503
+ ...snapshot,
504
+ durationMs,
505
+ })
506
+ }
507
+
508
+ function emitEvent(api, partial) {
509
+ const { policy, buffer } = api
510
+ if (!policy.shouldEmit(partial.type)) return
511
+
512
+ const labels = metricLabels(api, partial)
513
+ const event = {
514
+ id: createId('evt'),
515
+ timestamp: new Date().toISOString(),
516
+ environment: policy.environment,
517
+ payloadSummary: policy.sanitizePayload(partial.payload),
518
+ state: api.stateProvider?.() || undefined,
519
+ ...(Object.keys(api.attributes).length > 0 ? { attributes: api.attributes } : {}),
520
+ ...partial,
521
+ }
522
+
523
+ buffer.push(event)
524
+ recordStateMetrics(api, event.state)
525
+ api.metricsRegistry.recordEventEmitted(event.type)
526
+
527
+ if (event.type === 'bus.trigger' && event.turnId) {
528
+ api.phaseTracker.onBusEvent(event, labels)
529
+ }
530
+
531
+ for (const exporter of api.exporters) {
532
+ dispatchEvent(exporter, event, api.metricsRegistry)
533
+ }
534
+ }
535
+
536
+ function recordStateMetrics(api, state) {
537
+ if (!state || typeof state !== 'object') return
538
+ for (const [key, value] of Object.entries(state)) {
539
+ if (typeof value === 'number' && !Number.isNaN(value)) {
540
+ api.metricsRegistry.recordStateGauge(key, value)
541
+ }
542
+ }
543
+ }
544
+
545
+ function metricLabels(api, event) {
546
+ const labels = { environment: api.policy.environment }
547
+ if (event?.name) labels.start_event = event.name
548
+ if (event?.phase) labels.phase = event.phase
549
+ if (event?.source) labels.source = event.source
550
+
551
+ const metadata = event?.turnMetadata || api.correlation.getContext().turnMetadata
552
+ if (metadata?.input_plugin) labels.input_plugin = metadata.input_plugin
553
+
554
+ const plugin = extractPluginFromPayload(event?.payload)
555
+ if (plugin) labels.input_plugin = plugin
556
+
557
+ return labels
558
+ }
559
+
560
+ function extractPluginFromPayload(payload) {
561
+ if (!payload) return undefined
562
+ const item = Array.isArray(payload) ? payload[0] : payload
563
+ if (item?.plugin) return String(item.plugin)
564
+ return undefined
565
+ }
566
+
567
+ function dispatchEvent(exporter, event, metricsRegistry) {
568
+ try {
569
+ exporter.onEvent?.(event)
570
+ } catch {
571
+ metricsRegistry.recordExporterError(exporter.id)
572
+ }
573
+ }
574
+
575
+ function dispatchPhaseEnd(api, event) {
576
+ for (const exporter of api.exporters) {
577
+ try {
578
+ exporter.onPhaseEnd?.(event)
579
+ } catch {
580
+ api.metricsRegistry.recordExporterError(exporter.id)
581
+ }
582
+ }
583
+ }
584
+
585
+ function dispatchMetric(exporter, metric, metricsRegistry) {
586
+ try {
587
+ exporter.onMetric?.(metric)
588
+ } catch {
589
+ metricsRegistry.recordExporterError(exporter.id)
590
+ }
591
+ }
592
+
593
+ function normalizeEventName(name) {
594
+ if (typeof name === 'string') return name
595
+ return String(name)
596
+ }
597
+
598
+ function publishGlobal(api, identity) {
599
+ if (typeof globalThis === 'undefined') return
600
+ globalThis[identity.globalKey] = {
601
+ getTimeline: () => api.getTimeline(),
602
+ getMetrics: () => api.getMetrics(),
603
+ getExporterStatus: () => api.getExporterStatus(),
604
+ getPolicyStats: () => api.getPolicyStats(),
605
+ }
606
+ }
607
+
608
+ function removeGlobal(identity) {
609
+ if (typeof globalThis === 'undefined') return
610
+ delete globalThis[identity.globalKey]
611
+ }
@@ -0,0 +1,14 @@
1
+ /**
2
+ * Normalize phase configuration for TurnMetricsCollector and trace exporters.
3
+ *
4
+ * @param {Array<{ id: string, startEvent: string, endEvent: string }>} phases
5
+ */
6
+ export function definePhaseModel(phases = []) {
7
+ return phases
8
+ .filter((phase) => phase?.id && phase?.startEvent && phase?.endEvent)
9
+ .map((phase) => ({
10
+ id: String(phase.id),
11
+ startEvent: String(phase.startEvent),
12
+ endEvent: String(phase.endEvent),
13
+ }))
14
+ }
@@ -0,0 +1,21 @@
1
+ /**
2
+ * Decide whether a bus event should be recorded as telemetry.
3
+ * Turn detection always runs regardless of this filter.
4
+ */
5
+ export function createEventInstrumentation(options = {}) {
6
+ const allowlist = options.eventAllowlist
7
+ ? new Set(options.eventAllowlist.map(String))
8
+ : null
9
+ const eventFilter = typeof options.eventFilter === 'function'
10
+ ? options.eventFilter
11
+ : null
12
+
13
+ return {
14
+ shouldRecord(eventName) {
15
+ const name = String(eventName)
16
+ if (allowlist && !allowlist.has(name)) return false
17
+ if (eventFilter && !eventFilter(name)) return false
18
+ return true
19
+ },
20
+ }
21
+ }
@@ -0,0 +1,9 @@
1
+ /**
2
+ * Default heuristic for error-like semantic events.
3
+ */
4
+ export function isErrorEvent(event) {
5
+ const preview = event.payloadSummary?.preview || ''
6
+ if (/error|fail|exception/i.test(preview)) return true
7
+ if (/error|fail|exception/i.test(event.name || '')) return true
8
+ return false
9
+ }
@@ -0,0 +1,44 @@
1
+ /**
2
+ * Shared telemetry attribute prefix for spans and metric labels.
3
+ */
4
+ export const SEVO_ATTR_PREFIX = 'sevo.'
5
+
6
+ export function sevoAttributes(event) {
7
+ return {
8
+ ...event.attributes,
9
+ [`${SEVO_ATTR_PREFIX}session_id`]: event.sessionId,
10
+ [`${SEVO_ATTR_PREFIX}turn_id`]: event.turnId,
11
+ [`${SEVO_ATTR_PREFIX}trace_id`]: event.traceId,
12
+ [`${SEVO_ATTR_PREFIX}event_name`]: event.name,
13
+ [`${SEVO_ATTR_PREFIX}environment`]: event.environment,
14
+ }
15
+ }
16
+
17
+ /** Canonical Prometheus label keys (no sevo. prefix — see metrics-roadmap.md). */
18
+ export const SEVO_METRIC_LABEL_KEYS = new Set([
19
+ 'environment',
20
+ 'phase',
21
+ 'status',
22
+ 'reason',
23
+ 'event_type',
24
+ 'key',
25
+ 'event',
26
+ 'metric',
27
+ 'exporter',
28
+ 'vital',
29
+ 'rating',
30
+ 'navigationType',
31
+ 'source',
32
+ 'start_event',
33
+ 'input_plugin',
34
+ ])
35
+
36
+ export function sevoMetricLabelAttributes(labels = {}) {
37
+ const output = {}
38
+ for (const [key, value] of Object.entries(labels)) {
39
+ if (value == null) continue
40
+ const labelKey = SEVO_METRIC_LABEL_KEYS.has(key) ? key : `${SEVO_ATTR_PREFIX}${key}`
41
+ output[labelKey] = String(value)
42
+ }
43
+ return output
44
+ }