@noego/telemetry

Bounded structured telemetry for Node, browsers, and Electron. The core package owns envelope normalization, batching, transport contracts, routing, and collector semantics. SQLite is an explicit Node-only storage terminal.

import {
  DEFAULT_METADATA_SNAPSHOT_LIMITS,
  DEFAULT_TELEMETRY_ADMISSION_POLICY,
  NodeTelemetryProducerHost,
} from '@noego/telemetry/node/producer';

const host = new NodeTelemetryProducerHost({
  source: 'api',
  processKind: 'server',
  transport, // Any TelemetryBatchTransport implementation.
  admission: DEFAULT_TELEMETRY_ADMISSION_POLICY,
  metadata: DEFAULT_METADATA_SNAPSHOT_LIMITS,
  producerId: null,
});

host.client.info('tool.set.resolve.started', {
  conversationId: 169,
  toolCount: 8,
});

Producer calls only take a bounded metadata snapshot and enqueue it. Encoding, checksums, transport work, metric extraction, persistence, and maintenance run asynchronously downstream.

Producer-only Node applications should import @noego/telemetry/node/producer. That entry contains no SQLite, Proper, SQLStack, filesystem, or native-addon dependency. The existing @noego/telemetry/node entry remains the compatible collector/combined composition surface and therefore includes SQLite support.

Node supports producer, collector, and combined roles. Browser code injects a browser-safe transport through @noego/telemetry/browser; Electron renderers use the browser client while the main or utility process composes the Node collector. Custom batch transports and custom storage terminals implement the public core contracts, so pipes and durable targets can be chained or fanned out without changing event producers.

Rust N-API collector

Electron applications should use NativeTelemetryHost.combined(...) from @noego/telemetry/node when collector work must not run on Electron's event loop. The N-API boundary validates its constructor configuration, starts one named noego-telemetry-collector Rust thread, and sends it commands through a bounded channel. Batch validation, metric extraction, SQLite transactions, rollups, retention, lease heartbeats, checkpoints, incremental reclaim, and shutdown execute on that thread. JavaScript receives promises backed by N-API tasks; no SQLite statement executes in the calling JavaScript thread.

Build the native addon with npm run build:native, or use npm run build to build the addon and TypeScript package together. The build requires a Rust toolchain with Cargo. The resulting N-API 9 addon is loaded by package-relative path and works under both supported Node and Electron runtimes. There is no fallback from NativeTelemetryHost to synchronous JavaScript SQLite.

Collector and combined Node hosts can create same-process producers with host.createLocalProducer({ source, processKind, admission, metadata, producerId }). Each producer receives its own in-memory durable pipe and sequence identity; the host owns and drains all of them before collector shutdown.

SQLite owns its schema and runs bundled Proper migrations through its sole writer connection. Table names are predefined; a validated prefix or logical table override map is available as an initialization escape hatch. Metric definitions write generic versioned rows and never create application tables.

SQLite idempotency is deliberately time-bounded. Exact duplicate acknowledgements are retained for raw + lateArrival; after that window, the durable per-producer watermark rejects reused or overlapping sequence ranges. The ingestion horizon is the longest configured raw/sample/rollup retention window. Batches containing events older than that horizon are rejected, which allows inactive producer watermarks to be removed after their acknowledgements, raw rows, samples, and extraction failures have expired without letting an old retry resurrect a retained aggregate. Retention catches up in 500-row transactions until its work deadline, and also bounds completed maintenance runs, released/expired reader leases, extraction failures, and unreferenced inactive metric definitions. Committed producer drop counters are accumulated transactionally in a fixed target/reason/priority table and exposed in the SQLite target status; duplicate batches never increment them twice.

Node collector hosts run maintenance once at startup and once, within the same absolute shutdown deadline, after producers drain. Regular scheduling remains collector-owned. A cardinality reject marks only that metric/version/ resolution/bucket as durably rejected: it is not query coverage and cannot authorize raw/sample deletion, but it also cannot block other rollups or later retention stages. Unchanged rejections are not recomputed; a late sample invalidates the marker and retries the bucket. Retention keyset-scans beyond protected rows, and due-bucket selection filters current markers before its page limit, so old or rejected buckets cannot starve newer work.

Metric query ranges are half-open and return only buckets fully contained in the requested interval. An unaligned leading or trailing bucket is represented as a partial-bucket coverage gap instead of returning data from outside the range. Historical definition versions are never merged implicitly: overlapping versions are returned as parallel, version-labelled segments, and graph output uses separate version/resolution series.

The Node CLI uses the same bounded query contracts:

telemetry timeline query --config telemetry.config.yml \
  --storage-base /path/to/app-data \
  --label tool.set.resolve.started \
  --from 2026-07-10T10:00:00Z \
  --to 2026-07-10T12:00:00Z

telemetry metrics graph --config telemetry.config.yml \
  --storage-base /path/to/app-data \
  --metric tool_set_resolve_by_conversation \
  --where conversationId=169 \
  --measurement count \
  --resolution 15m \
  --from 2026-07-10T10:00:00Z \
  --to 2026-07-10T12:00:00Z \
  --type line --format svg --output tool-resolves.svg

--where values use JSON primitive typing: 169, true, false, and null remain typed values, while ordinary text remains text. Quote a numeric-looking string as JSON (for example --where 'conversationId="169"'). Repeating a dimension or passing a non-empty JSON array creates a bounded in filter.

Read-only timeline, metric, graph, and guarded SQL commands can query a live SQLite collector through a concurrent WAL reader. Migration and maintenance commands acquire the exclusive telemetry lease and refuse a live collector. See the @noego/telemetry/core, /node/producer, /node, /browser, /electron, /sqlite, /trace-adapter, /cli, and /testing exports for composition.