@chidchanun/bcp 0.2.16 → 0.2.18

package/docs/observability-v3.md

@@ -0,0 +1,402 @@
+# Observability Platform v3
+
+BCP Framework `0.2.17` extends `bcp/observability` from metrics/health into request-to-background distributed tracing and correlation.
+
+The existing Observability Platform v2 APIs remain available. v3 adds tracing without changing the public entrypoint.
+
+## Goals
+
+Observability v3 gives one logical operation a stable trace/correlation identity as it crosses HTTP middleware, background work, workflows, transactional events, realtime delivery and cache operations.
+
+```text
+HTTP request
+   |
+   +-- database
+   |
+   +-- outbox event
+   |      |
+   |      +-- durable job
+   |             |
+   |             +-- workflow
+   |                    |
+   |                    +-- realtime
+   |
+   +-- cache
+
+traceId + correlationId follow the operation.
+```
+
+BCP provides propagation primitives instead of coupling tracing to one vendor or collector.
+
+## Create a tracer
+
+```ts
+import {
+    createMemoryTraceSpanExporter,
+    createTracer,
+} from "bcp/observability";
+
+const exporter =
+    createMemoryTraceSpanExporter();
+
+export const tracer =
+    createTracer({
+        exporter,
+        serviceName: "api",
+        defaultAttributes: {
+            environment: "production",
+        },
+    });
+```
+
+`createMemoryTraceSpanExporter()` is mainly useful for tests and local inspection. Production applications can implement `TraceSpanExporter` and forward completed spans to an OpenTelemetry bridge, APM agent, log pipeline or another collector.
+
+## Root and child spans
+
+```ts
+await tracer.withSpan(
+    "order.checkout",
+    async span => {
+        span.setAttribute(
+            "order.id",
+            order.id
+        );
+
+        await tracer.withSpan(
+            "database.order.insert",
+            async () => {
+                await createOrder();
+            },
+            {
+                kind: "client",
+            }
+        );
+    }
+);
+```
+
+Nested `withSpan()` calls automatically reuse the active `traceId`, create a new `spanId`, and set the active span as `parentSpanId`.
+
+The active trace context uses Node `AsyncLocalStorage`, so it flows through normal awaited asynchronous work.
+
+## Span kinds
+
+Supported kinds are:
+
+```text
+internal
+server
+client
+producer
+consumer
+```
+
+Examples:
+
+- HTTP inbound request: `server`
+- SQL/HTTP/cache call: `client`
+- queue/outbox publish: `producer`
+- queue/event handler: `consumer`
+- framework/application operation: `internal`
+
+## Span attributes and events
+
+```ts
+await tracer.withSpan(
+    "payment.charge",
+    async span => {
+        span.setAttribute(
+            "payment.provider",
+            "example"
+        );
+
+        span.addEvent(
+            "payment.requested",
+            {
+                amount: 1490,
+            }
+        );
+    }
+);
+```
+
+Attribute values are intentionally limited to strings, finite numbers and booleans.
+
+If a `withSpan()` callback throws, BCP marks the span as `error`, records an `exception` event and rethrows the original application error.
+
+## HTTP request tracing
+
+Use the Middleware System v2 integration:
+
+```ts
+import {
+    createRequestTracingMiddleware,
+} from "bcp/observability";
+
+export const middleware =
+    createRequestTracingMiddleware(
+        tracer
+    );
+```
+
+The middleware:
+
+1. Reads an incoming W3C `traceparent` header when valid.
+2. Preserves the incoming `x-correlation-id` when supplied.
+3. Starts a server span.
+4. Makes the span context available through `AsyncLocalStorage`.
+5. Adds the current `traceparent` and `x-correlation-id` to the response.
+
+The default span name is `HTTP <METHOD>`. Applications can provide a lower-cardinality route name:
+
+```ts
+createRequestTracingMiddleware(
+    tracer,
+    {
+        spanName:
+            request =>
+                `route ${request.nextUrl.pathname}`,
+    }
+);
+```
+
+Avoid putting unbounded IDs directly into metric labels. Span names can also become labels when explicitly configured in trace metrics.
+
+## W3C trace context
+
+BCP supports W3C version `00` `traceparent` values:
+
+```text
+00-<32 hex trace id>-<16 hex span id>-<2 hex flags>
+```
+
+Helpers:
+
+```ts
+import {
+    extractTraceHeaders,
+    formatTraceparent,
+    injectTraceHeaders,
+    parseTraceparent,
+} from "bcp/observability";
+```
+
+Example outbound request:
+
+```ts
+const headers =
+    new Headers();
+
+injectTraceHeaders(
+    headers
+);
+
+await fetch(
+    serviceUrl,
+    {
+        headers,
+    }
+);
+```
+
+`injectTraceHeaders()` uses the current context by default.
+
+## Propagate through jobs, workflows and events
+
+For non-HTTP transports use a trace carrier:
+
+```ts
+import {
+    createTraceCarrier,
+} from "bcp/observability";
+
+const trace =
+    createTraceCarrier();
+
+await jobs.enqueue(
+    "order.process",
+    {
+        orderId,
+        trace,
+    }
+);
+```
+
+Consumer:
+
+```ts
+import {
+    runWithTraceCarrier,
+} from "bcp/observability";
+
+jobs.register(
+    "order.process",
+    async ({ payload }) =>
+        runWithTraceCarrier(
+            payload.trace,
+            () =>
+                tracer.withSpan(
+                    "job order.process",
+                    async () => {
+                        await processOrder(
+                            payload.orderId
+                        );
+                    },
+                    {
+                        kind: "consumer",
+                    }
+                )
+        )
+);
+```
+
+The same carrier can be stored in workflow input, outbox/event metadata or realtime payload metadata when the application needs trace continuity across those boundaries.
+
+BCP does not mutate durable job/event schemas automatically in `0.2.17`; propagation remains explicit and provider-neutral.
+
+## Correlation IDs
+
+Every root trace gets a `correlationId`. Incoming HTTP requests may supply one through:
+
+```text
+x-correlation-id
+```
+
+Access trace fields for structured logs:
+
+```ts
+import {
+    getTraceLogFields,
+} from "bcp/observability";
+
+logger.info(
+    "order created",
+    {
+        ...getTraceLogFields(),
+        orderId,
+    }
+);
+```
+
+Output fields are:
+
+```text
+traceId
+spanId
+correlationId
+```
+
+This keeps logs searchable even when the log backend does not understand tracing natively.
+
+## Trace metrics
+
+Bridge completed spans into the existing BCP metrics registry:
+
+```ts
+import {
+    createCompositeTraceSpanExporter,
+    createMetricsRegistry,
+    createTraceMetricsExporter,
+    createTracer,
+} from "bcp/observability";
+
+const metrics =
+    createMetricsRegistry();
+
+const traceMetrics =
+    createTraceMetricsExporter(
+        metrics
+    );
+
+const tracer =
+    createTracer({
+        exporter:
+            createCompositeTraceSpanExporter([
+                traceMetrics,
+                myProductionExporter,
+            ]),
+    });
+```
+
+Default metrics:
+
+```text
+bcp_trace_spans_total
+bcp_trace_span_duration_seconds
+```
+
+Default labels are only:
+
+```text
+kind
+status
+```
+
+`includeSpanName: true` adds a `span` label. Use it only when span names are controlled and low-cardinality.
+
+## Exporter failure behavior
+
+Span-export errors are intentionally isolated from application execution. A failing exporter does not turn a successful business operation into an application failure.
+
+Exporter lifecycle can be closed explicitly:
+
+```ts
+await tracer.shutdown();
+```
+
+Composite exporter shutdown runs in reverse registration order.
+
+## Production topology
+
+```text
+Application
+   |
+   +-- createTracer()
+   |      |
+   |      +-- memory exporter (tests)
+   |      +-- trace metrics exporter
+   |      +-- custom production exporter
+   |
+   +-- createRequestTracingMiddleware()
+   |
+   +-- createTraceCarrier()/runWithTraceCarrier()
+```
+
+BCP does not install an OpenTelemetry SDK or vendor APM client. Applications own collector/provider dependencies, authentication, batching and transport shutdown.
+
+## Compatibility
+
+`0.2.17` is intended to be backward-compatible with `0.2.16`.
+
+Existing APIs remain available:
+
+```text
+createMetricsRegistry()
+createMetricsResponse()
+createRequestMetricsMiddleware()
+createHealthRegistry()
+```
+
+The npm-prepared `bcp/observability` runtime is now compiled to `observability.mjs`, matching the hardened runtime packaging already used by cache/jobs/workflow/events/realtime/testing/plugins.
+
+## Validation
+
+Before releasing `0.2.17` run:
+
+```bash
+npm run typecheck
+npm run test:unit
+npm run test:integration
+npm run test:e2e
+npm run test:package
+npm run rc:check
+```
+
+Related guides:
+
+- [Observability Platform v2](observability.md)
+- [Cache Platform v2](cache-platform-v2.md)
+- [Durable Jobs](durable-jobs.md)
+- [Workflow Orchestration](workflow-orchestration.md)
+- [Transactional Outbox & Events](transactional-outbox-events.md)
+- [Realtime Platform](realtime-platform.md)

package/docs/platform-manifest.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "version": "0.2.16",
+  "version": "0.2.18",
   "releaseState": "unreleased",
-  "baseline": "cache-platform-v2",
+  "baseline": "deployment-platform-v2",
   "runtime": {
     "node": ">=24.11.0",
     "react": "19",
@@ -26,6 +26,7 @@
     "bcp/testing",
     "bcp/plugins",
     "bcp/observability",
+    "bcp/deployment",
     "bcp/server",
     "bcp/server-only",
     "bcp/middleware"
@@ -71,6 +72,29 @@
     "prometheusMetrics": true,
     "requestMetricsMiddleware": true,
     "healthChecks": true,
+    "observabilityPlatformV3": true,
+    "distributedTracing": true,
+    "traceContextPropagation": true,
+    "w3cTraceparent": true,
+    "correlationIds": true,
+    "requestTracingMiddleware": true,
+    "memorySpanExporter": true,
+    "compositeSpanExporter": true,
+    "traceMetricsExporter": true,
+    "traceLogFields": true,
+    "compiledObservabilityRuntime": true,
+    "deploymentPlatformV2": true,
+    "deploymentRuntimeLifecycle": true,
+    "deploymentResourceRegistry": true,
+    "deploymentReadiness": true,
+    "deploymentDiagnostics": true,
+    "deploymentSignalHandling": true,
+    "deploymentShutdownHooks": true,
+    "deploymentRuntimeMetadata": true,
+    "compiledConfigRuntime": true,
+    "compiledAuthRuntime": true,
+    "compiledServerRuntime": true,
+    "compiledMiddlewareRuntime": true,
     "backgroundJobsPlatform": true,
     "jobQueueAdapterContract": true,
     "inMemoryJobQueue": true,
@@ -200,7 +224,7 @@
     "s3-compatible"
   ],
   "compatibility": {
-    "previousBaseline": "0.2.15",
+    "previousBaseline": "0.2.17",
     "intentionalBreakingChangesFromPreviousBaseline": false,
     "migrationGuide": "migration-0.2.md"
   },
@@ -217,6 +241,8 @@
     "authSessionStore": "auth-session-store.md",
     "authorizationSecurity": "authorization-security.md",
     "observability": "observability.md",
+    "observabilityV3": "observability-v3.md",
+    "deploymentPlatformV2": "deployment-platform-v2.md",
     "backgroundJobs": "background-jobs.md",
     "jobScheduling": "job-scheduling.md",
     "durableJobs": "durable-jobs.md",
@@ -227,6 +253,6 @@
     "pluginModulePlatform": "plugin-module-platform.md",
     "cachePlatformV2": "cache-platform-v2.md",
     "migrationGuide": "migration-0.2.md",
-    "releaseNotes": "releases/0.2.16.md"
+    "releaseNotes": "releases/0.2.18.md"
   }
 }

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.