npm - @semiont/observability - Versions diffs - 0.5.5 → 0.5.7 - Mend

@semiont/observability 0.5.5 → 0.5.7

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 (5) hide show

package/README.md +2 -2
package/dist/index.d.ts +14 -6
package/dist/index.js.map +1 -1
package/dist/process-logger.js.map +1 -1
package/package.json +12 -12

package/README.md CHANGED Viewed

@@ -180,7 +180,7 @@ registerJobQueueProvider(() => ({
   running: jobs.running.size,
 }));
-registerVectorIndexSizeProvider(() => qdrant.getCollectionInfo());
+registerVectorIndexSizeProvider(() => vectorStore.count());
 ```
 ## Implementation notes
@@ -197,4 +197,4 @@ Apache-2.0 — see [LICENSE](https://github.com/The-AI-Alliance/semiont/blob/mai
 - [`@semiont/core`](https://github.com/The-AI-Alliance/semiont/tree/main/packages/core) — Tier 1 `busLog`, domain types
 - [`@semiont/sdk`](https://github.com/The-AI-Alliance/semiont/tree/main/packages/sdk) — high-level Semiont client, the primary consumer of this package's spanning helpers
-- [`@semiont/api-client`](https://github.com/The-AI-Alliance/semiont/tree/main/packages/api-client) — HTTP transport, propagates `traceparent` on every request
+- [`@semiont/http-transport`](https://github.com/The-AI-Alliance/semiont/tree/main/packages/http-transport) — HTTP transport, propagates `traceparent` on every request

package/dist/index.d.ts CHANGED Viewed

@@ -8,17 +8,25 @@ export { Attributes, Span, SpanKind, SpanStatusCode } from '@opentelemetry/api';
  * import from `@semiont/observability/node` or `/web` at the process entry
  * point. Everything else uses this module.
  *
- * Tier 2 of `.plans/OBSERVABILITY.md`. The public surface is intentionally
- * thin:
+ * Tier 2 of `.plans/OBSERVABILITY.md`. The public surface:
  *
- *   - `withSpan(name, fn, attrs?)` — wrap an async block in a span.
- *   - `injectTraceparent(payload)` / `extractTraceparent(value)` — W3C
+ *   - `withSpan(name, fn, options?)` — wrap an async block in a span;
+ *     `options` carries `kind` and `attrs`.
+ *   - `withActorSpan(actor, channel, fn, extraAttrs?)` — consumer-span
+ *     wrapper for bus-event handlers, with handler-duration recording.
+ *   - `injectTraceparent(payload)` / `extractTraceparent(payload)` — W3C
  *     trace-context propagation across the SSE channel (the bus payload
  *     gets a `_trace?: { traceparent }` sibling to `correlationId`).
- *   - `setSpanContextFromTraceparent(traceparent, fn)` — set incoming
- *     traceparent as the parent context for a synchronous block.
+ *   - `withTraceparent(carrier, fn)` — run `fn` with the incoming
+ *     traceparent as the parent context.
  *   - `getActiveTraceparent()` — read the active span's traceparent for
  *     manual propagation (e.g. attaching to a fetch header or SSE field).
+ *   - `getLogTraceContext()` — active `trace_id` / `span_id` for log-line
+ *     correlation.
+ *   - Metric recorders (`recordBusEmit`, `recordHandlerDuration`,
+ *     `recordJobOutcome`, `recordSubscriberConnect` / `Disconnect`,
+ *     `recordInferenceUsage`) and gauge providers
+ *     (`registerJobQueueProvider`, `registerVectorIndexSizeProvider`).
  *
  * No-op when no exporter is configured: `@opentelemetry/api`'s default
  * tracer is a no-op, so `withSpan` is essentially free until

package/dist/index.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/*\n @semiont/observability — public API.\n \n Universal surface (works in Node + browser). For SDK initialization,\n * import from `@semiont/observability/node` or `/web` at the process entry\n * point. Everything else uses this module.\n \n Tier 2 of `.plans/OBSERVABILITY.md`. The public surface is intentionally\n * thin:\n \n - `withSpan(name, fn, attrs?)` — wrap an async block in a span.\n * - `injectTraceparent(payload)` / `extractTraceparent(value)` — W3C\n * trace-context propagation across the SSE channel (the bus payload\n * gets a `_trace?: { traceparent }` sibling to `correlationId`).\n * - `setSpanContextFromTraceparent(traceparent, fn)` — set incoming\n * traceparent as the parent context for a synchronous block.\n * - `getActiveTraceparent()` — read the active span's traceparent for\n * manual propagation (e.g. attaching to a fetch header or SSE field).\n \n No-op when no exporter is configured: `@opentelemetry/api`'s default\n * tracer is a no-op, so `withSpan` is essentially free until\n * `initObservability()` runs.\n /\n\nimport {\n context,\n isSpanContextValid,\n metrics,\n propagation,\n SpanKind,\n SpanStatusCode,\n trace,\n type Attributes,\n type Counter,\n type Histogram,\n type ObservableGauge,\n type Span,\n type UpDownCounter,\n} from '@opentelemetry/api';\nimport { setBusLogTraceIdProvider } from '@semiont/core';\n\n// Wire `busLog`'s trace-id provider once at module load. When an OTel\n// SDK is initialized (and a span is active when `busLog` fires), the\n// emitted line gets a `trace=<8hex>` suffix that correlates the\n// grep-timeline with the trace UI. No-op when no SDK is active.\nsetBusLogTraceIdProvider(() => {\n const span = trace.getActiveSpan();\n if (!span) return undefined;\n const ctx = span.spanContext();\n if (!isSpanContextValid(ctx)) return undefined;\n return ctx.traceId;\n});\n\nconst TRACER_NAME = 'semiont';\n\nconst tracer = () => trace.getTracer(TRACER_NAME);\n\n// ── withSpan ───────────────────────────────────────────────────────────\n\n/*\n Wrap an async block in a span. The span is started before `fn` runs and\n * ended after it resolves or rejects; exceptions are recorded and the span\n * status is set to ERROR. `kind` defaults to INTERNAL.\n /\nexport async function withSpan<T>(\n name: string,\n fn: (span: Span) => Promise<T> \| T,\n options?: { kind?: SpanKind; attrs?: Attributes },\n): Promise<T> {\n const span = tracer().startSpan(name, {\n kind: options?.kind ?? SpanKind.INTERNAL,\n ...(options?.attrs ? { attributes: options.attrs } : {}),\n });\n try {\n return await context.with(trace.setSpan(context.active(), span), () => fn(span));\n } catch (err) {\n span.recordException(err as Error);\n span.setStatus({\n code: SpanStatusCode.ERROR,\n message: err instanceof Error ? err.message : String(err),\n });\n throw err;\n } finally {\n span.end();\n }\n}\n\n// ── Traceparent on bus payloads ────────────────────────────────────────\n\nconst TRACE_FIELD = '_trace';\n\n/\n Sibling of `correlationId` on bus payloads. Lives on the SSE event body\n * because SSE has no header trailer; the SDK strips it before delivering\n * the payload to subscribers. Additive — payloads without `_trace` parse\n * unchanged.\n /\nexport interface TraceCarrier {\n /* W3C `traceparent` header value (`00-<traceId>-<spanId>-<flags>`). /\n traceparent: string;\n /* W3C `tracestate` header value (vendor-specific extensions). /\n tracestate?: string;\n}\n\n/\n Read the active span's W3C traceparent (and tracestate). Returns\n * `undefined` if no span is active.\n /\nexport function getActiveTraceparent(): TraceCarrier \| undefined {\n const carrier: Record<string, string> = {};\n propagation.inject(context.active(), carrier);\n const traceparent = carrier['traceparent'];\n if (!traceparent) return undefined;\n return carrier['tracestate']\n ? { traceparent, tracestate: carrier['tracestate'] }\n : { traceparent };\n}\n\n/\n Attach the active span's trace-context to a payload object as\n * `_trace`. No-op when no span is active. Returns the same object\n * reference for chaining.\n /\nexport function injectTraceparent<T extends Record<string, unknown>>(payload: T): T {\n const carrier = getActiveTraceparent();\n if (carrier) {\n (payload as Record<string, unknown>)[TRACE_FIELD] = carrier;\n }\n return payload;\n}\n\n/\n Strip and return the `_trace` field from a payload. Mutates `payload`.\n * The field is internal plumbing and should not be visible to subscribers.\n /\nexport function extractTraceparent<T extends Record<string, unknown>>(\n payload: T,\n): TraceCarrier \| undefined {\n const carrier = (payload as Record<string, unknown>)[TRACE_FIELD] as\n \| TraceCarrier\n \| undefined;\n if (carrier !== undefined) {\n delete (payload as Record<string, unknown>)[TRACE_FIELD];\n }\n if (!carrier \|\| typeof carrier.traceparent !== 'string') return undefined;\n return carrier;\n}\n\n/\n Run `fn` with the given W3C traceparent set as the parent context.\n * Any spans started inside `fn` will be children of the incoming trace.\n * No-op if `carrier` is undefined.\n /\nexport function withTraceparent<T>(\n carrier: TraceCarrier \| undefined,\n fn: () => T,\n): T {\n if (!carrier) return fn();\n const carrierObj: Record<string, string> = { traceparent: carrier.traceparent };\n if (carrier.tracestate) carrierObj['tracestate'] = carrier.tracestate;\n const ctx = propagation.extract(context.active(), carrierObj);\n return context.with(ctx, fn);\n}\n\n// ── Actor handler convenience ──────────────────────────────────────────\n\n/\n Wrap a bus-event handler in an `actor.<name>:<channel>` consumer span.\n * Used at every `eventBus.get(channel).subscribe(handler)` site inside\n * an actor (Stower, Gatherer, Matcher, Browser, Smelter), to attribute\n * each in-process subscriber's work to a span without scattering manual\n * `withSpan` calls across handler bodies.\n \n The span's parent is the active context at the time the handler\n * fires — which is the `bus.dispatch:<channel>` span on the backend\n * (Subject.next runs synchronously inside the dispatch span), or the\n * `bus.emit:<channel>` span when an actor emits to itself.\n /\nexport async function withActorSpan<T>(\n actor: string,\n channel: string,\n fn: (span: Span) => Promise<T> \| T,\n extraAttrs?: Attributes,\n): Promise<T> {\n const start = performance.now();\n try {\n return await withSpan(`actor.${actor}:${channel}`, fn, {\n kind: SpanKind.CONSUMER,\n attrs: {\n actor,\n 'bus.channel': channel,\n ...(extraAttrs ?? {}),\n },\n });\n } finally {\n recordHandlerDuration(actor, channel, performance.now() - start);\n }\n}\n\n// ── Log correlation ────────────────────────────────────────────────────\n\n/\n Read the active span's `trace_id` / `span_id` for log-line correlation.\n * Tier 3 of `.plans/OBSERVABILITY.md`. Each structured log line gets\n * tagged with these so a log query in CloudWatch / Loki / Datadog can\n * jump to the trace in Tempo / Jaeger / X-Ray.\n \n Returns `undefined` if no span is active, or if the active span's\n * context is invalid (uninitialized SDK, no-op tracer).\n /\nexport function getLogTraceContext(): { trace_id: string; span_id: string } \| undefined {\n const span = trace.getActiveSpan();\n if (!span) return undefined;\n const ctx = span.spanContext();\n if (!isSpanContextValid(ctx)) return undefined;\n return { trace_id: ctx.traceId, span_id: ctx.spanId };\n}\n\n// ── Metrics — Tier 3 ───────────────────────────────────────────────────\n\nconst METER_NAME = 'semiont';\n\nconst meter = () => metrics.getMeter(METER_NAME);\n\nlet _busEmitCounter: Counter \| undefined;\nlet _handlerDurationHistogram: Histogram \| undefined;\nlet _jobOutcomeCounter: Counter \| undefined;\nlet _jobDurationHistogram: Histogram \| undefined;\nlet _inferenceCallsCounter: Counter \| undefined;\nlet _inferenceTokensCounter: Counter \| undefined;\nlet _inferenceDurationHistogram: Histogram \| undefined;\nlet _sseSubscribers: UpDownCounter \| undefined;\nlet _jobQueueGauge: ObservableGauge \| undefined;\nlet _jobQueueProvider: (() => Promise<JobQueueSnapshot> \| JobQueueSnapshot) \| undefined;\nlet _vectorIndexSizeGauge: ObservableGauge \| undefined;\nlet _vectorIndexSizeProvider: (() => Promise<number> \| number) \| undefined;\n\n/* Snapshot of job-queue contents by status. Match `JobQueue.getStats()`. /\nexport interface JobQueueSnapshot {\n pending: number;\n running: number;\n complete: number;\n failed: number;\n cancelled: number;\n}\n\nfunction busEmitCounter(): Counter {\n if (!_busEmitCounter) {\n _busEmitCounter = meter().createCounter('semiont.bus.emit', {\n description: 'Bus emits by channel and scope',\n });\n }\n return _busEmitCounter;\n}\n\nfunction handlerDurationHistogram(): Histogram {\n if (!_handlerDurationHistogram) {\n _handlerDurationHistogram = meter().createHistogram('semiont.handler.duration', {\n description: 'In-process actor handler duration',\n unit: 'ms',\n });\n }\n return _handlerDurationHistogram;\n}\n\nfunction jobOutcomeCounter(): Counter {\n if (!_jobOutcomeCounter) {\n _jobOutcomeCounter = meter().createCounter('semiont.job.outcome', {\n description: 'Worker job completions by type and outcome',\n });\n }\n return _jobOutcomeCounter;\n}\n\nfunction jobDurationHistogram(): Histogram {\n if (!_jobDurationHistogram) {\n _jobDurationHistogram = meter().createHistogram('semiont.job.duration', {\n description: 'Worker job duration by type',\n unit: 'ms',\n });\n }\n return _jobDurationHistogram;\n}\n\nfunction inferenceCallsCounter(): Counter {\n if (!_inferenceCallsCounter) {\n _inferenceCallsCounter = meter().createCounter('semiont.inference.calls', {\n description: 'Inference API calls by provider, model, and outcome',\n });\n }\n return _inferenceCallsCounter;\n}\n\nfunction inferenceTokensCounter(): Counter {\n if (!_inferenceTokensCounter) {\n _inferenceTokensCounter = meter().createCounter('semiont.inference.tokens', {\n description: 'Inference token usage by provider, model, and direction',\n });\n }\n return _inferenceTokensCounter;\n}\n\nfunction inferenceDurationHistogram(): Histogram {\n if (!_inferenceDurationHistogram) {\n _inferenceDurationHistogram = meter().createHistogram('semiont.inference.duration', {\n description: 'Inference call duration by provider, model, and outcome',\n unit: 'ms',\n });\n }\n return _inferenceDurationHistogram;\n}\n\nfunction sseSubscribersCounter(): UpDownCounter {\n if (!_sseSubscribers) {\n _sseSubscribers = meter().createUpDownCounter('semiont.sse.subscribers', {\n description: 'Active SSE subscribers',\n });\n }\n return _sseSubscribers;\n}\n\n/* Increment the bus-emit counter. Called at every transport `emit` site. /\nexport function recordBusEmit(channel: string, scope?: string): void {\n busEmitCounter().add(1, {\n 'bus.channel': channel,\n ...(scope ? { 'bus.scope': scope } : {}),\n });\n}\n\n/* Record an in-process actor handler's duration. /\nexport function recordHandlerDuration(actor: string, channel: string, durationMs: number): void {\n handlerDurationHistogram().record(durationMs, {\n actor,\n 'bus.channel': channel,\n });\n}\n\n/* Record a worker job's outcome and duration. /\nexport function recordJobOutcome(jobType: string, outcome: 'completed' \| 'failed', durationMs: number): void {\n jobOutcomeCounter().add(1, { 'job.type': jobType, 'job.outcome': outcome });\n jobDurationHistogram().record(durationMs, { 'job.type': jobType, 'job.outcome': outcome });\n}\n\n/* Increment the SSE subscriber gauge — call on `/bus/subscribe` open. /\nexport function recordSubscriberConnect(): void {\n sseSubscribersCounter().add(1);\n}\n\n/* Decrement on disconnect. Pair with `recordSubscriberConnect`. /\nexport function recordSubscriberDisconnect(): void {\n sseSubscribersCounter().add(-1);\n}\n\n/\n Register a callback that returns the current job-queue snapshot.\n * Polled at the SDK's metric-collection interval. The single gauge\n * emits one observation per status (`pending`, `running`, …) tagged\n * with the `job.status` attribute. Idempotent — last registered\n * provider wins.\n /\nexport function registerJobQueueProvider(\n provider: () => Promise<JobQueueSnapshot> \| JobQueueSnapshot,\n): void {\n _jobQueueProvider = provider;\n if (!_jobQueueGauge) {\n _jobQueueGauge = meter().createObservableGauge('semiont.job.queue.size', {\n description: 'Job queue size by status',\n });\n _jobQueueGauge.addCallback(async (observer) => {\n if (!_jobQueueProvider) return;\n const snap = await _jobQueueProvider();\n observer.observe(snap.pending, { 'job.status': 'pending' });\n observer.observe(snap.running, { 'job.status': 'running' });\n observer.observe(snap.complete, { 'job.status': 'complete' });\n observer.observe(snap.failed, { 'job.status': 'failed' });\n observer.observe(snap.cancelled, { 'job.status': 'cancelled' });\n });\n }\n}\n\n/\n Register a callback that returns the current vector-index size\n * (point count). Async to allow remote queries (Qdrant). Polled at\n * the metric-collection interval.\n /\nexport function registerVectorIndexSizeProvider(\n provider: () => Promise<number> \| number,\n): void {\n _vectorIndexSizeProvider = provider;\n if (!_vectorIndexSizeGauge) {\n _vectorIndexSizeGauge = meter().createObservableGauge('semiont.vector.index.size', {\n description: 'Vector store point count',\n });\n _vectorIndexSizeGauge.addCallback(async (observer) => {\n if (_vectorIndexSizeProvider) {\n const value = await _vectorIndexSizeProvider();\n observer.observe(value);\n }\n });\n }\n}\n\n/\n Record an inference call. Token counts are optional — providers that\n * don't expose them (or fail before generating) record only call count\n * and duration.\n */\nexport function recordInferenceUsage(opts: {\n provider: string;\n model: string;\n durationMs: number;\n outcome: 'success' \| 'error';\n inputTokens?: number;\n outputTokens?: number;\n}): void {\n const baseAttrs = {\n 'inference.provider': opts.provider,\n 'inference.model': opts.model,\n 'inference.outcome': opts.outcome,\n };\n inferenceCallsCounter().add(1, baseAttrs);\n inferenceDurationHistogram().record(opts.durationMs, baseAttrs);\n if (opts.inputTokens != null && opts.inputTokens > 0) {\n inferenceTokensCounter().add(opts.inputTokens, {\n 'inference.provider': opts.provider,\n 'inference.model': opts.model,\n 'inference.direction': 'input',\n });\n }\n if (opts.outputTokens != null && opts.outputTokens > 0) {\n inferenceTokensCounter().add(opts.outputTokens, {\n 'inference.provider': opts.provider,\n 'inference.model': opts.model,\n 'inference.direction': 'output',\n });\n }\n}\n\n// ── Re-exports from @opentelemetry/api ─────────────────────────────────\n\nexport { SpanKind, SpanStatusCode, type Attributes, type Span } from '@opentelemetry/api';\n"]}
1	+ {"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/*\n @semiont/observability — public API.\n \n Universal surface (works in Node + browser). For SDK initialization,\n * import from `@semiont/observability/node` or `/web` at the process entry\n * point. Everything else uses this module.\n \n Tier 2 of `.plans/OBSERVABILITY.md`. The public surface:\n \n - `withSpan(name, fn, options?)` — wrap an async block in a span;\n * `options` carries `kind` and `attrs`.\n * - `withActorSpan(actor, channel, fn, extraAttrs?)` — consumer-span\n * wrapper for bus-event handlers, with handler-duration recording.\n * - `injectTraceparent(payload)` / `extractTraceparent(payload)` — W3C\n * trace-context propagation across the SSE channel (the bus payload\n * gets a `_trace?: { traceparent }` sibling to `correlationId`).\n * - `withTraceparent(carrier, fn)` — run `fn` with the incoming\n * traceparent as the parent context.\n * - `getActiveTraceparent()` — read the active span's traceparent for\n * manual propagation (e.g. attaching to a fetch header or SSE field).\n * - `getLogTraceContext()` — active `trace_id` / `span_id` for log-line\n * correlation.\n * - Metric recorders (`recordBusEmit`, `recordHandlerDuration`,\n * `recordJobOutcome`, `recordSubscriberConnect` / `Disconnect`,\n * `recordInferenceUsage`) and gauge providers\n * (`registerJobQueueProvider`, `registerVectorIndexSizeProvider`).\n \n No-op when no exporter is configured: `@opentelemetry/api`'s default\n * tracer is a no-op, so `withSpan` is essentially free until\n * `initObservability()` runs.\n /\n\nimport {\n context,\n isSpanContextValid,\n metrics,\n propagation,\n SpanKind,\n SpanStatusCode,\n trace,\n type Attributes,\n type Counter,\n type Histogram,\n type ObservableGauge,\n type Span,\n type UpDownCounter,\n} from '@opentelemetry/api';\nimport { setBusLogTraceIdProvider } from '@semiont/core';\n\n// Wire `busLog`'s trace-id provider once at module load. When an OTel\n// SDK is initialized (and a span is active when `busLog` fires), the\n// emitted line gets a `trace=<8hex>` suffix that correlates the\n// grep-timeline with the trace UI. No-op when no SDK is active.\nsetBusLogTraceIdProvider(() => {\n const span = trace.getActiveSpan();\n if (!span) return undefined;\n const ctx = span.spanContext();\n if (!isSpanContextValid(ctx)) return undefined;\n return ctx.traceId;\n});\n\nconst TRACER_NAME = 'semiont';\n\nconst tracer = () => trace.getTracer(TRACER_NAME);\n\n// ── withSpan ───────────────────────────────────────────────────────────\n\n/*\n Wrap an async block in a span. The span is started before `fn` runs and\n * ended after it resolves or rejects; exceptions are recorded and the span\n * status is set to ERROR. `kind` defaults to INTERNAL.\n /\nexport async function withSpan<T>(\n name: string,\n fn: (span: Span) => Promise<T> \| T,\n options?: { kind?: SpanKind; attrs?: Attributes },\n): Promise<T> {\n const span = tracer().startSpan(name, {\n kind: options?.kind ?? SpanKind.INTERNAL,\n ...(options?.attrs ? { attributes: options.attrs } : {}),\n });\n try {\n return await context.with(trace.setSpan(context.active(), span), () => fn(span));\n } catch (err) {\n span.recordException(err as Error);\n span.setStatus({\n code: SpanStatusCode.ERROR,\n message: err instanceof Error ? err.message : String(err),\n });\n throw err;\n } finally {\n span.end();\n }\n}\n\n// ── Traceparent on bus payloads ────────────────────────────────────────\n\nconst TRACE_FIELD = '_trace';\n\n/\n Sibling of `correlationId` on bus payloads. Lives on the SSE event body\n * because SSE has no header trailer; the SDK strips it before delivering\n * the payload to subscribers. Additive — payloads without `_trace` parse\n * unchanged.\n /\nexport interface TraceCarrier {\n /* W3C `traceparent` header value (`00-<traceId>-<spanId>-<flags>`). /\n traceparent: string;\n /* W3C `tracestate` header value (vendor-specific extensions). /\n tracestate?: string;\n}\n\n/\n Read the active span's W3C traceparent (and tracestate). Returns\n * `undefined` if no span is active.\n /\nexport function getActiveTraceparent(): TraceCarrier \| undefined {\n const carrier: Record<string, string> = {};\n propagation.inject(context.active(), carrier);\n const traceparent = carrier['traceparent'];\n if (!traceparent) return undefined;\n return carrier['tracestate']\n ? { traceparent, tracestate: carrier['tracestate'] }\n : { traceparent };\n}\n\n/\n Attach the active span's trace-context to a payload object as\n * `_trace`. No-op when no span is active. Returns the same object\n * reference for chaining.\n /\nexport function injectTraceparent<T extends Record<string, unknown>>(payload: T): T {\n const carrier = getActiveTraceparent();\n if (carrier) {\n (payload as Record<string, unknown>)[TRACE_FIELD] = carrier;\n }\n return payload;\n}\n\n/\n Strip and return the `_trace` field from a payload. Mutates `payload`.\n * The field is internal plumbing and should not be visible to subscribers.\n /\nexport function extractTraceparent<T extends Record<string, unknown>>(\n payload: T,\n): TraceCarrier \| undefined {\n const carrier = (payload as Record<string, unknown>)[TRACE_FIELD] as\n \| TraceCarrier\n \| undefined;\n if (carrier !== undefined) {\n delete (payload as Record<string, unknown>)[TRACE_FIELD];\n }\n if (!carrier \|\| typeof carrier.traceparent !== 'string') return undefined;\n return carrier;\n}\n\n/\n Run `fn` with the given W3C traceparent set as the parent context.\n * Any spans started inside `fn` will be children of the incoming trace.\n * No-op if `carrier` is undefined.\n /\nexport function withTraceparent<T>(\n carrier: TraceCarrier \| undefined,\n fn: () => T,\n): T {\n if (!carrier) return fn();\n const carrierObj: Record<string, string> = { traceparent: carrier.traceparent };\n if (carrier.tracestate) carrierObj['tracestate'] = carrier.tracestate;\n const ctx = propagation.extract(context.active(), carrierObj);\n return context.with(ctx, fn);\n}\n\n// ── Actor handler convenience ──────────────────────────────────────────\n\n/\n Wrap a bus-event handler in an `actor.<name>:<channel>` consumer span.\n * Used at every `eventBus.get(channel).subscribe(handler)` site inside\n * an actor (Stower, Gatherer, Matcher, Browser, Smelter), to attribute\n * each in-process subscriber's work to a span without scattering manual\n * `withSpan` calls across handler bodies.\n \n The span's parent is the active context at the time the handler\n * fires — which is the `bus.dispatch:<channel>` span on the backend\n * (Subject.next runs synchronously inside the dispatch span), or the\n * `bus.emit:<channel>` span when an actor emits to itself.\n /\nexport async function withActorSpan<T>(\n actor: string,\n channel: string,\n fn: (span: Span) => Promise<T> \| T,\n extraAttrs?: Attributes,\n): Promise<T> {\n const start = performance.now();\n try {\n return await withSpan(`actor.${actor}:${channel}`, fn, {\n kind: SpanKind.CONSUMER,\n attrs: {\n actor,\n 'bus.channel': channel,\n ...(extraAttrs ?? {}),\n },\n });\n } finally {\n recordHandlerDuration(actor, channel, performance.now() - start);\n }\n}\n\n// ── Log correlation ────────────────────────────────────────────────────\n\n/\n Read the active span's `trace_id` / `span_id` for log-line correlation.\n * Tier 3 of `.plans/OBSERVABILITY.md`. Each structured log line gets\n * tagged with these so a log query in CloudWatch / Loki / Datadog can\n * jump to the trace in Tempo / Jaeger / X-Ray.\n \n Returns `undefined` if no span is active, or if the active span's\n * context is invalid (uninitialized SDK, no-op tracer).\n /\nexport function getLogTraceContext(): { trace_id: string; span_id: string } \| undefined {\n const span = trace.getActiveSpan();\n if (!span) return undefined;\n const ctx = span.spanContext();\n if (!isSpanContextValid(ctx)) return undefined;\n return { trace_id: ctx.traceId, span_id: ctx.spanId };\n}\n\n// ── Metrics — Tier 3 ───────────────────────────────────────────────────\n\nconst METER_NAME = 'semiont';\n\nconst meter = () => metrics.getMeter(METER_NAME);\n\nlet _busEmitCounter: Counter \| undefined;\nlet _handlerDurationHistogram: Histogram \| undefined;\nlet _jobOutcomeCounter: Counter \| undefined;\nlet _jobDurationHistogram: Histogram \| undefined;\nlet _inferenceCallsCounter: Counter \| undefined;\nlet _inferenceTokensCounter: Counter \| undefined;\nlet _inferenceDurationHistogram: Histogram \| undefined;\nlet _sseSubscribers: UpDownCounter \| undefined;\nlet _jobQueueGauge: ObservableGauge \| undefined;\nlet _jobQueueProvider: (() => Promise<JobQueueSnapshot> \| JobQueueSnapshot) \| undefined;\nlet _vectorIndexSizeGauge: ObservableGauge \| undefined;\nlet _vectorIndexSizeProvider: (() => Promise<number> \| number) \| undefined;\n\n/* Snapshot of job-queue contents by status. Match `JobQueue.getStats()`. /\nexport interface JobQueueSnapshot {\n pending: number;\n running: number;\n complete: number;\n failed: number;\n cancelled: number;\n}\n\nfunction busEmitCounter(): Counter {\n if (!_busEmitCounter) {\n _busEmitCounter = meter().createCounter('semiont.bus.emit', {\n description: 'Bus emits by channel and scope',\n });\n }\n return _busEmitCounter;\n}\n\nfunction handlerDurationHistogram(): Histogram {\n if (!_handlerDurationHistogram) {\n _handlerDurationHistogram = meter().createHistogram('semiont.handler.duration', {\n description: 'In-process actor handler duration',\n unit: 'ms',\n });\n }\n return _handlerDurationHistogram;\n}\n\nfunction jobOutcomeCounter(): Counter {\n if (!_jobOutcomeCounter) {\n _jobOutcomeCounter = meter().createCounter('semiont.job.outcome', {\n description: 'Worker job completions by type and outcome',\n });\n }\n return _jobOutcomeCounter;\n}\n\nfunction jobDurationHistogram(): Histogram {\n if (!_jobDurationHistogram) {\n _jobDurationHistogram = meter().createHistogram('semiont.job.duration', {\n description: 'Worker job duration by type',\n unit: 'ms',\n });\n }\n return _jobDurationHistogram;\n}\n\nfunction inferenceCallsCounter(): Counter {\n if (!_inferenceCallsCounter) {\n _inferenceCallsCounter = meter().createCounter('semiont.inference.calls', {\n description: 'Inference API calls by provider, model, and outcome',\n });\n }\n return _inferenceCallsCounter;\n}\n\nfunction inferenceTokensCounter(): Counter {\n if (!_inferenceTokensCounter) {\n _inferenceTokensCounter = meter().createCounter('semiont.inference.tokens', {\n description: 'Inference token usage by provider, model, and direction',\n });\n }\n return _inferenceTokensCounter;\n}\n\nfunction inferenceDurationHistogram(): Histogram {\n if (!_inferenceDurationHistogram) {\n _inferenceDurationHistogram = meter().createHistogram('semiont.inference.duration', {\n description: 'Inference call duration by provider, model, and outcome',\n unit: 'ms',\n });\n }\n return _inferenceDurationHistogram;\n}\n\nfunction sseSubscribersCounter(): UpDownCounter {\n if (!_sseSubscribers) {\n _sseSubscribers = meter().createUpDownCounter('semiont.sse.subscribers', {\n description: 'Active SSE subscribers',\n });\n }\n return _sseSubscribers;\n}\n\n/* Increment the bus-emit counter. Called at every transport `emit` site. /\nexport function recordBusEmit(channel: string, scope?: string): void {\n busEmitCounter().add(1, {\n 'bus.channel': channel,\n ...(scope ? { 'bus.scope': scope } : {}),\n });\n}\n\n/* Record an in-process actor handler's duration. /\nexport function recordHandlerDuration(actor: string, channel: string, durationMs: number): void {\n handlerDurationHistogram().record(durationMs, {\n actor,\n 'bus.channel': channel,\n });\n}\n\n/* Record a worker job's outcome and duration. /\nexport function recordJobOutcome(jobType: string, outcome: 'completed' \| 'failed', durationMs: number): void {\n jobOutcomeCounter().add(1, { 'job.type': jobType, 'job.outcome': outcome });\n jobDurationHistogram().record(durationMs, { 'job.type': jobType, 'job.outcome': outcome });\n}\n\n/* Increment the SSE subscriber gauge — call on `/bus/subscribe` open. /\nexport function recordSubscriberConnect(): void {\n sseSubscribersCounter().add(1);\n}\n\n/* Decrement on disconnect. Pair with `recordSubscriberConnect`. /\nexport function recordSubscriberDisconnect(): void {\n sseSubscribersCounter().add(-1);\n}\n\n/\n Register a callback that returns the current job-queue snapshot.\n * Polled at the SDK's metric-collection interval. The single gauge\n * emits one observation per status (`pending`, `running`, …) tagged\n * with the `job.status` attribute. Idempotent — last registered\n * provider wins.\n /\nexport function registerJobQueueProvider(\n provider: () => Promise<JobQueueSnapshot> \| JobQueueSnapshot,\n): void {\n _jobQueueProvider = provider;\n if (!_jobQueueGauge) {\n _jobQueueGauge = meter().createObservableGauge('semiont.job.queue.size', {\n description: 'Job queue size by status',\n });\n _jobQueueGauge.addCallback(async (observer) => {\n if (!_jobQueueProvider) return;\n const snap = await _jobQueueProvider();\n observer.observe(snap.pending, { 'job.status': 'pending' });\n observer.observe(snap.running, { 'job.status': 'running' });\n observer.observe(snap.complete, { 'job.status': 'complete' });\n observer.observe(snap.failed, { 'job.status': 'failed' });\n observer.observe(snap.cancelled, { 'job.status': 'cancelled' });\n });\n }\n}\n\n/\n Register a callback that returns the current vector-index size\n * (point count). Async to allow remote queries (Qdrant). Polled at\n * the metric-collection interval.\n /\nexport function registerVectorIndexSizeProvider(\n provider: () => Promise<number> \| number,\n): void {\n _vectorIndexSizeProvider = provider;\n if (!_vectorIndexSizeGauge) {\n _vectorIndexSizeGauge = meter().createObservableGauge('semiont.vector.index.size', {\n description: 'Vector store point count',\n });\n _vectorIndexSizeGauge.addCallback(async (observer) => {\n if (_vectorIndexSizeProvider) {\n const value = await _vectorIndexSizeProvider();\n observer.observe(value);\n }\n });\n }\n}\n\n/\n Record an inference call. Token counts are optional — providers that\n * don't expose them (or fail before generating) record only call count\n * and duration.\n */\nexport function recordInferenceUsage(opts: {\n provider: string;\n model: string;\n durationMs: number;\n outcome: 'success' \| 'error';\n inputTokens?: number;\n outputTokens?: number;\n}): void {\n const baseAttrs = {\n 'inference.provider': opts.provider,\n 'inference.model': opts.model,\n 'inference.outcome': opts.outcome,\n };\n inferenceCallsCounter().add(1, baseAttrs);\n inferenceDurationHistogram().record(opts.durationMs, baseAttrs);\n if (opts.inputTokens != null && opts.inputTokens > 0) {\n inferenceTokensCounter().add(opts.inputTokens, {\n 'inference.provider': opts.provider,\n 'inference.model': opts.model,\n 'inference.direction': 'input',\n });\n }\n if (opts.outputTokens != null && opts.outputTokens > 0) {\n inferenceTokensCounter().add(opts.outputTokens, {\n 'inference.provider': opts.provider,\n 'inference.model': opts.model,\n 'inference.direction': 'output',\n });\n }\n}\n\n// ── Re-exports from @opentelemetry/api ─────────────────────────────────\n\nexport { SpanKind, SpanStatusCode, type Attributes, type Span } from '@opentelemetry/api';\n"]}

package/dist/process-logger.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"sources":["../src/index.ts","../src/process-logger.ts"],"names":["trace"],"mappings":";;;;;AA6CA,wBAAA,CAAyB,MAAM;AAC7B,EAAA,MAAM,IAAA,GAAO,MAAM,aAAA,EAAc;AACjC,EAAA,IAAI,CAAC,MAAM,OAAO,MAAA;AAClB,EAAA,MAAM,GAAA,GAAM,KAAK,WAAA,EAAY;AAC7B,EAAA,IAAI,CAAC,kBAAA,CAAmB,GAAG,CAAA,EAAG,OAAO,MAAA;AACrC,EAAA,OAAO,GAAA,CAAI,OAAA;AACb,CAAC,CAAA;AA+JM,SAAS,kBAAA,GAAwE;AACtF,EAAA,MAAM,IAAA,GAAO,MAAM,aAAA,EAAc;AACjC,EAAA,IAAI,CAAC,MAAM,OAAO,MAAA;AAClB,EAAA,MAAM,GAAA,GAAM,KAAK,WAAA,EAAY;AAC7B,EAAA,IAAI,CAAC,kBAAA,CAAmB,GAAG,CAAA,EAAG,OAAO,MAAA;AACrC,EAAA,OAAO,EAAE,QAAA,EAAU,GAAA,CAAI,OAAA,EAAS,OAAA,EAAS,IAAI,MAAA,EAAO;AACtD;;;AClMA,IAAM,kBAAA,GAAqB,OAAA,CAAQ,MAAA,CAAO,CAAC,IAAA,KAAS;AAClD,EAAA,MAAMA,SAAQ,kBAAA,EAAmB;AACjC,EAAA,IAAIA,MAAAA,EAAO;AACT,IAAA,IAAA,CAAK,WAAWA,MAAAA,CAAM,QAAA;AACtB,IAAA,IAAA,CAAK,UAAUA,MAAAA,CAAM,OAAA;AAAA,EACvB;AACA,EAAA,OAAO,IAAA;AACT,CAAC,CAAA,EAAE;AAEI,SAAS,oBAAoB,SAAA,EAA2B;AAC7D,EAAA,MAAM,KAAA,GAAQ,OAAA,CAAQ,GAAA,CAAI,SAAA,IAAa,MAAA;AACvC,EAAA,MAAM,SAAS,OAAA,CAAQ,GAAA,CAAI,UAAA,KAAe,QAAA,GACtC,QAAQ,MAAA,CAAO,OAAA;AAAA,IACb,QAAQ,MAAA,CAAO,SAAA,CAAU,EAAE,MAAA,EAAQ,uBAAuB,CAAA;AAAA,IAC1D,QAAQ,MAAA,CAAO,MAAA,CAAO,EAAE,KAAA,EAAO,MAAM,CAAA;AAAA,IACrC,kBAAA;AAAA,IACA,OAAA,CAAQ,MAAA,CAAO,MAAA,CAAO,CAAC,EAAE,KAAA,EAAO,GAAA,EAAK,OAAA,EAAS,SAAA,EAAW,GAAG,IAAA,EAAK,KAAM;AACrE,MAAA,MAAM,OAAA,GAAU,MAAA,CAAO,IAAA,CAAK,IAAI,CAAA,CAAE,MAAA,GAAS,CAAA,GAAI,CAAA,CAAA,EAAI,IAAA,CAAK,SAAA,CAAU,IAAI,CAAC,CAAA,CAAA,GAAK,EAAA;AAC5E,MAAA,OAAO,CAAA,EAAG,SAAS,CAAA,EAAA,EAAK,GAAA,CAAI,WAAA,EAAa,CAAA,GAAA,EAAM,SAAS,CAAA,EAAA,EAAK,OAAO,CAAA,EAAG,OAAO,CAAA,CAAA;AAAA,IAChF,CAAC;AAAA,GACH,GACA,QAAQ,MAAA,CAAO,OAAA;AAAA,IACb,OAAA,CAAQ,OAAO,SAAA,EAAU;AAAA,IACzB,QAAQ,MAAA,CAAO,MAAA,CAAO,EAAE,KAAA,EAAO,MAAM,CAAA;AAAA,IACrC,kBAAA;AAAA,IACA,OAAA,CAAQ,OAAO,IAAA;AAAK,GACtB;AAEJ,EAAA,MAAM,MAAA,GAAS,QAAQ,YAAA,CAAa;AAAA,IAClC,KAAA;AAAA,IACA,WAAA,EAAa,EAAE,SAAA,EAAU;AAAA,IACzB,MAAA;AAAA,IACA,YAAY,CAAC,IAAI,OAAA,CAAQ,UAAA,CAAW,SAAS;AAAA,GAC9C,CAAA;AAED,EAAA,OAAO,MAAA;AACT","file":"process-logger.js","sourcesContent":["/*\n @semiont/observability — public API.\n \n Universal surface (works in Node + browser). For SDK initialization,\n * import from `@semiont/observability/node` or `/web` at the process entry\n * point. Everything else uses this module.\n \n Tier 2 of `.plans/OBSERVABILITY.md`. The public surface is intentionally\n * thin:\n \n - `withSpan(name, fn, attrs?)` — wrap an async block in a span.\n * - `injectTraceparent(payload)` / `extractTraceparent(value)` — W3C\n * trace-context propagation across the SSE channel (the bus payload\n * gets a `_trace?: { traceparent }` sibling to `correlationId`).\n * - `setSpanContextFromTraceparent(traceparent, fn)` — set incoming\n * traceparent as the parent context for a synchronous block.\n * - `getActiveTraceparent()` — read the active span's traceparent for\n * manual propagation (e.g. attaching to a fetch header or SSE field).\n \n No-op when no exporter is configured: `@opentelemetry/api`'s default\n * tracer is a no-op, so `withSpan` is essentially free until\n * `initObservability()` runs.\n /\n\nimport {\n context,\n isSpanContextValid,\n metrics,\n propagation,\n SpanKind,\n SpanStatusCode,\n trace,\n type Attributes,\n type Counter,\n type Histogram,\n type ObservableGauge,\n type Span,\n type UpDownCounter,\n} from '@opentelemetry/api';\nimport { setBusLogTraceIdProvider } from '@semiont/core';\n\n// Wire `busLog`'s trace-id provider once at module load. When an OTel\n// SDK is initialized (and a span is active when `busLog` fires), the\n// emitted line gets a `trace=<8hex>` suffix that correlates the\n// grep-timeline with the trace UI. No-op when no SDK is active.\nsetBusLogTraceIdProvider(() => {\n const span = trace.getActiveSpan();\n if (!span) return undefined;\n const ctx = span.spanContext();\n if (!isSpanContextValid(ctx)) return undefined;\n return ctx.traceId;\n});\n\nconst TRACER_NAME = 'semiont';\n\nconst tracer = () => trace.getTracer(TRACER_NAME);\n\n// ── withSpan ───────────────────────────────────────────────────────────\n\n/*\n Wrap an async block in a span. The span is started before `fn` runs and\n * ended after it resolves or rejects; exceptions are recorded and the span\n * status is set to ERROR. `kind` defaults to INTERNAL.\n /\nexport async function withSpan<T>(\n name: string,\n fn: (span: Span) => Promise<T> \| T,\n options?: { kind?: SpanKind; attrs?: Attributes },\n): Promise<T> {\n const span = tracer().startSpan(name, {\n kind: options?.kind ?? SpanKind.INTERNAL,\n ...(options?.attrs ? { attributes: options.attrs } : {}),\n });\n try {\n return await context.with(trace.setSpan(context.active(), span), () => fn(span));\n } catch (err) {\n span.recordException(err as Error);\n span.setStatus({\n code: SpanStatusCode.ERROR,\n message: err instanceof Error ? err.message : String(err),\n });\n throw err;\n } finally {\n span.end();\n }\n}\n\n// ── Traceparent on bus payloads ────────────────────────────────────────\n\nconst TRACE_FIELD = '_trace';\n\n/\n Sibling of `correlationId` on bus payloads. Lives on the SSE event body\n * because SSE has no header trailer; the SDK strips it before delivering\n * the payload to subscribers. Additive — payloads without `_trace` parse\n * unchanged.\n /\nexport interface TraceCarrier {\n /* W3C `traceparent` header value (`00-<traceId>-<spanId>-<flags>`). /\n traceparent: string;\n /* W3C `tracestate` header value (vendor-specific extensions). /\n tracestate?: string;\n}\n\n/\n Read the active span's W3C traceparent (and tracestate). Returns\n * `undefined` if no span is active.\n /\nexport function getActiveTraceparent(): TraceCarrier \| undefined {\n const carrier: Record<string, string> = {};\n propagation.inject(context.active(), carrier);\n const traceparent = carrier['traceparent'];\n if (!traceparent) return undefined;\n return carrier['tracestate']\n ? { traceparent, tracestate: carrier['tracestate'] }\n : { traceparent };\n}\n\n/\n Attach the active span's trace-context to a payload object as\n * `_trace`. No-op when no span is active. Returns the same object\n * reference for chaining.\n /\nexport function injectTraceparent<T extends Record<string, unknown>>(payload: T): T {\n const carrier = getActiveTraceparent();\n if (carrier) {\n (payload as Record<string, unknown>)[TRACE_FIELD] = carrier;\n }\n return payload;\n}\n\n/\n Strip and return the `_trace` field from a payload. Mutates `payload`.\n * The field is internal plumbing and should not be visible to subscribers.\n /\nexport function extractTraceparent<T extends Record<string, unknown>>(\n payload: T,\n): TraceCarrier \| undefined {\n const carrier = (payload as Record<string, unknown>)[TRACE_FIELD] as\n \| TraceCarrier\n \| undefined;\n if (carrier !== undefined) {\n delete (payload as Record<string, unknown>)[TRACE_FIELD];\n }\n if (!carrier \|\| typeof carrier.traceparent !== 'string') return undefined;\n return carrier;\n}\n\n/\n Run `fn` with the given W3C traceparent set as the parent context.\n * Any spans started inside `fn` will be children of the incoming trace.\n * No-op if `carrier` is undefined.\n /\nexport function withTraceparent<T>(\n carrier: TraceCarrier \| undefined,\n fn: () => T,\n): T {\n if (!carrier) return fn();\n const carrierObj: Record<string, string> = { traceparent: carrier.traceparent };\n if (carrier.tracestate) carrierObj['tracestate'] = carrier.tracestate;\n const ctx = propagation.extract(context.active(), carrierObj);\n return context.with(ctx, fn);\n}\n\n// ── Actor handler convenience ──────────────────────────────────────────\n\n/\n Wrap a bus-event handler in an `actor.<name>:<channel>` consumer span.\n * Used at every `eventBus.get(channel).subscribe(handler)` site inside\n * an actor (Stower, Gatherer, Matcher, Browser, Smelter), to attribute\n * each in-process subscriber's work to a span without scattering manual\n * `withSpan` calls across handler bodies.\n \n The span's parent is the active context at the time the handler\n * fires — which is the `bus.dispatch:<channel>` span on the backend\n * (Subject.next runs synchronously inside the dispatch span), or the\n * `bus.emit:<channel>` span when an actor emits to itself.\n /\nexport async function withActorSpan<T>(\n actor: string,\n channel: string,\n fn: (span: Span) => Promise<T> \| T,\n extraAttrs?: Attributes,\n): Promise<T> {\n const start = performance.now();\n try {\n return await withSpan(`actor.${actor}:${channel}`, fn, {\n kind: SpanKind.CONSUMER,\n attrs: {\n actor,\n 'bus.channel': channel,\n ...(extraAttrs ?? {}),\n },\n });\n } finally {\n recordHandlerDuration(actor, channel, performance.now() - start);\n }\n}\n\n// ── Log correlation ────────────────────────────────────────────────────\n\n/\n Read the active span's `trace_id` / `span_id` for log-line correlation.\n * Tier 3 of `.plans/OBSERVABILITY.md`. Each structured log line gets\n * tagged with these so a log query in CloudWatch / Loki / Datadog can\n * jump to the trace in Tempo / Jaeger / X-Ray.\n \n Returns `undefined` if no span is active, or if the active span's\n * context is invalid (uninitialized SDK, no-op tracer).\n /\nexport function getLogTraceContext(): { trace_id: string; span_id: string } \| undefined {\n const span = trace.getActiveSpan();\n if (!span) return undefined;\n const ctx = span.spanContext();\n if (!isSpanContextValid(ctx)) return undefined;\n return { trace_id: ctx.traceId, span_id: ctx.spanId };\n}\n\n// ── Metrics — Tier 3 ───────────────────────────────────────────────────\n\nconst METER_NAME = 'semiont';\n\nconst meter = () => metrics.getMeter(METER_NAME);\n\nlet _busEmitCounter: Counter \| undefined;\nlet _handlerDurationHistogram: Histogram \| undefined;\nlet _jobOutcomeCounter: Counter \| undefined;\nlet _jobDurationHistogram: Histogram \| undefined;\nlet _inferenceCallsCounter: Counter \| undefined;\nlet _inferenceTokensCounter: Counter \| undefined;\nlet _inferenceDurationHistogram: Histogram \| undefined;\nlet _sseSubscribers: UpDownCounter \| undefined;\nlet _jobQueueGauge: ObservableGauge \| undefined;\nlet _jobQueueProvider: (() => Promise<JobQueueSnapshot> \| JobQueueSnapshot) \| undefined;\nlet _vectorIndexSizeGauge: ObservableGauge \| undefined;\nlet _vectorIndexSizeProvider: (() => Promise<number> \| number) \| undefined;\n\n/* Snapshot of job-queue contents by status. Match `JobQueue.getStats()`. /\nexport interface JobQueueSnapshot {\n pending: number;\n running: number;\n complete: number;\n failed: number;\n cancelled: number;\n}\n\nfunction busEmitCounter(): Counter {\n if (!_busEmitCounter) {\n _busEmitCounter = meter().createCounter('semiont.bus.emit', {\n description: 'Bus emits by channel and scope',\n });\n }\n return _busEmitCounter;\n}\n\nfunction handlerDurationHistogram(): Histogram {\n if (!_handlerDurationHistogram) {\n _handlerDurationHistogram = meter().createHistogram('semiont.handler.duration', {\n description: 'In-process actor handler duration',\n unit: 'ms',\n });\n }\n return _handlerDurationHistogram;\n}\n\nfunction jobOutcomeCounter(): Counter {\n if (!_jobOutcomeCounter) {\n _jobOutcomeCounter = meter().createCounter('semiont.job.outcome', {\n description: 'Worker job completions by type and outcome',\n });\n }\n return _jobOutcomeCounter;\n}\n\nfunction jobDurationHistogram(): Histogram {\n if (!_jobDurationHistogram) {\n _jobDurationHistogram = meter().createHistogram('semiont.job.duration', {\n description: 'Worker job duration by type',\n unit: 'ms',\n });\n }\n return _jobDurationHistogram;\n}\n\nfunction inferenceCallsCounter(): Counter {\n if (!_inferenceCallsCounter) {\n _inferenceCallsCounter = meter().createCounter('semiont.inference.calls', {\n description: 'Inference API calls by provider, model, and outcome',\n });\n }\n return _inferenceCallsCounter;\n}\n\nfunction inferenceTokensCounter(): Counter {\n if (!_inferenceTokensCounter) {\n _inferenceTokensCounter = meter().createCounter('semiont.inference.tokens', {\n description: 'Inference token usage by provider, model, and direction',\n });\n }\n return _inferenceTokensCounter;\n}\n\nfunction inferenceDurationHistogram(): Histogram {\n if (!_inferenceDurationHistogram) {\n _inferenceDurationHistogram = meter().createHistogram('semiont.inference.duration', {\n description: 'Inference call duration by provider, model, and outcome',\n unit: 'ms',\n });\n }\n return _inferenceDurationHistogram;\n}\n\nfunction sseSubscribersCounter(): UpDownCounter {\n if (!_sseSubscribers) {\n _sseSubscribers = meter().createUpDownCounter('semiont.sse.subscribers', {\n description: 'Active SSE subscribers',\n });\n }\n return _sseSubscribers;\n}\n\n/* Increment the bus-emit counter. Called at every transport `emit` site. /\nexport function recordBusEmit(channel: string, scope?: string): void {\n busEmitCounter().add(1, {\n 'bus.channel': channel,\n ...(scope ? { 'bus.scope': scope } : {}),\n });\n}\n\n/* Record an in-process actor handler's duration. /\nexport function recordHandlerDuration(actor: string, channel: string, durationMs: number): void {\n handlerDurationHistogram().record(durationMs, {\n actor,\n 'bus.channel': channel,\n });\n}\n\n/* Record a worker job's outcome and duration. /\nexport function recordJobOutcome(jobType: string, outcome: 'completed' \| 'failed', durationMs: number): void {\n jobOutcomeCounter().add(1, { 'job.type': jobType, 'job.outcome': outcome });\n jobDurationHistogram().record(durationMs, { 'job.type': jobType, 'job.outcome': outcome });\n}\n\n/* Increment the SSE subscriber gauge — call on `/bus/subscribe` open. /\nexport function recordSubscriberConnect(): void {\n sseSubscribersCounter().add(1);\n}\n\n/* Decrement on disconnect. Pair with `recordSubscriberConnect`. /\nexport function recordSubscriberDisconnect(): void {\n sseSubscribersCounter().add(-1);\n}\n\n/\n Register a callback that returns the current job-queue snapshot.\n * Polled at the SDK's metric-collection interval. The single gauge\n * emits one observation per status (`pending`, `running`, …) tagged\n * with the `job.status` attribute. Idempotent — last registered\n * provider wins.\n /\nexport function registerJobQueueProvider(\n provider: () => Promise<JobQueueSnapshot> \| JobQueueSnapshot,\n): void {\n _jobQueueProvider = provider;\n if (!_jobQueueGauge) {\n _jobQueueGauge = meter().createObservableGauge('semiont.job.queue.size', {\n description: 'Job queue size by status',\n });\n _jobQueueGauge.addCallback(async (observer) => {\n if (!_jobQueueProvider) return;\n const snap = await _jobQueueProvider();\n observer.observe(snap.pending, { 'job.status': 'pending' });\n observer.observe(snap.running, { 'job.status': 'running' });\n observer.observe(snap.complete, { 'job.status': 'complete' });\n observer.observe(snap.failed, { 'job.status': 'failed' });\n observer.observe(snap.cancelled, { 'job.status': 'cancelled' });\n });\n }\n}\n\n/\n Register a callback that returns the current vector-index size\n * (point count). Async to allow remote queries (Qdrant). Polled at\n * the metric-collection interval.\n /\nexport function registerVectorIndexSizeProvider(\n provider: () => Promise<number> \| number,\n): void {\n _vectorIndexSizeProvider = provider;\n if (!_vectorIndexSizeGauge) {\n _vectorIndexSizeGauge = meter().createObservableGauge('semiont.vector.index.size', {\n description: 'Vector store point count',\n });\n _vectorIndexSizeGauge.addCallback(async (observer) => {\n if (_vectorIndexSizeProvider) {\n const value = await _vectorIndexSizeProvider();\n observer.observe(value);\n }\n });\n }\n}\n\n/\n Record an inference call. Token counts are optional — providers that\n * don't expose them (or fail before generating) record only call count\n * and duration.\n /\nexport function recordInferenceUsage(opts: {\n provider: string;\n model: string;\n durationMs: number;\n outcome: 'success' \| 'error';\n inputTokens?: number;\n outputTokens?: number;\n}): void {\n const baseAttrs = {\n 'inference.provider': opts.provider,\n 'inference.model': opts.model,\n 'inference.outcome': opts.outcome,\n };\n inferenceCallsCounter().add(1, baseAttrs);\n inferenceDurationHistogram().record(opts.durationMs, baseAttrs);\n if (opts.inputTokens != null && opts.inputTokens > 0) {\n inferenceTokensCounter().add(opts.inputTokens, {\n 'inference.provider': opts.provider,\n 'inference.model': opts.model,\n 'inference.direction': 'input',\n });\n }\n if (opts.outputTokens != null && opts.outputTokens > 0) {\n inferenceTokensCounter().add(opts.outputTokens, {\n 'inference.provider': opts.provider,\n 'inference.model': opts.model,\n 'inference.direction': 'output',\n });\n }\n}\n\n// ── Re-exports from @opentelemetry/api ─────────────────────────────────\n\nexport { SpanKind, SpanStatusCode, type Attributes, type Span } from '@opentelemetry/api';\n","/\n Process-level structured logger for Node entry points.\n \n Used by long-lived Node processes (backend, workers, smelter) that\n * want JSON-structured stdout with active-span trace correlation. The\n * `trace_id` / `span_id` fields are populated from the current OTel\n * span context via `getLogTraceContext` — this is the same Tier 3\n * correlation that lets a grep through stdout line up with the trace\n * UI without manual stitching.\n \n Reads `LOG_LEVEL` (default `info`) and `LOG_FORMAT` (`json` default,\n * `simple` for human-friendly dev output).\n \n Co-located with `getLogTraceContext` deliberately: this is the\n * only reasonably-shaped consumer of that helper, and putting them in\n * the same package keeps the trace-id wiring in one place.\n */\n\nimport winston from 'winston';\nimport type { Logger } from '@semiont/core';\nimport { getLogTraceContext } from './index.js';\n\nconst traceContextFormat = winston.format((info) => {\n const trace = getLogTraceContext();\n if (trace) {\n info.trace_id = trace.trace_id;\n info.span_id = trace.span_id;\n }\n return info;\n})();\n\nexport function createProcessLogger(component: string): Logger {\n const level = process.env.LOG_LEVEL ?? 'info';\n const format = process.env.LOG_FORMAT === 'simple'\n ? winston.format.combine(\n winston.format.timestamp({ format: 'YYYY-MM-DD HH:mm:ss' }),\n winston.format.errors({ stack: true }),\n traceContextFormat,\n winston.format.printf(({ level: lvl, message, timestamp, ...meta }) => {\n const metaStr = Object.keys(meta).length > 0 ? ` ${JSON.stringify(meta)}` : '';\n return `${timestamp} [${lvl.toUpperCase()}] [${component}] ${message}${metaStr}`;\n }),\n )\n : winston.format.combine(\n winston.format.timestamp(),\n winston.format.errors({ stack: true }),\n traceContextFormat,\n winston.format.json(),\n );\n\n const logger = winston.createLogger({\n level,\n defaultMeta: { component },\n format,\n transports: [new winston.transports.Console()],\n });\n\n return logger as unknown as Logger;\n}\n"]}
1	+ {"version":3,"sources":["../src/index.ts","../src/process-logger.ts"],"names":["trace"],"mappings":";;;;;AAqDA,wBAAA,CAAyB,MAAM;AAC7B,EAAA,MAAM,IAAA,GAAO,MAAM,aAAA,EAAc;AACjC,EAAA,IAAI,CAAC,MAAM,OAAO,MAAA;AAClB,EAAA,MAAM,GAAA,GAAM,KAAK,WAAA,EAAY;AAC7B,EAAA,IAAI,CAAC,kBAAA,CAAmB,GAAG,CAAA,EAAG,OAAO,MAAA;AACrC,EAAA,OAAO,GAAA,CAAI,OAAA;AACb,CAAC,CAAA;AA+JM,SAAS,kBAAA,GAAwE;AACtF,EAAA,MAAM,IAAA,GAAO,MAAM,aAAA,EAAc;AACjC,EAAA,IAAI,CAAC,MAAM,OAAO,MAAA;AAClB,EAAA,MAAM,GAAA,GAAM,KAAK,WAAA,EAAY;AAC7B,EAAA,IAAI,CAAC,kBAAA,CAAmB,GAAG,CAAA,EAAG,OAAO,MAAA;AACrC,EAAA,OAAO,EAAE,QAAA,EAAU,GAAA,CAAI,OAAA,EAAS,OAAA,EAAS,IAAI,MAAA,EAAO;AACtD;;;AC1MA,IAAM,kBAAA,GAAqB,OAAA,CAAQ,MAAA,CAAO,CAAC,IAAA,KAAS;AAClD,EAAA,MAAMA,SAAQ,kBAAA,EAAmB;AACjC,EAAA,IAAIA,MAAAA,EAAO;AACT,IAAA,IAAA,CAAK,WAAWA,MAAAA,CAAM,QAAA;AACtB,IAAA,IAAA,CAAK,UAAUA,MAAAA,CAAM,OAAA;AAAA,EACvB;AACA,EAAA,OAAO,IAAA;AACT,CAAC,CAAA,EAAE;AAEI,SAAS,oBAAoB,SAAA,EAA2B;AAC7D,EAAA,MAAM,KAAA,GAAQ,OAAA,CAAQ,GAAA,CAAI,SAAA,IAAa,MAAA;AACvC,EAAA,MAAM,SAAS,OAAA,CAAQ,GAAA,CAAI,UAAA,KAAe,QAAA,GACtC,QAAQ,MAAA,CAAO,OAAA;AAAA,IACb,QAAQ,MAAA,CAAO,SAAA,CAAU,EAAE,MAAA,EAAQ,uBAAuB,CAAA;AAAA,IAC1D,QAAQ,MAAA,CAAO,MAAA,CAAO,EAAE,KAAA,EAAO,MAAM,CAAA;AAAA,IACrC,kBAAA;AAAA,IACA,OAAA,CAAQ,MAAA,CAAO,MAAA,CAAO,CAAC,EAAE,KAAA,EAAO,GAAA,EAAK,OAAA,EAAS,SAAA,EAAW,GAAG,IAAA,EAAK,KAAM;AACrE,MAAA,MAAM,OAAA,GAAU,MAAA,CAAO,IAAA,CAAK,IAAI,CAAA,CAAE,MAAA,GAAS,CAAA,GAAI,CAAA,CAAA,EAAI,IAAA,CAAK,SAAA,CAAU,IAAI,CAAC,CAAA,CAAA,GAAK,EAAA;AAC5E,MAAA,OAAO,CAAA,EAAG,SAAS,CAAA,EAAA,EAAK,GAAA,CAAI,WAAA,EAAa,CAAA,GAAA,EAAM,SAAS,CAAA,EAAA,EAAK,OAAO,CAAA,EAAG,OAAO,CAAA,CAAA;AAAA,IAChF,CAAC;AAAA,GACH,GACA,QAAQ,MAAA,CAAO,OAAA;AAAA,IACb,OAAA,CAAQ,OAAO,SAAA,EAAU;AAAA,IACzB,QAAQ,MAAA,CAAO,MAAA,CAAO,EAAE,KAAA,EAAO,MAAM,CAAA;AAAA,IACrC,kBAAA;AAAA,IACA,OAAA,CAAQ,OAAO,IAAA;AAAK,GACtB;AAEJ,EAAA,MAAM,MAAA,GAAS,QAAQ,YAAA,CAAa;AAAA,IAClC,KAAA;AAAA,IACA,WAAA,EAAa,EAAE,SAAA,EAAU;AAAA,IACzB,MAAA;AAAA,IACA,YAAY,CAAC,IAAI,OAAA,CAAQ,UAAA,CAAW,SAAS;AAAA,GAC9C,CAAA;AAED,EAAA,OAAO,MAAA;AACT","file":"process-logger.js","sourcesContent":["/*\n @semiont/observability — public API.\n \n Universal surface (works in Node + browser). For SDK initialization,\n * import from `@semiont/observability/node` or `/web` at the process entry\n * point. Everything else uses this module.\n \n Tier 2 of `.plans/OBSERVABILITY.md`. The public surface:\n \n - `withSpan(name, fn, options?)` — wrap an async block in a span;\n * `options` carries `kind` and `attrs`.\n * - `withActorSpan(actor, channel, fn, extraAttrs?)` — consumer-span\n * wrapper for bus-event handlers, with handler-duration recording.\n * - `injectTraceparent(payload)` / `extractTraceparent(payload)` — W3C\n * trace-context propagation across the SSE channel (the bus payload\n * gets a `_trace?: { traceparent }` sibling to `correlationId`).\n * - `withTraceparent(carrier, fn)` — run `fn` with the incoming\n * traceparent as the parent context.\n * - `getActiveTraceparent()` — read the active span's traceparent for\n * manual propagation (e.g. attaching to a fetch header or SSE field).\n * - `getLogTraceContext()` — active `trace_id` / `span_id` for log-line\n * correlation.\n * - Metric recorders (`recordBusEmit`, `recordHandlerDuration`,\n * `recordJobOutcome`, `recordSubscriberConnect` / `Disconnect`,\n * `recordInferenceUsage`) and gauge providers\n * (`registerJobQueueProvider`, `registerVectorIndexSizeProvider`).\n \n No-op when no exporter is configured: `@opentelemetry/api`'s default\n * tracer is a no-op, so `withSpan` is essentially free until\n * `initObservability()` runs.\n /\n\nimport {\n context,\n isSpanContextValid,\n metrics,\n propagation,\n SpanKind,\n SpanStatusCode,\n trace,\n type Attributes,\n type Counter,\n type Histogram,\n type ObservableGauge,\n type Span,\n type UpDownCounter,\n} from '@opentelemetry/api';\nimport { setBusLogTraceIdProvider } from '@semiont/core';\n\n// Wire `busLog`'s trace-id provider once at module load. When an OTel\n// SDK is initialized (and a span is active when `busLog` fires), the\n// emitted line gets a `trace=<8hex>` suffix that correlates the\n// grep-timeline with the trace UI. No-op when no SDK is active.\nsetBusLogTraceIdProvider(() => {\n const span = trace.getActiveSpan();\n if (!span) return undefined;\n const ctx = span.spanContext();\n if (!isSpanContextValid(ctx)) return undefined;\n return ctx.traceId;\n});\n\nconst TRACER_NAME = 'semiont';\n\nconst tracer = () => trace.getTracer(TRACER_NAME);\n\n// ── withSpan ───────────────────────────────────────────────────────────\n\n/*\n Wrap an async block in a span. The span is started before `fn` runs and\n * ended after it resolves or rejects; exceptions are recorded and the span\n * status is set to ERROR. `kind` defaults to INTERNAL.\n /\nexport async function withSpan<T>(\n name: string,\n fn: (span: Span) => Promise<T> \| T,\n options?: { kind?: SpanKind; attrs?: Attributes },\n): Promise<T> {\n const span = tracer().startSpan(name, {\n kind: options?.kind ?? SpanKind.INTERNAL,\n ...(options?.attrs ? { attributes: options.attrs } : {}),\n });\n try {\n return await context.with(trace.setSpan(context.active(), span), () => fn(span));\n } catch (err) {\n span.recordException(err as Error);\n span.setStatus({\n code: SpanStatusCode.ERROR,\n message: err instanceof Error ? err.message : String(err),\n });\n throw err;\n } finally {\n span.end();\n }\n}\n\n// ── Traceparent on bus payloads ────────────────────────────────────────\n\nconst TRACE_FIELD = '_trace';\n\n/\n Sibling of `correlationId` on bus payloads. Lives on the SSE event body\n * because SSE has no header trailer; the SDK strips it before delivering\n * the payload to subscribers. Additive — payloads without `_trace` parse\n * unchanged.\n /\nexport interface TraceCarrier {\n /* W3C `traceparent` header value (`00-<traceId>-<spanId>-<flags>`). /\n traceparent: string;\n /* W3C `tracestate` header value (vendor-specific extensions). /\n tracestate?: string;\n}\n\n/\n Read the active span's W3C traceparent (and tracestate). Returns\n * `undefined` if no span is active.\n /\nexport function getActiveTraceparent(): TraceCarrier \| undefined {\n const carrier: Record<string, string> = {};\n propagation.inject(context.active(), carrier);\n const traceparent = carrier['traceparent'];\n if (!traceparent) return undefined;\n return carrier['tracestate']\n ? { traceparent, tracestate: carrier['tracestate'] }\n : { traceparent };\n}\n\n/\n Attach the active span's trace-context to a payload object as\n * `_trace`. No-op when no span is active. Returns the same object\n * reference for chaining.\n /\nexport function injectTraceparent<T extends Record<string, unknown>>(payload: T): T {\n const carrier = getActiveTraceparent();\n if (carrier) {\n (payload as Record<string, unknown>)[TRACE_FIELD] = carrier;\n }\n return payload;\n}\n\n/\n Strip and return the `_trace` field from a payload. Mutates `payload`.\n * The field is internal plumbing and should not be visible to subscribers.\n /\nexport function extractTraceparent<T extends Record<string, unknown>>(\n payload: T,\n): TraceCarrier \| undefined {\n const carrier = (payload as Record<string, unknown>)[TRACE_FIELD] as\n \| TraceCarrier\n \| undefined;\n if (carrier !== undefined) {\n delete (payload as Record<string, unknown>)[TRACE_FIELD];\n }\n if (!carrier \|\| typeof carrier.traceparent !== 'string') return undefined;\n return carrier;\n}\n\n/\n Run `fn` with the given W3C traceparent set as the parent context.\n * Any spans started inside `fn` will be children of the incoming trace.\n * No-op if `carrier` is undefined.\n /\nexport function withTraceparent<T>(\n carrier: TraceCarrier \| undefined,\n fn: () => T,\n): T {\n if (!carrier) return fn();\n const carrierObj: Record<string, string> = { traceparent: carrier.traceparent };\n if (carrier.tracestate) carrierObj['tracestate'] = carrier.tracestate;\n const ctx = propagation.extract(context.active(), carrierObj);\n return context.with(ctx, fn);\n}\n\n// ── Actor handler convenience ──────────────────────────────────────────\n\n/\n Wrap a bus-event handler in an `actor.<name>:<channel>` consumer span.\n * Used at every `eventBus.get(channel).subscribe(handler)` site inside\n * an actor (Stower, Gatherer, Matcher, Browser, Smelter), to attribute\n * each in-process subscriber's work to a span without scattering manual\n * `withSpan` calls across handler bodies.\n \n The span's parent is the active context at the time the handler\n * fires — which is the `bus.dispatch:<channel>` span on the backend\n * (Subject.next runs synchronously inside the dispatch span), or the\n * `bus.emit:<channel>` span when an actor emits to itself.\n /\nexport async function withActorSpan<T>(\n actor: string,\n channel: string,\n fn: (span: Span) => Promise<T> \| T,\n extraAttrs?: Attributes,\n): Promise<T> {\n const start = performance.now();\n try {\n return await withSpan(`actor.${actor}:${channel}`, fn, {\n kind: SpanKind.CONSUMER,\n attrs: {\n actor,\n 'bus.channel': channel,\n ...(extraAttrs ?? {}),\n },\n });\n } finally {\n recordHandlerDuration(actor, channel, performance.now() - start);\n }\n}\n\n// ── Log correlation ────────────────────────────────────────────────────\n\n/\n Read the active span's `trace_id` / `span_id` for log-line correlation.\n * Tier 3 of `.plans/OBSERVABILITY.md`. Each structured log line gets\n * tagged with these so a log query in CloudWatch / Loki / Datadog can\n * jump to the trace in Tempo / Jaeger / X-Ray.\n \n Returns `undefined` if no span is active, or if the active span's\n * context is invalid (uninitialized SDK, no-op tracer).\n /\nexport function getLogTraceContext(): { trace_id: string; span_id: string } \| undefined {\n const span = trace.getActiveSpan();\n if (!span) return undefined;\n const ctx = span.spanContext();\n if (!isSpanContextValid(ctx)) return undefined;\n return { trace_id: ctx.traceId, span_id: ctx.spanId };\n}\n\n// ── Metrics — Tier 3 ───────────────────────────────────────────────────\n\nconst METER_NAME = 'semiont';\n\nconst meter = () => metrics.getMeter(METER_NAME);\n\nlet _busEmitCounter: Counter \| undefined;\nlet _handlerDurationHistogram: Histogram \| undefined;\nlet _jobOutcomeCounter: Counter \| undefined;\nlet _jobDurationHistogram: Histogram \| undefined;\nlet _inferenceCallsCounter: Counter \| undefined;\nlet _inferenceTokensCounter: Counter \| undefined;\nlet _inferenceDurationHistogram: Histogram \| undefined;\nlet _sseSubscribers: UpDownCounter \| undefined;\nlet _jobQueueGauge: ObservableGauge \| undefined;\nlet _jobQueueProvider: (() => Promise<JobQueueSnapshot> \| JobQueueSnapshot) \| undefined;\nlet _vectorIndexSizeGauge: ObservableGauge \| undefined;\nlet _vectorIndexSizeProvider: (() => Promise<number> \| number) \| undefined;\n\n/* Snapshot of job-queue contents by status. Match `JobQueue.getStats()`. /\nexport interface JobQueueSnapshot {\n pending: number;\n running: number;\n complete: number;\n failed: number;\n cancelled: number;\n}\n\nfunction busEmitCounter(): Counter {\n if (!_busEmitCounter) {\n _busEmitCounter = meter().createCounter('semiont.bus.emit', {\n description: 'Bus emits by channel and scope',\n });\n }\n return _busEmitCounter;\n}\n\nfunction handlerDurationHistogram(): Histogram {\n if (!_handlerDurationHistogram) {\n _handlerDurationHistogram = meter().createHistogram('semiont.handler.duration', {\n description: 'In-process actor handler duration',\n unit: 'ms',\n });\n }\n return _handlerDurationHistogram;\n}\n\nfunction jobOutcomeCounter(): Counter {\n if (!_jobOutcomeCounter) {\n _jobOutcomeCounter = meter().createCounter('semiont.job.outcome', {\n description: 'Worker job completions by type and outcome',\n });\n }\n return _jobOutcomeCounter;\n}\n\nfunction jobDurationHistogram(): Histogram {\n if (!_jobDurationHistogram) {\n _jobDurationHistogram = meter().createHistogram('semiont.job.duration', {\n description: 'Worker job duration by type',\n unit: 'ms',\n });\n }\n return _jobDurationHistogram;\n}\n\nfunction inferenceCallsCounter(): Counter {\n if (!_inferenceCallsCounter) {\n _inferenceCallsCounter = meter().createCounter('semiont.inference.calls', {\n description: 'Inference API calls by provider, model, and outcome',\n });\n }\n return _inferenceCallsCounter;\n}\n\nfunction inferenceTokensCounter(): Counter {\n if (!_inferenceTokensCounter) {\n _inferenceTokensCounter = meter().createCounter('semiont.inference.tokens', {\n description: 'Inference token usage by provider, model, and direction',\n });\n }\n return _inferenceTokensCounter;\n}\n\nfunction inferenceDurationHistogram(): Histogram {\n if (!_inferenceDurationHistogram) {\n _inferenceDurationHistogram = meter().createHistogram('semiont.inference.duration', {\n description: 'Inference call duration by provider, model, and outcome',\n unit: 'ms',\n });\n }\n return _inferenceDurationHistogram;\n}\n\nfunction sseSubscribersCounter(): UpDownCounter {\n if (!_sseSubscribers) {\n _sseSubscribers = meter().createUpDownCounter('semiont.sse.subscribers', {\n description: 'Active SSE subscribers',\n });\n }\n return _sseSubscribers;\n}\n\n/* Increment the bus-emit counter. Called at every transport `emit` site. /\nexport function recordBusEmit(channel: string, scope?: string): void {\n busEmitCounter().add(1, {\n 'bus.channel': channel,\n ...(scope ? { 'bus.scope': scope } : {}),\n });\n}\n\n/* Record an in-process actor handler's duration. /\nexport function recordHandlerDuration(actor: string, channel: string, durationMs: number): void {\n handlerDurationHistogram().record(durationMs, {\n actor,\n 'bus.channel': channel,\n });\n}\n\n/* Record a worker job's outcome and duration. /\nexport function recordJobOutcome(jobType: string, outcome: 'completed' \| 'failed', durationMs: number): void {\n jobOutcomeCounter().add(1, { 'job.type': jobType, 'job.outcome': outcome });\n jobDurationHistogram().record(durationMs, { 'job.type': jobType, 'job.outcome': outcome });\n}\n\n/* Increment the SSE subscriber gauge — call on `/bus/subscribe` open. /\nexport function recordSubscriberConnect(): void {\n sseSubscribersCounter().add(1);\n}\n\n/* Decrement on disconnect. Pair with `recordSubscriberConnect`. /\nexport function recordSubscriberDisconnect(): void {\n sseSubscribersCounter().add(-1);\n}\n\n/\n Register a callback that returns the current job-queue snapshot.\n * Polled at the SDK's metric-collection interval. The single gauge\n * emits one observation per status (`pending`, `running`, …) tagged\n * with the `job.status` attribute. Idempotent — last registered\n * provider wins.\n /\nexport function registerJobQueueProvider(\n provider: () => Promise<JobQueueSnapshot> \| JobQueueSnapshot,\n): void {\n _jobQueueProvider = provider;\n if (!_jobQueueGauge) {\n _jobQueueGauge = meter().createObservableGauge('semiont.job.queue.size', {\n description: 'Job queue size by status',\n });\n _jobQueueGauge.addCallback(async (observer) => {\n if (!_jobQueueProvider) return;\n const snap = await _jobQueueProvider();\n observer.observe(snap.pending, { 'job.status': 'pending' });\n observer.observe(snap.running, { 'job.status': 'running' });\n observer.observe(snap.complete, { 'job.status': 'complete' });\n observer.observe(snap.failed, { 'job.status': 'failed' });\n observer.observe(snap.cancelled, { 'job.status': 'cancelled' });\n });\n }\n}\n\n/\n Register a callback that returns the current vector-index size\n * (point count). Async to allow remote queries (Qdrant). Polled at\n * the metric-collection interval.\n /\nexport function registerVectorIndexSizeProvider(\n provider: () => Promise<number> \| number,\n): void {\n _vectorIndexSizeProvider = provider;\n if (!_vectorIndexSizeGauge) {\n _vectorIndexSizeGauge = meter().createObservableGauge('semiont.vector.index.size', {\n description: 'Vector store point count',\n });\n _vectorIndexSizeGauge.addCallback(async (observer) => {\n if (_vectorIndexSizeProvider) {\n const value = await _vectorIndexSizeProvider();\n observer.observe(value);\n }\n });\n }\n}\n\n/\n Record an inference call. Token counts are optional — providers that\n * don't expose them (or fail before generating) record only call count\n * and duration.\n /\nexport function recordInferenceUsage(opts: {\n provider: string;\n model: string;\n durationMs: number;\n outcome: 'success' \| 'error';\n inputTokens?: number;\n outputTokens?: number;\n}): void {\n const baseAttrs = {\n 'inference.provider': opts.provider,\n 'inference.model': opts.model,\n 'inference.outcome': opts.outcome,\n };\n inferenceCallsCounter().add(1, baseAttrs);\n inferenceDurationHistogram().record(opts.durationMs, baseAttrs);\n if (opts.inputTokens != null && opts.inputTokens > 0) {\n inferenceTokensCounter().add(opts.inputTokens, {\n 'inference.provider': opts.provider,\n 'inference.model': opts.model,\n 'inference.direction': 'input',\n });\n }\n if (opts.outputTokens != null && opts.outputTokens > 0) {\n inferenceTokensCounter().add(opts.outputTokens, {\n 'inference.provider': opts.provider,\n 'inference.model': opts.model,\n 'inference.direction': 'output',\n });\n }\n}\n\n// ── Re-exports from @opentelemetry/api ─────────────────────────────────\n\nexport { SpanKind, SpanStatusCode, type Attributes, type Span } from '@opentelemetry/api';\n","/\n Process-level structured logger for Node entry points.\n \n Used by long-lived Node processes (backend, workers, smelter) that\n * want JSON-structured stdout with active-span trace correlation. The\n * `trace_id` / `span_id` fields are populated from the current OTel\n * span context via `getLogTraceContext` — this is the same Tier 3\n * correlation that lets a grep through stdout line up with the trace\n * UI without manual stitching.\n \n Reads `LOG_LEVEL` (default `info`) and `LOG_FORMAT` (`json` default,\n * `simple` for human-friendly dev output).\n \n Co-located with `getLogTraceContext` deliberately: this is the\n * only reasonably-shaped consumer of that helper, and putting them in\n * the same package keeps the trace-id wiring in one place.\n */\n\nimport winston from 'winston';\nimport type { Logger } from '@semiont/core';\nimport { getLogTraceContext } from './index.js';\n\nconst traceContextFormat = winston.format((info) => {\n const trace = getLogTraceContext();\n if (trace) {\n info.trace_id = trace.trace_id;\n info.span_id = trace.span_id;\n }\n return info;\n})();\n\nexport function createProcessLogger(component: string): Logger {\n const level = process.env.LOG_LEVEL ?? 'info';\n const format = process.env.LOG_FORMAT === 'simple'\n ? winston.format.combine(\n winston.format.timestamp({ format: 'YYYY-MM-DD HH:mm:ss' }),\n winston.format.errors({ stack: true }),\n traceContextFormat,\n winston.format.printf(({ level: lvl, message, timestamp, ...meta }) => {\n const metaStr = Object.keys(meta).length > 0 ? ` ${JSON.stringify(meta)}` : '';\n return `${timestamp} [${lvl.toUpperCase()}] [${component}] ${message}${metaStr}`;\n }),\n )\n : winston.format.combine(\n winston.format.timestamp(),\n winston.format.errors({ stack: true }),\n traceContextFormat,\n winston.format.json(),\n );\n\n const logger = winston.createLogger({\n level,\n defaultMeta: { component },\n format,\n transports: [new winston.transports.Console()],\n });\n\n return logger;\n}\n"]}

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@semiont/observability",
-  "version": "0.5.5",
+  "version": "0.5.7",
   "description": "OpenTelemetry-based tracing for Semiont — Tier 2 of OBSERVABILITY.md. Process-init helpers (Node + Web), withSpan helper, W3C traceparent inject/extract for bus payloads. No-op when no exporter is configured.",
   "type": "module",
   "main": "dist/index.js",
@@ -28,7 +28,7 @@
     }
   },
   "engines": {
-    "node": ">=20.18.1"
+    "node": ">=24.0.0"
   },
   "files": [
     "dist",
@@ -55,24 +55,24 @@
   "author": "Semiont Team",
   "license": "Apache-2.0",
   "devDependencies": {
-    "rollup": "^4.60.3",
+    "rollup": "^4.61.0",
     "rollup-plugin-dts": "^6.4.1",
     "tsup": "^8.5.1",
     "typescript": "^6.0.2",
-    "vitest": "^4.1.0"
+    "vitest": "^4.1.8"
   },
   "dependencies": {
-    "@opentelemetry/api": "^1.9.0",
-    "@semiont/core": "*",
-    "@opentelemetry/context-async-hooks": "^2.7.0",
-    "@opentelemetry/core": "^2.7.0",
-    "@opentelemetry/exporter-metrics-otlp-http": "^0.215.0",
-    "@opentelemetry/exporter-trace-otlp-http": "^0.215.0",
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/context-async-hooks": "^2.7.1",
+    "@opentelemetry/core": "^2.7.1",
+    "@opentelemetry/exporter-metrics-otlp-http": "^0.218.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.218.0",
     "@opentelemetry/resources": "^2.7.0",
     "@opentelemetry/sdk-metrics": "^2.7.0",
     "@opentelemetry/sdk-trace-base": "^2.7.0",
-    "@opentelemetry/sdk-trace-web": "^2.7.0",
-    "@opentelemetry/semantic-conventions": "^1.40.0",
+    "@opentelemetry/sdk-trace-web": "^2.7.1",
+    "@opentelemetry/semantic-conventions": "^1.41.1",
+    "@semiont/core": "*",
     "winston": "^3.17.0"
   }
 }