@semiont/observability 0.5.1 → 0.5.3

package/README.md

@@ -62,6 +62,20 @@ Configuration is via the standard `OTEL_*` env vars:
 | `OTEL_CONSOLE_EXPORTER=true` | Dev-only: emit spans + metrics to stderr |
 | `OTEL_SDK_DISABLED=true` | Skip initialization entirely |
 
+## Process logger (Node)
+
+For long-lived Node entry points (backend, workers, smelter), the package exposes a winston-based structured logger that auto-correlates each line with the active span:
+
+```ts
+// worker-main.ts (or smelter-main.ts, etc.)
+import { createProcessLogger } from '@semiont/observability/process-logger';
+
+const logger = createProcessLogger('worker');
+logger.info('Started', { config });
+```
+
+Reads `LOG_LEVEL` (default `info`) and `LOG_FORMAT` (`json` default, `simple` for dev). When an OTel SDK is initialized and a span is active at log time, every emitted line gets `trace_id` / `span_id` fields — Tier 3 correlation between grep-the-stdout and the trace UI. Lives on its own subpath so consumers that don't want winston in their bundle can ignore it.
+
 ## Quick start (Web)
 
 ```ts
@@ -93,7 +107,7 @@ await withSpan(
 );
 
 // Actor handler wrapper — used by the bus dispatcher to standardize
-// span names across StowerVM, BrowserVM, GathererVM, MatcherVM, SmelterVM.
+// span names across state units (StowerStateUnit, BrowserStateUnit, GathererStateUnit, MatcherStateUnit, SmelterStateUnit).
 await withActorSpan('stower', 'mark:create', () => handler(payload));
 ```
 

package/dist/process-logger.d.ts

@@ -0,0 +1,23 @@
+import { Logger } from '@semiont/core';
+
+/**
+ * Process-level structured logger for Node entry points.
+ *
+ * Used by long-lived Node processes (backend, workers, smelter) that
+ * want JSON-structured stdout with active-span trace correlation. The
+ * `trace_id` / `span_id` fields are populated from the current OTel
+ * span context via `getLogTraceContext` — this is the same Tier 3
+ * correlation that lets a grep through stdout line up with the trace
+ * UI without manual stitching.
+ *
+ * Reads `LOG_LEVEL` (default `info`) and `LOG_FORMAT` (`json` default,
+ * `simple` for human-friendly dev output).
+ *
+ * Co-located with `getLogTraceContext` deliberately: this is the
+ * only reasonably-shaped consumer of that helper, and putting them in
+ * the same package keeps the trace-id wiring in one place.
+ */
+
+declare function createProcessLogger(component: string): Logger;
+
+export { createProcessLogger };

package/dist/process-logger.js

@@ -0,0 +1,57 @@
+import winston from 'winston';
+import { trace, isSpanContextValid } from '@opentelemetry/api';
+import { setBusLogTraceIdProvider } from '@semiont/core';
+
+// src/process-logger.ts
+setBusLogTraceIdProvider(() => {
+  const span = trace.getActiveSpan();
+  if (!span) return void 0;
+  const ctx = span.spanContext();
+  if (!isSpanContextValid(ctx)) return void 0;
+  return ctx.traceId;
+});
+function getLogTraceContext() {
+  const span = trace.getActiveSpan();
+  if (!span) return void 0;
+  const ctx = span.spanContext();
+  if (!isSpanContextValid(ctx)) return void 0;
+  return { trace_id: ctx.traceId, span_id: ctx.spanId };
+}
+
+// src/process-logger.ts
+var traceContextFormat = winston.format((info) => {
+  const trace2 = getLogTraceContext();
+  if (trace2) {
+    info.trace_id = trace2.trace_id;
+    info.span_id = trace2.span_id;
+  }
+  return info;
+})();
+function createProcessLogger(component) {
+  const level = process.env.LOG_LEVEL ?? "info";
+  const format = process.env.LOG_FORMAT === "simple" ? winston.format.combine(
+    winston.format.timestamp({ format: "YYYY-MM-DD HH:mm:ss" }),
+    winston.format.errors({ stack: true }),
+    traceContextFormat,
+    winston.format.printf(({ level: lvl, message, timestamp, ...meta }) => {
+      const metaStr = Object.keys(meta).length > 0 ? ` ${JSON.stringify(meta)}` : "";
+      return `${timestamp} [${lvl.toUpperCase()}] [${component}] ${message}${metaStr}`;
+    })
+  ) : winston.format.combine(
+    winston.format.timestamp(),
+    winston.format.errors({ stack: true }),
+    traceContextFormat,
+    winston.format.json()
+  );
+  const logger = winston.createLogger({
+    level,
+    defaultMeta: { component },
+    format,
+    transports: [new winston.transports.Console()]
+  });
+  return logger;
+}
+
+export { createProcessLogger };
+//# sourceMappingURL=process-logger.js.map
+//# sourceMappingURL=process-logger.js.map

package/dist/process-logger.js.map

@@ -0,0 +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"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@semiont/observability",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "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",
@@ -20,6 +20,11 @@
       "types": "./dist/web.d.ts",
       "import": "./dist/web.js",
       "default": "./dist/web.js"
+    },
+    "./process-logger": {
+      "types": "./dist/process-logger.d.ts",
+      "import": "./dist/process-logger.js",
+      "default": "./dist/process-logger.js"
     }
   },
   "engines": {
@@ -65,6 +70,7 @@
     "@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/semantic-conventions": "^1.40.0",
+    "winston": "^3.17.0"
   }
 }