@nxgt/telemetry 0.1.0 → 0.2.1

package/dist/telemetry/telemetry.d.ts

@@ -0,0 +1,83 @@
+import type { Exporter } from '../export/exporter';
+import type { Resource, Severity, Signal } from '../model/signal';
+import { type Sampler } from '../trace/sampler';
+export interface TelemetryOptions {
+    readonly version?: string;
+    readonly environment?: string;
+    /** Stamped on the resource, so every signal carries them. */
+    readonly attributes?: Readonly<Record<string, unknown>>;
+    /** Asked once, for a root span. Default: `alwaysSample`. */
+    readonly sampler?: Sampler;
+    /** Logs below this are never built. Spans are unaffected. Default `info`. */
+    readonly minimum?: Severity;
+    /** Whether a recorded failure carries its stack. Default true. */
+    readonly stackTraces?: boolean;
+    /** Flush once this many signals are waiting. Default 512. */
+    readonly batch?: number;
+    /** Flush this long after the first signal of a batch, in ms. Default 1000. */
+    readonly linger?: number;
+    /** How long `close` waits for the backlog, in ms. Default 10000. */
+    readonly drainTimeout?: number;
+    /** Default: `console.error`. It must not throw; if it does, it is ignored. */
+    readonly onExportError?: (failure: unknown) => void;
+    /** In order. A batch reaches them one after the other. */
+    readonly exporters?: readonly Exporter[];
+}
+export declare const TELEMETRY_DEFAULTS: Readonly<{
+    minimum: Severity;
+    stackTraces: true;
+    batch: 512;
+    linger: 1000;
+    drainTimeout: 10000;
+}>;
+/**
+ * A service's telemetry: its resource, its sampler, and the pipeline its
+ * signals go through.
+ *
+ * Build it with {@link createTelemetry}. `install()` makes it the one a logger
+ * or a span finds when there is none in scope.
+ */
+export declare class Telemetry {
+    readonly resource: Resource;
+    readonly sampler: Sampler;
+    readonly minimum: Severity;
+    readonly stackTraces: boolean;
+    private readonly pipeline;
+    constructor(options: TelemetryOptions & {
+        readonly service: string;
+    });
+    /** Never blocks, never throws. False once closed. */
+    emit(signal: Signal): boolean;
+    /** The one a logger or a span finds with nothing in scope. Returns itself. */
+    install(): this;
+    /**
+     * Ships the backlog and closes the exporters. **It has to be awaited**:
+     * JavaScript cannot block, so a process that exits without waiting loses
+     * its last batch — which is the batch that explains the shutdown.
+     *
+     * Idempotent, and it stands down as the installed default.
+     */
+    close(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+}
+/**
+ * ```ts
+ * const telemetry = createTelemetry('checkout', {
+ *   environment: 'production',
+ *   sampler: ratioSampler(0.1),
+ *   exporters: [consoleExporter()],
+ * }).install();
+ * ```
+ *
+ * `service` has no default on purpose: it is the key everything groups by, and
+ * a service called `unknown` is a dashboard nobody can read.
+ */
+export declare function createTelemetry(service: string, options?: TelemetryOptions): Telemetry;
+/** The installed default, if `install()` has been called. */
+export declare function installedTelemetry(): Telemetry | undefined;
+/**
+ * Only for a test that needs the process back the way it found it. Production
+ * code stands an instance down by closing it.
+ */
+export declare function uninstallTelemetry(telemetry?: Telemetry): void;
+//# sourceMappingURL=telemetry.d.ts.map

package/dist/telemetry/telemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../../src/telemetry/telemetry.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAEnD,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAClE,OAAO,EAAgB,KAAK,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAE9D,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,6DAA6D;IAC7D,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACxD,4DAA4D;IAC5D,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,6EAA6E;IAC7E,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC;IAC5B,kEAAkE;IAClE,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B,6DAA6D;IAC7D,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,oEAAoE;IACpE,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,8EAA8E;IAC9E,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;IACpD,0DAA0D;IAC1D,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAC;CACzC;AAED,eAAO,MAAM,kBAAkB;aACX,QAAQ;;;;;EAK1B,CAAC;AAIH;;;;;;GAMG;AACH,qBAAa,SAAS;IACrB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAE9B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAW;gBAExB,OAAO,EAAE,gBAAgB,GAAG;QAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE;IAuBpE,qDAAqD;IACrD,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAI7B,8EAA8E;IAC9E,OAAO,IAAI,IAAI;IAKf;;;;;;OAMG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAKtB,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC;CAG5C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAC9B,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,gBAAqB,GAC5B,SAAS,CAEX;AAED,6DAA6D;AAC7D,wBAAgB,kBAAkB,IAAI,SAAS,GAAG,SAAS,CAE1D;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,CAAC,EAAE,SAAS,GAAG,IAAI,CAE9D"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nxgt/telemetry",
-	"version": "0.1.0",
+	"version": "0.2.1",
 	"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",
@@ -50,7 +50,7 @@
 		]
 	},
 	"devDependencies": {
-		"@types/bun": "^1.4.0"
+		"@types/bun": "^1.4.2"
 	},
 	"peerDependencies": {
 		"typescript": "^6.0.3"