@chidchanun/bcp 0.2.15 → 0.2.17

package/docs/releases/0.2.17.md

@@ -0,0 +1,166 @@
+# BCP Framework 0.2.17 — Observability Platform v3
+
+State: **unreleased**
+
+`0.2.17` adds provider-neutral distributed tracing and correlation to the existing `bcp/observability` package while preserving the metrics, Prometheus and health APIs introduced in Observability Platform v2.
+
+## Highlights
+
+- `createTracer()` root/child span runtime
+- Node `AsyncLocalStorage` trace context
+- W3C `traceparent` parsing/formatting
+- HTTP trace header injection/extraction
+- stable `correlationId`
+- `createRequestTracingMiddleware()` for Middleware System v2
+- `createTraceCarrier()` / `runWithTraceCarrier()` for jobs/workflows/events/realtime payloads
+- span attributes and events
+- automatic error status/exception events for failed callbacks
+- `createMemoryTraceSpanExporter()`
+- `createCompositeTraceSpanExporter()`
+- `createTraceMetricsExporter()`
+- `getTraceLogFields()` for structured logging correlation
+- compiled npm runtime `observability.mjs`
+
+## Public API additions
+
+```text
+createTracer
+currentTraceContext
+runWithTraceContext
+createTraceCarrier
+extractTraceCarrier
+runWithTraceCarrier
+injectTraceHeaders
+extractTraceHeaders
+formatTraceparent
+parseTraceparent
+createRequestTracingMiddleware
+createMemoryTraceSpanExporter
+createCompositeTraceSpanExporter
+createTraceMetricsExporter
+getTraceLogFields
+```
+
+New public types include:
+
+```text
+TraceContext
+TraceCarrier
+TraceSpan
+TraceSpanRecord
+TraceSpanEvent
+TraceSpanExporter
+TraceSpanKind
+TraceSpanStatus
+TraceAttributes
+Tracer
+TracerOptions
+StartTraceSpanOptions
+RequestTracingOptions
+TraceIdFactory
+TraceMetricsOptions
+```
+
+## Trace model
+
+A root operation owns a `traceId` and `correlationId`. Every nested span receives its own `spanId` while inheriting the trace and correlation identity.
+
+```text
+traceId
+  |
+  +-- HTTP span
+       |
+       +-- database span
+       +-- cache span
+       +-- producer span
+              |
+              +-- consumer span
+```
+
+Normal awaited asynchronous calls retain the active context through `AsyncLocalStorage`.
+
+## HTTP propagation
+
+The request tracing middleware understands W3C version `00` `traceparent` headers and `x-correlation-id`.
+
+Responses include the active span's `traceparent` plus the correlation ID unless `includeResponseHeaders: false` is configured.
+
+## Background propagation
+
+`0.2.17` intentionally does not add mandatory tracing fields to job, workflow, outbox or realtime schemas.
+
+Applications can explicitly transport:
+
+```ts
+const trace =
+    createTraceCarrier();
+```
+
+and restore it with:
+
+```ts
+runWithTraceCarrier(
+    payload.trace,
+    handler
+);
+```
+
+This keeps tracing provider-neutral and avoids breaking existing persisted data.
+
+## Trace metrics
+
+`createTraceMetricsExporter()` integrates completed spans with the existing metrics registry.
+
+Default metrics:
+
+```text
+bcp_trace_spans_total
+bcp_trace_span_duration_seconds
+```
+
+Default labels:
+
+```text
+kind
+status
+```
+
+Span-name labels remain opt-in to reduce accidental high-cardinality metrics.
+
+## Exporter model
+
+BCP ships an in-memory exporter for tests and a composite exporter for fan-out. Production collector/APM integration remains application-owned through `TraceSpanExporter`.
+
+Exporter delivery failures are isolated from business execution.
+
+## Packaging
+
+Prepared npm packages now compile `bcp/observability` into:
+
+```text
+packages/client/src/observability.mjs
+```
+
+The package smoke test imports this compiled runtime and exercises trace creation, context propagation and trace metrics.
+
+## Compatibility
+
+- Previous baseline: `0.2.16`
+- Intentional breaking changes: **none**
+- Existing Observability v2 metrics/health APIs remain supported.
+- Existing `bcp/observability` import path remains unchanged.
+
+## Validation
+
+The release candidate must pass:
+
+```bash
+npm run typecheck
+npm run test:unit
+npm run test:integration
+npm run test:e2e
+npm run test:package
+npm run rc:check
+```
+
+Do not tag or publish until the exact release commit passes the full validation sequence.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chidchanun/bcp",
-  "version": "0.2.15",
+  "version": "0.2.17",
   "description": "BCP Framework - a React full-stack framework with file-based routing, SSR, APIs, middleware, islands, caching and standalone production builds.",
   "type": "module",
   "license": "MIT",
@@ -38,7 +38,7 @@
     },
     "./cache": {
       "types": "./packages/client/src/cache.ts",
-      "default": "./packages/client/src/cache.ts"
+      "default": "./packages/client/src/cache.mjs"
     },
     "./config": {
       "types": "./packages/client/src/config.ts",
@@ -95,7 +95,7 @@
     "./observability": {
       "types": "./packages/client/src/observability.ts",
       "browser": "./packages/client/src/server-only.browser.mjs",
-      "default": "./packages/client/src/observability.ts"
+      "default": "./packages/client/src/observability.mjs"
     },
     "./server": {
       "types": "./packages/client/src/server.ts",