@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/LICENSE.md
ADDED
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
The MIT License (MIT)
|
|
2
|
+
|
|
3
|
+
Copyright © 2024 Alex Lana and Hands for Bots contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
|
|
6
|
+
|
|
7
|
+
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
|
|
8
|
+
|
|
9
|
+
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,142 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Semantic Event Observability
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Semantic observability for async event systems: logs, metrics, and tracing with **optional** exporters.
|
|
4
|
+
|
|
5
|
+
Built to sit on top of proven stacks (OpenTelemetry, Grafana Faro, Langfuse, LangSmith). If an exporter dependency is missing, the host application keeps working — telemetry is simply skipped for that backend.
|
|
6
|
+
|
|
7
|
+
**Scope:** semantic flow observability (turns, phases, queue pressure, telemetry health) — **not** service uptime, `/health` endpoints, or K8s probes. See [architecture — scope](./docs/architecture.md#scope).
|
|
8
|
+
|
|
9
|
+
> **Working title.** The npm name lives in `packageIdentity.js`. Change `PACKAGE_SLUG` there when the final product name is decided.
|
|
10
|
+
|
|
11
|
+
## Quick start (Hands for Bots)
|
|
12
|
+
|
|
13
|
+
Add the **Observability** output plugin:
|
|
14
|
+
|
|
15
|
+
```javascript
|
|
16
|
+
bot_settings.plugins.push({
|
|
17
|
+
type: 'output',
|
|
18
|
+
plugin: 'Observability',
|
|
19
|
+
environment: 'development',
|
|
20
|
+
exporters: ['memory', 'devPanel'],
|
|
21
|
+
})
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
Enable the dev panel:
|
|
25
|
+
|
|
26
|
+
```javascript
|
|
27
|
+
localStorage.setItem('semantic-event-observability:debug', 'true')
|
|
28
|
+
location.reload()
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
**−** collapses the panel to its title bar. That choice stays in `localStorage` (`semantic-event-observability:panel`). **×** turns the panel off.
|
|
32
|
+
|
|
33
|
+
Configure exporters and policy via plugin options:
|
|
34
|
+
|
|
35
|
+
```javascript
|
|
36
|
+
{
|
|
37
|
+
type: 'output',
|
|
38
|
+
plugin: 'Observability',
|
|
39
|
+
environment: 'production',
|
|
40
|
+
sampleRate: 0.2,
|
|
41
|
+
maxEventsPerMinute: 120,
|
|
42
|
+
exporters: ['memory', 'devPanel', 'faro', 'otel', 'langfuse', 'langsmith'],
|
|
43
|
+
exporterConfig: {
|
|
44
|
+
faro: { /* optional injected client */ },
|
|
45
|
+
otel: { /* api: injected OpenTelemetry API */ },
|
|
46
|
+
langfuse: { project: 'my-app' },
|
|
47
|
+
langsmith: { projectName: 'my-app' },
|
|
48
|
+
},
|
|
49
|
+
}
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
## Generic event bus
|
|
53
|
+
|
|
54
|
+
```javascript
|
|
55
|
+
import { createObservability, instrumentEventBus } from './index.js'
|
|
56
|
+
|
|
57
|
+
const observability = createObservability({
|
|
58
|
+
turnStartEvents: ['user.message'],
|
|
59
|
+
turnEndEvents: ['bot.response'],
|
|
60
|
+
exporters: ['memory', 'console', 'otel'],
|
|
61
|
+
})
|
|
62
|
+
|
|
63
|
+
instrumentEventBus(observability, myBus, {
|
|
64
|
+
stateProvider: () => ({ queueDepth: myQueue.length }),
|
|
65
|
+
})
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
## Exporters
|
|
69
|
+
|
|
70
|
+
| ID | Dependency | Destination |
|
|
71
|
+
|----|------------|-------------|
|
|
72
|
+
| `memory` | none | Ring buffer / debug export |
|
|
73
|
+
| `console` | none | Browser console |
|
|
74
|
+
| `devPanel` | none | Floating debug panel |
|
|
75
|
+
| `otel` | `@opentelemetry/api` (optional) | Tempo / Mimir via OTel collector |
|
|
76
|
+
| `faro` | `@grafana/faro-web-sdk` (optional) | Loki via Faro collector |
|
|
77
|
+
| `langfuse` | `@langfuse/tracing` (optional) | Langfuse traces |
|
|
78
|
+
| `langsmith` | `langsmith` (optional) | LangSmith runs |
|
|
79
|
+
| `webVitals` | `web-vitals` (optional) | Core Web Vitals → `sevo_web_vital` |
|
|
80
|
+
|
|
81
|
+
Dependencies are **optional peer dependencies**. Inject clients manually when dynamic import is not available:
|
|
82
|
+
|
|
83
|
+
```javascript
|
|
84
|
+
exporterConfig: {
|
|
85
|
+
faro: { client: window.faro },
|
|
86
|
+
otel: { api: traceApi },
|
|
87
|
+
langfuse: { startObservation },
|
|
88
|
+
langsmith: { RunTree },
|
|
89
|
+
}
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
## Attributes, baggage and counters
|
|
93
|
+
|
|
94
|
+
```javascript
|
|
95
|
+
observability.setAttributes({ 'greeting.kind': 'directed', 'greeting.index': 3 })
|
|
96
|
+
observability.getTraceHeaders()
|
|
97
|
+
// { traceparent: '00-…', baggage: 'greeting.kind=directed,greeting.index=3' }
|
|
98
|
+
observability.recordCounter('h4b_experiment_exposed_total', 1, { experiment: 'greeting', 'greeting.kind': 'directed' })
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
- **`setAttributes(attributes)` / `getAttributes()`.** Replaces the attributes (strings, finite numbers, booleans) put on every event (`event.attributes`) and every span: turn root, phases and events. Keep them to codes, never user text.
|
|
102
|
+
- **`baggage` header.** `getTraceHeaders()` adds the attributes as a [W3C Baggage](https://www.w3.org/TR/baggage/) header. If an injected carrier already has a `baggage` header, the two are merged and the attributes win on the same key. Nothing is added when `enabled: false`.
|
|
103
|
+
- **`recordCounter(name, value = 1, labels)`.** A counter that is never sampled nor rate-limited. The `otel` exporter creates the OpenTelemetry Counter on first use and keeps the labels as given (no `sevo.` prefix).
|
|
104
|
+
- **Baggage helpers.** `encodeBaggage`, `parseBaggage` and `mergeBaggage` come from the main entry and from `@handsforbots/semantic-event-observability/baggage`, which has no other imports and suits a server.
|
|
105
|
+
|
|
106
|
+
## Security defaults
|
|
107
|
+
|
|
108
|
+
- Payload redaction via denylist (`password`, `token`, `history`, …)
|
|
109
|
+
- Payload truncation (`maxPayloadBytes`, default 2 KB)
|
|
110
|
+
- Per-minute rate limit (`maxEventsPerMinute`, default 120)
|
|
111
|
+
- Sampling (`sampleRate`, default 1 in dev — lower in production)
|
|
112
|
+
- Turn events are never sampled out
|
|
113
|
+
|
|
114
|
+
Defense in depth: also rate-limit at the collector before Loki/Tempo.
|
|
115
|
+
|
|
116
|
+
## Grafana
|
|
117
|
+
|
|
118
|
+
| File | Use |
|
|
119
|
+
|------|-----|
|
|
120
|
+
| `grafana/semantic-event-observability.json` | Import template (select Loki/Tempo/Prometheus datasources) |
|
|
121
|
+
| `grafana/semantic-event-observability.lgtm.json` | Pre-provisioned in [`examples/`](../../examples/) via `docker-compose.observability.yml` |
|
|
122
|
+
|
|
123
|
+
The example stack mounts the `.lgtm.json` variant into `grafana/otel-lgtm` and sets it as the home dashboard.
|
|
124
|
+
|
|
125
|
+
## Documentation
|
|
126
|
+
|
|
127
|
+
- [Getting started](./docs/getting-started.md)
|
|
128
|
+
- [Architecture](./docs/architecture.md)
|
|
129
|
+
- [Library roadmap & abstractions](./docs/roadmap.md)
|
|
130
|
+
- [Metrics checklist (`sevo_*`)](./docs/metrics-roadmap.md)
|
|
131
|
+
- [Exporters](./docs/exporters.md)
|
|
132
|
+
- [Tail sampling guidance](./docs/tail-sampling.md)
|
|
133
|
+
- [Grafana dashboard validation](./docs/grafana-validation.md)
|
|
134
|
+
- [Custom exporter cookbook](./docs/custom-exporter.md)
|
|
135
|
+
- [Publishing to npm](./docs/publishing.md)
|
|
136
|
+
- [Hands for Bots adapter](./docs/handsforbots-adapter.md)
|
|
137
|
+
- [Hands for Bots roadmap (`hfb_*`)](./docs/handsforbots-roadmap.md)
|
|
138
|
+
- [Renaming the package](./docs/renaming.md)
|
|
139
|
+
|
|
140
|
+
## Future npm publish
|
|
141
|
+
|
|
142
|
+
See [publishing.md](./docs/publishing.md). TypeScript types ship in `index.d.ts`.
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Generic adapter for event buses exposing on() and trigger().
|
|
3
|
+
*/
|
|
4
|
+
export function instrumentEventBus(observability, bus, options = {}) {
|
|
5
|
+
return observability.instrument(bus, options)
|
|
6
|
+
}
|
|
7
|
+
|
|
8
|
+
/**
|
|
9
|
+
* Convenience helper to bootstrap observability + bus instrumentation in one call.
|
|
10
|
+
*/
|
|
11
|
+
export function createInstrumentedBus(bus, options = {}) {
|
|
12
|
+
const { createObservability } = options
|
|
13
|
+
if (typeof createObservability !== 'function') {
|
|
14
|
+
throw new Error('createInstrumentedBus requires createObservability in options')
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
const observability = createObservability(options.observability || {})
|
|
18
|
+
observability.instrument(bus, options.instrument || {})
|
|
19
|
+
return { observability, bus }
|
|
20
|
+
}
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Instrument BroadcastChannel, MessagePort, or similar postMessage APIs.
|
|
3
|
+
*/
|
|
4
|
+
export function instrumentChannel(observability, channel, options = {}) {
|
|
5
|
+
if (!channel || typeof channel.postMessage !== 'function') {
|
|
6
|
+
throw new Error('instrumentChannel expects an object with postMessage()')
|
|
7
|
+
}
|
|
8
|
+
|
|
9
|
+
const eventName = options.eventName || 'channel.post'
|
|
10
|
+
const recordType = options.type || 'custom'
|
|
11
|
+
|
|
12
|
+
const originalPostMessage = channel.postMessage.bind(channel)
|
|
13
|
+
channel.postMessage = function instrumentedPostMessage(data, transfer) {
|
|
14
|
+
observability.record(eventName, data, { type: recordType })
|
|
15
|
+
if (transfer !== undefined) {
|
|
16
|
+
return originalPostMessage(data, transfer)
|
|
17
|
+
}
|
|
18
|
+
return originalPostMessage(data)
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
return channel
|
|
22
|
+
}
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
import { createId } from '../utils/id.js'
|
|
2
|
+
import TurnModel, { defineTurnModel } from './TurnModel.js'
|
|
3
|
+
|
|
4
|
+
/**
|
|
5
|
+
* Tracks turn/session correlation for async event flows.
|
|
6
|
+
*/
|
|
7
|
+
export default class CorrelationContext {
|
|
8
|
+
constructor(options = {}) {
|
|
9
|
+
this.sessionId = options.sessionId || createId('session')
|
|
10
|
+
this.turnModel = new TurnModel(
|
|
11
|
+
options.turnModel || defineTurnModel({
|
|
12
|
+
startEvents: options.turnStartEvents,
|
|
13
|
+
endEvents: options.turnEndEvents,
|
|
14
|
+
}),
|
|
15
|
+
)
|
|
16
|
+
this.turnMetadata = {}
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
startSession(sessionId = createId('session')) {
|
|
20
|
+
this.sessionId = sessionId
|
|
21
|
+
this.turnModel = new TurnModel({
|
|
22
|
+
startEvents: [...this.turnModel.startEvents],
|
|
23
|
+
endEvents: [...this.turnModel.endEvents],
|
|
24
|
+
})
|
|
25
|
+
this.turnMetadata = {}
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
observeBusEvent(eventName) {
|
|
29
|
+
return this.turnModel.observeBusEvent(eventName)
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
getContext() {
|
|
33
|
+
return {
|
|
34
|
+
sessionId: this.sessionId,
|
|
35
|
+
...this.turnModel.getContext(),
|
|
36
|
+
turnMetadata: { ...this.turnMetadata },
|
|
37
|
+
}
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
setTurnMetadata(metadata = {}) {
|
|
41
|
+
this.turnMetadata = { ...this.turnMetadata, ...metadata }
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
getActiveTurnAge() {
|
|
45
|
+
return this.turnModel.getActiveTurnAge()
|
|
46
|
+
}
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
export { defineTurnModel }
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* In-memory ring buffer for dev panel and debug export.
|
|
3
|
+
*/
|
|
4
|
+
export default class EventBuffer {
|
|
5
|
+
constructor(maxSize = 200) {
|
|
6
|
+
this.maxSize = maxSize
|
|
7
|
+
this.events = []
|
|
8
|
+
this.metrics = []
|
|
9
|
+
}
|
|
10
|
+
|
|
11
|
+
push(event) {
|
|
12
|
+
this.events.push(event)
|
|
13
|
+
if (this.events.length > this.maxSize) {
|
|
14
|
+
this.events.shift()
|
|
15
|
+
}
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
pushMetric(metric) {
|
|
19
|
+
this.metrics.push(metric)
|
|
20
|
+
if (this.metrics.length > this.maxSize) {
|
|
21
|
+
this.metrics.shift()
|
|
22
|
+
}
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
getTimeline(limit = this.maxSize) {
|
|
26
|
+
return this.events.slice(-limit)
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
getMetrics(limit = this.maxSize) {
|
|
30
|
+
return this.metrics.slice(-limit)
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
clear() {
|
|
34
|
+
this.events = []
|
|
35
|
+
this.metrics = []
|
|
36
|
+
}
|
|
37
|
+
}
|
|
@@ -0,0 +1,200 @@
|
|
|
1
|
+
export const SEVO_METRICS = {
|
|
2
|
+
TURN_DURATION: 'sevo_turn_duration_ms',
|
|
3
|
+
PHASE_DURATION: 'sevo_phase_duration_ms',
|
|
4
|
+
PHASE_WAIT: 'sevo_phase_wait_ms',
|
|
5
|
+
TURNS_TOTAL: 'sevo_turns_total',
|
|
6
|
+
EVENTS_DROPPED: 'sevo_events_dropped_total',
|
|
7
|
+
STATE_GAUGE: 'sevo_state_gauge',
|
|
8
|
+
EVENTS_EMITTED: 'sevo_events_emitted_total',
|
|
9
|
+
EXPORTER_ERRORS: 'sevo_exporter_errors_total',
|
|
10
|
+
ACTIVE_TURNS: 'sevo_active_turns',
|
|
11
|
+
SESSION_TURNS_TOTAL: 'sevo_session_turns_total',
|
|
12
|
+
WEB_VITAL: 'sevo_web_vital',
|
|
13
|
+
BUS_EVENTS_TOTAL: 'sevo_bus_events_total',
|
|
14
|
+
CUSTOM_METRICS_TOTAL: 'sevo_custom_metrics_total',
|
|
15
|
+
LISTENER_DURATION: 'sevo_listener_duration_ms',
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
/** @deprecated Use SEVO_METRICS */
|
|
19
|
+
export const SEO_METRICS = SEVO_METRICS
|
|
20
|
+
|
|
21
|
+
/**
|
|
22
|
+
* Canonical sevo_* metric recording for Semantic Event Observability.
|
|
23
|
+
*/
|
|
24
|
+
export function createMetricsRegistry(options = {}) {
|
|
25
|
+
const environment = options.environment || 'development'
|
|
26
|
+
const listeners = new Set()
|
|
27
|
+
|
|
28
|
+
function emit(metric) {
|
|
29
|
+
const record = {
|
|
30
|
+
name: metric.name,
|
|
31
|
+
type: metric.type,
|
|
32
|
+
value: metric.value,
|
|
33
|
+
labels: {
|
|
34
|
+
environment,
|
|
35
|
+
...(metric.labels || {}),
|
|
36
|
+
},
|
|
37
|
+
timestamp: new Date().toISOString(),
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
for (const listener of listeners) {
|
|
41
|
+
try { listener(record) } catch { /* noop */ }
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
return record
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
return {
|
|
48
|
+
SEVO_METRICS,
|
|
49
|
+
|
|
50
|
+
subscribe(listener) {
|
|
51
|
+
listeners.add(listener)
|
|
52
|
+
return () => listeners.delete(listener)
|
|
53
|
+
},
|
|
54
|
+
|
|
55
|
+
recordTurnDuration(durationMs, labels = {}) {
|
|
56
|
+
if (durationMs == null || Number.isNaN(durationMs)) return
|
|
57
|
+
return emit({
|
|
58
|
+
name: SEVO_METRICS.TURN_DURATION,
|
|
59
|
+
type: 'histogram',
|
|
60
|
+
value: Math.max(0, durationMs),
|
|
61
|
+
labels,
|
|
62
|
+
})
|
|
63
|
+
},
|
|
64
|
+
|
|
65
|
+
recordPhaseDuration(phase, durationMs, labels = {}) {
|
|
66
|
+
if (durationMs == null || Number.isNaN(durationMs)) return
|
|
67
|
+
return emit({
|
|
68
|
+
name: SEVO_METRICS.PHASE_DURATION,
|
|
69
|
+
type: 'histogram',
|
|
70
|
+
value: Math.max(0, durationMs),
|
|
71
|
+
labels: { phase, ...labels },
|
|
72
|
+
})
|
|
73
|
+
},
|
|
74
|
+
|
|
75
|
+
recordPhaseWait(phase, waitMs, labels = {}) {
|
|
76
|
+
if (waitMs == null || Number.isNaN(waitMs)) return
|
|
77
|
+
return emit({
|
|
78
|
+
name: SEVO_METRICS.PHASE_WAIT,
|
|
79
|
+
type: 'histogram',
|
|
80
|
+
value: Math.max(0, waitMs),
|
|
81
|
+
labels: { phase, ...labels },
|
|
82
|
+
})
|
|
83
|
+
},
|
|
84
|
+
|
|
85
|
+
recordTurnStatus(status, labels = {}) {
|
|
86
|
+
return emit({
|
|
87
|
+
name: SEVO_METRICS.TURNS_TOTAL,
|
|
88
|
+
type: 'counter',
|
|
89
|
+
value: 1,
|
|
90
|
+
labels: { status, ...labels },
|
|
91
|
+
})
|
|
92
|
+
},
|
|
93
|
+
|
|
94
|
+
recordEventDropped(reason) {
|
|
95
|
+
return emit({
|
|
96
|
+
name: SEVO_METRICS.EVENTS_DROPPED,
|
|
97
|
+
type: 'counter',
|
|
98
|
+
value: 1,
|
|
99
|
+
labels: { reason: reason || 'unknown' },
|
|
100
|
+
})
|
|
101
|
+
},
|
|
102
|
+
|
|
103
|
+
recordStateGauge(key, value, labels = {}) {
|
|
104
|
+
if (typeof value !== 'number' || Number.isNaN(value)) return
|
|
105
|
+
return emit({
|
|
106
|
+
name: SEVO_METRICS.STATE_GAUGE,
|
|
107
|
+
type: 'gauge',
|
|
108
|
+
value,
|
|
109
|
+
labels: { key, ...labels },
|
|
110
|
+
})
|
|
111
|
+
},
|
|
112
|
+
|
|
113
|
+
recordEventEmitted(eventType, labels = {}) {
|
|
114
|
+
return emit({
|
|
115
|
+
name: SEVO_METRICS.EVENTS_EMITTED,
|
|
116
|
+
type: 'counter',
|
|
117
|
+
value: 1,
|
|
118
|
+
labels: { event_type: eventType || 'unknown', ...labels },
|
|
119
|
+
})
|
|
120
|
+
},
|
|
121
|
+
|
|
122
|
+
recordExporterError(exporterId) {
|
|
123
|
+
return emit({
|
|
124
|
+
name: SEVO_METRICS.EXPORTER_ERRORS,
|
|
125
|
+
type: 'counter',
|
|
126
|
+
value: 1,
|
|
127
|
+
labels: { exporter: exporterId || 'unknown' },
|
|
128
|
+
})
|
|
129
|
+
},
|
|
130
|
+
|
|
131
|
+
recordActiveTurns(count) {
|
|
132
|
+
if (typeof count !== 'number' || Number.isNaN(count)) return
|
|
133
|
+
return emit({
|
|
134
|
+
name: SEVO_METRICS.ACTIVE_TURNS,
|
|
135
|
+
type: 'gauge',
|
|
136
|
+
value: Math.max(0, count),
|
|
137
|
+
labels: {},
|
|
138
|
+
})
|
|
139
|
+
},
|
|
140
|
+
|
|
141
|
+
recordSessionTurnsRollup(counts = {}, labels = {}) {
|
|
142
|
+
const records = []
|
|
143
|
+
if (counts.completed > 0) {
|
|
144
|
+
records.push(emit({
|
|
145
|
+
name: SEVO_METRICS.SESSION_TURNS_TOTAL,
|
|
146
|
+
type: 'counter',
|
|
147
|
+
value: counts.completed,
|
|
148
|
+
labels: { status: 'completed', ...labels },
|
|
149
|
+
}))
|
|
150
|
+
}
|
|
151
|
+
if (counts.abandoned > 0) {
|
|
152
|
+
records.push(emit({
|
|
153
|
+
name: SEVO_METRICS.SESSION_TURNS_TOTAL,
|
|
154
|
+
type: 'counter',
|
|
155
|
+
value: counts.abandoned,
|
|
156
|
+
labels: { status: 'abandoned', ...labels },
|
|
157
|
+
}))
|
|
158
|
+
}
|
|
159
|
+
return records
|
|
160
|
+
},
|
|
161
|
+
|
|
162
|
+
recordWebVital(name, value, labels = {}) {
|
|
163
|
+
if (value == null || Number.isNaN(value)) return
|
|
164
|
+
return emit({
|
|
165
|
+
name: SEVO_METRICS.WEB_VITAL,
|
|
166
|
+
type: 'histogram',
|
|
167
|
+
value: Math.max(0, value),
|
|
168
|
+
labels: { vital: name || 'unknown', ...labels },
|
|
169
|
+
})
|
|
170
|
+
},
|
|
171
|
+
|
|
172
|
+
recordBusEvent(eventName, labels = {}) {
|
|
173
|
+
return emit({
|
|
174
|
+
name: SEVO_METRICS.BUS_EVENTS_TOTAL,
|
|
175
|
+
type: 'counter',
|
|
176
|
+
value: 1,
|
|
177
|
+
labels: { event: eventName || 'unknown', ...labels },
|
|
178
|
+
})
|
|
179
|
+
},
|
|
180
|
+
|
|
181
|
+
recordCustomMetric(metricName, labels = {}) {
|
|
182
|
+
return emit({
|
|
183
|
+
name: SEVO_METRICS.CUSTOM_METRICS_TOTAL,
|
|
184
|
+
type: 'counter',
|
|
185
|
+
value: 1,
|
|
186
|
+
labels: { metric: metricName || 'unknown', ...labels },
|
|
187
|
+
})
|
|
188
|
+
},
|
|
189
|
+
|
|
190
|
+
recordListenerDuration(durationMs, labels = {}) {
|
|
191
|
+
if (durationMs == null || Number.isNaN(durationMs)) return
|
|
192
|
+
return emit({
|
|
193
|
+
name: SEVO_METRICS.LISTENER_DURATION,
|
|
194
|
+
type: 'histogram',
|
|
195
|
+
value: Math.max(0, durationMs),
|
|
196
|
+
labels,
|
|
197
|
+
})
|
|
198
|
+
},
|
|
199
|
+
}
|
|
200
|
+
}
|
|
@@ -0,0 +1,143 @@
|
|
|
1
|
+
import { isErrorEvent } from './isErrorEvent.js'
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Tracks phases within a turn from bus events and manual start/end calls.
|
|
5
|
+
*/
|
|
6
|
+
export function createPhaseTracker(options = {}) {
|
|
7
|
+
const phases = options.phases || []
|
|
8
|
+
const isError = options.isError || isErrorEvent
|
|
9
|
+
const onPhaseStart = options.onPhaseStart || (() => {})
|
|
10
|
+
const onPhaseEnd = options.onPhaseEnd || (() => {})
|
|
11
|
+
const onPhaseWait = options.onPhaseWait || (() => {})
|
|
12
|
+
const onRenderDuration = options.onRenderDuration || (() => {})
|
|
13
|
+
const onTurnStatus = options.onTurnStatus || (() => {})
|
|
14
|
+
|
|
15
|
+
const phaseByStartEvent = new Map(phases.map((phase) => [phase.startEvent, phase]))
|
|
16
|
+
const phaseByEndEvent = new Map(phases.map((phase) => [phase.endEvent, phase]))
|
|
17
|
+
|
|
18
|
+
/** @type {Map<string, TurnPhaseState>} */
|
|
19
|
+
const turns = new Map()
|
|
20
|
+
|
|
21
|
+
return {
|
|
22
|
+
onTurnAbandoned(event) {
|
|
23
|
+
turns.delete(event.turnId)
|
|
24
|
+
},
|
|
25
|
+
|
|
26
|
+
onTurnStart(event) {
|
|
27
|
+
turns.set(event.turnId, {
|
|
28
|
+
turnStartedAt: Date.now(),
|
|
29
|
+
openPhases: new Map(),
|
|
30
|
+
lastPhaseEndedAt: null,
|
|
31
|
+
hasError: false,
|
|
32
|
+
})
|
|
33
|
+
},
|
|
34
|
+
|
|
35
|
+
onTurnEnd(event, labels = {}) {
|
|
36
|
+
const state = turns.get(event.turnId)
|
|
37
|
+
if (state?.lastPhaseEndedAt != null) {
|
|
38
|
+
const renderMs = Math.max(0, Date.now() - state.lastPhaseEndedAt)
|
|
39
|
+
onRenderDuration(renderMs, { ...labels, phase: 'render' })
|
|
40
|
+
}
|
|
41
|
+
onTurnStatus(state?.hasError ? 'error' : 'completed', labels)
|
|
42
|
+
turns.delete(event.turnId)
|
|
43
|
+
},
|
|
44
|
+
|
|
45
|
+
onBusEvent(event, labels = {}) {
|
|
46
|
+
if (!event.turnId) return
|
|
47
|
+
|
|
48
|
+
const state = turns.get(event.turnId)
|
|
49
|
+
if (!state) return
|
|
50
|
+
|
|
51
|
+
markErrorIfNeeded(state, event)
|
|
52
|
+
|
|
53
|
+
const startPhase = phaseByStartEvent.get(event.name)
|
|
54
|
+
if (startPhase) {
|
|
55
|
+
beginPhase(state, event.turnId, startPhase.id, labels, 'bus')
|
|
56
|
+
return
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
const endPhase = phaseByEndEvent.get(event.name)
|
|
60
|
+
if (endPhase) {
|
|
61
|
+
finishPhase(state, event.turnId, endPhase.id, labels, 'bus')
|
|
62
|
+
}
|
|
63
|
+
},
|
|
64
|
+
|
|
65
|
+
startPhase(turnId, phaseId, labels = {}) {
|
|
66
|
+
if (!turnId || !phaseId) return false
|
|
67
|
+
const state = turns.get(turnId)
|
|
68
|
+
if (!state) return false
|
|
69
|
+
beginPhase(state, turnId, String(phaseId), labels, 'manual')
|
|
70
|
+
return true
|
|
71
|
+
},
|
|
72
|
+
|
|
73
|
+
endPhase(turnId, phaseId, labels = {}) {
|
|
74
|
+
if (!turnId || !phaseId) return false
|
|
75
|
+
const state = turns.get(turnId)
|
|
76
|
+
if (!state) return false
|
|
77
|
+
return finishPhase(state, turnId, String(phaseId), labels, 'manual')
|
|
78
|
+
},
|
|
79
|
+
|
|
80
|
+
getTurnState(turnId) {
|
|
81
|
+
return turns.get(turnId) || null
|
|
82
|
+
},
|
|
83
|
+
|
|
84
|
+
clear() {
|
|
85
|
+
turns.clear()
|
|
86
|
+
},
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
function beginPhase(state, turnId, phaseId, labels, source) {
|
|
90
|
+
if (state.openPhases.has(phaseId)) return
|
|
91
|
+
|
|
92
|
+
if (state.turnStartedAt != null) {
|
|
93
|
+
const waitMs = Math.max(0, Date.now() - state.turnStartedAt)
|
|
94
|
+
onPhaseWait({
|
|
95
|
+
turnId,
|
|
96
|
+
phase: phaseId,
|
|
97
|
+
waitMs,
|
|
98
|
+
source,
|
|
99
|
+
labels,
|
|
100
|
+
})
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
state.openPhases.set(phaseId, { startedAt: Date.now(), source })
|
|
104
|
+
onPhaseStart({
|
|
105
|
+
turnId,
|
|
106
|
+
phase: phaseId,
|
|
107
|
+
source,
|
|
108
|
+
labels,
|
|
109
|
+
})
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
function finishPhase(state, turnId, phaseId, labels, source) {
|
|
113
|
+
const open = state.openPhases.get(phaseId)
|
|
114
|
+
if (!open) return false
|
|
115
|
+
|
|
116
|
+
const durationMs = Math.max(0, Date.now() - open.startedAt)
|
|
117
|
+
state.openPhases.delete(phaseId)
|
|
118
|
+
state.lastPhaseEndedAt = Date.now()
|
|
119
|
+
|
|
120
|
+
onPhaseEnd({
|
|
121
|
+
turnId,
|
|
122
|
+
phase: phaseId,
|
|
123
|
+
durationMs,
|
|
124
|
+
source: open.source || source,
|
|
125
|
+
labels,
|
|
126
|
+
})
|
|
127
|
+
return true
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
function markErrorIfNeeded(state, event) {
|
|
131
|
+
if (isError(event) && !state.hasError) {
|
|
132
|
+
state.hasError = true
|
|
133
|
+
}
|
|
134
|
+
}
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
/**
|
|
138
|
+
* @typedef {object} TurnPhaseState
|
|
139
|
+
* @property {number} turnStartedAt
|
|
140
|
+
* @property {Map<string, { startedAt: number, source: string }>} openPhases
|
|
141
|
+
* @property {number | null} lastPhaseEndedAt
|
|
142
|
+
* @property {boolean} hasError
|
|
143
|
+
*/
|