@ddd-ts-kit/tracing 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,401 @@
-# Temporary Holding Version
+# @ddd-ts-kit/tracing
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+OpenTelemetry tracing that the domain never sees. Nothing in `domain/` or `application/` imports
+this package: use cases, adapters, events and jobs are wrapped where they are wired, in the
+composition root, and one user action reads as one trace.
+
+```
+npm i @ddd-ts-kit/tracing @opentelemetry/api
+# for the Node bootstrap (@ddd-ts-kit/tracing/node)
+npm i @opentelemetry/sdk-node @opentelemetry/auto-instrumentations-node @opentelemetry/exporter-trace-otlp-http
+# for the test harness (@ddd-ts-kit/tracing/testing)
+npm i -D @opentelemetry/sdk-trace-base @opentelemetry/context-async-hooks
+```
+
+## Setup
+
+```ts
+// platform/tracing.ts: imported before everything else
+import { initTracing } from '@ddd-ts-kit/tracing/node';
+
+export const tracing = initTracing({ serviceName: 'clinic-api' });
+```
+
+```ts
+// main.ts
+import { tracing } from '@/platform/tracing.js'; // first import, see "Load order"
+import { createApplication, kernelModule } from '@ddd-ts-kit/di';
+import { traceApplication, tracedPublisher, tracedRoutes } from '@ddd-ts-kit/tracing';
+
+const app = createApplication({
+  modules: [kernelModule({ instrumentation: traceApplication(), eventPublisher: outbox }), schedulingModule, notificationModule],
+});
+
+mountExpress(server, routes, { executionScope: app.resolve(ExecutionScope), around: tracedRoutes() });
+new OutboxRelay({ store, publisher: tracedPublisher(bus), clock }).start({ intervalMs: 1_000 });
+
+await app.start();
+process.on('SIGTERM', () => void app.stop().then(() => tracing.shutdown()));
+```
+
+That is all: `traceApplication()` is the value `kernelModule` wraps the application with, and
+no class knows about it. Three places stay outside of the kernel module and take one wrapper
+each: the HTTP pipeline (`around: tracedRoutes()`), the publisher an outbox relay sends with
+(`tracedPublisher(bus)`), and a project that builds its own tracer provider (see "Span
+processors").
+
+### Jaeger, in five lines
+
+Jaeger v2 receives OTLP natively, so there is nothing between the application and Jaeger:
+
+```yaml
+services:
+  jaeger:
+    image: jaegertracing/jaeger:2.22.0
+    profiles: [observability]
+    ports: ['127.0.0.1:16686:16686', '127.0.0.1:4318:4318']
+```
+
+```
+docker compose --profile observability up -d jaeger
+OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318 node dist/main.js
+```
+
+`initTracing({ serviceName })` needs nothing else: the endpoint comes from the standard
+`OTEL_EXPORTER_OTLP_ENDPOINT` (or `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`) variable, and without
+either nothing is exported. Open `http://127.0.0.1:16686` and search the service.
+
+### Load order
+
+Auto-instrumentation patches `http` and the database drivers when they are loaded, so
+`initTracing` must have run before. In an ES module the static imports are evaluated before the
+first statement of the file: keep the call in its own module and import that module first (as
+above), or preload it with `node --import ./dist/platform/tracing.js`. Packages published as ES
+modules also need the `@opentelemetry/instrumentation` loader hook.
+
+## What a trace looks like
+
+One request that books an appointment, announces it to two other bounded contexts through the
+outbox, and is published by the relay a moment later, from a timer and outside of any request:
+
+```
+POST /appointments                                        SERVER    scheduling
+  command BookAppointment                                 INTERNAL
+    repository AppointmentRepository.findOverlapping      INTERNAL
+    repository AppointmentRepository.save                 INTERNAL
+    unit-of-work before-commit                            INTERNAL  after every save, before the commit
+      domain-event scheduling.appointment.booked          INTERNAL
+        handler AppointmentBookedPublisher                INTERNAL
+          outbox append scheduling.appointment.booked     INTERNAL  (the response is sent once this is committed)
+            publish scheduling.appointment.booked         PRODUCER  by the relay, later, same trace
+              process notification.appointment-booked     CONSUMER  notification
+                command SendBookingConfirmation           INTERNAL
+                  external MailGateway.send               INTERNAL
+              process analytics.appointment-booked        CONSUMER  analytics
+                command RecordBooking                     INTERNAL
+                  repository BookingRepository.save       INTERNAL
+```
+
+This is the tree as produced, asserted span for span by
+`test/scenarios/one-action-one-trace.spec.ts` and, against a real Jaeger, by
+`test/jaeger/real-jaeger.spec.ts`. A scheduled job is a trace of its own:
+
+```
+job scheduling.send-reminders                             INTERNAL  (root)
+  command SendReminders                                   INTERNAL
+    repository AppointmentRepository.findOverlapping      INTERNAL
+```
+
+### The phases of a unit of work
+
+The handlers of domain events are not under the save that recorded the event: the unit of work
+dispatches them once the command handler has returned. Under the span of the command, in order:
+
+```
+command SendParcels                                       INTERNAL
+  repository ParcelRepository.save                        INTERNAL
+  repository ParcelRepository.save                        INTERNAL
+  unit-of-work before-commit                              INTERNAL  the events of both saves
+    domain-event shipping.parcel.sent                     INTERNAL
+      repository ParcelRepository.save                    INTERNAL  a handler saves another aggregate
+    domain-event shipping.parcel.sent                     INTERNAL
+  unit-of-work before-commit                              INTERNAL  what the handlers recorded in turn
+    domain-event shipping.parcel.tracked                  INTERNAL
+  unit-of-work after-commit                               INTERNAL  once committed, same trace
+    domain-event shipping.parcel.sent                     INTERNAL
+    domain-event shipping.parcel.sent                     INTERNAL
+```
+
+- `unit-of-work before-commit` follows the save spans. What the handlers recorded in turn is
+  under a second span of the same name.
+- `unit-of-work after-commit` is there when an event has a handler of that phase, and holds
+  only those events. It is a child of the command span, and stays in the trace when its
+  handler fails: the command span still says `succeeded`.
+- A handler declared with a kind (`@DomainEventHandler`) is a `handler <ClassName>` span under
+  its `domain-event` span; a callback attached with `dispatcher.on` has none.
+- Outside any unit of work (a repository called alone) the `domain-event` spans stay under the
+  save span that dispatched them, without a phase span.
+
+This tree is asserted by `test/unit-of-work-phases.spec.ts`.
+
+### Span names, kinds and attributes
+
+| Span | Kind | Made by | Attributes |
+|---|---|---|---|
+| `<METHOD> <route template>` | SERVER | `tracedRoutes()` (renames the span an HTTP instrumentation opened, or starts one) | `http.route`, `http.request.method`, `http.response.status_code`, `app.operation`, `app.correlation_id`, `app.origin`, `app.outcome`, `app.error.code` |
+| `command <Name>`, `query <Name>` | INTERNAL | `traceUseCases()`, a bus middleware | `app.use_case.kind`, `app.use_case.name`, `app.context`, `app.outcome`, `app.error.code`, `error.type` |
+| `<kind> <Port>.<method>`: `repository`, `gateway`, `external`, `publisher` | INTERNAL | `traceBindings()` | `code.namespace` (the adapter class), `code.function`, `app.dependency.kind`, `app.context` |
+| `unit-of-work before-commit` | INTERNAL | `tracedDomainEvents()`, around each round of events dispatched at the end of a unit of work, before the commit | none |
+| `unit-of-work after-commit` | INTERNAL | `tracedDomainEvents()`, around the events that have an `after-commit` handler, once the unit of work has committed | none |
+| `domain-event <name>` | INTERNAL | `tracedDomainEvents()` | `app.domain_event.name` |
+| `handler <ClassName>` | INTERNAL | `traceBindings()`, kind `domain-event-handler` | `code.namespace`, `code.function`, `app.dependency.kind`, `app.context` |
+| `outbox append <type>` | INTERNAL | `tracedPublisher()` around a publisher that stores | `messaging.system` (`outbox`), `messaging.operation.name` (`append`), `messaging.operation.type` (`create`), `messaging.destination.name`, `messaging.message.id` |
+| `publish <type>` | PRODUCER | `tracedPublisher()` around a bus | `messaging.system`, `messaging.operation.name` (`publish`), `messaging.operation.type` (`send`), `messaging.destination.name`, `messaging.message.id` |
+| `process <consumer>` | CONSUMER | `tracedConsumer()`, one per delivery | `messaging.system`, `messaging.operation.*` (`process`), `messaging.destination.name`, `messaging.message.id`, `messaging.consumer.group.name`, `app.messaging.source`, `app.messaging.attempt`, `app.messaging.redelivered`, `app.context`, `app.correlation_id`, `app.origin`, `app.outcome` |
+| `job <name>` | INTERNAL, always a root | `tracedJob()` | `app.job.name`, `app.job.scheduled_at`, `app.job.attempt`, `app.context`, `app.correlation_id`, `app.origin`, `app.outcome` |
+
+- Names are stable and of low cardinality: a route template, never a URL; a class, a port, an
+  event type or a consumer name, never an identifier.
+- `app.outcome` is `succeeded`, `refused` (a business answer), `failed`, and for a delivery
+  `dead-lettered`. A `DomainError` is an answer, not an incident: the use case span says
+  `refused` and `app.error.code`, and is not an error. Anything else sets the status ERROR with
+  `error.type` (the class name) and `app.error.code` (the `code`, when it is shaped like one).
+- **A request refused by authorization has no use case span**: the middleware sits after the use
+  case guard, so the trace is the SERVER span alone, with the status answered and the code
+  (`FORBIDDEN`). A use case refused by its own rules has its span, `refused`.
+- **One mechanism per span.** A use case is traced by the bus middleware, a consumer by
+  `process <consumer>`, a job by `job <name>`: `traceBindings()` leaves the bindings of kind
+  `use-case`, `consumer` and `job` alone.
+- **Privacy**: class, method, port, context, codes and the identifiers of the kit (event id,
+  correlation id, job name). Never arguments, results, payloads, SQL parameter values, error
+  messages, aggregate ids, nor anything about the actor or the tenant.
+
+### Across the asynchronous boundary
+
+The trace context is captured when the integration event is created, inside the request:
+`outbox append <type>` stamps its own `traceparent` on the event, and the outbox stores it with
+the record (every outbox store of the kit persists and restores it exactly: the contract suite
+of `@ddd-ts-kit/testing` says so for the in-memory, Drizzle, Knex, Prisma and TypeORM stores).
+The relay publishes later, from another call chain or another process: `tracedPublisher(bus)`
+makes `publish <type>` a child of what the record names, never of the loop of the relay, and
+stamps its own span on what goes out, so the consumers are its children. A tick that finds
+nothing to publish makes no span, and there is no span per tick.
+
+An event without `traceparent` (stored before tracing was configured) continues the active
+span instead.
+
+**Continue or link.** The messaging conventions of OpenTelemetry allow a consumer to continue
+the trace of the producer or to start a new one that links to it. The default is to continue,
+`traceApplication({ consumers: 'continue' })`: following one action end to end is then opening
+one trace, and Jaeger shows a link only as a reference to click through, one consumer at a
+time. Choose `consumers: 'link'` for a system where one event fans out to so many consumers,
+or is retried for so long, that a trace would never end: each delivery is then the root of its
+own trace, linked to the publication.
+
+**Deliveries.** A provider tells each handler which delivery this is (`EventDelivery` of the
+kernel: attempt, last attempt, transport, source, consumer), and each attempt is a span of its
+own: `app.messaging.attempt` counts from 1, `app.messaging.redelivered` marks the ones after
+the first, a failed attempt is an error with the code of what was thrown, and the attempt
+after which the provider gives the event up says `app.outcome: dead-lettered`. RabbitMQ, Kafka,
+NATS, Redis Streams and the in-memory bus all say it; their `traceparent` travels in the
+envelope and in a real header (`traceparent`).
+
+## The pieces, without `kernelModule`
+
+`traceApplication()` is these, one per member, for a composition written by hand:
+
+```ts
+bus.use(traceUseCases());                                              // after authorization, outside the unit of work
+traceDependency(new KnexOrderRepository(db), { kind: 'repository', context: 'ordering', port: 'OrderRepository' });
+tracedDomainEvents(dispatcher);
+tracedPublisher(new OutboxPublisher(store));                           // outbox append <type>
+tracedPublisher(bus);                                                  // publish <type>
+tracedSubscriber(bus, { trace: 'continue' });                          // process <type>
+tracedConsumer(handler, { consumer: 'billing.invoice-on-order-placed', context: 'billing' });
+tracedJob(run, { name: 'billing.send-reminders', context: 'billing' });
+tracedErrorReporter(reporter);
+createApplication({ modules, decorate: traceBindings() });             // bindings only
+configureTracing({ executionScope });                                  // correlation id on spans and log fields
+```
+
+The last two lines are for an application whose kernel module is given no `instrumentation`.
+With it, `traceBindings()` is already the `binding` member the kernel module puts around every
+binding and the execution scope is handed over by the module, so the `decorate` hook adds
+nothing (wrapping an instance twice is a no-op). A project generated by the CLI has neither line: it calls
+`traceApplication()` once in `src/platform/lay-foundations.ts`, `tracedRoutes()` in
+`src/platform/auth/http-boundary.ts`, `tracedPublisher(...)` in
+`src/platform/compose-application.ts`, and `initTracing` in `src/platform/tracing.ts`. The
+rule `tracing/platform-only` keeps these imports in the platform directory, `main.ts` and
+`apps/`.
+
+A publisher names its transport itself (`messagingSystem`: `rabbitmq`, `kafka`, `nats`,
+`redis`, `in-memory`, and `outbox` for the outbox publisher); `scopedPublisher` and
+`validatingPublisher` pass it on, and `tracedPublisher(publisher, { system })` says it for a
+publisher of your own.
+
+For a custom transport: `captureTraceparent()` when storing a message,
+`runWithTraceparent(traceparent, fn)` when handling it. `spanContextFromTraceparent` accepts
+version `00` only and rejects all-zero ids. `withSpan(name, fn, attributes?)` exists for
+platform code (a migration, a startup step); domain and application code never call it.
+
+## What a dependency span contains
+
+`traceDependency` opens one span per call of an async method, named `<kind> <Port>.<method>`
+after the port when it is given and after the class otherwise.
+
+- Never arguments, return values or error messages; the error is rethrown untouched.
+- Synchronous methods are not traced. A method declared `async` is traced from its first call; a
+  method that merely returns a promise is traced from its second call. A traced call returns a
+  promise, so do not wrap an object whose methods return a chainable query builder.
+- Getters, symbols, generators and lifecycle hooks (`onModuleInit`, `onModuleDestroy`,
+  `onApplicationBootstrap`, `onApplicationShutdown`, `dispose`) are left alone.
+- The instance is wrapped in place: same object, `instanceof` and `this` intact, wrapping twice
+  is a no-op. Nothing enumerable is added, so the instance spreads and compares as before.
+- `private` is a compile-time keyword: at run time a private method is a method and a function
+  held in a private field is a method too. Both are traced when async, and a method that calls
+  another through `this` produces a child span. The aspects of `@ddd-ts-kit/aspects` differ on
+  purpose: they advise the call made from outside only.
+- A frozen or sealed instance is fronted by a proxy instead. Its methods and getters run with
+  the real instance as `this`; the calls it makes on itself are then not traced.
+- **Order of the wrappers of a repository** under `kernelModule({ instrumentation })`,
+  outermost first: the `decorate` hook of the application when there is one, the span, the
+  hand-over of domain events (`dispatchingOnSave` of the kernel), then the aspects of the
+  binding (`retry`, `timeout`). So `repository X.save` covers the retries, and a retried save
+  announces its events once. Inside a unit of work `repository X.save` contains no
+  `domain-event` span: the save only queues the events, and they are dispatched under
+  `unit-of-work before-commit`, a sibling that follows the saves. Outside any unit of work the
+  save dispatches before it resolves, and the `domain-event` spans are its children.
+
+## Noise
+
+A trace tells the story of an action and nothing else. The defaults, and the option for each:
+
+| What | Default | Option |
+|---|---|---|
+| Probes, metrics, documentation | no span for `/health`, `/healthz`, `/live`, `/livez`, `/ready`, `/readyz`, `/startup`, `/metrics`, `/docs`, `/openapi.json`, `/favicon.ico` and what is below them; no span for the documentation routes of `@ddd-ts-kit/http` wherever they are mounted | `initTracing({ ignoredPaths })`, `tracedRoutes({ ignore })` |
+| Outbox relay | no span per tick, none when nothing is published; the queries of its polling make no span (see the drivers) | |
+| Instrumentations on | `http` and `undici` and `grpc` (the two sides of a request), `pg`, `mysql2`, `mysql`, `mongodb`, `ioredis`, `redis` | `initTracing({ autoInstrumentations })`, or `instrumentations` to replace them all |
+| Database drivers | the statement as written, with its placeholders, never the values bound to them; only inside a trace (`requireParentSpan`), so a poller or a pool makes no trace of its own; no connection or pool checkout span (`ignoreConnectSpans`) | `autoInstrumentations` |
+| Instrumentations off | `fs`, `dns`, `net` (how a call was made, not what was done); `express`, `connect`, `router`, `koa`, `hapi`, `restify`, `nestjs-core` (a span per middleware, where the kit names the request by its route); `amqplib`, `kafkajs` (they would double `publish` and `process`); `knex`, `generic-pool`, `dataloader`, `lru-memoizer`, `mongoose` (they repeat the driver); logging bridges, runtime and host metrics | `autoInstrumentations: { '@opentelemetry/instrumentation-fs': { enabled: true } }` |
+| Attributes | an allow-list (`DEFAULT_ALLOWED_ATTRIBUTES`): what the kit writes and what the instrumentations kept on say of a request, a query, a peer. Headers, bodies, parameter values, user and client identifiers are dropped before export | `initTracing({ allowedAttributes })`, `new AttributeAllowList({ allowed, alsoAllowed })` |
+| Volume | under one local root (a request, a delivery, a job run), at most 25 dependency, domain event or publication spans share a name and 200 exist in total; beyond, the call runs untraced (an event published past the cap still carries the trace on) and `app.dependency_spans.dropped` counts on the root | `configureTracing({ maxSpansPerName, maxSpansPerRoot })` |
+| Secrets | query string values and userinfo of recorded URLs become `REDACTED`; exception messages and stack traces are dropped | |
+
+Use case, consumer, job and request spans are never capped: there is one per unit of work.
+
+### Sampling
+
+`initTracing({ sampleRatio: 0.2 })` samples a share of the traces where they start, and a
+sampled parent is always followed: a trace is kept or dropped whole, across the outbox and the
+contexts, since the decision travels in the `traceparent` stored with the event. Without the
+option the standard `OTEL_TRACES_SAMPLER` variables apply, and by default every trace is kept.
+
+Keeping every trace that ends in error, whatever the ratio, cannot be decided when a trace
+starts. That is tail sampling, and it belongs to a collector, which sees whole traces. Sample
+everything in the application and decide there:
+
+```yaml
+# OpenTelemetry Collector (contrib): between the applications and Jaeger
+receivers:
+  otlp: { protocols: { http: { endpoint: 0.0.0.0:4318 } } }
+processors:
+  tail_sampling:
+    decision_wait: 30s
+    policies:
+      - { name: errors, type: status_code, status_code: { status_codes: [ERROR] } }
+      - { name: dead-letters, type: string_attribute, string_attribute: { key: app.outcome, values: [dead-lettered] } }
+      - { name: the-rest, type: probabilistic, probabilistic: { sampling_percentage: 10 } }
+exporters:
+  otlp_http/jaeger: { endpoint: http://jaeger:4318 }
+service:
+  pipelines:
+    traces: { receivers: [otlp], processors: [tail_sampling], exporters: [otlp_http/jaeger] }
+```
+
+`decision_wait` must cover the delay of the outbox relay and of the retries, or the late spans
+of a trace are decided apart.
+
+## Span processors
+
+For a provider you build yourself, add them before the exporting processor:
+
+| Processor | Effect |
+|---|---|
+| `LocalRootTracker` | enables the per-root caps, names the correlation on the local root, and lets `tracedRoutes()` recognise the span of an HTTP instrumentation |
+| `UrlSecretSpanProcessor` | `url.full`, `http.url`, `url.query`: query values and userinfo become `REDACTED`, parameter names stay |
+| `ErrorMessageScrubber` | drops `exception.message`, `exception.stacktrace` and the status message recorded by instrumentations; keeps `exception.type` |
+| `AttributeAllowList` | keeps the allowed attributes only |
+
+`initTracing` installs the four, then `extraSpanProcessors`, then the exporter.
+
+## Pivoting: trace, logs, audit trail, error tracker
+
+Every span that starts a unit of work (the SERVER span, `process <consumer>`, `job <name>`)
+carries `app.correlation_id` and `app.origin`: the correlation id of the kit, the same in every
+bounded context an action reaches. From there:
+
+```ts
+const logger = pino({ mixin: () => traceLogFields() });
+// inside a unit of work: { correlationId, origin, actorId, tenantId?, causationId?, trace_id, span_id }
+```
+
+| From | To | By |
+|---|---|---|
+| a trace | its log lines | `trace_id` of the log fields, or `correlationId` |
+| a trace | the audit entries of the action | `app.correlation_id` is the `correlationId` of the `AuditEntry` |
+| an error report | its trace | `traceId` of the `ErrorReport`, filled by `tracedErrorReporter` (also for a failed job or a buried event, reported once their spans are over) |
+| a log line, an audit entry | the trace | search the tag `app.correlation_id` in Jaeger |
+
+`traceApplication()` gives the execution scope of the application to `configureTracing`; a
+composition by hand calls `configureTracing({ executionScope })` itself, and
+`traceLogFields(scope)` takes the scope as an argument for a logger built earlier.
+`correlationIdFromActiveSpan()` answers the trace id, usable as a support reference when the
+project has no execution scope. **Nothing personal becomes a span attribute**: the actor and
+the tenant stay in the log fields, where retention is yours.
+
+## Asserting traces in a project
+
+```ts
+import { expectSpanTree, installTestTracing } from '@ddd-ts-kit/tracing/testing';
+
+const tracing = installTestTracing();          // a real provider that keeps the ended spans; uninstall() when done
+
+it('books an appointment in one trace', async () => {
+  const trace = await tracing.traceOf(() => app.resolve(CommandBus).execute(new BookAppointment('09:00')));
+
+  expectSpanTree(trace, [
+    {
+      name: 'command BookAppointment',
+      attributes: { 'app.context': 'scheduling', 'app.outcome': 'succeeded' },
+      children: [
+        { name: 'repository AppointmentRepository.findOverlapping' },
+        { name: 'repository AppointmentRepository.save' },
+        { name: 'unit-of-work before-commit', children: [{ name: 'domain-event scheduling.appointment.booked' }] },
+      ],
+    },
+  ]);
+});
+```
+
+- `traceOf(action)` answers the spans that ended during the action as plain data (`SpanNode`:
+  name, kind, status, attributes, trace and span ids, links, children in the order they
+  started): one tree per root, so two traces are two trees.
+- `expectSpanTree(actual, expected)` is exact on names and structure: a span that is not listed
+  fails, and so does a listed one that is missing. Kinds, statuses and attributes are checked
+  when given (`undefined` expects an attribute to be absent), and a span is expected not to be
+  an error unless `status: 'ERROR'` says so. On a mismatch the error lists what differs, then
+  shows both trees as indented text. It depends on no test runner.
+- `installTestTracing({ processors, sampler })` takes the processors of the project and a
+  sampler, to assert scrubbing or sampling.
+
+## Tests
+
+```
+npx vitest run packages/tracing
+DDD_TS_KIT_TEST_JAEGER_IMAGE=jaegertracing/jaeger:2.22.0 npx vitest run packages/tracing/test/jaeger
+```
+
+The second command needs Docker: it starts a Jaeger of its own (a container named
+`ddd-ts-kit-test-trace-jaeger-<pid>`, on two free loopback ports), runs the scenario above with
+`initTracing({ serviceName })` and the standard endpoint variable, reads the trace back through
+the HTTP API of Jaeger and asserts the same tree, then removes the container.

package/dist/application/trace-application.d.ts

@@ -0,0 +1,39 @@
+import type { BusMiddleware, DomainEventDispatcher, ErrorReporter, ExecutionScope, IntegrationEventCallback, IntegrationEventPublisher, JobExecution } from '@ddd-ts-kit/kernel';
+import { type TracedBinding } from '../dependency/trace-bindings.js';
+import type { ConsumerTrace } from '../events/consumer-trace.js';
+export interface TraceApplicationOptions {
+    /**
+     * How a consumed event relates to its publication. Default `continue`: the consumers are
+     * children of the publication, so one action is one trace. `link` starts a trace per
+     * delivery, linked to it.
+     */
+    readonly consumers?: ConsumerTrace;
+}
+type JobRun = (execution: JobExecution) => Promise<void>;
+/** The wrappers `kernelModule({ instrumentation })` of `@ddd-ts-kit/di` applies, one per kind of span. */
+export interface TracedApplication {
+    readonly binding: <T>(instance: T, binding: TracedBinding) => T;
+    readonly useCase: BusMiddleware;
+    readonly publisher: (publisher: IntegrationEventPublisher) => IntegrationEventPublisher;
+    readonly consumer: (handler: IntegrationEventCallback, consumer: {
+        readonly consumer: string;
+        readonly context: string;
+    }) => IntegrationEventCallback;
+    readonly domainEvents: (dispatcher: DomainEventDispatcher) => DomainEventDispatcher;
+    readonly job: (run: JobRun, job: {
+        readonly name: string;
+        readonly context: string;
+    }) => JobRun;
+    readonly errorReporter: (reporter: ErrorReporter) => ErrorReporter;
+    readonly executionScope: (scope: ExecutionScope) => void;
+}
+/**
+ * Everything that traces an application, in one value: `kernelModule({ instrumentation:
+ * traceApplication() })`. Use cases, repositories and adapters, the dispatch of domain events
+ * and their handlers, the outbox, the publications, the consumers and the jobs each get their
+ * span; error reports carry the trace id, and the execution scope of the application is given
+ * to `configureTracing`, so spans and log fields carry the correlation id.
+ */
+export declare function traceApplication(options?: TraceApplicationOptions): TracedApplication;
+export {};
+//# sourceMappingURL=trace-application.d.ts.map

package/dist/application/trace-application.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-application.d.ts","sourceRoot":"","sources":["../../src/application/trace-application.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EACb,qBAAqB,EACrB,aAAa,EACb,cAAc,EACd,wBAAwB,EACxB,yBAAyB,EACzB,YAAY,EACb,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EAAiB,KAAK,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAEpF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAMjE,MAAM,WAAW,uBAAuB;IACtC;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,aAAa,CAAC;CACpC;AAED,KAAK,MAAM,GAAG,CAAC,SAAS,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAEzD,0GAA0G;AAC1G,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,OAAO,EAAE,aAAa,KAAK,CAAC,CAAC;IAChE,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,CAAC,SAAS,EAAE,yBAAyB,KAAK,yBAAyB,CAAC;IACxF,QAAQ,CAAC,QAAQ,EAAE,CACjB,OAAO,EAAE,wBAAwB,EACjC,QAAQ,EAAE;QAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,KAC9D,wBAAwB,CAAC;IAC9B,QAAQ,CAAC,YAAY,EAAE,CAAC,UAAU,EAAE,qBAAqB,KAAK,qBAAqB,CAAC;IACpF,QAAQ,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,KAAK,MAAM,CAAC;IAChG,QAAQ,CAAC,aAAa,EAAE,CAAC,QAAQ,EAAE,aAAa,KAAK,aAAa,CAAC;IACnE,QAAQ,CAAC,cAAc,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC;CAC1D;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,GAAE,uBAA4B,GAAG,iBAAiB,CAezF"}

package/dist/application/trace-application.js

@@ -0,0 +1,31 @@
+import { configureTracing } from '../configuration/configure-tracing.js';
+import { tracedErrorReporter } from '../correlation/traced-error-reporter.js';
+import { traceBindings } from '../dependency/trace-bindings.js';
+import { tracedDomainEvents } from '../domain-events/traced-domain-events.js';
+import { tracedConsumer } from '../events/traced-consumer.js';
+import { tracedPublisher } from '../events/traced-publisher.js';
+import { tracedJob } from '../jobs/traced-job.js';
+import { traceUseCases } from '../use-case/trace-use-cases.js';
+/**
+ * Everything that traces an application, in one value: `kernelModule({ instrumentation:
+ * traceApplication() })`. Use cases, repositories and adapters, the dispatch of domain events
+ * and their handlers, the outbox, the publications, the consumers and the jobs each get their
+ * span; error reports carry the trace id, and the execution scope of the application is given
+ * to `configureTracing`, so spans and log fields carry the correlation id.
+ */
+export function traceApplication(options = {}) {
+    const trace = options.consumers ?? 'continue';
+    return {
+        binding: traceBindings(),
+        useCase: traceUseCases(),
+        publisher: (publisher) => tracedPublisher(publisher),
+        consumer: (handler, { consumer, context }) => tracedConsumer(handler, { consumer, context, trace }),
+        domainEvents: tracedDomainEvents,
+        job: tracedJob,
+        errorReporter: tracedErrorReporter,
+        executionScope: (executionScope) => {
+            configureTracing({ executionScope });
+        },
+    };
+}
+//# sourceMappingURL=trace-application.js.map

package/dist/application/trace-application.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-application.js","sourceRoot":"","sources":["../../src/application/trace-application.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,gBAAgB,EAAE,MAAM,uCAAuC,CAAC;AACzE,OAAO,EAAE,mBAAmB,EAAE,MAAM,yCAAyC,CAAC;AAC9E,OAAO,EAAE,aAAa,EAAsB,MAAM,iCAAiC,CAAC;AACpF,OAAO,EAAE,kBAAkB,EAAE,MAAM,0CAA0C,CAAC;AAE9E,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAChE,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AA4B/D;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAO,GAA4B,EAAE;IACpE,MAAM,KAAK,GAAG,OAAO,CAAC,SAAS,IAAI,UAAU,CAAC;IAE9C,OAAO;QACL,OAAO,EAAE,aAAa,EAAE;QACxB,OAAO,EAAE,aAAa,EAAE;QACxB,SAAS,EAAE,CAAC,SAAS,EAAE,EAAE,CAAC,eAAe,CAAC,SAAS,CAAC;QACpD,QAAQ,EAAE,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,cAAc,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QACnG,YAAY,EAAE,kBAAkB;QAChC,GAAG,EAAE,SAAS;QACd,aAAa,EAAE,mBAAmB;QAClC,cAAc,EAAE,CAAC,cAAc,EAAE,EAAE;YACjC,gBAAgB,CAAC,EAAE,cAAc,EAAE,CAAC,CAAC;QACvC,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/configuration/configure-tracing.d.ts

@@ -0,0 +1,9 @@
+import type { TracingConfiguration } from './tracing-configuration.js';
+/**
+ * Overrides the given keys and keeps the others. Lifecycle hooks are read when an
+ * instance is wrapped, the caps on every call.
+ */
+export declare function configureTracing(overrides: Partial<TracingConfiguration>): void;
+export declare function resetTracingConfiguration(): void;
+export declare function tracingConfiguration(): TracingConfiguration;
+//# sourceMappingURL=configure-tracing.d.ts.map

package/dist/configuration/configure-tracing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"configure-tracing.d.ts","sourceRoot":"","sources":["../../src/configuration/configure-tracing.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAUvE;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,OAAO,CAAC,oBAAoB,CAAC,GAAG,IAAI,CAE/E;AAED,wBAAgB,yBAAyB,IAAI,IAAI,CAEhD;AAED,wBAAgB,oBAAoB,IAAI,oBAAoB,CAE3D"}

package/dist/configuration/configure-tracing.js

@@ -0,0 +1,21 @@
+import { DEFAULT_LIFECYCLE_HOOKS } from './default-lifecycle-hooks.js';
+const defaults = {
+    maxSpansPerName: 25,
+    maxSpansPerRoot: 200,
+    lifecycleHooks: DEFAULT_LIFECYCLE_HOOKS,
+};
+let current = defaults;
+/**
+ * Overrides the given keys and keeps the others. Lifecycle hooks are read when an
+ * instance is wrapped, the caps on every call.
+ */
+export function configureTracing(overrides) {
+    current = { ...current, ...overrides };
+}
+export function resetTracingConfiguration() {
+    current = defaults;
+}
+export function tracingConfiguration() {
+    return current;
+}
+//# sourceMappingURL=configure-tracing.js.map

package/dist/configuration/configure-tracing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"configure-tracing.js","sourceRoot":"","sources":["../../src/configuration/configure-tracing.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAGvE,MAAM,QAAQ,GAAyB;IACrC,eAAe,EAAE,EAAE;IACnB,eAAe,EAAE,GAAG;IACpB,cAAc,EAAE,uBAAuB;CACxC,CAAC;AAEF,IAAI,OAAO,GAAyB,QAAQ,CAAC;AAE7C;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,SAAwC;IACvE,OAAO,GAAG,EAAE,GAAG,OAAO,EAAE,GAAG,SAAS,EAAE,CAAC;AACzC,CAAC;AAED,MAAM,UAAU,yBAAyB;IACvC,OAAO,GAAG,QAAQ,CAAC;AACrB,CAAC;AAED,MAAM,UAAU,oBAAoB;IAClC,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/configuration/default-lifecycle-hooks.d.ts

@@ -0,0 +1,2 @@
+export declare const DEFAULT_LIFECYCLE_HOOKS: readonly string[];
+//# sourceMappingURL=default-lifecycle-hooks.d.ts.map

package/dist/configuration/default-lifecycle-hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"default-lifecycle-hooks.d.ts","sourceRoot":"","sources":["../../src/configuration/default-lifecycle-hooks.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,uBAAuB,EAAE,SAAS,MAAM,EAMpD,CAAC"}

package/dist/configuration/default-lifecycle-hooks.js

@@ -0,0 +1,8 @@
+export const DEFAULT_LIFECYCLE_HOOKS = [
+    'onModuleInit',
+    'onModuleDestroy',
+    'onApplicationBootstrap',
+    'onApplicationShutdown',
+    'dispose',
+];
+//# sourceMappingURL=default-lifecycle-hooks.js.map

package/dist/configuration/default-lifecycle-hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"default-lifecycle-hooks.js","sourceRoot":"","sources":["../../src/configuration/default-lifecycle-hooks.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,uBAAuB,GAAsB;IACxD,cAAc;IACd,iBAAiB;IACjB,wBAAwB;IACxB,uBAAuB;IACvB,SAAS;CACV,CAAC"}

package/dist/configuration/tracing-configuration.d.ts

@@ -0,0 +1,16 @@
+import type { ExecutionScope } from '@ddd-ts-kit/kernel';
+export interface TracingConfiguration {
+    /** Dependency spans sharing one name allowed under one local root. */
+    readonly maxSpansPerName: number;
+    /** Dependency spans allowed in total under one local root. */
+    readonly maxSpansPerRoot: number;
+    /** Method names never wrapped: frameworks call them outside of any request. */
+    readonly lifecycleHooks: readonly string[];
+    /**
+     * When given, the local root span of each unit of work names its correlation id and its
+     * origin (`app.correlation_id`, `app.origin`), and `traceLogFields()` carries the log fields
+     * of the execution context. Never the actor, the tenant or the session.
+     */
+    readonly executionScope?: ExecutionScope;
+}
+//# sourceMappingURL=tracing-configuration.d.ts.map

package/dist/configuration/tracing-configuration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracing-configuration.d.ts","sourceRoot":"","sources":["../../src/configuration/tracing-configuration.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEzD,MAAM,WAAW,oBAAoB;IACnC,sEAAsE;IACtE,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,8DAA8D;IAC9D,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,+EAA+E;IAC/E,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C;;;;OAIG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,cAAc,CAAC;CAC1C"}

package/dist/configuration/tracing-configuration.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=tracing-configuration.js.map

package/dist/configuration/tracing-configuration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracing-configuration.js","sourceRoot":"","sources":["../../src/configuration/tracing-configuration.ts"],"names":[],"mappings":""}

package/dist/correlation/correlation-id-from-active-span.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Trace id of the active span. Usable as the correlation id of a log line and as the
+ * support reference shown to an end user: it leads straight to the trace.
+ */
+export declare function correlationIdFromActiveSpan(): string | undefined;
+//# sourceMappingURL=correlation-id-from-active-span.d.ts.map

package/dist/correlation/correlation-id-from-active-span.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"correlation-id-from-active-span.d.ts","sourceRoot":"","sources":["../../src/correlation/correlation-id-from-active-span.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,wBAAgB,2BAA2B,IAAI,MAAM,GAAG,SAAS,CAIhE"}

package/dist/correlation/correlation-id-from-active-span.js

@@ -0,0 +1,10 @@
+import { isSpanContextValid, trace } from '@opentelemetry/api';
+/**
+ * Trace id of the active span. Usable as the correlation id of a log line and as the
+ * support reference shown to an end user: it leads straight to the trace.
+ */
+export function correlationIdFromActiveSpan() {
+    const spanContext = trace.getActiveSpan()?.spanContext();
+    return spanContext !== undefined && isSpanContextValid(spanContext) ? spanContext.traceId : undefined;
+}
+//# sourceMappingURL=correlation-id-from-active-span.js.map

package/dist/correlation/correlation-id-from-active-span.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"correlation-id-from-active-span.js","sourceRoot":"","sources":["../../src/correlation/correlation-id-from-active-span.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAE/D;;;GAGG;AACH,MAAM,UAAU,2BAA2B;IACzC,MAAM,WAAW,GAAG,KAAK,CAAC,aAAa,EAAE,EAAE,WAAW,EAAE,CAAC;IAEzD,OAAO,WAAW,KAAK,SAAS,IAAI,kBAAkB,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;AACxG,CAAC"}

package/dist/correlation/trace-log-fields.d.ts

@@ -0,0 +1,13 @@
+import { type ExecutionScope, type LogFields } from '@ddd-ts-kit/kernel';
+export interface TraceLogFields extends LogFields {
+    trace_id?: string;
+    span_id?: string;
+}
+/**
+ * Fields for a logger mixin (pino `mixin`, winston format...): the trace and span ids inside a
+ * span, and, inside the execution scope given here or to `configureTracing`, the log fields of
+ * the execution context (`logFieldsOf`: correlation, causation, origin, actor and tenant ids).
+ * Empty outside of both.
+ */
+export declare function traceLogFields(scope?: ExecutionScope): TraceLogFields;
+//# sourceMappingURL=trace-log-fields.d.ts.map

package/dist/correlation/trace-log-fields.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-log-fields.d.ts","sourceRoot":"","sources":["../../src/correlation/trace-log-fields.ts"],"names":[],"mappings":"AACA,OAAO,EAAe,KAAK,cAAc,EAAE,KAAK,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAGtF,MAAM,WAAW,cAAe,SAAQ,SAAS;IAC/C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,CAAC,EAAE,cAAc,GAAG,cAAc,CAUrE"}