@maroonedsoftware/telemetry 0.0.0-stage → 0.1.1

package/AGENTS.md

@@ -0,0 +1,179 @@
+# AGENTS.md — @maroonedsoftware/telemetry
+
+Machine-oriented guide for AI agents. Human prose and long-form examples live in [README.md](./README.md).
+Repo-wide conventions live in the [root AGENTS.md](../../AGENTS.md).
+
+## Purpose
+
+Collects application metrics into one-minute buckets in memory (`MetricsRecorder`), so an app can keep
+its own numbers over time and chart them. Not an OpenTelemetry SDK replacement: it holds aggregates, not
+raw observations, and has no percentiles. Reach for the OTel SDK directly when you only need to ship
+metrics to a collector and never read them back.
+
+## Install
+
+```bash
+pnpm add @maroonedsoftware/telemetry injectkit reflect-metadata
+```
+
+Required peers: none beyond `injectkit`'s own `reflect-metadata`.
+Optional peers: `kysely` — unlocks the `./kysely` subpath (`MetricsStore`). `@opentelemetry/api`, `/core`,
+`/resources`, `/sdk-metrics` and `/sdk-trace` — unlock the `./otlp` subpath. The OTLP exporters themselves
+(`@opentelemetry/exporter-metrics-otlp-http` and the like) are the app's choice and not peers.
+
+## Position in the graph
+
+- **Depends on:** nothing internal
+- **Depended on by:** nothing internal
+- **Subpath exports:** `./kysely` — `MetricsStore`, the PostgreSQL store; a subpath so the root entry stays free of `kysely`
+- **Subpath exports:** `./otlp` — `OtlpMetricsBridge`, `OtlpSpanBridge` and the id helpers; a subpath so the root entry stays free of the OTel SDK
+
+## API surface
+
+| Export                       | Kind      | Shape                                                                                                                            | Notes                                                                    |
+| ---------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| `MetricsRecorder`            | class     | `observe(name, value, labels?, at?)`, `gauge(name, read, options?)`, `sampleGauges(now?)`, `drain()`, `pending`, `onGaugeError?` | `@Injectable()`; register as a singleton                                 |
+| `GaugeReader`                | type      | `() => number \| undefined \| Promise<number \| undefined>`                                                                      | `undefined` records nothing                                              |
+| `GaugeOptions`               | interface | `{ labels?: MetricLabels; every?: Duration }`                                                                                    | `every` defaults to zero (every pass)                                    |
+| `GaugeErrorHandler`          | type      | `(name: string, error: unknown) => void`                                                                                         |                                                                          |
+| `MetricAggregate`            | interface | `{ count, sum, min, max, last }`                                                                                                 |                                                                          |
+| `aggregateOf`                | function  | `(value: number) => MetricAggregate`                                                                                             |                                                                          |
+| `mergeAggregates`            | function  | `(previous, next) => MetricAggregate`                                                                                            | associative; `last` is taken from `next`                                 |
+| `MetricBucket`               | interface | `{ name, labels, labelsKey, start: DateTime, aggregate }`                                                                        | `start` is the UTC minute                                                |
+| `minuteOf`                   | function  | `(at: DateTime) => DateTime`                                                                                                     | UTC start of minute                                                      |
+| `MetricLabels`               | type      | `Readonly<Record<string, string>>`                                                                                               | string values only                                                       |
+| `labelsKey`                  | function  | `(labels: MetricLabels) => string`                                                                                               | sorted JSON; `'{}'` for none                                             |
+| `FinishedSpan`               | interface | `{ traceId, spanId, parentSpanId?, name, start, end, ok, error?, attributes?, links? }`                                          | the app's own ids; work already done                                     |
+| `SpanLink`                   | interface | `{ traceId, spanId }`                                                                                                            |                                                                          |
+| `SpanAttributeValue`         | type      | `string \| number \| boolean`                                                                                                    |                                                                          |
+| `OtlpMetricsReceiver`        | class     | `new OtlpMetricsReceiver({ maxSeriesPerName?, maxNames? })`; `receive(body, now?) => OtlpReceiveResult`                          | OTLP/JSON only; holds cumulative baselines and the caps; one per process |
+| `OtlpMetricsReceiverOptions` | interface | `{ maxSeriesPerName?: number; maxNames?: number }`                                                                               | defaults 50 and 500                                                      |
+| `OtlpReceiveResult`          | interface | `{ buckets: MetricBucket[]; dropped: number; unsupported: number }`                                                              |                                                                          |
+| `OtlpPayloadError`           | class     | `extends Error`                                                                                                                  | body is not a metrics export; answer 400                                 |
+| `MetricResolution`           | type      | `'minute' \| 'hour'`                                                                                                             |                                                                          |
+| `resolutionFor`              | function  | `(from, to, limit?) => MetricResolution`                                                                                         | minutes up to `limit` (48h), else hours                                  |
+| `MINUTE_RESOLUTION_LIMIT`    | const     | `Duration` (48 hours)                                                                                                            |                                                                          |
+
+### `./kysely`
+
+| Export                | Kind      | Shape                                                                                                                                                                | Notes                                                                         |
+| --------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| `MetricsStore<DB>`    | class     | `new MetricsStore(db: Kysely<DB>, options)`; `upsertMinutes(buckets, source?)`, `rollupHour(hour)`, `prune(resolution, olderThan, now?)`, `series(query)`, `names()` | runs on `db.withoutPlugins()`; not `@Injectable()`, construct it in a factory |
+| `MetricsStoreOptions` | interface | `{ table: string; scope?: Record<string, string>; batchSize?: number }`                                                                                              | `scope` columns must be in the primary key                                    |
+| `MetricSeriesQuery`   | interface | `{ names, from, to, resolution, labels? }`                                                                                                                           | `to` is exclusive; `labels` matches with `@>`                                 |
+| `MetricSeries`        | interface | `{ name, labels, labelsKey, source, points: MetricPoint[] }`                                                                                                         | points oldest first                                                           |
+| `MetricPoint`         | interface | `{ start: DateTime; aggregate: MetricAggregate }`                                                                                                                    |                                                                               |
+| `MetricName`          | interface | `{ name, source, labelKeys: string[], lastSeen: DateTime }`                                                                                                          |                                                                               |
+
+### `./otlp`
+
+| Export                     | Kind      | Shape                                                                                              | Notes                                                                    |
+| -------------------------- | --------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| `OtlpMetricsBridge`        | class     | `new OtlpMetricsBridge({ exporter, resource?, scope?, kindOf? })`; `export(buckets)`, `shutdown()` | builds `ResourceMetrics` directly, no `MeterProvider`; delta temporality |
+| `OtlpMetricsBridgeOptions` | interface | as above                                                                                           | `kindOf` defaults to `gauge`                                             |
+| `MetricKind`               | type      | `'gauge' \| 'counter' \| 'histogram'`                                                              | gauge → `last`, counter → `sum`, histogram → count/sum/min/max           |
+| `OtlpSpanBridge`           | class     | `new OtlpSpanBridge({ exporter, resource?, scope? })`; `export(spans)`, `shutdown()`               | builds finished `ReadableSpan`s with recorded times                      |
+| `OtlpSpanBridgeOptions`    | interface | as above                                                                                           |                                                                          |
+| `otlpTraceId`              | function  | `(id: string) => string`                                                                           | 32 hex; kept if already, else sha256-derived                             |
+| `otlpSpanId`               | function  | `(id: string) => string`                                                                           | 16 hex; same rule                                                        |
+
+## Canonical usage
+
+```typescript
+import { MetricsRecorder } from '@maroonedsoftware/telemetry';
+
+registry.register(MetricsRecorder).useClass(MetricsRecorder).asSingleton();
+
+const recorder = container.get(MetricsRecorder);
+recorder.observe('work.job.ms', 412, { queue: 'catalog.sync' });
+recorder.gauge('station.listeners', () => audience.count());
+
+// your loop, once a minute
+await recorder.sampleGauges();
+await write(recorder.drain());
+```
+
+With the store, in the app's own loop and jobs:
+
+```typescript
+import { MetricsStore } from '@maroonedsoftware/telemetry/kysely';
+
+const store = new MetricsStore(db, { table: 'app.metric_samples' });
+await store.upsertMinutes(recorder.drain()); // every minute
+await store.rollupHour(DateTime.utc().minus({ hours: 1 })); // hourly job
+await store.prune('minute', Duration.fromObject({ days: 7 })); // nightly job
+```
+
+Exporting over OTLP:
+
+```typescript
+import { OtlpMetricsBridge, OtlpSpanBridge } from '@maroonedsoftware/telemetry/otlp';
+import { OTLPMetricExporter } from '@opentelemetry/exporter-metrics-otlp-http';
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
+
+const metrics = new OtlpMetricsBridge({ exporter: new OTLPMetricExporter({ url }), kindOf: name => (name.endsWith('.ms') ? 'histogram' : 'gauge') });
+const spans = new OtlpSpanBridge({ exporter: new OTLPTraceExporter({ url }) });
+
+const buckets = recorder.drain();
+await store.upsertMinutes(buckets);
+await metrics.export(buckets).catch(log); // a dead collector must not stop the store write
+await spans.export(finishedSinceLastFlush);
+```
+
+Receiving OTLP/JSON from other services, in the app's own route:
+
+```typescript
+import { OtlpMetricsReceiver, OtlpPayloadError } from '@maroonedsoftware/telemetry';
+
+const receiver = new OtlpMetricsReceiver({ maxSeriesPerName: 50 }); // a singleton
+
+const { buckets, dropped } = receiver.receive(ctx.request.body); // throws OtlpPayloadError → 400
+await store.upsertMinutes(buckets, 'otlp');
+ctx.body = dropped > 0 ? { partialSuccess: { rejectedDataPoints: String(dropped) } } : {};
+```
+
+## Rules for generated code
+
+- Register `MetricsRecorder` as a singleton. A scoped or transient recorder splits observations across
+  instances and the loop drains only one of them.
+- Name metrics in dot notation (`work.job.ms`), with the unit as the last segment when there is one.
+- Keep label values from a small, known set (a queue name, a plugin id). Never put an id, a user, or
+  free text in a label: every distinct label set is a row per minute.
+- Drain on shutdown too, after producers have stopped, or the last partial minute is lost.
+- Create the table from the reference DDL in the README, in the app's own migration. Column names are
+  fixed; add `scope` columns to the primary key, first.
+- Roll an hour up only once it is complete. Rolling up early is not wrong (the next run replaces the row)
+  but the hour row lags until then.
+
+- Export to OTLP after the store write, and never let an export failure skip or retry the store write.
+- Give every metric that is a duration or a count a `kindOf` answer; the default sends everything as a gauge.
+
+- Keep one `OtlpMetricsReceiver` per process. A new one per request loses every cumulative baseline, so
+  cumulative sums and histograms never produce a point.
+- Put received metrics behind authentication and a size limit on the body: the caps bound rows, not bytes.
+
+## Gotchas
+
+- `drain()` includes the still-open minute. A store must merge (upsert) rather than insert, or a
+  minute flushed twice is double-counted or rejected.
+- The OTLP metrics are delta. A collector feeding Prometheus needs the `deltatocumulative` processor.
+- `otlpTraceId` hashes, so a trace id is only stable for the same app id string. Two apps sharing a trace
+  must agree on the id string, or pass real 32-hex ids.
+- The receiver reads OTLP/JSON only. A sender on the default `http/protobuf` encoding must be switched to
+  `http/json` (`OTEL_EXPORTER_OTLP_METRICS_PROTOCOL=http/json`).
+- A cumulative series' first point, and its first after a sender restart, produce nothing: they set the baseline.
+- The caps last for the receiver's life. A dropped series stays dropped until the process restarts.
+- `observe()` silently drops `NaN` and `Infinity`.
+- `MetricsStore` ignores the app's Kysely plugins. Rows from `series()` are mapped by the store, never
+  read raw, so a `CamelCasePlugin` cannot rename its columns underneath it.
+- A gauge whose reader throws is marked sampled anyway, so it is retried at its `every` cadence, not on
+  the next pass.
+
+## Working inside this package
+
+`src/` holds one concern per file (`metric.aggregate.ts`, `metric.labels.ts`, `metric.bucket.ts`,
+`metric.resolution.ts`, `metrics.recorder.ts`) behind the `src/index.ts` barrel, `metrics.store.ts` behind the
+`src/kysely.ts` subpath entry, and the `otlp.*.ts` bridges behind `src/otlp.ts`.
+`otlp.metrics.receiver.ts` is in the root entry on purpose: it parses JSON and needs no OTel SDK; tests mirror them in `tests/`. Keep the root
+entry free of I/O and of external SDKs. A new subpath needs an `exports` entry, a tsup entry in
+`build`, and its SDK as an optional peer. Every user-visible change needs a changeset.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marooned Software
+
+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

@@ -1,3 +1,125 @@
-# Temporary Holding Version
+# @maroonedsoftware/telemetry
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Minute-bucket metrics for ServerKit. Producers observe numbers into an in-process recorder; a loop you own drains it once a minute and writes what it drained wherever you keep metrics.
+
+## Features
+
+- **One shape for every metric**: each series' minute is five numbers (`count`, `sum`, `min`, `max`, `last`), which read as a gauge, a counter or a duration
+- **Gauge registry**: register a reader once, sample it on every pass or at its own cadence
+- **Merge-friendly**: aggregates are associative, so a later flush of the same minute merges into the row already stored, and minutes fold into hours
+- **No I/O in the recorder**: storage and export are separate, so a dead database or collector never blocks a producer
+- **A PostgreSQL store** (`/kysely`): merging upserts, idempotent hourly rollups, pruning, range reads
+- **OpenTelemetry bridges** (`/otlp`): send the same buckets, and finished spans, to any OTLP exporter
+- **An OTLP/JSON receiver**: read other services' metric exports into the same buckets, with cumulative-to-delta and a cardinality cap
+- **Zero internal dependencies**: [injectkit](https://www.npmjs.com/package/injectkit) and [luxon](https://moment.github.io/luxon/) only
+
+## Installation
+
+```bash
+pnpm add @maroonedsoftware/telemetry injectkit reflect-metadata
+```
+
+## Quick start
+
+```typescript
+import { MetricsRecorder } from '@maroonedsoftware/telemetry';
+import { Duration } from 'luxon';
+
+const recorder = new MetricsRecorder(); // register as a singleton in your container
+
+// Anywhere work happens:
+recorder.observe('work.job.ms', 412, { queue: 'catalog.sync' });
+
+// Once, where a reading lives:
+recorder.gauge('disk.free.bytes', () => disk.free(), { every: Duration.fromObject({ minutes: 15 }) });
+
+// In a loop you own, once a minute:
+await recorder.sampleGauges();
+const buckets = recorder.drain();
+```
+
+## Storing metrics in PostgreSQL
+
+`@maroonedsoftware/telemetry/kysely` needs `kysely` installed. The table belongs to your app; create it in your own migration:
+
+```sql
+create table app.metric_samples (
+  resolution  text             not null check (resolution in ('minute', 'hour')),
+  bucket      timestamptz      not null,
+  name        text             not null,
+  labels      jsonb            not null default '{}',
+  labels_key  text             not null,
+  source      text             not null default 'app',
+  count       double precision not null,
+  sum         double precision not null,
+  min         double precision not null,
+  max         double precision not null,
+  last        double precision not null,
+  primary key (resolution, name, labels_key, bucket)
+);
+create index metric_samples_bucket on app.metric_samples (resolution, bucket);
+```
+
+To keep several tenants in one table, add a column per tenant key to the front of the primary key and the index, and pass it as `scope`.
+
+```typescript
+import { MetricsStore } from '@maroonedsoftware/telemetry/kysely';
+import { resolutionFor } from '@maroonedsoftware/telemetry';
+
+const store = new MetricsStore(db, { table: 'app.metric_samples' });
+
+await store.upsertMinutes(recorder.drain()); // a later flush of the same minute merges in
+await store.rollupHour(DateTime.utc().minus({ hours: 1 })); // idempotent: replaces the hour row
+await store.prune('minute', Duration.fromObject({ days: 7 }));
+await store.prune('hour', Duration.fromObject({ days: 400 }));
+
+const series = await store.series({ names: ['work.job.ms'], from, to, resolution: resolutionFor(from, to) });
+```
+
+## Exporting over OTLP
+
+`@maroonedsoftware/telemetry/otlp` needs `@opentelemetry/api`, `/core`, `/resources`, `/sdk-metrics` and `/sdk-trace`, plus whichever exporter you send with.
+
+```typescript
+import { OtlpMetricsBridge, OtlpSpanBridge } from '@maroonedsoftware/telemetry/otlp';
+
+const metrics = new OtlpMetricsBridge({
+  exporter: new OTLPMetricExporter({ url: 'http://collector:4318/v1/metrics' }),
+  kindOf: name => (name.endsWith('.ms') ? 'histogram' : name.endsWith('.count') ? 'counter' : 'gauge'),
+});
+await metrics.export(buckets);
+
+const spans = new OtlpSpanBridge({ exporter: new OTLPTraceExporter({ url: 'http://collector:4318/v1/traces' }) });
+await spans.export([{ traceId: 'job-42', spanId: 'job-42/run', name: 'job.run', start, end, ok: true }]);
+```
+
+Metrics go out with delta temporality: each bucket is one point spanning its minute. Spans keep the times you recorded, and your own ids are hashed into OTLP form so the same id always lands in the same trace.
+
+## Receiving OTLP/JSON
+
+`OtlpMetricsReceiver` turns the body of an OTLP/HTTP `POST /v1/metrics` sent as JSON into minute buckets, so other services' metrics land in the same store. It needs no OTel packages.
+
+```typescript
+import { OtlpMetricsReceiver } from '@maroonedsoftware/telemetry';
+
+const receiver = new OtlpMetricsReceiver({ maxSeriesPerName: 50, maxNames: 500 }); // keep one per process
+
+const { buckets, dropped, unsupported } = receiver.receive(body);
+await store.upsertMinutes(buckets, 'otlp');
+```
+
+Gauges and up-down sums are read as values; monotonic sums and histograms contribute their increase, with cumulative series differenced against their previous point. Exponential histograms and summaries are counted as unsupported. Senders must use `http/json`, not protobuf.
+
+## Reading an aggregate
+
+| Kind     | Read                                        |
+| -------- | ------------------------------------------- |
+| Gauge    | `last`, or `sum / count` for the mean       |
+| Counter  | `sum`                                       |
+| Duration | `sum / count` for the mean, `max` for worst |
+
+There are no percentiles: those need a histogram or sketch per bucket.
+
+## License
+
+MIT

package/dist/chunk-7QVYU63E.js

@@ -0,0 +1,7 @@
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+export {
+  __name
+};
+//# sourceMappingURL=chunk-7QVYU63E.js.map

package/dist/chunk-7QVYU63E.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/chunk-E7OXUL3D.js

@@ -0,0 +1,25 @@
+import {
+  __name
+} from "./chunk-7QVYU63E.js";
+
+// src/metric.aggregate.ts
+var aggregateOf = /* @__PURE__ */ __name((value) => ({
+  count: 1,
+  sum: value,
+  min: value,
+  max: value,
+  last: value
+}), "aggregateOf");
+var mergeAggregates = /* @__PURE__ */ __name((previous, next) => ({
+  count: previous.count + next.count,
+  sum: previous.sum + next.sum,
+  min: Math.min(previous.min, next.min),
+  max: Math.max(previous.max, next.max),
+  last: next.last
+}), "mergeAggregates");
+
+export {
+  aggregateOf,
+  mergeAggregates
+};
+//# sourceMappingURL=chunk-E7OXUL3D.js.map

package/dist/chunk-E7OXUL3D.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/metric.aggregate.ts"],"sourcesContent":["/**\n * Five numbers that summarise every observation of one series inside one bucket.\n *\n * One shape covers all three kinds of metric, so a store needs a single row type:\n * - a **gauge** reads `last` (or `sum / count` for the bucket's mean),\n * - a **counter** reads `sum`,\n * - a **duration** reads `sum / count` for the mean and `max` for the worst.\n *\n * There are no percentiles. They need a histogram or a sketch per bucket, and the\n * mean beside the max is enough to see that something got slow.\n */\nexport interface MetricAggregate {\n  /** How many observations were folded in. */\n  count: number;\n  /** Their total. */\n  sum: number;\n  /** The smallest observation. */\n  min: number;\n  /** The largest observation. */\n  max: number;\n  /** The most recent observation. */\n  last: number;\n}\n\n/**\n * The aggregate of a single observation.\n *\n * @param value - The observed value. The caller is expected to have rejected non-finite values.\n */\nexport const aggregateOf = (value: number): MetricAggregate => ({ count: 1, sum: value, min: value, max: value, last: value });\n\n/**\n * Folds `next` into `previous`.\n *\n * Associative, so buckets can be merged in any grouping (a flush into a stored row, minutes into an\n * hour). Not commutative in `last`: `next` is taken to be the later of the two.\n *\n * @param previous - The earlier aggregate.\n * @param next - The later aggregate.\n * @returns A new aggregate; neither input is modified.\n */\nexport const mergeAggregates = (previous: MetricAggregate, next: MetricAggregate): MetricAggregate => ({\n  count: previous.count + next.count,\n  sum: previous.sum + next.sum,\n  min: Math.min(previous.min, next.min),\n  max: Math.max(previous.max, next.max),\n  last: next.last,\n});\n"],"mappings":";;;;;AA6BO,IAAMA,cAAc,wBAACC,WAAoC;EAAEC,OAAO;EAAGC,KAAKF;EAAOG,KAAKH;EAAOI,KAAKJ;EAAOK,MAAML;AAAM,IAAjG;AAYpB,IAAMM,kBAAkB,wBAACC,UAA2BC,UAA4C;EACrGP,OAAOM,SAASN,QAAQO,KAAKP;EAC7BC,KAAKK,SAASL,MAAMM,KAAKN;EACzBC,KAAKM,KAAKN,IAAII,SAASJ,KAAKK,KAAKL,GAAG;EACpCC,KAAKK,KAAKL,IAAIG,SAASH,KAAKI,KAAKJ,GAAG;EACpCC,MAAMG,KAAKH;AACb,IAN+B;","names":["aggregateOf","value","count","sum","min","max","last","mergeAggregates","previous","next","Math"]}

package/dist/finished.span.d.ts

@@ -0,0 +1,44 @@
+import { DateTime } from 'luxon';
+/**
+ * An attribute value on a {@link FinishedSpan}.
+ */
+export type SpanAttributeValue = string | number | boolean;
+/**
+ * A reference from one span to another that is not its parent: work one decision caused in another
+ * trace, say.
+ */
+export interface SpanLink {
+    traceId: string;
+    spanId: string;
+}
+/**
+ * A unit of work that has already happened, described after the fact.
+ *
+ * Apps that time their own work (a job runner wrapping each run, a tool loop timing each call) can
+ * describe it in this plain shape and hand it to an exporter, rather than threading a live tracer
+ * through the work. The ids are the app's own strings: an exporter that needs a particular format
+ * (OTLP's 16- and 8-byte hex) derives one from them.
+ */
+export interface FinishedSpan {
+    /** Groups the spans of one piece of work. */
+    traceId: string;
+    /** Identifies this span within its trace. */
+    spanId: string;
+    /** The span this one ran inside, in the same trace. */
+    parentSpanId?: string;
+    /** What the work was: `job.run`, `plugin.invoke`. */
+    name: string;
+    /** When it began. */
+    start: DateTime;
+    /** When it ended. */
+    end: DateTime;
+    /** Whether it succeeded. */
+    ok: boolean;
+    /** Why it failed, when it did. Never sent as anything but a status message. */
+    error?: string;
+    /** Anything else worth keeping about it. */
+    attributes?: Readonly<Record<string, SpanAttributeValue>>;
+    /** Spans in other traces this one relates to. */
+    links?: readonly SpanLink[];
+}
+//# sourceMappingURL=finished.span.d.ts.map

package/dist/finished.span.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"finished.span.d.ts","sourceRoot":"","sources":["../src/finished.span.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAEjC;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAE3D;;;GAGG;AACH,MAAM,WAAW,QAAQ;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,6CAA6C;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf,uDAAuD;IACvD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qDAAqD;IACrD,IAAI,EAAE,MAAM,CAAC;IACb,qBAAqB;IACrB,KAAK,EAAE,QAAQ,CAAC;IAChB,qBAAqB;IACrB,GAAG,EAAE,QAAQ,CAAC;IACd,4BAA4B;IAC5B,EAAE,EAAE,OAAO,CAAC;IACZ,+EAA+E;IAC/E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4CAA4C;IAC5C,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAAC;IAC1D,iDAAiD;IACjD,KAAK,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAC;CAC7B"}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export * from './finished.span.js';
+export * from './metric.aggregate.js';
+export * from './metric.bucket.js';
+export * from './metric.labels.js';
+export * from './metric.resolution.js';
+export * from './metrics.recorder.js';
+export * from './otlp.metrics.receiver.js';
+//# 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,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,wBAAwB,CAAC;AACvC,cAAc,uBAAuB,CAAC;AACtC,cAAc,4BAA4B,CAAC"}