@nxgt/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,156 @@
+# @nxgt/telemetry
+
+Logs and traces for a TypeScript service, with no OpenTelemetry SDK.
+
+```sh
+bun add @nxgt/telemetry
+```
+
+Zero runtime dependencies. Bun and Node; a browser gets everything but the
+automatic context.
+
+## What it is
+
+A span is a block you `await`, and the current one travels with your work —
+through every `await`, every timer, every promise — in an `AsyncLocalStorage`.
+Logs written inside it carry its `traceId` and `spanId` without being told. A
+`traceparent` header is read on the way in and written on the way out, so the
+trace continues across services. Signals are handed to a pipeline that never
+blocks the caller and never throws at it, and exporters ship them: the console,
+a file, [OTLP](https://www.npmjs.com/package/@nxgt/telemetry-otlp), MongoDB.
+
+It is the TypeScript counterpart of `stx-telemetry` on the JVM, and shares its
+vocabulary exactly: the same severities, span kinds, statuses, `traceparent`
+rules, sampling rule and attribute names. A trace started in one and continued
+in the other is one trace.
+
+## Trace identity
+
+```ts
+import { randomTraceId, parseTraceparent, renderTraceparent } from '@nxgt/telemetry';
+
+const incoming = parseTraceparent(request.headers.get('traceparent'));
+// → { traceId, spanId, sampled, remote: true }, or null
+
+renderTraceparent({ traceId, spanId, sampled: true, remote: false });
+// → '00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01'
+```
+
+`parseTraceparent` **returns `null` and never throws.** A header a stranger
+controls must not be able to fail a request: an unusable one simply starts a
+fresh trace. It rejects fewer than four fields, a version that is not two hex
+characters, the forbidden version `ff`, an id of the wrong length or all zeros
+or not hex, and flags that are not hex. A later version is accepted and its
+extra fields ignored. `tracestate` is not read, and nothing here writes one.
+
+`TraceId` and `SpanId` are branded strings: the hex is the representation, so
+there is nothing to convert before writing a header, and the compiler still
+refuses a span id where a trace id belongs. `isValidTraceId` and
+`isValidSpanId` are the guards that turn a `string` into one.
+
+## Sampling
+
+```ts
+import { ratioSampler, alwaysSample, neverSample } from '@nxgt/telemetry';
+
+const sampler = ratioSampler(0.1);   // keep a tenth of traces
+```
+
+The sampler is asked **once, for the root span**, and the answer travels with
+the trace — down through every child and out in the `traceparent`. A sampler
+consulted per span produces traces missing their middles, and a gap in a trace
+looks like work that never happened.
+
+The decision is a function of the trace id, not a coin toss, and the rule is
+OpenTelemetry's: two services at the same ratio make the **same** decision about
+the same trace. Two services tossing independently at 10% keep a whole trace 1%
+of the time.
+
+**Logs are never sampled.** A log dropped because its trace was not kept is a
+log missing at precisely the moment somebody is reading logs to find out what
+happened. The `traceId` is attached either way, so an unsampled trace's logs
+still group.
+
+## Attributes
+
+An attribute is a **scalar, or a list of scalars** — that is what a backend can
+index, filter and group by, and what OTLP accepts. Anything with structure is an
+event type, not an attribute.
+
+```ts
+import { attributesOf } from '@nxgt/telemetry';
+
+attributesOf({ orderId: 'o-1', amount: 4200, retried: false });
+attributesOf({ orderId: 'o-1', code: undefined });   // → { orderId: 'o-1' }
+```
+
+The coercion never refuses a value, because a log call must not fail: a
+non-finite number, a `bigint` and a `Date` become text, an object becomes its
+JSON, and a circular object still says something. `undefined` is dropped — one
+absent field should not log `null` — while an explicit `null` is kept, because
+somebody wrote it.
+
+## API
+
+### Trace identity
+
+| | |
+| --- | --- |
+| `TraceId`, `SpanId` | branded 32- and 16-character lowercase hex strings |
+| `SpanContext` | `{ traceId, spanId, sampled, remote }` — a span's place in a trace, as it travels |
+| `randomTraceId()`, `randomSpanId()` | from `crypto.getRandomValues`, never `Math.random()` |
+| `isValidTraceId(hex)`, `isValidSpanId(hex)` | type guards: right length, lowercase hex, not all zeros |
+| `renderTraceparent(context)` | the header value, version `00` |
+| `parseTraceparent(header)` | a `SpanContext` with `remote: true`, or `null` |
+| `INVALID_TRACE_ID`, `INVALID_SPAN_ID` | all zeros |
+| `DETACHED_SPAN_CONTEXT`, `isDetached(context)` | what a span carries when no telemetry is installed |
+
+### Sampling
+
+| | |
+| --- | --- |
+| `Sampler` | `{ sample(traceId): boolean }` |
+| `alwaysSample`, `neverSample` | the constants |
+| `ratioSampler(ratio)` | keeps `ratio` of traces, by trace id. Throws `RangeError` outside `0..1` |
+
+### Attributes
+
+| | |
+| --- | --- |
+| `AttributeScalar`, `AttributeValue`, `Attributes` | a scalar, a scalar or list of them, and a read-only record of those |
+| `attributesOf(record)` | coerces a record of anything; drops `undefined` |
+| `coerceAttribute(value)` | one value, the same way |
+| `mergeAttributes(left, right)` | the right-hand side wins; neither argument is modified |
+| `isEmptyAttributes(attributes)`, `EMPTY_ATTRIBUTES` | |
+
+### The signal model
+
+| | |
+| --- | --- |
+| `Severity` | `'debug' \| 'info' \| 'warn' \| 'error'`. There is no `trace` level |
+| `SEVERITY_NUMBER`, `SEVERITIES`, `meetsSeverity(severity, minimum)` | OTLP's numbers, ascending, and the floor test |
+| `SpanKind`, `SPAN_KIND_NUMBER` | `internal` 1, `server` 2, `client` 3, `producer` 4, `consumer` 5 |
+| `SpanStatus` | `'ok' \| 'error' \| 'cancelled'` |
+| `Resource` | `{ service, version?, environment?, attributes }` |
+| `LogRecord`, `SpanRecord`, `SpanEvent`, `ErrorInfo` | the records an exporter receives |
+| `Signal` | `LogRecord \| SpanRecord`, discriminated on `type` |
+| `signalAt(signal)`, `signalSpan(signal)` | when it happened, and which span it belongs to, whichever kind it is |
+
+## Traps
+
+- **There is no `trace` severity.** Detail below `debug` belongs on a span as an
+  attribute, attached to the work it describes, rather than on a line somebody
+  has to correlate by hand.
+- **Instants are epoch milliseconds**, which is the precision a JavaScript wall
+  clock has. OTLP wants nanoseconds, and the exporter multiplies; do not read a
+  sub-millisecond duration out of a span.
+- **A nested list is not an attribute.** `['a', ['b']]` is flattened into text
+  rather than dropped — the value survives, but it stops being something a
+  backend can group by. Put structure in an event type.
+- **`ratioSampler` throws on a bad ratio**, at construction. That is the one
+  place in this library that refuses an argument, and it is deliberate: it is
+  not on the path that writes a signal.
+
+## License
+
+[MIT](LICENSE)

package/dist/attributes/attributes.d.ts

@@ -0,0 +1,36 @@
+/**
+ * An attribute is a scalar, or a list of scalars. That is what a backend can
+ * index, filter and group by, and it is what OTLP accepts. Anything with
+ * structure is an event type, not an attribute.
+ *
+ * The coercion below never refuses a value: a log call must not fail, so a
+ * shape that does not belong here is rendered rather than rejected.
+ */
+export type AttributeScalar = string | number | boolean | null;
+export type AttributeValue = AttributeScalar | readonly AttributeScalar[];
+export type Attributes = Readonly<Record<string, AttributeValue>>;
+/** Shared, frozen, and the one to return when there is nothing to say. */
+export declare const EMPTY_ATTRIBUTES: Attributes;
+/**
+ * Whatever a caller passed, as something that can be indexed.
+ *
+ * - `undefined` and a symbol render as `null`;
+ * - a non-finite number renders as its text, because `NaN` is not JSON;
+ * - a `bigint` renders as its text, for the same reason;
+ * - a `Date` renders as an ISO-8601 instant;
+ * - an array renders element by element, and a nested array is flattened into
+ *   text rather than dropped;
+ * - anything else is JSON if it will serialise, and `String(value)` if it will
+ *   not — a circular object still says something.
+ */
+export declare function coerceAttribute(value: unknown): AttributeValue;
+/**
+ * A record of anything, as attributes. Keys whose value is `undefined` are
+ * dropped — `{ orderId, code }` with no `code` should not log `code: null` —
+ * while an explicit `null` is kept, because somebody wrote it.
+ */
+export declare function attributesOf(input: Readonly<Record<string, unknown>> | undefined): Attributes;
+/** Both, with the right-hand side winning. Neither argument is modified. */
+export declare function mergeAttributes(left: Attributes, right: Attributes): Attributes;
+export declare function isEmptyAttributes(attributes: Attributes): boolean;
+//# sourceMappingURL=attributes.d.ts.map

package/dist/attributes/attributes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attributes.d.ts","sourceRoot":"","sources":["../../src/attributes/attributes.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;AAE/D,MAAM,MAAM,cAAc,GAAG,eAAe,GAAG,SAAS,eAAe,EAAE,CAAC;AAE1E,MAAM,MAAM,UAAU,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC;AAElE,0EAA0E;AAC1E,eAAO,MAAM,gBAAgB,EAAE,UAA8B,CAAC;AAE9D;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,CAwB9D;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAC3B,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,GAClD,UAAU,CAcZ;AAED,4EAA4E;AAC5E,wBAAgB,eAAe,CAC9B,IAAI,EAAE,UAAU,EAChB,KAAK,EAAE,UAAU,GACf,UAAU,CAKZ;AAED,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAEjE"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from './attributes/attributes';
+export * from './model/signal';
+export * from './trace/ids';
+export * from './trace/sampler';
+//# 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,cAAc,yBAAyB,CAAC;AACxC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC"}

package/dist/index.js

@@ -0,0 +1,217 @@
+// src/attributes/attributes.ts
+var EMPTY_ATTRIBUTES = Object.freeze({});
+function coerceAttribute(value) {
+  if (value === null || value === undefined)
+    return null;
+  switch (typeof value) {
+    case "string":
+    case "boolean":
+      return value;
+    case "number":
+      return Number.isFinite(value) ? value : String(value);
+    case "bigint":
+      return String(value);
+    case "symbol":
+    case "function":
+      return null;
+  }
+  if (value instanceof Date) {
+    const at = value.getTime();
+    return Number.isNaN(at) ? String(value) : value.toISOString();
+  }
+  if (Array.isArray(value))
+    return value.map(coerceScalar);
+  return render(value);
+}
+function attributesOf(input) {
+  if (input === undefined)
+    return EMPTY_ATTRIBUTES;
+  const attributes = {};
+  let any = false;
+  for (const key of Object.keys(input)) {
+    const value = input[key];
+    if (value === undefined)
+      continue;
+    attributes[key] = coerceAttribute(value);
+    any = true;
+  }
+  return any ? attributes : EMPTY_ATTRIBUTES;
+}
+function mergeAttributes(left, right) {
+  if (left === right)
+    return left;
+  if (isEmpty(left))
+    return right;
+  if (isEmpty(right))
+    return left;
+  return { ...left, ...right };
+}
+function isEmptyAttributes(attributes) {
+  return isEmpty(attributes);
+}
+function isEmpty(attributes) {
+  for (const _ in attributes)
+    return false;
+  return true;
+}
+function coerceScalar(value) {
+  const coerced = coerceAttribute(value);
+  return Array.isArray(coerced) ? render(value) : coerced;
+}
+function render(value) {
+  try {
+    const json = JSON.stringify(value);
+    if (json !== undefined)
+      return json;
+  } catch {}
+  try {
+    return String(value);
+  } catch {
+    return "[unrenderable]";
+  }
+}
+// src/model/signal.ts
+var SEVERITY_NUMBER = Object.freeze({
+  debug: 5,
+  info: 9,
+  warn: 13,
+  error: 17
+});
+var SEVERITIES = Object.freeze([
+  "debug",
+  "info",
+  "warn",
+  "error"
+]);
+function meetsSeverity(severity, minimum) {
+  return SEVERITY_NUMBER[severity] >= SEVERITY_NUMBER[minimum];
+}
+var SPAN_KIND_NUMBER = Object.freeze({
+  internal: 1,
+  server: 2,
+  client: 3,
+  producer: 4,
+  consumer: 5
+});
+function signalAt(signal) {
+  return signal.type === "log" ? signal.at : signal.startedAt;
+}
+function signalSpan(signal) {
+  return signal.type === "log" ? signal.span : signal.context;
+}
+// src/trace/ids.ts
+var INVALID_TRACE_ID = "0".repeat(32);
+var INVALID_SPAN_ID = "0".repeat(16);
+var TRACE_ID_PATTERN = /^[0-9a-f]{32}$/;
+var SPAN_ID_PATTERN = /^[0-9a-f]{16}$/;
+var HEX_PATTERN = /^[0-9a-f]+$/;
+function isValidTraceId(hex) {
+  return TRACE_ID_PATTERN.test(hex) && hex !== INVALID_TRACE_ID;
+}
+function isValidSpanId(hex) {
+  return SPAN_ID_PATTERN.test(hex) && hex !== INVALID_SPAN_ID;
+}
+function randomTraceId() {
+  return randomHex(16);
+}
+function randomSpanId() {
+  return randomHex(8);
+}
+var DETACHED_SPAN_CONTEXT = Object.freeze({
+  traceId: INVALID_TRACE_ID,
+  spanId: INVALID_SPAN_ID,
+  sampled: false,
+  remote: false
+});
+function isDetached(context) {
+  return !isValidTraceId(context.traceId);
+}
+function renderTraceparent(context) {
+  return `00-${context.traceId}-${context.spanId}-${context.sampled ? "01" : "00"}`;
+}
+function parseTraceparent(header) {
+  if (!header)
+    return null;
+  const parts = header.trim().toLowerCase().split("-");
+  if (parts.length < 4)
+    return null;
+  const [version, traceId, spanId, flags] = parts;
+  if (version.length !== 2 || !HEX_PATTERN.test(version) || version === "ff") {
+    return null;
+  }
+  if (!isValidTraceId(traceId) || !isValidSpanId(spanId))
+    return null;
+  if (!HEX_PATTERN.test(flags))
+    return null;
+  const parsed = Number.parseInt(flags, 16);
+  if (Number.isNaN(parsed))
+    return null;
+  return {
+    traceId,
+    spanId,
+    sampled: (parsed & 1) === 1,
+    remote: true
+  };
+}
+var HEX = "0123456789abcdef";
+function randomHex(bytes) {
+  const buffer = new Uint8Array(bytes);
+  crypto.getRandomValues(buffer);
+  let hex = "";
+  for (const byte of buffer) {
+    hex += HEX[byte >> 4];
+    hex += HEX[byte & 15];
+  }
+  return hex;
+}
+// src/trace/sampler.ts
+var alwaysSample = { sample: () => true };
+var neverSample = { sample: () => false };
+var MAX_UINT64 = (1n << 64n) - 1n;
+var SCALE = 1n << 53n;
+function ratioSampler(ratio) {
+  if (!Number.isFinite(ratio) || ratio < 0 || ratio > 1) {
+    throw new RangeError(`A sampling ratio is between 0 and 1, not ${ratio}`);
+  }
+  if (ratio === 0)
+    return neverSample;
+  if (ratio === 1)
+    return alwaysSample;
+  const threshold = BigInt(Math.round(ratio * Number(SCALE))) * MAX_UINT64 / SCALE;
+  return {
+    sample(traceId) {
+      if (!isValidTraceId(traceId))
+        return false;
+      return BigInt(`0x${traceId.slice(-16)}`) < threshold;
+    }
+  };
+}
+export {
+  DETACHED_SPAN_CONTEXT,
+  EMPTY_ATTRIBUTES,
+  INVALID_SPAN_ID,
+  INVALID_TRACE_ID,
+  SEVERITIES,
+  SEVERITY_NUMBER,
+  SPAN_KIND_NUMBER,
+  alwaysSample,
+  attributesOf,
+  coerceAttribute,
+  isDetached,
+  isEmptyAttributes,
+  isValidSpanId,
+  isValidTraceId,
+  meetsSeverity,
+  mergeAttributes,
+  neverSample,
+  parseTraceparent,
+  randomSpanId,
+  randomTraceId,
+  ratioSampler,
+  renderTraceparent,
+  signalAt,
+  signalSpan
+};
+
+//# debugId=909718EB5895F3DC64756E2164756E21
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1,13 @@
+{
+  "version": 3,
+  "sources": ["../src/attributes/attributes.ts", "../src/model/signal.ts", "../src/trace/ids.ts", "../src/trace/sampler.ts"],
+  "sourcesContent": [
+    "/**\n * An attribute is a scalar, or a list of scalars. That is what a backend can\n * index, filter and group by, and it is what OTLP accepts. Anything with\n * structure is an event type, not an attribute.\n *\n * The coercion below never refuses a value: a log call must not fail, so a\n * shape that does not belong here is rendered rather than rejected.\n */\n\nexport type AttributeScalar = string | number | boolean | null;\n\nexport type AttributeValue = AttributeScalar | readonly AttributeScalar[];\n\nexport type Attributes = Readonly<Record<string, AttributeValue>>;\n\n/** Shared, frozen, and the one to return when there is nothing to say. */\nexport const EMPTY_ATTRIBUTES: Attributes = Object.freeze({});\n\n/**\n * Whatever a caller passed, as something that can be indexed.\n *\n * - `undefined` and a symbol render as `null`;\n * - a non-finite number renders as its text, because `NaN` is not JSON;\n * - a `bigint` renders as its text, for the same reason;\n * - a `Date` renders as an ISO-8601 instant;\n * - an array renders element by element, and a nested array is flattened into\n *   text rather than dropped;\n * - anything else is JSON if it will serialise, and `String(value)` if it will\n *   not — a circular object still says something.\n */\nexport function coerceAttribute(value: unknown): AttributeValue {\n\tif (value === null || value === undefined) return null;\n\n\tswitch (typeof value) {\n\t\tcase 'string':\n\t\tcase 'boolean':\n\t\t\treturn value;\n\t\tcase 'number':\n\t\t\treturn Number.isFinite(value) ? value : String(value);\n\t\tcase 'bigint':\n\t\t\treturn String(value);\n\t\tcase 'symbol':\n\t\tcase 'function':\n\t\t\treturn null;\n\t}\n\n\tif (value instanceof Date) {\n\t\tconst at = value.getTime();\n\t\treturn Number.isNaN(at) ? String(value) : value.toISOString();\n\t}\n\n\tif (Array.isArray(value)) return value.map(coerceScalar);\n\n\treturn render(value);\n}\n\n/**\n * A record of anything, as attributes. Keys whose value is `undefined` are\n * dropped — `{ orderId, code }` with no `code` should not log `code: null` —\n * while an explicit `null` is kept, because somebody wrote it.\n */\nexport function attributesOf(\n\tinput: Readonly<Record<string, unknown>> | undefined,\n): Attributes {\n\tif (input === undefined) return EMPTY_ATTRIBUTES;\n\n\tconst attributes: Record<string, AttributeValue> = {};\n\tlet any = false;\n\n\tfor (const key of Object.keys(input)) {\n\t\tconst value = input[key];\n\t\tif (value === undefined) continue;\n\t\tattributes[key] = coerceAttribute(value);\n\t\tany = true;\n\t}\n\n\treturn any ? attributes : EMPTY_ATTRIBUTES;\n}\n\n/** Both, with the right-hand side winning. Neither argument is modified. */\nexport function mergeAttributes(\n\tleft: Attributes,\n\tright: Attributes,\n): Attributes {\n\tif (left === right) return left;\n\tif (isEmpty(left)) return right;\n\tif (isEmpty(right)) return left;\n\treturn { ...left, ...right };\n}\n\nexport function isEmptyAttributes(attributes: Attributes): boolean {\n\treturn isEmpty(attributes);\n}\n\nfunction isEmpty(attributes: Attributes): boolean {\n\tfor (const _ in attributes) return false;\n\treturn true;\n}\n\nfunction coerceScalar(value: unknown): AttributeScalar {\n\tconst coerced = coerceAttribute(value);\n\treturn Array.isArray(coerced) ? render(value) : (coerced as AttributeScalar);\n}\n\nfunction render(value: unknown): string {\n\ttry {\n\t\tconst json = JSON.stringify(value);\n\t\tif (json !== undefined) return json;\n\t} catch {\n\t\t// Circular, or a `toJSON` that threw. `String` still says something.\n\t}\n\n\ttry {\n\t\treturn String(value);\n\t} catch {\n\t\treturn '[unrenderable]';\n\t}\n}\n",
+    "import type { Attributes } from '../attributes/attributes';\nimport type { SpanContext, SpanId } from '../trace/ids';\n\n/**\n * The signal model. It is shared with `stx-telemetry`, the Kotlin counterpart:\n * the same four severities, the same span kinds and statuses, the same\n * discriminator. Changing anything here means the two estates have diverged.\n *\n * Instants are epoch **milliseconds**, which is the precision a JavaScript wall\n * clock has. OTLP wants nanoseconds, and the exporter multiplies.\n */\n\n/**\n * Four levels, and there is no `trace`: detail below `debug` is an attribute on\n * a span, where it is attached to the work it describes rather than to a line\n * somebody has to correlate by hand.\n */\nexport type Severity = 'debug' | 'info' | 'warn' | 'error';\n\n/** OTLP's numbers, which is what makes a backend order them correctly. */\nexport const SEVERITY_NUMBER: Readonly<Record<Severity, number>> =\n\tObject.freeze({\n\t\tdebug: 5,\n\t\tinfo: 9,\n\t\twarn: 13,\n\t\terror: 17,\n\t});\n\n/** Ascending, so a floor can be compared by index as well as by number. */\nexport const SEVERITIES: readonly Severity[] = Object.freeze([\n\t'debug',\n\t'info',\n\t'warn',\n\t'error',\n] as const);\n\n/** Whether `severity` clears the `minimum` floor. */\nexport function meetsSeverity(severity: Severity, minimum: Severity): boolean {\n\treturn SEVERITY_NUMBER[severity] >= SEVERITY_NUMBER[minimum];\n}\n\nexport type SpanKind =\n\t| 'internal'\n\t| 'server'\n\t| 'client'\n\t| 'producer'\n\t| 'consumer';\n\nexport const SPAN_KIND_NUMBER: Readonly<Record<SpanKind, number>> =\n\tObject.freeze({\n\t\tinternal: 1,\n\t\tserver: 2,\n\t\tclient: 3,\n\t\tproducer: 4,\n\t\tconsumer: 5,\n\t});\n\n/**\n * `cancelled` is distinct from `error` on purpose: a shutdown and a timeout are\n * not failures, and a dashboard that counts them as such is a dashboard nobody\n * trusts.\n */\nexport type SpanStatus = 'ok' | 'error' | 'cancelled';\n\n/** What every signal from one telemetry is about. */\nexport interface Resource {\n\treadonly service: string;\n\treadonly version?: string;\n\treadonly environment?: string;\n\treadonly attributes: Attributes;\n}\n\n/** A failure, flattened: the stack is text, because it crosses the wire. */\nexport interface ErrorInfo {\n\treadonly type: string;\n\treadonly message?: string;\n\treadonly stackTrace?: string;\n}\n\nexport interface LogRecord {\n\treadonly type: 'log';\n\t/** Epoch milliseconds. */\n\treadonly at: number;\n\treadonly severity: Severity;\n\t/** The event's name, or the message when there is no type for it yet. */\n\treadonly name: string;\n\t/** The logger's name. It becomes the OTLP instrumentation scope. */\n\treadonly source: string;\n\treadonly attributes: Attributes;\n\t/** Absent for a log written outside any span. */\n\treadonly span?: SpanContext;\n\treadonly error?: ErrorInfo;\n}\n\nexport interface SpanEvent {\n\treadonly name: string;\n\t/** Epoch milliseconds. */\n\treadonly at: number;\n\treadonly attributes: Attributes;\n}\n\nexport interface SpanRecord {\n\treadonly type: 'span';\n\treadonly name: string;\n\treadonly context: SpanContext;\n\t/** Absent for a root span. */\n\treadonly parent?: SpanId;\n\treadonly kind: SpanKind;\n\t/** Epoch milliseconds. */\n\treadonly startedAt: number;\n\t/** Epoch milliseconds. */\n\treadonly endedAt: number;\n\treadonly status: SpanStatus;\n\treadonly attributes: Attributes;\n\treadonly events: readonly SpanEvent[];\n\treadonly error?: ErrorInfo;\n}\n\n/**\n * The discriminator is the field `type`, with the values `\"log\"` and `\"span\"`.\n * It is not a class name, so that metrics can arrive as a third variant without\n * anything in the model or in the `Exporter` contract changing.\n */\nexport type Signal = LogRecord | SpanRecord;\n\n/** When a signal happened, whichever kind it is. */\nexport function signalAt(signal: Signal): number {\n\treturn signal.type === 'log' ? signal.at : signal.startedAt;\n}\n\n/** The span a signal belongs to, whichever kind it is. */\nexport function signalSpan(signal: Signal): SpanContext | undefined {\n\treturn signal.type === 'log' ? signal.span : signal.context;\n}\n",
+    "/**\n * Trace identity, and the W3C `traceparent` header.\n *\n * The ids are branded strings: the hex representation is the representation, so\n * there is nothing to allocate and nothing to convert before writing a header,\n * and the brand still stops a span id being passed where a trace id belongs.\n */\n\ndeclare const traceIdBrand: unique symbol;\ndeclare const spanIdBrand: unique symbol;\n\n/** 32 lowercase hex characters. */\nexport type TraceId = string & { readonly [traceIdBrand]: true };\n\n/** 16 lowercase hex characters. */\nexport type SpanId = string & { readonly [spanIdBrand]: true };\n\nexport const INVALID_TRACE_ID = '0'.repeat(32) as TraceId;\nexport const INVALID_SPAN_ID = '0'.repeat(16) as SpanId;\n\nconst TRACE_ID_PATTERN = /^[0-9a-f]{32}$/;\nconst SPAN_ID_PATTERN = /^[0-9a-f]{16}$/;\nconst HEX_PATTERN = /^[0-9a-f]+$/;\n\nexport function isValidTraceId(hex: string): hex is TraceId {\n\treturn TRACE_ID_PATTERN.test(hex) && hex !== INVALID_TRACE_ID;\n}\n\nexport function isValidSpanId(hex: string): hex is SpanId {\n\treturn SPAN_ID_PATTERN.test(hex) && hex !== INVALID_SPAN_ID;\n}\n\n/**\n * From `crypto.getRandomValues`, never `Math.random()`: ids that collide join\n * two unrelated traces into one, which reads as a request that did work it\n * never did.\n */\nexport function randomTraceId(): TraceId {\n\treturn randomHex(16) as TraceId;\n}\n\nexport function randomSpanId(): SpanId {\n\treturn randomHex(8) as SpanId;\n}\n\n/** A span's place in a trace, as it travels. */\nexport interface SpanContext {\n\treadonly traceId: TraceId;\n\treadonly spanId: SpanId;\n\t/** Decided once, by the root, and inherited by everything below it. */\n\treadonly sampled: boolean;\n\t/** True when this context was parsed from an inbound header. */\n\treadonly remote: boolean;\n}\n\n/**\n * What a span carries when there is no telemetry installed. The block still\n * runs — a library that traces must work inside an application that has never\n * heard of this one — and nothing is emitted.\n */\nexport const DETACHED_SPAN_CONTEXT: SpanContext = Object.freeze({\n\ttraceId: INVALID_TRACE_ID,\n\tspanId: INVALID_SPAN_ID,\n\tsampled: false,\n\tremote: false,\n});\n\nexport function isDetached(context: SpanContext): boolean {\n\treturn !isValidTraceId(context.traceId);\n}\n\n/** `00-<trace id>-<span id>-<flags>`, version 00, the only one we write. */\nexport function renderTraceparent(context: SpanContext): string {\n\treturn `00-${context.traceId}-${context.spanId}-${context.sampled ? '01' : '00'}`;\n}\n\n/**\n * The inbound half. It **returns null, and never throws**: an unusable header\n * is a request that starts a fresh trace, not a request that fails.\n *\n * Rejected: fewer than four fields, a version that is not two characters, the\n * forbidden version `ff`, an id of the wrong length or all zeros or not hex,\n * and flags that are not hex. A later version is accepted and its extra fields\n * ignored, which is what the specification asks of a version-00 reader.\n *\n * `tracestate` is not read. Nothing here writes one either.\n */\nexport function parseTraceparent(\n\theader: string | null | undefined,\n): SpanContext | null {\n\tif (!header) return null;\n\n\tconst parts = header.trim().toLowerCase().split('-');\n\tif (parts.length < 4) return null;\n\n\tconst [version, traceId, spanId, flags] = parts as [\n\t\tstring,\n\t\tstring,\n\t\tstring,\n\t\tstring,\n\t];\n\n\tif (version.length !== 2 || !HEX_PATTERN.test(version) || version === 'ff') {\n\t\treturn null;\n\t}\n\tif (!isValidTraceId(traceId) || !isValidSpanId(spanId)) return null;\n\tif (!HEX_PATTERN.test(flags)) return null;\n\n\tconst parsed = Number.parseInt(flags, 16);\n\tif (Number.isNaN(parsed)) return null;\n\n\treturn {\n\t\ttraceId,\n\t\tspanId,\n\t\tsampled: (parsed & 0x01) === 0x01,\n\t\tremote: true,\n\t};\n}\n\nconst HEX = '0123456789abcdef';\n\nfunction randomHex(bytes: number): string {\n\tconst buffer = new Uint8Array(bytes);\n\tcrypto.getRandomValues(buffer);\n\n\tlet hex = '';\n\tfor (const byte of buffer) {\n\t\thex += HEX[byte >> 4];\n\t\thex += HEX[byte & 0x0f];\n\t}\n\treturn hex;\n}\n",
+    "import { isValidTraceId, type TraceId } from './ids';\n\n/**\n * Sampling is decided once, by the root span, and the answer travels with the\n * trace — down through every child and out over the wire in the `traceparent`.\n * A sampler consulted per span produces traces missing their middles, and a gap\n * in a trace looks like work that never happened.\n *\n * Logs are not sampled. That decision is about the volume of traces, and a log\n * dropped because its trace was not kept is a log missing at precisely the\n * moment somebody is reading logs to find out what happened.\n */\nexport interface Sampler {\n\tsample(traceId: TraceId): boolean;\n}\n\nexport const alwaysSample: Sampler = { sample: () => true };\n\nexport const neverSample: Sampler = { sample: () => false };\n\nconst MAX_UINT64 = (1n << 64n) - 1n;\nconst SCALE = 1n << 53n;\n\n/**\n * Keep this fraction of traces, decided **from the trace id** rather than by a\n * coin toss: two services at the same ratio then make the same decision about\n * the same trace. Two services tossing independently at 10% keep a whole trace\n * 1% of the time.\n *\n * The rule is OpenTelemetry's — the low 64 bits of the trace id against\n * `ratio × 2⁶⁴` — so anything else implementing it agrees with us.\n *\n * @throws RangeError if `ratio` is not between 0 and 1. This is a construction\n * error, raised where the mistake is, and never on the path that writes a\n * signal.\n */\nexport function ratioSampler(ratio: number): Sampler {\n\tif (!Number.isFinite(ratio) || ratio < 0 || ratio > 1) {\n\t\tthrow new RangeError(`A sampling ratio is between 0 and 1, not ${ratio}`);\n\t}\n\tif (ratio === 0) return neverSample;\n\tif (ratio === 1) return alwaysSample;\n\n\tconst threshold =\n\t\t(BigInt(Math.round(ratio * Number(SCALE))) * MAX_UINT64) / SCALE;\n\n\treturn {\n\t\tsample(traceId: TraceId): boolean {\n\t\t\tif (!isValidTraceId(traceId)) return false;\n\t\t\treturn BigInt(`0x${traceId.slice(-16)}`) < threshold;\n\t\t},\n\t};\n}\n"
+  ],
+  "mappings": "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",
+  "debugId": "909718EB5895F3DC64756E2164756E21",
+  "names": []
+}

package/dist/model/signal.d.ts

@@ -0,0 +1,90 @@
+import type { Attributes } from '../attributes/attributes';
+import type { SpanContext, SpanId } from '../trace/ids';
+/**
+ * The signal model. It is shared with `stx-telemetry`, the Kotlin counterpart:
+ * the same four severities, the same span kinds and statuses, the same
+ * discriminator. Changing anything here means the two estates have diverged.
+ *
+ * Instants are epoch **milliseconds**, which is the precision a JavaScript wall
+ * clock has. OTLP wants nanoseconds, and the exporter multiplies.
+ */
+/**
+ * Four levels, and there is no `trace`: detail below `debug` is an attribute on
+ * a span, where it is attached to the work it describes rather than to a line
+ * somebody has to correlate by hand.
+ */
+export type Severity = 'debug' | 'info' | 'warn' | 'error';
+/** OTLP's numbers, which is what makes a backend order them correctly. */
+export declare const SEVERITY_NUMBER: Readonly<Record<Severity, number>>;
+/** Ascending, so a floor can be compared by index as well as by number. */
+export declare const SEVERITIES: readonly Severity[];
+/** Whether `severity` clears the `minimum` floor. */
+export declare function meetsSeverity(severity: Severity, minimum: Severity): boolean;
+export type SpanKind = 'internal' | 'server' | 'client' | 'producer' | 'consumer';
+export declare const SPAN_KIND_NUMBER: Readonly<Record<SpanKind, number>>;
+/**
+ * `cancelled` is distinct from `error` on purpose: a shutdown and a timeout are
+ * not failures, and a dashboard that counts them as such is a dashboard nobody
+ * trusts.
+ */
+export type SpanStatus = 'ok' | 'error' | 'cancelled';
+/** What every signal from one telemetry is about. */
+export interface Resource {
+    readonly service: string;
+    readonly version?: string;
+    readonly environment?: string;
+    readonly attributes: Attributes;
+}
+/** A failure, flattened: the stack is text, because it crosses the wire. */
+export interface ErrorInfo {
+    readonly type: string;
+    readonly message?: string;
+    readonly stackTrace?: string;
+}
+export interface LogRecord {
+    readonly type: 'log';
+    /** Epoch milliseconds. */
+    readonly at: number;
+    readonly severity: Severity;
+    /** The event's name, or the message when there is no type for it yet. */
+    readonly name: string;
+    /** The logger's name. It becomes the OTLP instrumentation scope. */
+    readonly source: string;
+    readonly attributes: Attributes;
+    /** Absent for a log written outside any span. */
+    readonly span?: SpanContext;
+    readonly error?: ErrorInfo;
+}
+export interface SpanEvent {
+    readonly name: string;
+    /** Epoch milliseconds. */
+    readonly at: number;
+    readonly attributes: Attributes;
+}
+export interface SpanRecord {
+    readonly type: 'span';
+    readonly name: string;
+    readonly context: SpanContext;
+    /** Absent for a root span. */
+    readonly parent?: SpanId;
+    readonly kind: SpanKind;
+    /** Epoch milliseconds. */
+    readonly startedAt: number;
+    /** Epoch milliseconds. */
+    readonly endedAt: number;
+    readonly status: SpanStatus;
+    readonly attributes: Attributes;
+    readonly events: readonly SpanEvent[];
+    readonly error?: ErrorInfo;
+}
+/**
+ * The discriminator is the field `type`, with the values `"log"` and `"span"`.
+ * It is not a class name, so that metrics can arrive as a third variant without
+ * anything in the model or in the `Exporter` contract changing.
+ */
+export type Signal = LogRecord | SpanRecord;
+/** When a signal happened, whichever kind it is. */
+export declare function signalAt(signal: Signal): number;
+/** The span a signal belongs to, whichever kind it is. */
+export declare function signalSpan(signal: Signal): SpanContext | undefined;
+//# sourceMappingURL=signal.d.ts.map

package/dist/model/signal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signal.d.ts","sourceRoot":"","sources":["../../src/model/signal.ts"],"names":[],"mappings":"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"}

package/dist/trace/ids.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Trace identity, and the W3C `traceparent` header.
+ *
+ * The ids are branded strings: the hex representation is the representation, so
+ * there is nothing to allocate and nothing to convert before writing a header,
+ * and the brand still stops a span id being passed where a trace id belongs.
+ */
+declare const traceIdBrand: unique symbol;
+declare const spanIdBrand: unique symbol;
+/** 32 lowercase hex characters. */
+export type TraceId = string & {
+    readonly [traceIdBrand]: true;
+};
+/** 16 lowercase hex characters. */
+export type SpanId = string & {
+    readonly [spanIdBrand]: true;
+};
+export declare const INVALID_TRACE_ID: TraceId;
+export declare const INVALID_SPAN_ID: SpanId;
+export declare function isValidTraceId(hex: string): hex is TraceId;
+export declare function isValidSpanId(hex: string): hex is SpanId;
+/**
+ * From `crypto.getRandomValues`, never `Math.random()`: ids that collide join
+ * two unrelated traces into one, which reads as a request that did work it
+ * never did.
+ */
+export declare function randomTraceId(): TraceId;
+export declare function randomSpanId(): SpanId;
+/** A span's place in a trace, as it travels. */
+export interface SpanContext {
+    readonly traceId: TraceId;
+    readonly spanId: SpanId;
+    /** Decided once, by the root, and inherited by everything below it. */
+    readonly sampled: boolean;
+    /** True when this context was parsed from an inbound header. */
+    readonly remote: boolean;
+}
+/**
+ * What a span carries when there is no telemetry installed. The block still
+ * runs — a library that traces must work inside an application that has never
+ * heard of this one — and nothing is emitted.
+ */
+export declare const DETACHED_SPAN_CONTEXT: SpanContext;
+export declare function isDetached(context: SpanContext): boolean;
+/** `00-<trace id>-<span id>-<flags>`, version 00, the only one we write. */
+export declare function renderTraceparent(context: SpanContext): string;
+/**
+ * The inbound half. It **returns null, and never throws**: an unusable header
+ * is a request that starts a fresh trace, not a request that fails.
+ *
+ * Rejected: fewer than four fields, a version that is not two characters, the
+ * forbidden version `ff`, an id of the wrong length or all zeros or not hex,
+ * and flags that are not hex. A later version is accepted and its extra fields
+ * ignored, which is what the specification asks of a version-00 reader.
+ *
+ * `tracestate` is not read. Nothing here writes one either.
+ */
+export declare function parseTraceparent(header: string | null | undefined): SpanContext | null;
+export {};
+//# sourceMappingURL=ids.d.ts.map

package/dist/trace/ids.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.d.ts","sourceRoot":"","sources":["../../src/trace/ids.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,CAAC,MAAM,YAAY,EAAE,OAAO,MAAM,CAAC;AAC1C,OAAO,CAAC,MAAM,WAAW,EAAE,OAAO,MAAM,CAAC;AAEzC,mCAAmC;AACnC,MAAM,MAAM,OAAO,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,CAAC,YAAY,CAAC,EAAE,IAAI,CAAA;CAAE,CAAC;AAEjE,mCAAmC;AACnC,MAAM,MAAM,MAAM,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,CAAC,WAAW,CAAC,EAAE,IAAI,CAAA;CAAE,CAAC;AAE/D,eAAO,MAAM,gBAAgB,EAAqB,OAAO,CAAC;AAC1D,eAAO,MAAM,eAAe,EAAqB,MAAM,CAAC;AAMxD,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,IAAI,OAAO,CAE1D;AAED,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,IAAI,MAAM,CAExD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,IAAI,OAAO,CAEvC;AAED,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED,gDAAgD;AAChD,MAAM,WAAW,WAAW;IAC3B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,uEAAuE;IACvE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,gEAAgE;IAChE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CACzB;AAED;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,EAAE,WAKlC,CAAC;AAEH,wBAAgB,UAAU,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAExD;AAED,4EAA4E;AAC5E,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,CAE9D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC/B,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC/B,WAAW,GAAG,IAAI,CA4BpB"}

package/dist/trace/sampler.d.ts

@@ -0,0 +1,31 @@
+import { type TraceId } from './ids';
+/**
+ * Sampling is decided once, by the root span, and the answer travels with the
+ * trace — down through every child and out over the wire in the `traceparent`.
+ * A sampler consulted per span produces traces missing their middles, and a gap
+ * in a trace looks like work that never happened.
+ *
+ * Logs are not sampled. That decision is about the volume of traces, and a log
+ * dropped because its trace was not kept is a log missing at precisely the
+ * moment somebody is reading logs to find out what happened.
+ */
+export interface Sampler {
+    sample(traceId: TraceId): boolean;
+}
+export declare const alwaysSample: Sampler;
+export declare const neverSample: Sampler;
+/**
+ * Keep this fraction of traces, decided **from the trace id** rather than by a
+ * coin toss: two services at the same ratio then make the same decision about
+ * the same trace. Two services tossing independently at 10% keep a whole trace
+ * 1% of the time.
+ *
+ * The rule is OpenTelemetry's — the low 64 bits of the trace id against
+ * `ratio × 2⁶⁴` — so anything else implementing it agrees with us.
+ *
+ * @throws RangeError if `ratio` is not between 0 and 1. This is a construction
+ * error, raised where the mistake is, and never on the path that writes a
+ * signal.
+ */
+export declare function ratioSampler(ratio: number): Sampler;
+//# sourceMappingURL=sampler.d.ts.map

package/dist/trace/sampler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sampler.d.ts","sourceRoot":"","sources":["../../src/trace/sampler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,KAAK,OAAO,EAAE,MAAM,OAAO,CAAC;AAErD;;;;;;;;;GASG;AACH,MAAM,WAAW,OAAO;IACvB,MAAM,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC;CAClC;AAED,eAAO,MAAM,YAAY,EAAE,OAAgC,CAAC;AAE5D,eAAO,MAAM,WAAW,EAAE,OAAiC,CAAC;AAK5D;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAgBnD"}

package/package.json

@@ -0,0 +1,58 @@
+{
+	"name": "@nxgt/telemetry",
+	"version": "0.1.0",
+	"description": "Logs and traces for a TypeScript service, with no OpenTelemetry SDK: spans over AsyncLocalStorage, W3C traceparent propagation, declared events, and a pipeline that never blocks the caller",
+	"license": "MIT",
+	"type": "module",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"files": [
+		"dist",
+		"README.md",
+		"package.json",
+		"LICENSE"
+	],
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"default": "./dist/index.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"keywords": [
+		"telemetry",
+		"observability",
+		"tracing",
+		"logging",
+		"opentelemetry",
+		"otlp",
+		"traceparent",
+		"typescript"
+	],
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/softistx/nxgt-telemetry.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"
+	},
+	"nxgt": {
+		"entrypoints": [
+			"src/index.ts"
+		]
+	},
+	"devDependencies": {
+		"@types/bun": "^1.4.0"
+	},
+	"peerDependencies": {
+		"typescript": "^6.0.3"
+	}
+}