@handsforbots/semantic-event-observability 0.0.0-stage → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE.md +9 -0
- package/README.md +141 -2
- package/adapters/genericEventBus.js +20 -0
- package/adapters/instrumentChannel.js +22 -0
- package/core/CorrelationContext.js +49 -0
- package/core/EventBuffer.js +37 -0
- package/core/MetricsRegistry.js +200 -0
- package/core/PhaseTracker.js +143 -0
- package/core/Policy.js +87 -0
- package/core/SessionTracker.js +23 -0
- package/core/TraceContextBridge.js +74 -0
- package/core/TraceMapper.js +167 -0
- package/core/TurnMetricsCollector.js +19 -0
- package/core/TurnModel.js +87 -0
- package/core/baggage.d.ts +12 -0
- package/core/baggage.js +68 -0
- package/core/bucketEventName.js +11 -0
- package/core/createObservability.js +611 -0
- package/core/definePhaseModel.js +14 -0
- package/core/eventInstrumentation.js +21 -0
- package/core/isErrorEvent.js +9 -0
- package/core/telemetryAttributes.js +44 -0
- package/core/turnSpanNaming.js +73 -0
- package/docs/architecture.md +106 -0
- package/docs/custom-exporter.md +135 -0
- package/docs/exporters.md +180 -0
- package/docs/getting-started.md +192 -0
- package/docs/grafana-validation.md +71 -0
- package/docs/handsforbots-adapter.md +64 -0
- package/docs/handsforbots-roadmap.md +193 -0
- package/docs/metrics-roadmap.md +145 -0
- package/docs/publishing.md +55 -0
- package/docs/renaming.md +65 -0
- package/docs/roadmap.md +467 -0
- package/docs/tail-sampling.md +99 -0
- package/exporters/console.js +29 -0
- package/exporters/devPanel.js +204 -0
- package/exporters/faro.js +71 -0
- package/exporters/index.js +58 -0
- package/exporters/langfuse.js +161 -0
- package/exporters/langsmith.js +168 -0
- package/exporters/llmExporterState.js +84 -0
- package/exporters/memory.js +18 -0
- package/exporters/otel.js +236 -0
- package/exporters/otelTraceBackend.js +51 -0
- package/exporters/webVitals.js +73 -0
- package/grafana/semantic-event-observability.json +250 -0
- package/grafana/semantic-event-observability.lgtm.json +399 -0
- package/index.d.ts +312 -0
- package/index.js +31 -0
- package/package.json +83 -3
- package/packageIdentity.js +41 -0
- package/utils/id.js +10 -0
- package/utils/probeOptional.js +42 -0
- 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
|
+
}
|