@alxia/telemetry 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Steve Tsala
+
+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,95 @@
+# @alxia/telemetry
+
+Traces and logs for [alxia](https://www.npmjs.com/package/@alxia/core), on
+[`@nxgt/telemetry`](https://www.npmjs.com/package/@nxgt/telemetry): no
+OpenTelemetry SDK, no dependency. One server span per request, around
+everything the request runs, named for its route — and every log written
+inside it carrying its trace id.
+
+```sh
+bun add @alxia/telemetry @nxgt/telemetry @alxia/core
+bun add -d typescript
+```
+
+`@nxgt/telemetry` is a peer: the app's own copy, shared with its loggers.
+
+## Usage
+
+```ts
+import { alxia } from '@alxia/core';
+import { telemetry } from '@alxia/telemetry';
+import { consoleExporter, createLogger } from '@nxgt/telemetry';
+
+const tracing = telemetry({
+	service: 'checkout',
+	version: '1.4.0',
+	exporters: [consoleExporter()], // or @nxgt/telemetry-otlp's otlpExporter
+	traced: (ctx) => ctx.url.pathname !== '/health',
+});
+
+const log = createLogger('Orders');
+
+const app = alxia()
+	.use(tracing)
+	.get('/orders/:id', ({ params, span, reply }) => {
+		span?.attribute('order.id', params.id);
+		log.info('order read');                 // carries this request's traceId
+		return reply(200, { id: params.id });
+	})
+	.onStop(() => tracing.telemetry.close()); // awaited, or the last batch is lost
+
+app.listen(3000);
+```
+
+## The span
+
+- It is opened by an `around` hook: it holds the hooks, the handler,
+  everything they await and the `onResponse` hooks.
+- An inbound `traceparent` continues its trace, as a child of the caller's
+  span. An unusable one starts a fresh trace: the header came from a
+  stranger.
+- It starts as `GET /orders/o-1` and is renamed `GET /orders/:id` once
+  routing has matched, with `http.route`: one dashboard row per route, not
+  per order. A request no route matched keeps its path.
+- A route's error is its exception. Only a 5xx makes the span an error: a
+  401 a guard answered is the server working.
+- `traceResponse: true` says the `traceparent` back on the response.
+
+## What it records
+
+| attribute | |
+| --- | --- |
+| `http.request.method`, `url.path`, `url.scheme` | the request |
+| `server.address`, `server.port`, `client.address` | where it was addressed, and from |
+| `http.route` | the route, once matched |
+| `http.response.status_code` | the status |
+
+They are `@nxgt/telemetry-hono`'s names: a span from either reads the same
+in a dashboard.
+
+## Options
+
+The usual `@nxgt/telemetry` options and a `service`, or an existing
+telemetry as `instance` — adopted, never closed. And:
+
+| option | default | |
+| --- | --- | --- |
+| `traced` | every request | `(ctx) => boolean`: a health check |
+| `spanName` | `"<METHOD> <path>"` | the name before routing |
+| `traceResponse` | `false` | says `traceparent` back |
+
+A hook that throws costs its answer, never the request.
+
+## API
+
+| export | |
+| --- | --- |
+| `telemetry(options)` | the plugin, with the telemetry it writes to as `.telemetry`; routes after it read `span` and `telemetry` |
+| `TelemetryPluginOptions` | its options: `service` and `@nxgt/telemetry`'s options, or an `instance`; `traced`, `spanName`, `traceResponse` |
+| `HTTP_METHOD`, `URL_PATH`, `URL_SCHEME`, `HTTP_ROUTE`, `HTTP_STATUS`, `SERVER_ADDRESS`, `SERVER_PORT`, `CLIENT_ADDRESS` | the attribute names a server span carries: `http.request.method`, `url.path`, `url.scheme`, `http.route`, `http.response.status_code`, `server.address`, `server.port`, `client.address` |
+
+## Documentation
+
+- [Guide](https://github.com/softistx/alxia/tree/develop/packages/telemetry/docs): the span each request gets and what it records, how a trace crosses services, every option with its default, shutting down, and testing.
+- [Troubleshooting](https://github.com/softistx/alxia/blob/develop/packages/telemetry/docs/troubleshooting.md): a `tsc` error, an export failure, or a span or a log that is missing.
+- [Roadmap](https://github.com/softistx/alxia/blob/develop/packages/telemetry/docs/roadmap.md): what is coming, and what is not planned.

package/dist/attributes.d.ts

@@ -0,0 +1,21 @@
+import type { Attributes } from '@nxgt/telemetry';
+/**
+ * The semantic conventions a server span carries, by name: the ones a
+ * backend's HTTP dashboards look for. They are `@nxgt/telemetry-hono`'s
+ * names, kept twice on purpose — importing them would make this package
+ * depend on Hono — and a server span here and a client span from
+ * `@nxgt/telemetry-httpyz` must agree on them.
+ */
+export declare const HTTP_METHOD = "http.request.method";
+export declare const URL_PATH = "url.path";
+export declare const URL_SCHEME = "url.scheme";
+export declare const HTTP_ROUTE = "http.route";
+export declare const HTTP_STATUS = "http.response.status_code";
+export declare const SERVER_ADDRESS = "server.address";
+export declare const SERVER_PORT = "server.port";
+export declare const CLIENT_ADDRESS = "client.address";
+/** A 4xx is the server working: only a 5xx marks a span. */
+export declare function serverFailed(status: number): boolean;
+/** What is known of a request before routing: the route is not, yet. */
+export declare function requestAttributes(url: URL, method: string, ip: string | undefined): Attributes;
+//# sourceMappingURL=attributes.d.ts.map

package/dist/attributes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attributes.d.ts","sourceRoot":"","sources":["../src/attributes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,wBAAwB,CAAC;AACjD,eAAO,MAAM,QAAQ,aAAa,CAAC;AACnC,eAAO,MAAM,UAAU,eAAe,CAAC;AACvC,eAAO,MAAM,UAAU,eAAe,CAAC;AACvC,eAAO,MAAM,WAAW,8BAA8B,CAAC;AACvD,eAAO,MAAM,cAAc,mBAAmB,CAAC;AAC/C,eAAO,MAAM,WAAW,gBAAgB,CAAC;AACzC,eAAO,MAAM,cAAc,mBAAmB,CAAC;AAE/C,4DAA4D;AAC5D,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED,wEAAwE;AACxE,wBAAgB,iBAAiB,CAChC,GAAG,EAAE,GAAG,EACR,MAAM,EAAE,MAAM,EACd,EAAE,EAAE,MAAM,GAAG,SAAS,GACpB,UAAU,CASZ"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { CLIENT_ADDRESS, HTTP_METHOD, HTTP_ROUTE, HTTP_STATUS, SERVER_ADDRESS, SERVER_PORT, URL_PATH, URL_SCHEME, } from './attributes';
+export { type TelemetryPluginOptions, telemetry } from './telemetry';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,cAAc,EACd,WAAW,EACX,UAAU,EACV,WAAW,EACX,cAAc,EACd,WAAW,EACX,QAAQ,EACR,UAAU,GACV,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,KAAK,sBAAsB,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,100 @@
+// src/attributes.ts
+var HTTP_METHOD = "http.request.method";
+var URL_PATH = "url.path";
+var URL_SCHEME = "url.scheme";
+var HTTP_ROUTE = "http.route";
+var HTTP_STATUS = "http.response.status_code";
+var SERVER_ADDRESS = "server.address";
+var SERVER_PORT = "server.port";
+var CLIENT_ADDRESS = "client.address";
+function serverFailed(status) {
+  return status >= 500;
+}
+function requestAttributes(url, method, ip) {
+  return {
+    [HTTP_METHOD]: method,
+    [URL_PATH]: url.pathname,
+    [URL_SCHEME]: url.protocol.replace(":", ""),
+    [SERVER_ADDRESS]: url.hostname,
+    ...url.port === "" ? {} : { [SERVER_PORT]: Number(url.port) },
+    ...ip === undefined ? {} : { [CLIENT_ADDRESS]: ip }
+  };
+}
+// src/telemetry.ts
+import { alxia } from "@alxia/core";
+import {
+  continuing,
+  createTelemetry,
+  withTelemetry
+} from "@nxgt/telemetry";
+function telemetry(options) {
+  const instance = options.instance ?? createTelemetry(options.service, options).install();
+  const traced = guarded(options.traced ?? (() => true), () => true);
+  const spanName = guarded(options.spanName ?? defaultName, defaultName);
+  const scopes = new WeakMap;
+  const plugin = alxia().around((ctx, next) => {
+    if (!traced(ctx))
+      return next();
+    return withTelemetry(instance, () => continuing(ctx.request.headers.get("traceparent"), spanName(ctx), { kind: "server" }, async (scope) => {
+      scope.attributes(requestAttributes(ctx.url, ctx.request.method, ctx.ip));
+      scopes.set(ctx.request, scope);
+      let response;
+      try {
+        response = await next();
+      } finally {
+        if (ctx.route !== undefined) {
+          scope.name = `${ctx.request.method} ${ctx.route}`;
+          scope.attribute(HTTP_ROUTE, ctx.route);
+        }
+      }
+      record(scope, response.status, ctx.error);
+      if (options.traceResponse) {
+        try {
+          response.headers.set("traceparent", scope.traceparent());
+        } catch {}
+      }
+      return response;
+    }));
+  }).derive(({ request }) => ({
+    span: scopes.get(request),
+    telemetry: instance
+  }));
+  return Object.assign(plugin, { telemetry: instance });
+}
+function record(scope, status, error) {
+  if (error !== undefined) {
+    const before = scope.status;
+    scope.fail(error);
+    if (!serverFailed(status))
+      scope.status = before;
+  }
+  scope.attribute(HTTP_STATUS, status);
+  if (serverFailed(status) && scope.status === "ok")
+    scope.status = "error";
+}
+function defaultName(ctx) {
+  return `${ctx.request.method} ${ctx.url.pathname}`;
+}
+function guarded(hook, fallback) {
+  return (ctx) => {
+    try {
+      return hook(ctx);
+    } catch {
+      return fallback(ctx);
+    }
+  };
+}
+export {
+  CLIENT_ADDRESS,
+  HTTP_METHOD,
+  HTTP_ROUTE,
+  HTTP_STATUS,
+  SERVER_ADDRESS,
+  SERVER_PORT,
+  URL_PATH,
+  URL_SCHEME,
+  telemetry
+};
+
+//# debugId=1F0C16FED53E6A3964756E2164756E21
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1,11 @@
+{
+  "version": 3,
+  "sources": ["../src/attributes.ts", "../src/telemetry.ts"],
+  "sourcesContent": [
+    "import type { Attributes } from '@nxgt/telemetry';\n\n/**\n * The semantic conventions a server span carries, by name: the ones a\n * backend's HTTP dashboards look for. They are `@nxgt/telemetry-hono`'s\n * names, kept twice on purpose — importing them would make this package\n * depend on Hono — and a server span here and a client span from\n * `@nxgt/telemetry-httpyz` must agree on them.\n */\nexport const HTTP_METHOD = 'http.request.method';\nexport const URL_PATH = 'url.path';\nexport const URL_SCHEME = 'url.scheme';\nexport const HTTP_ROUTE = 'http.route';\nexport const HTTP_STATUS = 'http.response.status_code';\nexport const SERVER_ADDRESS = 'server.address';\nexport const SERVER_PORT = 'server.port';\nexport const CLIENT_ADDRESS = 'client.address';\n\n/** A 4xx is the server working: only a 5xx marks a span. */\nexport function serverFailed(status: number): boolean {\n\treturn status >= 500;\n}\n\n/** What is known of a request before routing: the route is not, yet. */\nexport function requestAttributes(\n\turl: URL,\n\tmethod: string,\n\tip: string | undefined,\n): Attributes {\n\treturn {\n\t\t[HTTP_METHOD]: method,\n\t\t[URL_PATH]: url.pathname,\n\t\t[URL_SCHEME]: url.protocol.replace(':', ''),\n\t\t[SERVER_ADDRESS]: url.hostname,\n\t\t...(url.port === '' ? {} : { [SERVER_PORT]: Number(url.port) }),\n\t\t...(ip === undefined ? {} : { [CLIENT_ADDRESS]: ip }),\n\t};\n}\n",
+    "import { alxia, type RequestContext } from '@alxia/core';\nimport {\n\tcontinuing,\n\tcreateTelemetry,\n\ttype SpanScope,\n\ttype Telemetry,\n\ttype TelemetryOptions,\n\twithTelemetry,\n} from '@nxgt/telemetry';\nimport {\n\tHTTP_ROUTE,\n\tHTTP_STATUS,\n\trequestAttributes,\n\tserverFailed,\n} from './attributes';\n\ninterface Hooks {\n\t/**\n\t * Whether a request gets a span. Every one does by default: a library\n\t * that decides which requests do not matter hides the one that did.\n\t */\n\treadonly traced?: (ctx: RequestContext) => boolean;\n\t/** The span's name before routing. `\"<METHOD> <path>\"` by default, then `\"<METHOD> <route>\"`. */\n\treadonly spanName?: (ctx: RequestContext) => string;\n\t/** Whether the response says `traceparent` back, so a caller can find the trace. Off by default. */\n\treadonly traceResponse?: boolean;\n}\n\n/**\n * A telemetry built from `service` and `@nxgt/telemetry`'s options, and\n * installed; or one handed over as `instance`, adopted and not closed.\n */\nexport type TelemetryPluginOptions =\n\t| (Hooks &\n\t\t\tTelemetryOptions & {\n\t\t\t\t/** The service name: everything groups by it. */\n\t\t\t\treadonly service: string;\n\t\t\t\treadonly instance?: undefined;\n\t\t\t})\n\t| (Hooks & {\n\t\t\treadonly instance: Telemetry;\n\t\t\treadonly service?: undefined;\n\t  });\n\n/**\n * One server span per request, with [`@nxgt/telemetry`](https://www.npmjs.com/package/@nxgt/telemetry),\n * as a plugin.\n *\n * The span is opened by an `around` hook, so it holds everything the\n * request runs — the hooks, the handler, what they await, the `onResponse`\n * hooks — and every log written with `createLogger` inside it carries its\n * trace id. An inbound `traceparent` continues its trace; an unusable one\n * starts a fresh trace. The span is named for the route, `GET /users/:id`,\n * once routing has matched. Only a 5xx marks it an error.\n *\n * Routes declared after the plugin read the span as `span`, and the\n * telemetry as `telemetry`.\n *\n * ```ts\n * const tracing = telemetry({ service: 'checkout', exporters: [otlpExporter({ endpoint })] });\n * const app = alxia().use(tracing).get(...);\n * app.onStop(() => tracing.telemetry.close());\n * ```\n */\nexport function telemetry(options: TelemetryPluginOptions) {\n\tconst instance =\n\t\toptions.instance ?? createTelemetry(options.service, options).install();\n\tconst traced = guarded(options.traced ?? (() => true), () => true);\n\tconst spanName = guarded(options.spanName ?? defaultName, defaultName);\n\tconst scopes = new WeakMap<Request, SpanScope>();\n\n\tconst plugin = alxia()\n\t\t.around((ctx, next) => {\n\t\t\tif (!traced(ctx)) return next();\n\t\t\treturn withTelemetry(instance, () =>\n\t\t\t\tcontinuing(\n\t\t\t\t\tctx.request.headers.get('traceparent'),\n\t\t\t\t\tspanName(ctx),\n\t\t\t\t\t{ kind: 'server' },\n\t\t\t\t\tasync (scope) => {\n\t\t\t\t\t\t// The span's own, not `SpanOptions.attributes`: those every span\n\t\t\t\t\t\t// and log inside inherits, and a database call is not the request.\n\t\t\t\t\t\tscope.attributes(\n\t\t\t\t\t\t\trequestAttributes(ctx.url, ctx.request.method, ctx.ip),\n\t\t\t\t\t\t);\n\t\t\t\t\t\tscopes.set(ctx.request, scope);\n\t\t\t\t\t\tlet response: Response;\n\t\t\t\t\t\ttry {\n\t\t\t\t\t\t\tresponse = await next();\n\t\t\t\t\t\t} finally {\n\t\t\t\t\t\t\t// Even a request that failed was routed, and the route is the name.\n\t\t\t\t\t\t\tif (ctx.route !== undefined) {\n\t\t\t\t\t\t\t\tscope.name = `${ctx.request.method} ${ctx.route}`;\n\t\t\t\t\t\t\t\tscope.attribute(HTTP_ROUTE, ctx.route);\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t}\n\t\t\t\t\t\trecord(scope, response.status, ctx.error);\n\t\t\t\t\t\tif (options.traceResponse) {\n\t\t\t\t\t\t\ttry {\n\t\t\t\t\t\t\t\tresponse.headers.set('traceparent', scope.traceparent());\n\t\t\t\t\t\t\t} catch {\n\t\t\t\t\t\t\t\t// An immutable response keeps its headers; the span is what matters.\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t}\n\t\t\t\t\t\treturn response;\n\t\t\t\t\t},\n\t\t\t\t),\n\t\t\t);\n\t\t})\n\t\t.derive(({ request }) => ({\n\t\t\t/** The server span around this request; `undefined` when `traced` said no. */\n\t\t\tspan: scopes.get(request),\n\t\t\ttelemetry: instance,\n\t\t}));\n\n\treturn Object.assign(plugin, { telemetry: instance });\n}\n\n/**\n * The status, and the failure. A route's error is recorded as the span's\n * exception, but only a 5xx makes it an error: a 401 a guard answered is\n * the server working.\n */\nfunction record(scope: SpanScope, status: number, error: unknown): void {\n\tif (error !== undefined) {\n\t\tconst before = scope.status;\n\t\tscope.fail(error);\n\t\tif (!serverFailed(status)) scope.status = before;\n\t}\n\tscope.attribute(HTTP_STATUS, status);\n\tif (serverFailed(status) && scope.status === 'ok') scope.status = 'error';\n}\n\nfunction defaultName(ctx: RequestContext): string {\n\treturn `${ctx.request.method} ${ctx.url.pathname}`;\n}\n\n/** A hook, and what to answer when it throws: observability never costs the request. */\nfunction guarded<T>(\n\thook: (ctx: RequestContext) => T,\n\tfallback: (ctx: RequestContext) => T,\n): (ctx: RequestContext) => T {\n\treturn (ctx) => {\n\t\ttry {\n\t\t\treturn hook(ctx);\n\t\t} catch {\n\t\t\treturn fallback(ctx);\n\t\t}\n\t};\n}\n"
+  ],
+  "mappings": ";AASO,IAAM,cAAc;AACpB,IAAM,WAAW;AACjB,IAAM,aAAa;AACnB,IAAM,aAAa;AACnB,IAAM,cAAc;AACpB,IAAM,iBAAiB;AACvB,IAAM,cAAc;AACpB,IAAM,iBAAiB;AAGvB,SAAS,YAAY,CAAC,QAAyB;AAAA,EACrD,OAAO,UAAU;AAAA;AAIX,SAAS,iBAAiB,CAChC,KACA,QACA,IACa;AAAA,EACb,OAAO;AAAA,KACL,cAAc;AAAA,KACd,WAAW,IAAI;AAAA,KACf,aAAa,IAAI,SAAS,QAAQ,KAAK,EAAE;AAAA,KACzC,iBAAiB,IAAI;AAAA,OAClB,IAAI,SAAS,KAAK,CAAC,IAAI,GAAG,cAAc,OAAO,IAAI,IAAI,EAAE;AAAA,OACzD,OAAO,YAAY,CAAC,IAAI,GAAG,iBAAiB,GAAG;AAAA,EACpD;AAAA;;ACpCD;AACA;AAAA;AAAA;AAAA;AAAA;AA+DO,SAAS,SAAS,CAAC,SAAiC;AAAA,EAC1D,MAAM,WACL,QAAQ,YAAY,gBAAgB,QAAQ,SAAS,OAAO,EAAE,QAAQ;AAAA,EACvE,MAAM,SAAS,QAAQ,QAAQ,WAAW,MAAM,OAAO,MAAM,IAAI;AAAA,EACjE,MAAM,WAAW,QAAQ,QAAQ,YAAY,aAAa,WAAW;AAAA,EACrE,MAAM,SAAS,IAAI;AAAA,EAEnB,MAAM,SAAS,MAAM,EACnB,OAAO,CAAC,KAAK,SAAS;AAAA,IACtB,IAAI,CAAC,OAAO,GAAG;AAAA,MAAG,OAAO,KAAK;AAAA,IAC9B,OAAO,cAAc,UAAU,MAC9B,WACC,IAAI,QAAQ,QAAQ,IAAI,aAAa,GACrC,SAAS,GAAG,GACZ,EAAE,MAAM,SAAS,GACjB,OAAO,UAAU;AAAA,MAGhB,MAAM,WACL,kBAAkB,IAAI,KAAK,IAAI,QAAQ,QAAQ,IAAI,EAAE,CACtD;AAAA,MACA,OAAO,IAAI,IAAI,SAAS,KAAK;AAAA,MAC7B,IAAI;AAAA,MACJ,IAAI;AAAA,QACH,WAAW,MAAM,KAAK;AAAA,gBACrB;AAAA,QAED,IAAI,IAAI,UAAU,WAAW;AAAA,UAC5B,MAAM,OAAO,GAAG,IAAI,QAAQ,UAAU,IAAI;AAAA,UAC1C,MAAM,UAAU,YAAY,IAAI,KAAK;AAAA,QACtC;AAAA;AAAA,MAED,OAAO,OAAO,SAAS,QAAQ,IAAI,KAAK;AAAA,MACxC,IAAI,QAAQ,eAAe;AAAA,QAC1B,IAAI;AAAA,UACH,SAAS,QAAQ,IAAI,eAAe,MAAM,YAAY,CAAC;AAAA,UACtD,MAAM;AAAA,MAGT;AAAA,MACA,OAAO;AAAA,KAET,CACD;AAAA,GACA,EACA,OAAO,GAAG,eAAe;AAAA,IAEzB,MAAM,OAAO,IAAI,OAAO;AAAA,IACxB,WAAW;AAAA,EACZ,EAAE;AAAA,EAEH,OAAO,OAAO,OAAO,QAAQ,EAAE,WAAW,SAAS,CAAC;AAAA;AAQrD,SAAS,MAAM,CAAC,OAAkB,QAAgB,OAAsB;AAAA,EACvE,IAAI,UAAU,WAAW;AAAA,IACxB,MAAM,SAAS,MAAM;AAAA,IACrB,MAAM,KAAK,KAAK;AAAA,IAChB,IAAI,CAAC,aAAa,MAAM;AAAA,MAAG,MAAM,SAAS;AAAA,EAC3C;AAAA,EACA,MAAM,UAAU,aAAa,MAAM;AAAA,EACnC,IAAI,aAAa,MAAM,KAAK,MAAM,WAAW;AAAA,IAAM,MAAM,SAAS;AAAA;AAGnE,SAAS,WAAW,CAAC,KAA6B;AAAA,EACjD,OAAO,GAAG,IAAI,QAAQ,UAAU,IAAI,IAAI;AAAA;AAIzC,SAAS,OAAU,CAClB,MACA,UAC6B;AAAA,EAC7B,OAAO,CAAC,QAAQ;AAAA,IACf,IAAI;AAAA,MACH,OAAO,KAAK,GAAG;AAAA,MACd,MAAM;AAAA,MACP,OAAO,SAAS,GAAG;AAAA;AAAA;AAAA;",
+  "debugId": "1F0C16FED53E6A3964756E2164756E21",
+  "names": []
+}

package/dist/telemetry.d.ts

@@ -0,0 +1,54 @@
+import { type RequestContext } from '@alxia/core';
+import { type SpanScope, type Telemetry, type TelemetryOptions } from '@nxgt/telemetry';
+interface Hooks {
+    /**
+     * Whether a request gets a span. Every one does by default: a library
+     * that decides which requests do not matter hides the one that did.
+     */
+    readonly traced?: (ctx: RequestContext) => boolean;
+    /** The span's name before routing. `"<METHOD> <path>"` by default, then `"<METHOD> <route>"`. */
+    readonly spanName?: (ctx: RequestContext) => string;
+    /** Whether the response says `traceparent` back, so a caller can find the trace. Off by default. */
+    readonly traceResponse?: boolean;
+}
+/**
+ * A telemetry built from `service` and `@nxgt/telemetry`'s options, and
+ * installed; or one handed over as `instance`, adopted and not closed.
+ */
+export type TelemetryPluginOptions = (Hooks & TelemetryOptions & {
+    /** The service name: everything groups by it. */
+    readonly service: string;
+    readonly instance?: undefined;
+}) | (Hooks & {
+    readonly instance: Telemetry;
+    readonly service?: undefined;
+});
+/**
+ * One server span per request, with [`@nxgt/telemetry`](https://www.npmjs.com/package/@nxgt/telemetry),
+ * as a plugin.
+ *
+ * The span is opened by an `around` hook, so it holds everything the
+ * request runs — the hooks, the handler, what they await, the `onResponse`
+ * hooks — and every log written with `createLogger` inside it carries its
+ * trace id. An inbound `traceparent` continues its trace; an unusable one
+ * starts a fresh trace. The span is named for the route, `GET /users/:id`,
+ * once routing has matched. Only a 5xx marks it an error.
+ *
+ * Routes declared after the plugin read the span as `span`, and the
+ * telemetry as `telemetry`.
+ *
+ * ```ts
+ * const tracing = telemetry({ service: 'checkout', exporters: [otlpExporter({ endpoint })] });
+ * const app = alxia().use(tracing).get(...);
+ * app.onStop(() => tracing.telemetry.close());
+ * ```
+ */
+export declare function telemetry(options: TelemetryPluginOptions): import("@alxia/core").Alxia<import("@alxia/core").Empty & {
+    /** The server span around this request; `undefined` when `traced` said no. */
+    span: SpanScope | undefined;
+    telemetry: Telemetry;
+}, import("@alxia/core").Empty, "", never> & {
+    telemetry: Telemetry;
+};
+export {};
+//# sourceMappingURL=telemetry.d.ts.map

package/dist/telemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../src/telemetry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAS,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EAGN,KAAK,SAAS,EACd,KAAK,SAAS,EACd,KAAK,gBAAgB,EAErB,MAAM,iBAAiB,CAAC;AAQzB,UAAU,KAAK;IACd;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,OAAO,CAAC;IACnD,iGAAiG;IACjG,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,MAAM,CAAC;IACpD,oGAAoG;IACpG,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;CACjC;AAED;;;GAGG;AACH,MAAM,MAAM,sBAAsB,GAC/B,CAAC,KAAK,GACN,gBAAgB,GAAG;IAClB,iDAAiD;IACjD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,CAAC;CAC9B,CAAC,GACF,CAAC,KAAK,GAAG;IACT,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC;IAC7B,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,CAAC;CAC5B,CAAC,CAAC;AAEN;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,sBAAsB;IA8CtD,8EAA8E;;;;;EAMhF"}

package/docs/README.md

@@ -0,0 +1,12 @@
+# @alxia/telemetry documentation
+
+The [package README](../README.md) is the short version. This folder is
+the long one: the span each request gets and what it records, how a trace
+crosses services, every option with its default, and what to do when a
+span or a log does not show up where you expected it.
+
+| Page | Read it when |
+| --- | --- |
+| [Guide](guide.md) | choosing between `service` and `instance`, leaving a health check untraced, continuing a caller's trace or calling another service, closing the telemetry on shutdown, sending to a collector, or testing the spans |
+| [Troubleshooting](troubleshooting.md) | `tsc` refused an option or a route, the server logged `[telemetry] export failed`, or a span or a log is missing or not what you expected |
+| [Roadmap](roadmap.md) | wondering what is coming, and what is not planned |

package/docs/guide.md

@@ -0,0 +1,461 @@
+# Guide
+
+This page covers what `telemetry()` records and when: the span it opens
+around each request, how it is named, what it carries, how a trace crosses
+services, each option with its default, and how to close it, test it, and
+call another service from inside it.
+
+```ts
+import { alxia } from '@alxia/core';
+import { telemetry } from '@alxia/telemetry';
+import { consoleExporter, createLogger } from '@nxgt/telemetry';
+
+const tracing = telemetry({ service: 'checkout', exporters: [consoleExporter()] });
+const log = createLogger('Orders');
+
+const app = alxia()
+	.use(tracing)
+	.get('/orders/:id', ({ params, span, reply }) => {
+		span?.attribute('order.id', params.id);
+		log.info('order read');
+		return reply(200, { id: params.id });
+	})
+	.onStop(() => tracing.telemetry.close());
+
+app.listen(3000);
+```
+
+`GET /orders/o-1` now writes a server span named `GET /orders/:id` to the
+console, and the `order read` log line carries that span's `traceId` and
+`spanId`. Swap `consoleExporter()` for any other `@nxgt/telemetry`
+exporter, and nothing else changes.
+
+## The signature
+
+```ts
+function telemetry(
+	options: TelemetryPluginOptions,
+): Alxia<Empty & { span: SpanScope | undefined; telemetry: Telemetry }, Empty, '', never> & {
+	telemetry: Telemetry;
+};
+
+type TelemetryPluginOptions =
+	| (Hooks & TelemetryOptions & { readonly service: string; readonly instance?: undefined })
+	| (Hooks & { readonly instance: Telemetry; readonly service?: undefined });
+
+interface Hooks {
+	readonly traced?: (ctx: RequestContext) => boolean;
+	readonly spanName?: (ctx: RequestContext) => string;
+	readonly traceResponse?: boolean;
+}
+```
+
+`SpanScope`, `Telemetry` and `TelemetryOptions` are `@nxgt/telemetry`'s;
+`RequestContext` is `@alxia/core`'s. `telemetry()` returns an app plugin:
+pass it to `use`, called. It adds a global `around` hook, which traces every
+request of the app, and a `derive`, which gives the routes declared
+**after** it `span` and `telemetry`. The telemetry it writes to is also on
+the plugin itself, as `.telemetry`, for the code that is not a route.
+
+## The span
+
+One span per request, of kind `server`, opened by the `around` hook. It
+holds everything the request runs: the `onRequest` hooks, routing,
+validation, the route's hooks and handler, whatever they await, and the
+`onResponse` hooks. A log written with `createLogger` anywhere inside it,
+and a span opened with `span()`, belong to it.
+
+```ts
+import { alxia } from '@alxia/core';
+import { telemetry } from '@alxia/telemetry';
+import { consoleExporter, createLogger, span } from '@nxgt/telemetry';
+
+const log = createLogger('Orders');
+
+const app = alxia()
+	.use(telemetry({ service: 'checkout', exporters: [consoleExporter()] }))
+	.get('/orders/:id', async ({ params, reply }) => {
+		const order = await span('orders.find', () => ({ id: params.id })); // a child of the server span
+		log.info('order read');                                            // carries the server span's ids
+		return reply(200, order);
+	});
+```
+
+Because the hook is global, a route declared before `use(telemetry(...))`
+is traced too; it only cannot read `span` and `telemetry` from its context.
+A WebSocket upgrade is not traced: `@alxia/core` runs no `around` hook for
+it, since there is no response to wrap.
+
+### Its name
+
+| The request | The span's name |
+| --- | --- |
+| before routing | `spanName(ctx)`, by default `"<METHOD> <path>"`: `GET /orders/o-1` |
+| routing matched a route | `"<METHOD> <route>"`: `GET /orders/:id`, and `http.route` is set |
+| no route matched (`404`, `405`) | stays what it was before routing |
+
+A route's name replaces any `spanName`: one dashboard row per route, not
+one per order. So `spanName` only names what routing did not match. A
+`HEAD` request answered by a `GET` route is named `HEAD /orders/:id`.
+
+### Its status, and the route's error
+
+| The response | The span's status | Its exception |
+| --- | --- | --- |
+| `2xx`, `3xx`, `4xx` | `ok` | none |
+| a `4xx` an `onError` hook made of a thrown error | `ok` | the error |
+| a `5xx` from a throw | `error` | the error |
+| a `5xx` the route replied | `error` | none |
+
+A `401` a guard answered is the server working, so a 4xx never marks a
+span. The error the route failed with is still recorded, as `ctx.error`
+holds it:
+
+```ts
+import { alxia } from '@alxia/core';
+import { telemetry } from '@alxia/telemetry';
+import { consoleExporter } from '@nxgt/telemetry';
+
+const app = alxia()
+	.use(telemetry({ service: 'checkout', exporters: [consoleExporter()] }))
+	.onError((error, { reply }) =>
+		error instanceof RangeError ? reply(400, { error: 'out_of_range' as const }) : undefined,
+	)
+	.get('/range', () => {
+		throw new RangeError('out of range');
+	});
+
+await app.request('/range'); // 400; the span is ok, with `out of range` as its exception
+```
+
+### What it records
+
+| Attribute | Exported as | Value | When |
+| --- | --- | --- | --- |
+| `http.request.method` | `HTTP_METHOD` | `GET` | always |
+| `url.path` | `URL_PATH` | `/orders/o-1` | always |
+| `url.scheme` | `URL_SCHEME` | `http` | always |
+| `server.address` | `SERVER_ADDRESS` | the request URL's host name | always |
+| `server.port` | `SERVER_PORT` | `3000`, a number | when the request URL names a port |
+| `client.address` | `CLIENT_ADDRESS` | the caller's address, as the app's `ip` option reads it | when there is one: not through `app.request` |
+| `http.route` | `HTTP_ROUTE` | `/orders/:id` | once routing matched |
+| `http.response.status_code` | `HTTP_STATUS` | `200`, a number | always |
+
+They are the names of `@nxgt/telemetry-hono`, so a span from either reads
+the same in a dashboard. The constants are exported for code that reads
+spans back, a test for one:
+
+```ts
+import { HTTP_ROUTE, HTTP_STATUS } from '@alxia/telemetry';
+import type { SpanRecord } from '@nxgt/telemetry';
+
+function routeOf(span: SpanRecord): string {
+	return `${String(span.attributes[HTTP_ROUTE])} ${String(span.attributes[HTTP_STATUS])}`;
+}
+```
+
+All of them are the server span's own: a child span — a database call, an
+outgoing request — and a log written inside the request carry its trace
+and span ids, not the request's path, method or the client's address. An
+attribute every log of a request should carry is yours to give, with
+`@nxgt/telemetry`'s `withAttributes`: it reaches what runs inside it, so
+an `around` hook declared after the plugin covers the whole request:
+
+```ts
+import { alxia } from '@alxia/core';
+import { telemetry } from '@alxia/telemetry';
+import { withAttributes } from '@nxgt/telemetry';
+
+const app = alxia()
+	.use(telemetry({ service: 'shop' }))
+	.around((ctx, next) =>
+		withAttributes({ 'tenant.id': ctx.request.headers.get('x-tenant') ?? 'none' }, next),
+	);
+```
+
+## Across services
+
+**In.** An inbound `traceparent` header continues its trace: the span takes
+its trace id, and the caller's span id as its parent. A header that cannot
+be read starts a fresh trace, as a request without one does.
+
+**Out.** Inside a request, the current span says the header an outgoing
+call should carry:
+
+```ts
+import { alxia } from '@alxia/core';
+import { telemetry } from '@alxia/telemetry';
+import { consoleExporter, span } from '@nxgt/telemetry';
+
+const app = alxia()
+	.use(telemetry({ service: 'checkout', exporters: [consoleExporter()] }))
+	.post('/orders/:id/reserve', async ({ params, reply }) => {
+		const stock = await span('stock.reserve', { kind: 'client' }, (scope) =>
+			fetch(`https://stock.example.com/reserve/${params.id}`, {
+				method: 'POST',
+				headers: { traceparent: scope.traceparent() },
+			}),
+		);
+		return reply(stock.ok ? 200 : 502, { reserved: stock.ok });
+	});
+```
+
+`currentTraceparent()` from `@nxgt/telemetry` says the same thing without a
+scope at hand. With httpyz, [`@nxgt/telemetry-httpyz`](https://www.npmjs.com/package/@nxgt/telemetry-httpyz)
+does it for every call.
+
+**Back.** With `traceResponse: true`, the response carries the span's
+`traceparent`, so a caller can find the trace of the request it made:
+
+```ts
+import { alxia } from '@alxia/core';
+import { telemetry } from '@alxia/telemetry';
+import { consoleExporter } from '@nxgt/telemetry';
+
+const app = alxia()
+	.use(telemetry({ service: 'checkout', exporters: [consoleExporter()], traceResponse: true }))
+	.get('/', ({ reply }) => reply(200, 'ok'));
+
+const response = await app.request('/');
+response.headers.get('traceparent'); // '00-<trace id>-<span id>-01'
+```
+
+## Options
+
+`telemetry()` takes either a `service`, and builds the telemetry, or an
+`instance`, and adopts it. Never both.
+
+| Option | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `service` | `string` | required, without `instance` | the service name every signal groups by; the telemetry is built with `createTelemetry(service, options)` and installed |
+| `instance` | `Telemetry` | required, without `service` | a telemetry you built: used as it is, neither installed nor closed by the plugin |
+| `traced` | `(ctx: RequestContext) => boolean` | every request | whether a request gets a span |
+| `spanName` | `(ctx: RequestContext) => string` | `"<METHOD> <path>"` | the span's name before routing, kept when no route matches |
+| `traceResponse` | `boolean` | `false` | sets `traceparent` on the response |
+
+With `service`, every [`TelemetryOptions`](https://www.npmjs.com/package/@nxgt/telemetry)
+of `@nxgt/telemetry` is accepted alongside:
+
+| Option | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `version`, `environment` | `string` | none | stamped on every signal's resource |
+| `attributes` | `Record<string, unknown>` | none | stamped on the resource too |
+| `exporters` | `readonly Exporter[]` | none | where signals go, in order; with none, they go nowhere |
+| `sampler` | `Sampler` | `alwaysSample` | which traces keep their spans; logs are never sampled |
+| `minimum` | `Severity` | `info` | logs below it are never built |
+| `stackTraces` | `boolean` | `true` | whether a recorded exception carries its stack |
+| `batch`, `linger`, `drainTimeout` | `number` | `512`, `1000` ms, `10000` ms | when the pipeline flushes, and how long `close()` waits |
+| `onExportError` | `(failure: unknown) => void` | `console.error` | what a failed export does |
+
+### `service` or `instance`
+
+`service` is the short way, for an app whose telemetry is this plugin's:
+the telemetry is installed, so a logger used outside any request — at
+start-up, in a job — finds it too.
+
+```ts
+import { telemetry } from '@alxia/telemetry';
+import { consoleExporter } from '@nxgt/telemetry';
+
+const tracing = telemetry({
+	service: 'checkout',
+	version: '1.4.0',
+	environment: 'production',
+	exporters: [consoleExporter()],
+});
+tracing.telemetry; // the Telemetry it built, to close on shutdown
+```
+
+`instance` is for a telemetry the app already has: built at start-up and
+shared with a worker, or built per test.
+
+```ts
+import { alxia } from '@alxia/core';
+import { telemetry } from '@alxia/telemetry';
+import { consoleExporter, createTelemetry } from '@nxgt/telemetry';
+
+const shared = createTelemetry('checkout', { exporters: [consoleExporter()] }).install();
+
+const app = alxia().use(telemetry({ instance: shared }));
+```
+
+The plugin runs each traced request inside the instance, so the logs in it
+reach it either way. Outside a request, and in a request `traced` said no
+to, a logger only finds a telemetry that is installed: call `install()` on
+an instance the whole process writes to, as above.
+
+### `traced`
+
+```ts
+telemetry({
+	service: 'checkout',
+	exporters: [consoleExporter()],
+	traced: (ctx) => ctx.url.pathname !== '/health' && ctx.url.pathname !== '/ready',
+});
+```
+
+A request it says no to runs without a span: its routes read `span` as
+`undefined`, and still read `telemetry`.
+
+### `spanName`
+
+```ts
+telemetry({
+	service: 'checkout',
+	exporters: [consoleExporter()],
+	spanName: (ctx) => `${ctx.request.method} ${ctx.url.pathname.split('/')[1] ?? ''}`,
+});
+```
+
+It runs before routing, so `ctx.route` is always `undefined` there; once a
+route matches, the span is renamed after it whatever `spanName` said.
+
+A `traced` or `spanName` that throws costs its answer, never the request:
+the request is traced, or named `"<METHOD> <path>"`, and nothing is logged.
+
+## What the routes read
+
+```ts
+import { alxia } from '@alxia/core';
+import { telemetry } from '@alxia/telemetry';
+import { consoleExporter } from '@nxgt/telemetry';
+
+const app = alxia()
+	.use(telemetry({ service: 'checkout', exporters: [consoleExporter()] }))
+	.get('/orders/:id', ({ params, span, telemetry: current, reply }) => {
+		span?.attribute('order.id', params.id);          // SpanScope | undefined
+		span?.event('cache.miss');
+		return reply(200, { service: current.resource.service });
+	});
+```
+
+| Field | Type | What it is |
+| --- | --- | --- |
+| `span` | `SpanScope \| undefined` | the server span: `attribute`, `attributes`, `event`, `fail`, `traceparent()`, a writable `name` and `status`; `undefined` when `traced` said no |
+| `telemetry` | `Telemetry` | the telemetry the plugin writes to, traced or not |
+
+Only the routes declared after `use(telemetry(...))`, in the same app or
+group, read them.
+
+## Shutting down
+
+The telemetry batches what it receives; `close()` ships the backlog, and
+has to be awaited, or the last batch is lost. The plugin closes nothing,
+not even a telemetry it built: close it in `onStop`, which `app.stop()`
+runs, and stop the app when the process is asked to end.
+
+```ts
+import { alxia } from '@alxia/core';
+import { telemetry } from '@alxia/telemetry';
+import { consoleExporter } from '@nxgt/telemetry';
+
+const tracing = telemetry({ service: 'checkout', exporters: [consoleExporter()] });
+
+const app = alxia()
+	.use(tracing)
+	.get('/', ({ reply }) => reply(200, 'ok'))
+	.onStop(() => tracing.telemetry.close());
+
+app.listen(3000);
+
+process.on('SIGTERM', async () => {
+	await app.stop();
+	process.exit(0);
+});
+```
+
+Once closed, a telemetry takes nothing more: the app still answers, and
+the spans of later requests are dropped.
+
+## Sending to a collector
+
+[`@nxgt/telemetry-otlp`](https://www.npmjs.com/package/@nxgt/telemetry-otlp)
+ships to any OpenTelemetry collector:
+
+```sh
+bun add @nxgt/telemetry-otlp
+```
+
+```ts
+import { alxia } from '@alxia/core';
+import { telemetry } from '@alxia/telemetry';
+import { ratioSampler } from '@nxgt/telemetry';
+import { otlpExporter } from '@nxgt/telemetry-otlp';
+
+const tracing = telemetry({
+	service: 'checkout',
+	version: '1.4.0',
+	environment: 'production',
+	sampler: ratioSampler(0.1),
+	exporters: [otlpExporter({ endpoint: 'http://localhost:4318' })],
+	traced: (ctx) => ctx.url.pathname !== '/health',
+});
+
+const app = alxia()
+	.use(tracing)
+	.get('/', ({ reply }) => reply(200, 'ok'))
+	.onStop(() => tracing.telemetry.close());
+
+app.listen(3000);
+```
+
+With `ratioSampler(0.1)`, one trace in ten keeps its spans. The others
+still open one, so their logs carry a trace id, and `span` is defined in
+the routes; it is only not exported.
+
+## Testing
+
+Give each test its own telemetry, as an `instance`, with an exporter that
+keeps what it receives, and close it before reading: `close()` is what
+flushes.
+
+```ts
+import { afterEach, expect, test } from 'bun:test';
+import { alxia } from '@alxia/core';
+import { telemetry } from '@alxia/telemetry';
+import {
+	createTelemetry,
+	type Exporter,
+	type Signal,
+	type SpanRecord,
+	uninstallTelemetry,
+} from '@nxgt/telemetry';
+
+afterEach(() => uninstallTelemetry());
+
+test('a route gets one server span, named after it', async () => {
+	const signals: Signal[] = [];
+	const exporter: Exporter = {
+		export(_resource, batch) {
+			signals.push(...batch);
+		},
+	};
+	const instance = createTelemetry('test', { exporters: [exporter] });
+	const app = alxia()
+		.use(telemetry({ instance }))
+		.get('/users/:id', ({ params, reply }) => reply(200, { id: params.id }));
+
+	await app.request('/users/7');
+	await instance.close();
+
+	const spans = signals.filter((signal): signal is SpanRecord => signal.type === 'span');
+	expect(spans[0]?.name).toBe('GET /users/:id');
+	expect(spans[0]?.attributes['http.response.status_code']).toBe(200);
+});
+```
+
+An `instance` is not installed, so tests do not share one through the
+process. A plugin built with `service` installs its telemetry for the whole
+process; `uninstallTelemetry()` after each test takes it back out.
+
+To continue a trace in a test, send the header a caller would:
+
+```ts
+await app.request('/users/1', {
+	headers: { traceparent: '00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01' },
+});
+// the span's trace id is 4bf92f3577b34da6a3ce929d0e0e4736, its parent 00f067aa0ba902b7
+```
+
+When something does not show up as expected, see
+[Troubleshooting](troubleshooting.md).

package/docs/roadmap.md

@@ -0,0 +1,49 @@
+# Roadmap
+
+What `@alxia/telemetry` gives an app, and what is coming. This page is a
+direction, not a commitment: the version something shipped in is the only
+number on it. Every release, with each change it made, is in
+[`CHANGELOG.md`](https://github.com/softistx/alxia/blob/develop/packages/telemetry/CHANGELOG.md).
+
+## Now
+
+Nothing scheduled yet.
+
+## Next
+
+Nothing scheduled yet.
+
+## Later
+
+Nothing scheduled yet.
+
+## Not planned
+
+- **A second telemetry implementation.** `@alxia/telemetry` is an adapter
+  over `@nxgt/telemetry`, a peer: the spans, the logs, the sampling and the
+  exporters are its, and so is everything they gain.
+- **The OpenTelemetry SDK.** Signals go out through `@nxgt/telemetry`'s
+  exporters — to a collector with `@nxgt/telemetry-otlp` — with no SDK and
+  no runtime dependency.
+
+## Shipped
+
+### 0.1.0
+
+- **One server span per request.** `alxia().use(telemetry({ service, exporters }))`
+  opens a span around everything a request runs — hooks, handler, what
+  they await — and every log written with `@nxgt/telemetry`'s
+  `createLogger` inside it carries its trace id.
+- **Named for the route.** The span is renamed `GET /orders/:id` once
+  routing has matched, with `http.route`: one dashboard row per route.
+- **Traces across services.** An inbound `traceparent` is continued, an
+  unreadable one starts a fresh trace, and `traceResponse` says it back.
+- **Errors where they belong.** A route's error is the span's exception;
+  only a 5xx marks the span an error.
+- **The same names as Hono's.** The attributes are
+  `@nxgt/telemetry-hono`'s, exported as constants, so a span from either
+  reads the same in a dashboard.
+- **Your telemetry, or one built for you.** `service` with
+  `@nxgt/telemetry`'s options, or an existing `instance`, adopted; `traced`
+  and `spanName` to choose and name the spans. Routes read `span` and
+  `telemetry`.

package/docs/troubleshooting.md

@@ -0,0 +1,361 @@
+# Troubleshooting
+
+Each entry is headed by the text you see: an error from `tsc`, a line in
+the server log, or, for what prints nothing, what you see in your traces.
+
+**Types**
+
+- [`Property 'span' does not exist on type 'Context<…>'`](#property-span-does-not-exist-on-type-context)
+- [`Type 'Alxia<Empty, Empty, "", never>' is not assignable to type 'TelemetryPluginOptions'`](#type-alxiaempty-empty--never-is-not-assignable-to-type-telemetrypluginoptions)
+- [`Property 'service' is missing in type '…' but required in type '{ readonly service: string; readonly instance?: undefined; }'`](#property-service-is-missing-in-type--but-required-in-type--readonly-service-string-readonly-instance-undefined-)
+- [`Type 'Telemetry' is not assignable to type 'undefined'`](#type-telemetry-is-not-assignable-to-type-undefined)
+- [`Object literal may only specify known properties, and 'version' does not exist in type 'Hooks & { readonly instance: Telemetry; … }'`](#object-literal-may-only-specify-known-properties-and-version-does-not-exist-in-type-hooks---readonly-instance-telemetry--)
+- [`Type 'string | undefined' is not assignable to type 'string'` in `spanName`](#type-string--undefined-is-not-assignable-to-type-string-in-spanname)
+
+**Server log**
+
+- [`[telemetry] export failed`](#telemetry-export-failed)
+
+**Missing signals**
+
+- [Nothing is exported, or the last requests are missing](#nothing-is-exported-or-the-last-requests-are-missing)
+- [A log written in a route has no `traceId`, or never arrives](#a-log-written-in-a-route-has-no-traceid-or-never-arrives)
+- [A log written outside a request never arrives](#a-log-written-outside-a-request-never-arrives)
+- [Logs carry a `traceId`, but its span is never exported](#logs-carry-a-traceid-but-its-span-is-never-exported)
+- [Spans stop arriving, and the app still answers](#spans-stop-arriving-and-the-app-still-answers)
+- [No span for a WebSocket connection](#no-span-for-a-websocket-connection)
+- [The response has no `traceparent` header](#the-response-has-no-traceparent-header)
+
+**Unexpected spans**
+
+- [The span starts a new trace although the caller sent `traceparent`](#the-span-starts-a-new-trace-although-the-caller-sent-traceparent)
+- [`spanName` only shows on requests no route matched](#spanname-only-shows-on-requests-no-route-matched)
+- [A span has an exception, and its status is `ok`](#a-span-has-an-exception-and-its-status-is-ok)
+
+## Types
+
+### `Property 'span' does not exist on type 'Context<…>'`
+
+```text
+error TS2339: Property 'span' does not exist on type 'Context<Empty, "/before", Empty>'.
+```
+
+**When:** a route reads `span` or `telemetry`, and is declared before
+`use(telemetry(...))`.
+
+**Why:** the plugin gives `span` and `telemetry` to the routes declared
+after it. The request is still traced, since the span is opened by a global
+hook; the route only cannot reach it.
+
+**Fix:** use the plugin first:
+
+```ts
+const app = alxia()
+	.use(telemetry({ service: 'checkout', exporters: [consoleExporter()] }))
+	.get('/orders/:id', ({ params, span, reply }) => {
+		span?.attribute('order.id', params.id);
+		return reply(200, { id: params.id });
+	});
+```
+
+### `Type 'Alxia<Empty, Empty, "", never>' is not assignable to type 'TelemetryPluginOptions'`
+
+```text
+error TS2769: No overload matches this call.
+  Overload 1 of 2, '(plugin: (app: Alxia<Empty, Empty, "", never>) => …): …', gave the following error.
+    Argument of type '(options: TelemetryPluginOptions) => …' is not assignable to parameter of type '(app: Alxia<Empty, Empty, "", never>) => …'.
+      Types of parameters 'options' and 'app' are incompatible.
+        Type 'Alxia<Empty, Empty, "", never>' is not assignable to type 'TelemetryPluginOptions'.
+```
+
+**When:** `app.use(telemetry)`, without calling it.
+
+**Why:** `telemetry` makes the plugin; it is not the plugin, and it needs a
+`service` or an `instance`.
+
+**Fix:**
+
+```ts
+alxia().use(telemetry({ service: 'checkout', exporters: [consoleExporter()] }));
+```
+
+### `Property 'service' is missing in type '…' but required in type '{ readonly service: string; readonly instance?: undefined; }'`
+
+```text
+error TS2345: Argument of type '{ exporters: never[]; }' is not assignable to parameter of type 'TelemetryPluginOptions'.
+  Type '{ exporters: never[]; }' is not assignable to type 'Hooks & TelemetryOptions & { readonly service: string; readonly instance?: undefined; }'.
+    Property 'service' is missing in type '{ exporters: never[]; }' but required in type '{ readonly service: string; readonly instance?: undefined; }'.
+```
+
+**When:** `telemetry({ exporters: [...] })`, with neither `service` nor
+`instance`.
+
+**Why:** the telemetry the plugin builds needs a service name: every signal
+groups by it, and there is no default.
+
+**Fix:** name the service, or hand over a telemetry you built:
+
+```ts
+telemetry({ service: 'checkout', exporters: [consoleExporter()] });
+```
+
+### `Type 'Telemetry' is not assignable to type 'undefined'`
+
+```text
+error TS2345: Argument of type '{ service: string; instance: Telemetry; }' is not assignable to parameter of type 'TelemetryPluginOptions'.
+  Types of property 'instance' are incompatible.
+    Type 'Telemetry' is not assignable to type 'undefined'.
+```
+
+**When:** `telemetry({ service, instance })`.
+
+**Why:** `service` builds a telemetry, `instance` adopts one; the plugin
+writes to exactly one.
+
+**Fix:** keep `instance`, whose service name was given to `createTelemetry`:
+
+```ts
+const instance = createTelemetry('checkout', { exporters: [consoleExporter()] });
+
+telemetry({ instance });
+```
+
+### `Object literal may only specify known properties, and 'version' does not exist in type 'Hooks & { readonly instance: Telemetry; … }'`
+
+```text
+error TS2353: Object literal may only specify known properties, and 'version' does not exist in type 'Hooks & { readonly instance: Telemetry; readonly service?: undefined; }'.
+```
+
+The same for `exporters`, `sampler`, `environment`, or any other
+`@nxgt/telemetry` option.
+
+**When:** `@nxgt/telemetry` options next to `instance`.
+
+**Why:** an adopted telemetry is already built; the plugin cannot change
+its exporters or its resource.
+
+**Fix:** give them to `createTelemetry`:
+
+```ts
+const instance = createTelemetry('checkout', {
+	version: '1.4.0',
+	exporters: [consoleExporter()],
+});
+
+telemetry({ instance, traceResponse: true });
+```
+
+### `Type 'string | undefined' is not assignable to type 'string'` in `spanName`
+
+```text
+error TS2322: Type '(ctx: RequestContext) => string | undefined' is not assignable to type '(ctx: RequestContext) => string'.
+  Type 'string | undefined' is not assignable to type 'string'.
+    Type 'undefined' is not assignable to type 'string'.
+```
+
+**When:** `spanName: (ctx) => ctx.route`.
+
+**Why:** `spanName` runs before routing, where `ctx.route` is always
+`undefined`. The route already names the span once it matches.
+
+**Fix:** name what routing has not matched from the path, or leave
+`spanName` out:
+
+```ts
+telemetry({
+	service: 'checkout',
+	exporters: [consoleExporter()],
+	spanName: (ctx) => `${ctx.request.method} unmatched`,
+});
+```
+
+## Server log
+
+### `[telemetry] export failed`
+
+Followed by the exporter's error, such as
+`OtlpUnreachableError: [telemetry] http://localhost:4318/v1/traces did not answer for traces after 3 attempt(s)`.
+
+**When:** an exporter throws or rejects: a collector that is down, a wrong
+endpoint, a refused key.
+
+**Why:** `@nxgt/telemetry` reports a failed export through
+`onExportError`, which is `console.error` by default. The request it came
+from was answered long before: an export never costs a request.
+
+**Fix:** point the exporter at a collector that answers, and send the
+failures where you want them:
+
+```ts
+telemetry({
+	service: 'checkout',
+	exporters: [otlpExporter({ endpoint: 'http://localhost:4318' })],
+	onExportError: (failure) => metrics.increment('telemetry.export_failed', String(failure)),
+});
+```
+
+## Missing signals
+
+### Nothing is exported, or the last requests are missing
+
+**When:** a script or a test exits right after its requests, or a server
+is stopped, and the last spans and logs never reach the exporter — with
+`consoleExporter()`, nothing is printed.
+
+**Why:** the telemetry batches signals, and ships a batch when it is full
+or a second after it started. A process that exits first loses it. The
+plugin never closes the telemetry, not even one it built from `service`.
+
+**Fix:** close it in `onStop`, await `app.stop()` on shutdown, and await
+`close()` in a script or a test before reading what was exported:
+
+```ts
+const app = alxia()
+	.use(tracing)
+	.onStop(() => tracing.telemetry.close());
+
+process.on('SIGTERM', async () => {
+	await app.stop();
+	process.exit(0);
+});
+```
+
+### A log written in a route has no `traceId`, or never arrives
+
+**When:** a span is exported for the request, but a `log.info` inside it
+is missing, or arrives without `span`.
+
+**Why:** the logger comes from another copy of `@nxgt/telemetry` than the
+one `@alxia/telemetry` uses: the request's span is held by one copy, and
+the other cannot see it. It is a peer for that reason, and a second copy
+appears when a package depends on a version the app's range does not
+satisfy.
+
+**Fix:** keep one copy, with a single range for every package that needs
+it, and check:
+
+```sh
+bun pm ls --all | grep @nxgt/telemetry@
+```
+
+### A log written outside a request never arrives
+
+**When:** a log at start-up, in a job or a timer, or in a request `traced`
+said no to, while the logs in traced requests arrive.
+
+**Why:** the plugin was given an `instance`. It runs each traced request
+inside that telemetry, but does not install it, so a logger with no request
+around it finds none.
+
+**Fix:** install the instance the whole process writes to:
+
+```ts
+const instance = createTelemetry('checkout', { exporters: [consoleExporter()] }).install();
+
+alxia().use(telemetry({ instance }));
+```
+
+### Logs carry a `traceId`, but its span is never exported
+
+**When:** a `sampler` such as `ratioSampler(0.1)` is set; most requests
+have logs with a trace id that no span in the backend has.
+
+**Why:** a sampler decides which traces keep their spans; logs are never
+sampled. A sampled-out request still opens its span, so `span` is defined
+in the route and the logs carry its ids, but the span is not exported.
+
+**Fix:** that is sampling working. Raise the ratio, or sample nothing out:
+
+```ts
+telemetry({ service: 'checkout', sampler: alwaysSample, exporters: [consoleExporter()] });
+```
+
+### Spans stop arriving, and the app still answers
+
+**When:** after `close()` on the plugin's telemetry — often a test that
+closes it in one case and sends requests in the next.
+
+**Why:** a closed telemetry takes nothing more, and the plugin keeps
+writing to it; the requests are answered as usual.
+
+**Fix:** build a plugin, with its own telemetry, per test:
+
+```ts
+const instance = createTelemetry('test', { exporters: [exporter] });
+const app = alxia().use(telemetry({ instance }));
+```
+
+### No span for a WebSocket connection
+
+**When:** a route declared with `app.ws`.
+
+**Why:** `@alxia/core` runs no `around` hook for a WebSocket upgrade, as
+there is no response to wrap, and the span is opened by one.
+
+**Fix:** open a span for the work a message does:
+
+```ts
+app.ws('/rooms/:room', {}, {
+	message: (socket, message) =>
+		span('room.message', () => socket.send(String(message))),
+});
+```
+
+### The response has no `traceparent` header
+
+**When:** a caller looks for the trace of the request it made.
+
+**Why:** the plugin says `traceparent` back only with `traceResponse`, and
+only on a request `traced` let through.
+
+**Fix:**
+
+```ts
+telemetry({ service: 'checkout', exporters: [consoleExporter()], traceResponse: true });
+```
+
+## Unexpected spans
+
+### The span starts a new trace although the caller sent `traceparent`
+
+**When:** the server span has no parent, and a trace id of its own.
+
+**Why:** the header could not be read as a W3C `traceparent`: a header from
+a stranger is not trusted, so a fresh trace starts.
+
+**Fix:** send the header the caller's current span says, unchanged, in the
+`00-<32 hex trace id>-<16 hex span id>-<2 hex flags>` form:
+
+```ts
+await fetch('https://checkout.example.com/orders/o-1', {
+	headers: { traceparent: currentTraceparent() ?? '' },
+});
+```
+
+### `spanName` only shows on requests no route matched
+
+**When:** a `spanName` is set, and the matched requests are still named
+`GET /orders/:id`.
+
+**Why:** `spanName` is the name before routing. Once a route matches, the
+span is renamed `"<METHOD> <route>"`, so a dashboard has one row per route.
+
+**Fix:** to add to a routed span, set an attribute rather than the name:
+
+```ts
+app.get('/orders/:id', ({ params, span, reply }) => {
+	span?.attribute('order.id', params.id);
+	return reply(200, { id: params.id });
+});
+```
+
+### A span has an exception, and its status is `ok`
+
+**When:** a route throws, and an `onError` hook answers with a `4xx`.
+
+**Why:** the error is recorded as the span's exception, but only a `5xx`
+makes a span an error: a `400` the app chose to answer is the server
+working.
+
+**Fix:** none needed. For an error that should mark the span, answer it
+with a `5xx`, or let it throw to the `500`.

package/package.json

@@ -0,0 +1,55 @@
+{
+	"name": "@alxia/telemetry",
+	"version": "0.1.0",
+	"description": "Traces and logs for alxia on @nxgt/telemetry: one server span per request around everything it runs, the traceparent continued, the route as its name",
+	"license": "MIT",
+	"type": "module",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"files": [
+		"dist",
+		"docs",
+		"README.md",
+		"package.json",
+		"LICENSE"
+	],
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"default": "./dist/index.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/softistx/alxia.git",
+		"directory": "packages/telemetry"
+	},
+	"publishConfig": {
+		"registry": "https://registry.npmjs.org",
+		"access": "public"
+	},
+	"scripts": {
+		"build": "bun run ../../build.ts",
+		"test": "bun test src",
+		"typecheck": "tsc --noEmit"
+	},
+	"alxia": {
+		"entrypoints": [
+			"src/index.ts"
+		]
+	},
+	"devDependencies": {
+		"@alxia/client": "^0.1.0",
+		"@alxia/core": "^0.1.0",
+		"@nxgt/telemetry": "^0.2.1",
+		"@types/bun": "^1.4.2",
+		"zod": "^4.6.5"
+	},
+	"peerDependencies": {
+		"@alxia/core": "^0.1.0",
+		"@nxgt/telemetry": "^0.2.1",
+		"typescript": "^6.0.3 || ^7.0.0"
+	}
+}