@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
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
|
package/core/baggage.js
ADDED
|
@@ -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
|
+
}
|