@zerotal/telemetry 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog — @zerotal/telemetry
+
+All notable changes to this package are documented here. The format is
+based on [Keep a Changelog](https://keepachangelog.com/); this package
+follows the Zerotal monorepo's unified versioning.
+
+**Maturity: `beta`**
+
+## [Unreleased]
+
+## [1.0.0] — 2026-08-05
+
+_First public release._
+
+### Changed
+
+- Renamed config interface to `TelemetryConfigShape`; added a `TelemetryConfig()` factory.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zerotal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,91 @@
+# @zerotal/telemetry
+
+> OpenTelemetry-style distributed tracing with zero external SDK dependency.
+
+A self-contained tracer with an OTLP-compatible span model, `AsyncLocalStorage` context propagation, and pluggable exporters. Wrap any operation in `withSpan()` and child spans automatically inherit the parent trace; export to the console, an OTLP endpoint, or a custom exporter.
+
+Part of the [Zerotal](../../README.md) framework. Requires **Bun ≥ 1.3.14**.
+
+## Installation
+
+```bash
+bun add @zerotal/telemetry
+```
+
+## Setup
+
+Register the provider in `bootstrap/providers.ts`. List it **before** other providers so the global tracer is ready when the rest of the application boots:
+
+```ts
+import { TelemetryProvider } from "@zerotal/telemetry";
+```
+
+## Usage
+
+`withSpan()` is the primary call-site API. It uses the global tracer; the span is ended, exported, and its status set automatically:
+
+```ts
+import { withSpan } from "@zerotal/telemetry";
+
+async function processOrder(id: string) {
+  return withSpan("process-order", async (span) => {
+    span.setAttribute("order.id", id);
+    const order = await Order.findOrFail(id);
+    await notifyWarehouse(order);
+  });
+}
+```
+
+Nested `withSpan()` calls automatically become children of the active span; the current span is available anywhere in the async stack:
+
+```ts
+import { currentSpan } from "@zerotal/telemetry";
+
+await withSpan("handle-request", async () => {
+  await withSpan("validate-input", async () => {
+    /* … */
+  });
+  await withSpan("query-db", async (span) => {
+    span.addEvent("db.query", { table: "orders", rows: 5 });
+  });
+});
+
+const traceId = currentSpan()?.data.traceId;
+```
+
+Trace every HTTP request with `TelemetryMiddleware` (register after `LoggerMiddleware`):
+
+```ts
+import { TelemetryMiddleware } from "@zerotal/telemetry";
+
+app.use([LoggerMiddleware, TelemetryMiddleware]);
+```
+
+For advanced scenarios, create a `Tracer` directly with a chosen exporter:
+
+```ts
+import { Tracer, ConsoleExporter } from "@zerotal/telemetry";
+
+const tracer = new Tracer({ exporter: new ConsoleExporter(), minDurationMs: 5 });
+
+await tracer.withSpan("my-op", async (span) => {
+  span.setAttribute("foo", "bar");
+});
+```
+
+## Exports
+
+- `withSpan` — global helper to run a callback inside an auto-managed span.
+- `currentSpan` — read the active span anywhere in the async call stack.
+- `Span` / `NoopSpan` — span primitives (`setAttribute`, `setAttributes`, `setStatus`, `addEvent`, `recordException`, `end`).
+- `SpanContext` — `AsyncLocalStorage`-backed context propagation.
+- `Tracer` — create a tracer with `withSpan()` and `startSpan()` for manual lifetime management.
+- `TelemetryMiddleware` — creates a `server`-kind root span per HTTP request; `.with({ spanName })` to customize.
+- Exporters: `NoopExporter` (default), `ConsoleExporter`, `OtlpExporter` (any OTLP HTTP/JSON backend).
+- `TelemetryProvider` — service provider; registers the global tracer.
+- `TelemetryConfig` — config factory.
+- Types: `SpanData`, `SpanEvent`, `SpanStatus`, `SpanStatusCode`, `SpanKind`, `TracerOptions`, `SpanOptions`, `SpanExporter`, `OtlpExporterOptions`, `TelemetryOptions`, `TelemetryConfigShape`.
+
+## Documentation
+
+- [Telemetry](../../docs/telemetry.md)

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@zerotal/telemetry",
+  "version": "1.0.0",
+  "license": "MIT",
+  "maturity": "beta",
+  "private": false,
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "CHANGELOG.md",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/*.spec.ts",
+    "!src/**/__fixtures__/**"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "bun": ">=1.3.14"
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@zerotal/core": "1.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.0"
+  },
+  "description": "OpenTelemetry tracing bridge for Zerotal framework events.",
+  "keywords": [
+    "zerotal",
+    "bun",
+    "typescript",
+    "framework"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zerotaldev/zerotal.git",
+    "directory": "packages/telemetry"
+  },
+  "homepage": "https://github.com/zerotaldev/zerotal/tree/main/packages/telemetry#readme",
+  "bugs": "https://github.com/zerotaldev/zerotal/issues"
+}

package/src/Span.ts

@@ -0,0 +1,134 @@
+// ── Types ─────────────────────────────────────────────────────────────────────
+
+export type SpanStatusCode = "unset" | "ok" | "error";
+export type SpanKind = "internal" | "server" | "client" | "producer" | "consumer";
+
+export interface SpanStatus {
+  code: SpanStatusCode;
+  message?: string;
+}
+
+export interface SpanEvent {
+  name: string;
+  timeMs: number;
+  attributes?: Record<string, unknown>;
+}
+
+export interface SpanData {
+  traceId: string;
+  spanId: string;
+  parentId: string | undefined;
+  name: string;
+  kind: SpanKind;
+  startMs: number;
+  endMs: number | undefined;
+  attributes: Record<string, string | number | boolean>;
+  status: SpanStatus;
+  events: SpanEvent[];
+}
+
+// ── Span ──────────────────────────────────────────────────────────────────────
+
+/**
+ * A single unit of work in a distributed trace.
+ *
+ * Spans are created by `Tracer.withSpan()` and `withSpan()`. They are
+ * automatically ended and exported when the wrapped callback resolves or
+ * throws. Manual `end()` is only needed for fire-and-forget patterns.
+ */
+export class Span {
+  readonly data: SpanData;
+
+  constructor(name: string, parentId?: string, traceId?: string, kind: SpanKind = "internal") {
+    this.data = {
+      traceId: traceId ?? _randomHex(16),
+      spanId: _randomHex(8),
+      parentId,
+      name,
+      kind,
+      startMs: Date.now(),
+      endMs: undefined,
+      attributes: {},
+      status: { code: "unset" },
+      events: [],
+    };
+  }
+
+  setAttribute(key: string, value: string | number | boolean): this {
+    this.data.attributes[key] = value;
+    return this;
+  }
+
+  setAttributes(attrs: Record<string, string | number | boolean>): this {
+    Object.assign(this.data.attributes, attrs);
+    return this;
+  }
+
+  setStatus(code: "ok" | "error", message?: string): this {
+    this.data.status = message !== undefined ? { code, message } : { code };
+    return this;
+  }
+
+  addEvent(name: string, attributes?: Record<string, unknown>): this {
+    const event: SpanEvent = { name, timeMs: Date.now() };
+    if (attributes !== undefined) event.attributes = attributes;
+    this.data.events.push(event);
+    return this;
+  }
+
+  recordException(error: Error): this {
+    return this.addEvent("exception", {
+      "exception.type": error.name,
+      "exception.message": error.message,
+      "exception.stack": error.stack ?? "",
+    });
+  }
+
+  end(): void {
+    if (this.data.endMs === undefined) this.data.endMs = Date.now();
+  }
+
+  get durationMs(): number {
+    return (this.data.endMs ?? Date.now()) - this.data.startMs;
+  }
+
+  get isEnded(): boolean {
+    return this.data.endMs !== undefined;
+  }
+}
+
+// ── NoopSpan ──────────────────────────────────────────────────────────────────
+
+/**
+ * A span whose methods are all no-ops.
+ * Used when telemetry is disabled so call sites never need null-checks.
+ */
+export class NoopSpan extends Span {
+  constructor() {
+    super("noop");
+  }
+  override setAttribute(_key: string, _value: string | number | boolean): this {
+    return this;
+  }
+  override setAttributes(_attrs: Record<string, string | number | boolean>): this {
+    return this;
+  }
+  override setStatus(_code: "ok" | "error", _message?: string): this {
+    return this;
+  }
+  override addEvent(_name: string, _attributes?: Record<string, unknown>): this {
+    return this;
+  }
+  override recordException(_error: Error): this {
+    return this;
+  }
+  override end(): void {}
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+export function _randomHex(bytes: number): string {
+  return Array.from(crypto.getRandomValues(new Uint8Array(bytes)))
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}

package/src/SpanContext.ts

@@ -0,0 +1,18 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { Span } from "./Span.ts";
+
+interface ActiveContext {
+  span: Span;
+}
+
+/**
+ * Propagates the active span through async call stacks via AsyncLocalStorage.
+ * Set by `Tracer.withSpan()`; read by nested `withSpan()` calls to attach
+ * child spans to the correct parent.
+ */
+export const SpanContext = new AsyncLocalStorage<ActiveContext>();
+
+/** Return the currently active span, or `undefined` if none is active. */
+export function currentSpan(): Span | undefined {
+  return SpanContext.getStore()?.span;
+}

package/src/Tracer.ts

@@ -0,0 +1,118 @@
+import { Span } from "./Span.ts";
+import { SpanContext } from "./SpanContext.ts";
+import type { SpanKind } from "./Span.ts";
+import type { SpanExporter } from "./exporters/SpanExporter.ts";
+
+export interface TracerOptions {
+  exporter: SpanExporter;
+  /** Drop spans in which the callback took less than this many ms. Default: 0 (keep all). */
+  minDurationMs?: number;
+  /** When true, export() errors are surfaced rather than swallowed. Default: false. */
+  rethrowExportErrors?: boolean;
+}
+
+export interface SpanOptions {
+  kind?: SpanKind;
+  attributes?: Record<string, string | number | boolean>;
+}
+
+/**
+ * Creates and manages spans. Normally one tracer lives for the lifetime of
+ * the process, registered via `TelemetryProvider`.
+ *
+ * @example
+ * const tracer = new Tracer({ exporter: new ConsoleExporter() });
+ *
+ * await tracer.withSpan('do-work', async (span) => {
+ *   span.setAttribute('work.type', 'heavy');
+ *   await heavyWork();
+ * });
+ */
+export class Tracer {
+  private readonly _exporter: SpanExporter;
+  private readonly _minDuration: number;
+  private readonly _rethrow: boolean;
+
+  constructor(options: TracerOptions) {
+    this._exporter = options.exporter;
+    this._minDuration = options.minDurationMs ?? 0;
+    this._rethrow = options.rethrowExportErrors ?? false;
+  }
+
+  /**
+   * Runs `fn` inside a new span. The span is automatically ended and exported
+   * when `fn` resolves or throws. Child spans created with `withSpan()` inside
+   * `fn` will automatically be attached as children.
+   */
+  async withSpan<T>(
+    name: string,
+    fn: (span: Span) => Promise<T>,
+    options: SpanOptions = {},
+  ): Promise<T> {
+    const parent = SpanContext.getStore()?.span;
+    const traceId = parent?.data.traceId;
+    const span = new Span(name, parent?.data.spanId, traceId, options.kind ?? "internal");
+
+    if (options.attributes) span.setAttributes(options.attributes);
+
+    let result: T;
+    try {
+      result = await SpanContext.run({ span }, () => fn(span));
+      if (span.data.status.code === "unset") span.setStatus("ok");
+    } catch (err) {
+      span.recordException(err instanceof Error ? err : new Error(String(err)));
+      span.setStatus("error", err instanceof Error ? err.message : String(err));
+      span.end();
+      await this._tryExport(span);
+      throw err;
+    }
+
+    span.end();
+    await this._tryExport(span);
+    return result;
+  }
+
+  /**
+   * Record an already-completed unit of work as a span. Used to bridge synchronous
+   * framework events (which carry their own `durationMs`) into the trace pipeline:
+   * the span is back-dated by `durationMs`, ended, and exported immediately. It has
+   * no parent/active context — these spans represent self-contained, past work.
+   */
+  async recordCompleted(
+    name: string,
+    durationMs: number,
+    options: SpanOptions & { status?: "ok" | "error"; errorMessage?: string } = {},
+  ): Promise<void> {
+    const span = new Span(name, undefined, undefined, options.kind ?? "internal");
+    const now = Date.now();
+    span.data.startMs = now - Math.max(0, durationMs);
+    span.data.endMs = now;
+    if (options.attributes) span.setAttributes(options.attributes);
+    span.setStatus(options.status ?? "ok", options.errorMessage);
+    await this._tryExport(span);
+  }
+
+  /** Start a span manually. Caller is responsible for calling `span.end()`. */
+  startSpan(name: string, options: SpanOptions = {}): Span {
+    const parent = SpanContext.getStore()?.span;
+    const traceId = parent?.data.traceId;
+    const span = new Span(name, parent?.data.spanId, traceId, options.kind ?? "internal");
+    if (options.attributes) span.setAttributes(options.attributes);
+    return span;
+  }
+
+  /** Flush any pending spans and tear down the exporter. */
+  async shutdown(): Promise<void> {
+    await this._exporter.shutdown?.();
+  }
+
+  private async _tryExport(span: Span): Promise<void> {
+    if (span.durationMs < this._minDuration) return;
+    try {
+      await this._exporter.export(span.data);
+    } catch (err) {
+      if (this._rethrow) throw err;
+      // Silently drop — telemetry failures must never affect the application
+    }
+  }
+}

package/src/bridge.ts

@@ -0,0 +1,68 @@
+import { FrameworkEvents } from "@zerotal/core";
+import type { AppBooted, RequestHandled, RequestFailed } from "@zerotal/core";
+import type { Tracer } from "./Tracer.ts";
+
+/** Extract the HTTP-readable fields from the opaque HttpContext object. */
+function _http(raw: object) {
+  return raw as {
+    response?: { status?: number };
+    request?: { method?: string };
+    url?: { pathname?: string };
+  };
+}
+
+/**
+ * Bridge the core lifecycle events (`AppBooted`, `RequestHandled`, `RequestFailed`)
+ * into the trace pipeline as completed spans. Telemetry subscribes to core; core
+ * never depends on telemetry.
+ *
+ * Feature packages forward their own signal (DB queries, jobs, scheduled tasks)
+ * through their own telemetry bridge, which resolves this tracer from the container
+ * when telemetry is installed. Telemetry therefore knows nothing about feature
+ * packages, and adding one requires no change here.
+ *
+ * Returns a function that removes every subscription (call in `onStopping()`).
+ */
+export function installEventBridge(tracer: Tracer): () => void {
+  const unsubs: Array<() => void> = [
+    // ── Application lifecycle ──────────────────────────────────────────────────
+    FrameworkEvents.on<AppBooted>("AppBooted", (e) => {
+      void tracer.recordCompleted("app.boot", e.durationMs, {
+        attributes: { "app.environment": e.environment, "app.providers": e.providerCount },
+      });
+    }),
+
+    // ── HTTP ───────────────────────────────────────────────────────────────────
+    FrameworkEvents.on<RequestHandled>("RequestHandled", (e) => {
+      const c = _http(e.ctx);
+      const status = c.response?.status ?? 0;
+      void tracer.recordCompleted("http.request", e.durationMs, {
+        kind: "server",
+        attributes: {
+          "http.method": c.request?.method ?? "?",
+          "http.route": c.url?.pathname ?? "?",
+          "http.status_code": status,
+        },
+        status: status >= 500 ? "error" : "ok",
+      });
+    }),
+
+    FrameworkEvents.on<RequestFailed>("RequestFailed", (e) => {
+      const c = _http(e.ctx);
+      void tracer.recordCompleted("http.request", e.durationMs, {
+        kind: "server",
+        attributes: {
+          "http.method": c.request?.method ?? "?",
+          "http.route": c.url?.pathname ?? "?",
+          "http.status_code": e.status,
+        },
+        status: "error",
+        errorMessage: e.error,
+      });
+    }),
+  ];
+
+  return () => {
+    for (const unsub of unsubs) unsub();
+  };
+}

package/src/config.ts

@@ -0,0 +1,42 @@
+import { deepMerge } from "@zerotal/core";
+
+export interface TelemetryConfigShape {
+  /**
+   * Exporter backend.
+   * - `'noop'`    - discards all spans (default when telemetry is not configured)
+   * - `'console'` - prints to stdout, useful in development
+   * - `'otlp'`    - sends to an OTLP HTTP endpoint
+   */
+  exporter?: "noop" | "console" | "otlp";
+
+  /** Only relevant when `exporter` is `'otlp'`. */
+  otlp?: {
+    endpoint?: string;
+    headers?: Record<string, string>;
+  };
+
+  /** Service name sent as a resource attribute. Defaults to `APP_NAME` env var or `'zerotal-app'`. */
+  serviceName?: string;
+
+  /** Service version. Defaults to `APP_VERSION` env var or `'0.0.0'`. */
+  serviceVersion?: string;
+
+  /** Drop spans shorter than this many milliseconds. Default: 0 (keep all). */
+  minDurationMs?: number;
+}
+
+const defaults: TelemetryConfigShape = {
+  exporter: "noop",
+  serviceName: "zerotal-app",
+};
+
+export function TelemetryConfig(options: Partial<TelemetryConfigShape> = {}): TelemetryConfigShape {
+  return deepMerge(defaults, options);
+}
+
+// Register this package's config namespace for typed config() dot-paths.
+declare module "@zerotal/core" {
+  interface ConfigRegistry {
+    telemetry: TelemetryConfigShape;
+  }
+}

package/src/exporters/ConsoleExporter.ts

@@ -0,0 +1,32 @@
+import type { SpanExporter } from "./SpanExporter.ts";
+import type { SpanData } from "../Span.ts";
+
+/**
+ * Prints completed spans to stdout in a human-readable format.
+ * Intended for development and debugging — not for production use.
+ *
+ * @example
+ * new Tracer({ exporter: new ConsoleExporter() })
+ */
+export class ConsoleExporter implements SpanExporter {
+  async export(span: SpanData): Promise<void> {
+    const duration = span.endMs !== undefined ? span.endMs - span.startMs : "?";
+    const parent = span.parentId ? `← ${span.parentId.slice(0, 8)}` : "(root)";
+    const status = span.status.code === "unset" ? "ok" : span.status.code;
+    const attrs = Object.entries(span.attributes)
+      .map(([k, v]) => `  ${k}: ${v}`)
+      .join("\n");
+
+    const lines = [
+      `[telemetry] ${span.name}`,
+      `  trace=${span.traceId.slice(0, 16)}  span=${span.spanId}  ${parent}`,
+      `  status=${status}  duration=${duration}ms`,
+    ];
+    if (attrs) lines.push(attrs);
+    if (span.events.length > 0) {
+      lines.push(`  events: ${span.events.map((e) => e.name).join(", ")}`);
+    }
+
+    console.log(lines.join("\n"));
+  }
+}

package/src/exporters/NoopExporter.ts

@@ -0,0 +1,7 @@
+import type { SpanExporter } from "./SpanExporter.ts";
+import type { SpanData } from "../Span.ts";
+
+/** Discards all spans. Used when telemetry is explicitly disabled. */
+export class NoopExporter implements SpanExporter {
+  async export(_span: SpanData): Promise<void> {}
+}

package/src/exporters/OtlpExporter.ts

@@ -0,0 +1,128 @@
+import type { SpanExporter } from "./SpanExporter.ts";
+import type { SpanData, SpanKind } from "../Span.ts";
+
+export interface OtlpExporterOptions {
+  /** OTLP HTTP/JSON endpoint. Default: `'http://localhost:4318/v1/traces'`. */
+  endpoint?: string;
+  /** Extra headers (e.g. `{ 'x-honeycomb-team': '<api-key>' }`). */
+  headers?: Record<string, string>;
+  /** Service name sent as a resource attribute. */
+  serviceName?: string;
+  /** Service version sent as a resource attribute. */
+  serviceVersion?: string;
+}
+
+const SPAN_KIND: Record<SpanKind, number> = {
+  internal: 1,
+  server: 2,
+  client: 3,
+  producer: 4,
+  consumer: 5,
+};
+
+const STATUS_CODE: Record<string, number> = {
+  unset: 0,
+  ok: 1,
+  error: 2,
+};
+
+/**
+ * Sends completed spans to an OTLP-compatible backend over HTTP/JSON.
+ *
+ * Compatible with OpenTelemetry Collector, Jaeger, Honeycomb, Grafana Tempo,
+ * and any service that accepts the OTLP trace JSON format.
+ *
+ * @example
+ * new OtlpExporter({
+ *   endpoint:    'https://api.honeycomb.io/v1/traces',
+ *   headers:     { 'x-honeycomb-team': env('HONEYCOMB_API_KEY') },
+ *   serviceName: 'my-api',
+ * })
+ */
+export class OtlpExporter implements SpanExporter {
+  private readonly _endpoint: string;
+  private readonly _headers: Record<string, string>;
+  private readonly _serviceName: string;
+  private readonly _serviceVer: string;
+
+  constructor(options: OtlpExporterOptions = {}) {
+    this._endpoint = options.endpoint ?? "http://localhost:4318/v1/traces";
+    this._headers = options.headers ?? {};
+    this._serviceName = options.serviceName ?? "zerotal-app";
+    this._serviceVer = options.serviceVersion ?? "0.0.0";
+  }
+
+  async export(span: SpanData): Promise<void> {
+    const body = this._buildPayload(span);
+    try {
+      await fetch(this._endpoint, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          ...this._headers,
+        },
+        body: JSON.stringify(body),
+      });
+    } catch {
+      // Silently drop — telemetry failures must not affect the application
+    }
+  }
+
+  private _buildPayload(span: SpanData): object {
+    const toNanoStr = (ms: number) => (BigInt(ms) * 1_000_000n).toString();
+
+    const otlpAttrs = (attrs: Record<string, string | number | boolean>) =>
+      Object.entries(attrs).map(([key, value]) => ({
+        key,
+        value:
+          typeof value === "string"
+            ? { stringValue: value }
+            : typeof value === "number"
+              ? Number.isInteger(value)
+                ? { intValue: value }
+                : { doubleValue: value }
+              : { boolValue: value },
+      }));
+
+    return {
+      resourceSpans: [
+        {
+          resource: {
+            attributes: otlpAttrs({
+              "service.name": this._serviceName,
+              "service.version": this._serviceVer,
+            }),
+          },
+          scopeSpans: [
+            {
+              scope: { name: "@zerotal/telemetry" },
+              spans: [
+                {
+                  traceId: span.traceId,
+                  spanId: span.spanId,
+                  parentSpanId: span.parentId ?? "",
+                  name: span.name,
+                  kind: SPAN_KIND[span.kind] ?? 1,
+                  startTimeUnixNano: toNanoStr(span.startMs),
+                  endTimeUnixNano: toNanoStr(span.endMs ?? span.startMs),
+                  attributes: otlpAttrs(span.attributes),
+                  status: {
+                    code: STATUS_CODE[span.status.code] ?? 0,
+                    message: span.status.message ?? "",
+                  },
+                  events: span.events.map((e) => ({
+                    name: e.name,
+                    timeUnixNano: toNanoStr(e.timeMs),
+                    attributes: otlpAttrs(
+                      (e.attributes ?? {}) as Record<string, string | number | boolean>,
+                    ),
+                  })),
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    };
+  }
+}

package/src/exporters/SpanExporter.ts

@@ -0,0 +1,8 @@
+import type { SpanData } from "../Span.ts";
+
+/** Receives completed spans and sends them to a backend. */
+export interface SpanExporter {
+  export(span: SpanData): Promise<void>;
+  /** Called on graceful shutdown — flush pending spans and close connections. */
+  shutdown?(): Promise<void>;
+}

package/src/index.ts

@@ -0,0 +1,34 @@
+// Core primitives
+export { Span, NoopSpan, _randomHex } from "./Span.ts";
+export type { SpanData, SpanEvent, SpanStatus, SpanStatusCode, SpanKind } from "./Span.ts";
+
+// Context propagation
+export { SpanContext, currentSpan } from "./SpanContext.ts";
+
+// Tracer
+export { Tracer } from "./Tracer.ts";
+export type { TracerOptions, SpanOptions } from "./Tracer.ts";
+
+// Global helper
+export { withSpan } from "./withSpan.ts";
+
+// Exporters
+export type { SpanExporter } from "./exporters/SpanExporter.ts";
+export { NoopExporter } from "./exporters/NoopExporter.ts";
+export { ConsoleExporter } from "./exporters/ConsoleExporter.ts";
+export { OtlpExporter } from "./exporters/OtlpExporter.ts";
+export type { OtlpExporterOptions } from "./exporters/OtlpExporter.ts";
+
+// Middleware
+export { TelemetryMiddleware } from "./middleware/TelemetryMiddleware.ts";
+export type { TelemetryOptions } from "./middleware/TelemetryMiddleware.ts";
+
+// Provider
+export { TelemetryProvider } from "./provider/TelemetryProvider.ts";
+
+// Event → span bridge (FrameworkEvents → trace pipeline)
+export { installEventBridge } from "./bridge.ts";
+
+// Config factory + types
+export { TelemetryConfig } from "./config.ts";
+export type { TelemetryConfigShape } from "./config.ts";

package/src/middleware/TelemetryMiddleware.ts

@@ -0,0 +1,65 @@
+import type { NextFn } from "@zerotal/core";
+import type { HttpContext } from "@zerotal/core";
+import { BaseMiddleware } from "@zerotal/core";
+import { _getGlobalTracer } from "../withSpan.ts";
+
+export interface TelemetryOptions {
+  /**
+   * Custom function to derive a span name from the request.
+   * Default: `"${method} ${pathname}"`.
+   */
+  spanName?: (ctx: HttpContext) => string;
+}
+
+/**
+ * Creates a server-kind root span for every incoming HTTP request.
+ *
+ * Standard `http.*` attributes are set automatically:
+ *   - `http.method`, `http.url`, `http.route`, `http.status_code`
+ *   - `http.request_id`
+ *
+ * Any child spans created with `withSpan()` inside route handlers or
+ * downstream middleware will automatically attach to this root span.
+ *
+ * Register near the top of the middleware stack, after `LoggerMiddleware`:
+ *   `app.use([LoggerMiddleware, TelemetryMiddleware, ...])`
+ */
+export class TelemetryMiddleware extends BaseMiddleware<TelemetryOptions> {
+  protected options: TelemetryOptions = {};
+
+  async handle(http: HttpContext, next: NextFn): Promise<Response | void> {
+    const tracer = _getGlobalTracer();
+    if (!tracer) return next();
+
+    const method = http.request.method.toUpperCase();
+    const path = http.url.pathname;
+    const name = this.options.spanName?.(http) ?? `${method} ${path}`;
+
+    await tracer.withSpan(
+      name,
+      async (span) => {
+        span.setAttributes({
+          "http.method": method,
+          "http.url": http.url.href,
+          "http.request_id": http.requestId,
+        });
+
+        await next();
+
+        const status = http.response?.status ?? 0;
+        span.setAttribute("http.status_code", status);
+
+        if (http.url.pathname !== path) {
+          // pathname changed — record the matched route
+          span.setAttribute("http.route", http.url.pathname);
+        }
+
+        if (status >= 500) span.setStatus("error", `HTTP ${status}`);
+        else span.setStatus("ok");
+      },
+      { kind: "server" },
+    );
+
+    return http.response;
+  }
+}

package/src/provider/TelemetryProvider.ts

@@ -0,0 +1,74 @@
+import { ServiceProvider } from "@zerotal/core";
+import type { AppEnvironment } from "@zerotal/core";
+import type { ConfigManager } from "@zerotal/core/config";
+import { Tracer } from "../Tracer.ts";
+import { installEventBridge } from "../bridge.ts";
+import { _setGlobalTracer, _getGlobalTracer } from "../withSpan.ts";
+import { NoopExporter } from "../exporters/NoopExporter.ts";
+import { ConsoleExporter } from "../exporters/ConsoleExporter.ts";
+import { OtlpExporter } from "../exporters/OtlpExporter.ts";
+import type { SpanExporter } from "../exporters/SpanExporter.ts";
+import type { TelemetryConfigShape } from "../config.ts";
+
+declare module "@zerotal/core" {
+  interface ContainerBindings {
+    telemetry: Tracer;
+  }
+}
+
+export class TelemetryProvider extends ServiceProvider {
+  static override provides = ["telemetry"] as const;
+  static override environments: AppEnvironment[] = ["web", "console", "test", "repl"];
+
+  private _disposeBridge: (() => void) | undefined = undefined;
+
+  override onRegister(): void {
+    this.app.container.singleton("telemetry", () => {
+      const config = this.app.container.makeSync("config") as ConfigManager;
+      const telConfig = config.get<TelemetryConfigShape>("telemetry", {});
+
+      const exporterType = telConfig.exporter ?? "noop";
+      const serviceName = telConfig.serviceName ?? "zerotal-app";
+      const serviceVersion = telConfig.serviceVersion ?? "0.0.0";
+
+      let exporter: SpanExporter;
+      switch (exporterType) {
+        case "console":
+          exporter = new ConsoleExporter();
+          break;
+        case "otlp": {
+          const otlpOpts: import("../exporters/OtlpExporter.ts").OtlpExporterOptions = {
+            serviceName,
+            serviceVersion,
+          };
+          if (telConfig.otlp?.endpoint) otlpOpts.endpoint = telConfig.otlp.endpoint;
+          if (telConfig.otlp?.headers) otlpOpts.headers = telConfig.otlp.headers;
+          exporter = new OtlpExporter(otlpOpts);
+          break;
+        }
+        case "noop":
+        default:
+          exporter = new NoopExporter();
+      }
+
+      const tracerOpts: import("../Tracer.ts").TracerOptions = { exporter };
+      if (telConfig.minDurationMs !== undefined) tracerOpts.minDurationMs = telConfig.minDurationMs;
+      return new Tracer(tracerOpts);
+    });
+  }
+
+  override async onBooted(): Promise<void> {
+    const tracer = (await this.app.container.make("telemetry")) as Tracer;
+    _setGlobalTracer(tracer);
+    // Forward framework events (HTTP, DB, queue, scheduler, boot) into the trace
+    // pipeline so an OTLP backend sees the same signal the devtools panel does.
+    this._disposeBridge = installEventBridge(tracer);
+  }
+
+  override async onStopping(): Promise<void> {
+    this._disposeBridge?.();
+    this._disposeBridge = undefined;
+    await _getGlobalTracer()?.shutdown();
+    _setGlobalTracer(undefined);
+  }
+}

package/src/withSpan.ts

@@ -0,0 +1,43 @@
+import type { Span } from "./Span.ts";
+import { NoopSpan } from "./Span.ts";
+import type { SpanOptions } from "./Tracer.ts";
+
+// Module-level tracer reference — set by TelemetryProvider on boot.
+let _globalTracer: import("./Tracer.ts").Tracer | undefined;
+
+/** @internal — called by TelemetryProvider */
+export function _setGlobalTracer(tracer: import("./Tracer.ts").Tracer | undefined): void {
+  _globalTracer = tracer;
+}
+
+/** @internal — exposed for testing */
+export function _getGlobalTracer(): import("./Tracer.ts").Tracer | undefined {
+  return _globalTracer;
+}
+
+/**
+ * Runs `fn` inside a named span using the global tracer registered by
+ * `TelemetryProvider`. If no tracer is registered the callback runs normally
+ * and receives a no-op span — no error is thrown.
+ *
+ * @example
+ * import { withSpan } from '@zerotal/telemetry';
+ *
+ * async function processOrder(id: string) {
+ *   return withSpan('process-order', async (span) => {
+ *     span.setAttribute('order.id', id);
+ *     // ...
+ *   });
+ * }
+ */
+export async function withSpan<T>(
+  name: string,
+  fn: (span: Span) => Promise<T>,
+  options: SpanOptions = {},
+): Promise<T> {
+  if (_globalTracer) {
+    return _globalTracer.withSpan(name, fn, options);
+  }
+  // No tracer — run the callback with a no-op span so call sites are always safe
+  return fn(new NoopSpan());
+}