@astroscope/node 2.1.1 → 3.0.0

package/dist/telemetry-B9aziFyQ.js

@@ -0,0 +1,202 @@
+import { maybeThen } from "@entwico/dash";
+import { SpanStatusCode, ValueType, context, createNoopMeter, metrics, trace } from "@opentelemetry/api";
+//#region src/observability/telemetry/gauges.ts
+/**
+* Gauges have no "first use" to bind on: their callback must be registered on
+* a real meter, and a meter obtained before the SDK started is a no-op
+* forever. A creation that lands on the no-op meter is parked here and retried
+* by the SDK right after `sdk.start()`. Keyed on `globalThis` so the
+* vite-runner and native module instances share one list.
+*/
+const STORE_KEY = Symbol.for("@astroscope/node/telemetry.gauges");
+function getPending() {
+	const g = globalThis;
+	let pending = g[STORE_KEY];
+	if (!pending) {
+		pending = [];
+		g[STORE_KEY] = pending;
+	}
+	return pending;
+}
+function registerGauge(bind) {
+	if (!bind()) getPending().push(bind);
+}
+function bindGauges() {
+	const pending = getPending();
+	for (const bind of pending.splice(0)) if (!bind()) pending.push(bind);
+}
+//#endregion
+//#region src/observability/telemetry/telemetry.ts
+/**
+* The telemetry seam for the astroscope packages — internal api, not for app
+* code (which uses `@opentelemetry/api` against the same SDK). Instruments
+* bind to the SDK meter lazily (a meter obtained before `startTelemetry()` is
+* a no-op forever, so a handle keeps trying until a real meter answers),
+* names, units and buckets have one owner, and no package needs its own
+* `@opentelemetry/api` copy. Without a started SDK — dev by default, or
+* `telemetry: false` — every call resolves to the api's no-op implementation.
+* @internal
+*/
+const DEFAULT_SCOPE = "@astroscope/node";
+const noopMeter = createNoopMeter();
+const NOOP_HISTOGRAM = noopMeter.createHistogram("noop");
+const NOOP_COUNTER = noopMeter.createCounter("noop");
+const NOOP_UP_DOWN_COUNTER = noopMeter.createUpDownCounter("noop");
+const NOOP_OBSERVABLE_GAUGE = noopMeter.createObservableGauge("noop");
+/**
+* Bucket boundaries in seconds for the three kinds of durations the platform
+* measures: `http` is the semconv set for server requests, `io` covers one
+* outbound call (1 ms – 2.5 s), `compute` a synchronous render (10 µs – 50 ms).
+*/
+const DURATION_BUCKETS = {
+	http: [
+		.005,
+		.01,
+		.025,
+		.05,
+		.075,
+		.1,
+		.25,
+		.5,
+		.75,
+		1,
+		2.5,
+		5,
+		7.5,
+		10
+	],
+	io: [
+		.001,
+		.0025,
+		.005,
+		.01,
+		.025,
+		.05,
+		.1,
+		.25,
+		.5,
+		1,
+		2.5
+	],
+	compute: [
+		1e-5,
+		5e-5,
+		1e-4,
+		25e-5,
+		5e-4,
+		.001,
+		.0025,
+		.005,
+		.01,
+		.05
+	]
+};
+function getMeter(options) {
+	return metrics.getMeter(options.scope ?? DEFAULT_SCOPE);
+}
+function describe(options) {
+	return {
+		...options.description && { description: options.description },
+		...options.unit && { unit: options.unit }
+	};
+}
+function bindLazily(create, noop) {
+	let instrument;
+	return () => {
+		if (instrument === void 0) {
+			const created = create();
+			if (created === noop) return;
+			instrument = created;
+		}
+		return instrument;
+	};
+}
+function createHistogram(name, options) {
+	const bound = bindLazily(() => getMeter(options).createHistogram(name, {
+		...describe(options),
+		valueType: ValueType.DOUBLE,
+		advice: { explicitBucketBoundaries: [...options.buckets] }
+	}), NOOP_HISTOGRAM);
+	return { record: (value, attributes) => bound()?.record(value, attributes) };
+}
+function createCounter(name, options = {}) {
+	const bound = bindLazily(() => getMeter(options).createCounter(name, {
+		...describe(options),
+		valueType: ValueType.INT
+	}), NOOP_COUNTER);
+	return { add: (value, attributes) => bound()?.add(value, attributes) };
+}
+function createUpDownCounter(name, options = {}) {
+	const bound = bindLazily(() => getMeter(options).createUpDownCounter(name, {
+		...describe(options),
+		valueType: ValueType.INT
+	}), NOOP_UP_DOWN_COUNTER);
+	return { add: (value, attributes) => bound()?.add(value, attributes) };
+}
+/**
+* An asynchronous gauge: `observe` runs at every collection (the Prometheus
+* scrape) and reports the current values. Registered with the SDK when it
+* starts, so calling this at module level is fine.
+*/
+function createObservableGauge(name, options, observe) {
+	registerGauge(() => {
+		const gauge = getMeter(options).createObservableGauge(name, {
+			...describe(options),
+			valueType: ValueType.DOUBLE
+		});
+		if (gauge === NOOP_OBSERVABLE_GAUGE) return false;
+		gauge.addCallback((result) => observe({ observe: (value, attributes) => result.observe(value, attributes) }));
+		return true;
+	});
+}
+/** the `error.type` attribute value for a thrown value: the error's class, else its type */
+function errorType(error) {
+	if (error instanceof Error) return error.constructor.name || error.name || "Error";
+	return typeof error;
+}
+/** starts a span the caller ends itself; `withSpan` for work that is one function */
+function startSpan(name, options = {}) {
+	const parent = options.parent ?? context.active();
+	const span = trace.getTracer(options.scope ?? DEFAULT_SCOPE).startSpan(name, {
+		...options.attributes && { attributes: options.attributes },
+		...options.kind !== void 0 && { kind: options.kind }
+	}, parent);
+	return {
+		span,
+		context: trace.setSpan(parent, span)
+	};
+}
+function endSpan(span, error, failed) {
+	if (failed) span.setStatus({
+		code: SpanStatusCode.ERROR,
+		message: error instanceof Error ? error.message : "unknown error"
+	});
+	else span.setStatus({ code: SpanStatusCode.OK });
+	span.end();
+}
+/**
+* Runs `fn` inside a span: status from the outcome, the span active for
+* everything `fn` awaits. A synchronous `fn` stays synchronous — no promise
+* is allocated on the common path.
+*/
+function withSpan(name, options, fn) {
+	const { span, context: spanContext } = startSpan(name, options);
+	let result;
+	try {
+		result = context.with(spanContext, fn);
+	} catch (error) {
+		endSpan(span, error, true);
+		throw error;
+	}
+	return maybeThen(result, (value) => {
+		endSpan(span, void 0, false);
+		return value;
+	}, (error) => {
+		endSpan(span, error, true);
+		throw error;
+	});
+}
+//#endregion
+export { createUpDownCounter as a, withSpan as c, createObservableGauge as i, bindGauges as l, createCounter as n, errorType as o, createHistogram as r, startSpan as s, DURATION_BUCKETS as t };
+
+//# sourceMappingURL=telemetry-B9aziFyQ.js.map

package/dist/telemetry-B9aziFyQ.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry-B9aziFyQ.js","names":[],"sources":["../src/observability/telemetry/gauges.ts","../src/observability/telemetry/telemetry.ts"],"sourcesContent":["/**\n * Gauges have no \"first use\" to bind on: their callback must be registered on\n * a real meter, and a meter obtained before the SDK started is a no-op\n * forever. A creation that lands on the no-op meter is parked here and retried\n * by the SDK right after `sdk.start()`. Keyed on `globalThis` so the\n * vite-runner and native module instances share one list.\n */\n\nconst STORE_KEY = Symbol.for('@astroscope/node/telemetry.gauges');\n\n/** returns whether the instrument bound to a real meter */\ntype Bind = () => boolean;\n\nfunction getPending(): Bind[] {\n  const g = globalThis as Record<symbol, unknown>;\n  let pending = g[STORE_KEY] as Bind[] | undefined;\n\n  if (!pending) {\n    pending = [];\n    g[STORE_KEY] = pending;\n  }\n\n  return pending;\n}\n\nexport function registerGauge(bind: Bind): void {\n  if (!bind()) {\n    getPending().push(bind);\n  }\n}\n\nexport function bindGauges(): void {\n  const pending = getPending();\n\n  for (const bind of pending.splice(0)) {\n    if (!bind()) {\n      pending.push(bind);\n    }\n  }\n}\n","import { type MaybePromise, maybeThen } from '@entwico/dash';\nimport {\n  type Attributes,\n  type Context,\n  type Counter,\n  type Histogram,\n  type Meter,\n  type Span,\n  type SpanKind,\n  SpanStatusCode,\n  type UpDownCounter,\n  ValueType,\n  context,\n  createNoopMeter,\n  metrics,\n  trace,\n} from '@opentelemetry/api';\nimport { registerGauge } from './gauges.js';\n\n/**\n * The telemetry seam for the astroscope packages — internal api, not for app\n * code (which uses `@opentelemetry/api` against the same SDK). Instruments\n * bind to the SDK meter lazily (a meter obtained before `startTelemetry()` is\n * a no-op forever, so a handle keeps trying until a real meter answers),\n * names, units and buckets have one owner, and no package needs its own\n * `@opentelemetry/api` copy. Without a started SDK — dev by default, or\n * `telemetry: false` — every call resolves to the api's no-op implementation.\n * @internal\n */\n\nconst DEFAULT_SCOPE = '@astroscope/node';\n\n// the no-op meter hands out singletons — the tell for \"no SDK registered yet\"\nconst noopMeter = createNoopMeter();\nconst NOOP_HISTOGRAM = noopMeter.createHistogram('noop');\nconst NOOP_COUNTER = noopMeter.createCounter('noop');\nconst NOOP_UP_DOWN_COUNTER = noopMeter.createUpDownCounter('noop');\nconst NOOP_OBSERVABLE_GAUGE = noopMeter.createObservableGauge('noop');\n\nexport interface InstrumentOptions {\n  /** instrumentation scope, `@astroscope/<package>`; defaults to `@astroscope/node` */\n  scope?: string | undefined;\n  description?: string | undefined;\n  /** UCUM unit, e.g. `s`, `{request}` */\n  unit?: string | undefined;\n}\n\nexport interface HistogramOptions extends InstrumentOptions {\n  /** explicit bucket boundaries; the SDK default set starts at 5, useless for seconds */\n  buckets: readonly number[];\n}\n\nexport interface HistogramHandle {\n  record(value: number, attributes?: Attributes | undefined): void;\n}\n\nexport interface CounterHandle {\n  add(value: number, attributes?: Attributes | undefined): void;\n}\n\n/** what an observable gauge callback reports: one value per attribute set */\nexport interface ObservableHandle {\n  observe(value: number, attributes?: Attributes | undefined): void;\n}\n\n/**\n * Bucket boundaries in seconds for the three kinds of durations the platform\n * measures: `http` is the semconv set for server requests, `io` covers one\n * outbound call (1 ms – 2.5 s), `compute` a synchronous render (10 µs – 50 ms).\n */\nexport const DURATION_BUCKETS = {\n  http: [0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10],\n  io: [0.001, 0.0025, 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5],\n  compute: [0.00001, 0.00005, 0.0001, 0.00025, 0.0005, 0.001, 0.0025, 0.005, 0.01, 0.05],\n} as const satisfies Record<string, readonly number[]>;\n\nfunction getMeter(options: InstrumentOptions): Meter {\n  return metrics.getMeter(options.scope ?? DEFAULT_SCOPE);\n}\n\nfunction describe(options: InstrumentOptions): { description?: string; unit?: string } {\n  return {\n    ...(options.description && { description: options.description }),\n    ...(options.unit && { unit: options.unit }),\n  };\n}\n\n// binds on first use after a real meter is registered; until then every use\n// creates a no-op instrument and drops the value\nfunction bindLazily<T>(create: () => T, noop: T): () => T | undefined {\n  let instrument: T | undefined;\n\n  return () => {\n    if (instrument === undefined) {\n      const created = create();\n\n      if (created === noop) {\n        return undefined;\n      }\n\n      instrument = created;\n    }\n\n    return instrument;\n  };\n}\n\nexport function createHistogram(name: string, options: HistogramOptions): HistogramHandle {\n  const bound = bindLazily<Histogram>(\n    () =>\n      getMeter(options).createHistogram(name, {\n        ...describe(options),\n        valueType: ValueType.DOUBLE,\n        advice: { explicitBucketBoundaries: [...options.buckets] },\n      }),\n    NOOP_HISTOGRAM,\n  );\n\n  return { record: (value, attributes) => bound()?.record(value, attributes) };\n}\n\nexport function createCounter(name: string, options: InstrumentOptions = {}): CounterHandle {\n  const bound = bindLazily<Counter>(\n    () => getMeter(options).createCounter(name, { ...describe(options), valueType: ValueType.INT }),\n    NOOP_COUNTER,\n  );\n\n  return { add: (value, attributes) => bound()?.add(value, attributes) };\n}\n\nexport function createUpDownCounter(name: string, options: InstrumentOptions = {}): CounterHandle {\n  const bound = bindLazily<UpDownCounter>(\n    () => getMeter(options).createUpDownCounter(name, { ...describe(options), valueType: ValueType.INT }),\n    NOOP_UP_DOWN_COUNTER,\n  );\n\n  return { add: (value, attributes) => bound()?.add(value, attributes) };\n}\n\n/**\n * An asynchronous gauge: `observe` runs at every collection (the Prometheus\n * scrape) and reports the current values. Registered with the SDK when it\n * starts, so calling this at module level is fine.\n */\nexport function createObservableGauge(\n  name: string,\n  options: InstrumentOptions,\n  observe: (result: ObservableHandle) => void,\n): void {\n  registerGauge(() => {\n    const gauge = getMeter(options).createObservableGauge(name, { ...describe(options), valueType: ValueType.DOUBLE });\n\n    if (gauge === NOOP_OBSERVABLE_GAUGE) {\n      return false;\n    }\n\n    gauge.addCallback((result) => observe({ observe: (value, attributes) => result.observe(value, attributes) }));\n\n    return true;\n  });\n}\n\n/** the `error.type` attribute value for a thrown value: the error's class, else its type */\nexport function errorType(error: unknown): string {\n  if (error instanceof Error) {\n    return error.constructor.name || error.name || 'Error';\n  }\n\n  return typeof error;\n}\n\nexport interface SpanOptions {\n  /** instrumentation scope, `@astroscope/<package>`; defaults to `@astroscope/node` */\n  scope?: string | undefined;\n  attributes?: Attributes | undefined;\n  kind?: SpanKind | undefined;\n  /** parent context; defaults to the active one (the request span inside a request) */\n  parent?: Context | undefined;\n}\n\nexport interface StartedSpan {\n  span: Span;\n  /** the context with `span` active — pass as `parent` to nest children */\n  context: Context;\n}\n\n/** starts a span the caller ends itself; `withSpan` for work that is one function */\nexport function startSpan(name: string, options: SpanOptions = {}): StartedSpan {\n  const parent = options.parent ?? context.active();\n  const span = trace.getTracer(options.scope ?? DEFAULT_SCOPE).startSpan(\n    name,\n    {\n      ...(options.attributes && { attributes: options.attributes }),\n      ...(options.kind !== undefined && { kind: options.kind }),\n    },\n    parent,\n  );\n\n  return { span, context: trace.setSpan(parent, span) };\n}\n\nfunction endSpan(span: Span, error: unknown, failed: boolean): void {\n  if (failed) {\n    span.setStatus({ code: SpanStatusCode.ERROR, message: error instanceof Error ? error.message : 'unknown error' });\n  } else {\n    span.setStatus({ code: SpanStatusCode.OK });\n  }\n\n  span.end();\n}\n\n/**\n * Runs `fn` inside a span: status from the outcome, the span active for\n * everything `fn` awaits. A synchronous `fn` stays synchronous — no promise\n * is allocated on the common path.\n */\nexport function withSpan<T>(name: string, options: SpanOptions, fn: () => MaybePromise<T>): MaybePromise<T> {\n  const { span, context: spanContext } = startSpan(name, options);\n  let result: MaybePromise<T>;\n\n  try {\n    result = context.with(spanContext, fn);\n  } catch (error) {\n    endSpan(span, error, true);\n\n    throw error;\n  }\n\n  return maybeThen(\n    result,\n    (value) => {\n      endSpan(span, undefined, false);\n\n      return value;\n    },\n    (error: unknown) => {\n      endSpan(span, error, true);\n\n      throw error;\n    },\n  );\n}\n"],"mappings":"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"}

package/dist/telemetry.d.ts

@@ -0,0 +1,68 @@
+import { MaybePromise } from "@entwico/dash";
+import { Attributes, Context, Span, SpanKind } from "@opentelemetry/api";
+//#region src/observability/telemetry/telemetry.d.ts
+export interface InstrumentOptions {
+  /** instrumentation scope, `@astroscope/<package>`; defaults to `@astroscope/node` */
+  scope?: string | undefined;
+  description?: string | undefined;
+  /** UCUM unit, e.g. `s`, `{request}` */
+  unit?: string | undefined;
+}
+export interface HistogramOptions extends InstrumentOptions {
+  /** explicit bucket boundaries; the SDK default set starts at 5, useless for seconds */
+  buckets: readonly number[];
+}
+export interface HistogramHandle {
+  record(value: number, attributes?: Attributes | undefined): void;
+}
+export interface CounterHandle {
+  add(value: number, attributes?: Attributes | undefined): void;
+}
+/** what an observable gauge callback reports: one value per attribute set */
+export interface ObservableHandle {
+  observe(value: number, attributes?: Attributes | undefined): void;
+}
+/**
+ * Bucket boundaries in seconds for the three kinds of durations the platform
+ * measures: `http` is the semconv set for server requests, `io` covers one
+ * outbound call (1 ms – 2.5 s), `compute` a synchronous render (10 µs – 50 ms).
+ */
+export declare const DURATION_BUCKETS: {
+  readonly http: readonly [0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10];
+  readonly io: readonly [0.001, 0.0025, 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5];
+  readonly compute: readonly [0.00001, 0.00005, 0.0001, 0.00025, 0.0005, 0.001, 0.0025, 0.005, 0.01, 0.05];
+};
+export declare function createHistogram(name: string, options: HistogramOptions): HistogramHandle;
+export declare function createCounter(name: string, options?: InstrumentOptions): CounterHandle;
+export declare function createUpDownCounter(name: string, options?: InstrumentOptions): CounterHandle;
+/**
+ * An asynchronous gauge: `observe` runs at every collection (the Prometheus
+ * scrape) and reports the current values. Registered with the SDK when it
+ * starts, so calling this at module level is fine.
+ */
+export declare function createObservableGauge(name: string, options: InstrumentOptions, observe: (result: ObservableHandle) => void): void;
+/** the `error.type` attribute value for a thrown value: the error's class, else its type */
+export declare function errorType(error: unknown): string;
+export interface SpanOptions {
+  /** instrumentation scope, `@astroscope/<package>`; defaults to `@astroscope/node` */
+  scope?: string | undefined;
+  attributes?: Attributes | undefined;
+  kind?: SpanKind | undefined;
+  /** parent context; defaults to the active one (the request span inside a request) */
+  parent?: Context | undefined;
+}
+export interface StartedSpan {
+  span: Span;
+  /** the context with `span` active — pass as `parent` to nest children */
+  context: Context;
+}
+/** starts a span the caller ends itself; `withSpan` for work that is one function */
+export declare function startSpan(name: string, options?: SpanOptions): StartedSpan;
+/**
+ * Runs `fn` inside a span: status from the outcome, the span active for
+ * everything `fn` awaits. A synchronous `fn` stays synchronous — no promise
+ * is allocated on the common path.
+ */
+export declare function withSpan<T>(name: string, options: SpanOptions, fn: () => MaybePromise<T>): MaybePromise<T>;
+//#endregion
+//# sourceMappingURL=telemetry.d.ts.map

package/dist/telemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.d.ts","names":[],"sources":["../src/observability/telemetry/telemetry.ts"],"mappings":";;;iBAuCiB;;EAEf;EACA;;EAEA;;iBAGe,yBAAyB;;EAExC;;iBAGe;EACf,OAAO,eAAe,aAAa;;iBAGpB;EACf,IAAI,eAAe,aAAa;;;iBAIjB;EACf,QAAQ,eAAe,aAAa;;;;;;;qBAQzB;;;;;wBAqCG,gBAAgB,cAAc,SAAS,mBAAmB;wBAc1D,cAAc,cAAc,UAAS,oBAAyB;wBAS9D,oBAAoB,cAAc,UAAS,oBAAyB;;;;;;wBAcpE,sBACd,cACA,SAAS,mBACT,UAAU,QAAQ;;wBAgBJ,UAAU;iBAQT;;EAEf;EACA,aAAa;EACb,OAAO;;EAEP,SAAS;;iBAGM;EACf,MAAM;;EAEN,SAAS;;;wBAIK,UAAU,cAAc,UAAS,cAAmB;;;;;;wBA6BpD,SAAS,GAAG,cAAc,SAAS,aAAa,UAAU,aAAa,KAAK,aAAa"}

package/dist/telemetry.js

@@ -0,0 +1,2 @@
+import { a as createUpDownCounter, c as withSpan, i as createObservableGauge, n as createCounter, o as errorType, r as createHistogram, s as startSpan, t as DURATION_BUCKETS } from "./telemetry-B9aziFyQ.js";
+export { DURATION_BUCKETS, createCounter, createHistogram, createObservableGauge, createUpDownCounter, errorType, startSpan, withSpan };