@docx-editor.dev/telemetry 0.0.0-stage → 2.29.0

package/dist/otel/index.d.ts

@@ -0,0 +1,57 @@
+/**
+ * OpenTelemetry: metrics and traces through the OpenTelemetry SDK you already run. This entry
+ * depends only on `@opentelemetry/api`; your SDK decides where data goes (OTLP to a
+ * collector, Datadog, Grafana, Honeycomb, New Relic, and others).
+ *
+ * @packageDocumentation
+ */
+import { MeterProvider, TracerProvider, Context } from '@opentelemetry/api';
+import { b as TelemetryExporter } from '../pipeline-DbVW7S-K.js';
+import '@docx-editor.dev/core';
+
+/**
+ * OpenTelemetry: metrics and traces through the OpenTelemetry SDK you already run. This entry
+ * depends only on `@opentelemetry/api`; your SDK decides where data goes (OTLP to a
+ * collector, Datadog, Grafana, Honeycomb, New Relic, and others).
+ *
+ * @packageDocumentation
+ */
+
+/** Options for {@link otelExporter}. @public */
+interface OtelExporterOptions {
+    /** Defaults to the global provider your SDK registered. */
+    readonly meterProvider?: MeterProvider;
+    /** Defaults to the global provider your SDK registered. */
+    readonly tracerProvider?: TracerProvider;
+    /**
+     * The parent of each `docx_editor.document.open` span. Browsers have no async context, so
+     * without this the span is a root span. Return your page-load or route span's context.
+     */
+    readonly parentContext?: () => Context | undefined;
+    /** Instrumentation scope name. Defaults to `@docx-editor.dev/telemetry`. */
+    readonly scope?: string;
+}
+/**
+ * Record metrics and traces with OpenTelemetry. The exporter reads the global providers at
+ * each use, so it can be created before your SDK starts.
+ *
+ * Metrics use the names in `METRICS`. Each document open becomes a
+ * `docx_editor.document.open` span, with an error status when it is refused. Other events
+ * become events on the active span; without one, a failure gets a short span of its own.
+ *
+ * @example
+ * ```ts
+ * import { createTelemetry } from '@docx-editor.dev/telemetry';
+ * import { otelExporter } from '@docx-editor.dev/telemetry/otel';
+ *
+ * // Before or after your OpenTelemetry SDK starts: the exporter reads the global providers at
+ * // each use.
+ * export const telemetry = createTelemetry({ exporters: [otelExporter()] });
+ * ```
+ *
+ * @public
+ */
+declare function otelExporter(options?: OtelExporterOptions): TelemetryExporter;
+
+export { TelemetryExporter, otelExporter };
+export type { OtelExporterOptions };

package/dist/otel/index.js

@@ -0,0 +1 @@
+import {c}from'../chunk-NUN46EXH.js';import {a}from'../chunk-DT2KMPUJ.js';import {SpanStatusCode,trace,metrics}from'@opentelemetry/api';var w="@docx-editor.dev/telemetry";function O(o){let n=o.getDelegate?.()??o;return /^Noop/.test(n?.constructor?.name??"")}var M=false;function E(o,n){let s=a();M||s==="production"||!O(o)||!O(n)||(M=true,console.warn("[docx-editor telemetry] otelExporter found no OpenTelemetry SDK. Register a MeterProvider and a TracerProvider before creating the exporter, or pass them as options. Until then every measurement is dropped."));}function h(o,n,s){return o.createObservableGauge(n.name,{unit:n.unit,description:n.description}).addCallback(t=>{for(let{value:i,attributes:a}of s.values())t.observe(i,a);}),{record(t,i={}){s.set(f(i),{value:t,attributes:i});},forget(t){s.delete(f(t));}}}function f(o){return JSON.stringify(Object.keys(o).sort().map(n=>[n,o[n]]))}function m(o){let n={...o.resource,...o.attributes};for(let[s,t]of Object.entries(o))if(!(s==="resource"||s==="attributes"||s==="hint"||s==="docs")){if(typeof t=="string"||typeof t=="number"||typeof t=="boolean")n[`docx_editor.${s}`]=t;else if(s==="shape"&&t&&typeof t=="object")for(let[i,a]of Object.entries(t))typeof a=="string"&&(n[`docx_editor.shape.${i}`]=a);else if(t&&typeof t=="object"&&!Array.isArray(t))for(let[i,a]of Object.entries(t))typeof a=="number"&&(n[`docx_editor.${s}.${i}`]=a);}return n}function j(o={}){let n=o.scope??w,s=()=>o.meterProvider??metrics.getMeterProvider(),t=()=>o.tracerProvider??trace.getTracerProvider(),i,a,l=new Map,p=new Map,g=false;function P(e){let r=p.get(e);return r||(r=new Map,p.set(e,r)),r}function k(){let e=s();return (e!==i||!a)&&(i=e,a=e.getMeter(n),l.clear()),a}function T(e){let r=k();g||(g=true,setTimeout(()=>E(s(),t()),5e3).unref?.());let c=l.get(e.name);if(c)return c;let d={unit:e.unit,description:e.description},u=e.kind==="counter"?r.createCounter(e.name,d):e.kind==="histogram"?r.createHistogram(e.name,{...d,...e.buckets?{advice:{explicitBucketBoundaries:[...e.buckets]}}:{}}):h(r,e,P(e.name));return l.set(e.name,u),u}return {name:"otel",metric(e){let r=T(e.definition),c=e.attributes;"add"in r?r.add(e.value,c):r.record(e.value,c);},event(e){if(e.kind==="document.open"){let d=e.time-(e.outcome==="opened"?e.durationMs:0),u=t().getTracer(n).startSpan("docx_editor.document.open",{startTime:d,attributes:m(e)},o.parentContext?.());e.outcome==="rejected"&&u.setStatus({code:SpanStatusCode.ERROR,message:e.code}),u.end(e.time);return}let r=trace.getActiveSpan();if(r){r.addEvent(`docx_editor.${e.kind}`,m(e));return}if(!c(e))return;let c$1=t().getTracer(n).startSpan(`docx_editor.${e.kind}`,{startTime:e.time,attributes:m(e)},o.parentContext?.());c$1.setStatus({code:SpanStatusCode.ERROR,message:"code"in e?e.code:e.kind}),c$1.end(e.time);},forget(e,r){p.get(e.name)?.delete(f(r));},async flush(){let e=r=>(r.getDelegate?.()??r).forceFlush?.();await Promise.all([e(s()),e(t())]);}}}export{j as otelExporter};

package/dist/pipeline-DbVW7S-K.d.cts

@@ -0,0 +1,223 @@
+import { EditorDiagnostic } from '@docx-editor.dev/core';
+
+/**
+ * The metric catalog: one definition per metric, in OpenTelemetry terms. Prometheus names are
+ * derived from it mechanically by {@link prometheusName}, so the two outputs cannot drift.
+ *
+ * Every label is a bounded enum. No metric carries a room name, a user, or a document.
+ */
+/** How a metric aggregates. @public */
+type MetricKind = 'counter' | 'gauge' | 'histogram';
+/** One metric in the catalog. @public */
+interface MetricDefinition {
+    /** OpenTelemetry name, such as `docx_editor.collab.room.load.duration`. */
+    readonly name: string;
+    readonly kind: MetricKind;
+    /** UCUM unit as OpenTelemetry writes it: `s`, `By`, `1`, or a `{annotation}`. */
+    readonly unit: string;
+    readonly description: string;
+    /** The label keys this metric may carry. Each value is a bounded enum. */
+    readonly labels: readonly string[];
+    /** Histogram bucket upper bounds, in the metric's unit. */
+    readonly buckets?: readonly number[];
+}
+/**
+ * Every metric the package records.
+ *
+ * @example
+ * ```ts
+ * import { METRICS, prometheusName } from '@docx-editor.dev/telemetry';
+ * prometheusName(METRICS.roomLoadDuration); // 'docx_editor_collab_room_load_duration_seconds'
+ * ```
+ *
+ * @public
+ */
+declare const METRICS: Readonly<{
+    documentOpens: MetricDefinition;
+    documentOpenDuration: MetricDefinition;
+    editRejections: MetricDefinition;
+    reviewSkipped: MetricDefinition;
+    fontFailures: MetricDefinition;
+    historyDiagnostics: MetricDefinition;
+    customNodeDiagnostics: MetricDefinition;
+    collabClientStatusTransitions: MetricDefinition;
+    collabClientConnectDuration: MetricDefinition;
+    collabClientParticipants: MetricDefinition;
+    editorInteractionDuration: MetricDefinition;
+    editorLayoutDuration: MetricDefinition;
+    editorPaintDuration: MetricDefinition;
+    droppedEvents: MetricDefinition;
+    roomsActive: MetricDefinition;
+    connectionsActive: MetricDefinition;
+    participantsActive: MetricDefinition;
+    roomParticipants: MetricDefinition;
+    roomParticipantsMax: MetricDefinition;
+    roomMemory: MetricDefinition;
+    roomsMemory: MetricDefinition;
+    roomNodes: MetricDefinition;
+    roomResourceUsage: MetricDefinition;
+    roomAge: MetricDefinition;
+    roomIdle: MetricDefinition;
+    roomLoadDuration: MetricDefinition;
+    roomStoreDuration: MetricDefinition;
+    admissionRejections: MetricDefinition;
+    messageRefusals: MetricDefinition;
+    updates: MetricDefinition;
+    updateBytes: MetricDefinition;
+    roomParticipantsByRoom: MetricDefinition;
+    roomMemoryByRoom: MetricDefinition;
+    migrations: MetricDefinition;
+}>;
+/** A key of {@link METRICS}. @public */
+type MetricId = keyof typeof METRICS;
+/**
+ * The Prometheus name of a metric: dots become underscores, the unit becomes a suffix, and a
+ * counter ends in `_total`, as the OpenTelemetry Prometheus exporter writes it.
+ *
+ * @example
+ * ```ts
+ * prometheusName(METRICS.editRejections); // 'docx_editor_edit_rejections_total'
+ * prometheusName(METRICS.editorInteractionDuration); // 'docx_editor_editor_interaction_duration_seconds'
+ * ```
+ *
+ * @public
+ */
+declare function prometheusName(definition: MetricDefinition): string;
+
+/**
+ * The shared delivery path: consent, the anonymity guard, and exporters that can never throw
+ * into the code they observe. The editor client and the room server both send through it.
+ */
+
+/** A metric attribute or a resource value. @public */
+type AttributeValue = string | number | boolean;
+/** Attributes or resource values, keyed by name. @public */
+type Attributes = Readonly<Record<string, AttributeValue>>;
+/** Context the package adds to every diagnostic before it reaches an exporter. @public */
+interface TelemetryEventContext {
+    /** The fixed hint for the event's code. A constant, never document content. */
+    readonly hint?: string;
+    /** The documentation section for the event's code. */
+    readonly docs?: string;
+    /** The version of the editor packages. Core and this package release together. */
+    readonly engineVersion: string;
+    /**
+     * Present only on a summary: the event that closes a deduplication window repeats the first
+     * one, with the number of identical events folded into it beyond the first. Count it, do not
+     * treat it as a new failure. Its `time` is the first event's. The Sentry exporter records
+     * summaries as breadcrumbs.
+     */
+    readonly repeated?: number;
+    /**
+     * The host's own values from `createTelemetry({ resource })`, such as `service.name`. The
+     * host decides what goes here, and every event carries it.
+     */
+    readonly resource: Attributes;
+    /**
+     * Your identifiers for this event: the client's `attributes`, then the values of the
+     * `moduleFor` module of the editor that sent it, such as a room, a document, or a user.
+     * Empty when you set none. The engine never adds a value here.
+     */
+    readonly attributes: Attributes;
+}
+/** A diagnostic as an exporter receives it. Switch on `kind` to narrow it. @public */
+type TelemetryEvent = EditorDiagnostic & TelemetryEventContext;
+/** One metric measurement. @public */
+interface MetricRecord {
+    readonly definition: MetricDefinition;
+    /** A counter increment, a gauge value, or a histogram sample, in the metric's unit. */
+    readonly value: number;
+    readonly attributes: Attributes;
+}
+/**
+ * Where telemetry goes. Implement `event`, `metric`, or both.
+ *
+ * An exporter never throws into the editor or the server: a failure is caught and reported
+ * once through `onExporterError`.
+ *
+ * @example
+ * ```ts
+ * const toMyLogger: TelemetryExporter = {
+ *   name: 'my-logger',
+ *   event: (event) => myLogger.warn(event.kind, { code: 'code' in event ? event.code : undefined }),
+ * };
+ * ```
+ *
+ * @public
+ */
+interface TelemetryExporter {
+    /** Shown in `onExporterError` reports. */
+    readonly name: string;
+    event?(event: TelemetryEvent): void;
+    metric?(record: MetricRecord): void;
+    /**
+     * Drop a series that no longer exists, such as a closed room's per-room gauge. Optional:
+     * an exporter without it keeps the series until it expires on its own.
+     */
+    forget?(definition: MetricDefinition, attributes: Attributes): void;
+    /**
+     * Start a series at zero before its first measurement. A scraper that sees a counter first
+     * at 1 cannot count that first increase, so the room server declares its known series when
+     * it starts. Optional: an exporter without it creates each series at its first measurement.
+     */
+    declare?(definition: MetricDefinition, attributes: Attributes): void;
+    /** Send anything buffered. Called by `flush()` and when a page is hidden. */
+    flush?(): void | Promise<void>;
+    /** Flush and release resources. Called by `shutdown()`. */
+    shutdown?(): void | Promise<void>;
+    /**
+     * Called once when a telemetry client or room server takes the exporter. An exporter that
+     * holds events, such as a batching one, reads `consented()` before it sends, so events queued
+     * before consent was withdrawn are discarded, not sent.
+     */
+    attach?(context: TelemetryExporterContext): void;
+}
+/** What a telemetry client tells an exporter it takes. @public */
+interface TelemetryExporterContext {
+    /** Whether the host's consent is given, read now. */
+    consented(): boolean;
+    /**
+     * Whether the page is hidden or closing, read now. While it is, a browser exporter sends with
+     * `sendBeacon` or `keepalive`, which still deliver after the page goes away.
+     */
+    pageClosing(): boolean;
+}
+/** Options shared by the editor client and the room server. @public */
+interface TelemetryPipelineOptions {
+    /** Where telemetry goes. Nothing is recorded or sent without at least one exporter. */
+    readonly exporters: readonly TelemetryExporter[];
+    /**
+     * Whether the viewer agreed to telemetry. Read before each event and metric, so a consent
+     * banner can change it at any time. Events before consent are dropped, not buffered.
+     * Defaults to `true`: without this option, events are sent. Pass it whenever your app asks
+     * for consent.
+     *
+     * @example
+     * ```ts
+     * consent: () => window.cookieConsent?.analytics === true
+     * ```
+     */
+    readonly consent?: boolean | (() => boolean);
+    /**
+     * Values added to every event, such as `{ 'service.name': 'contracts-app' }`. Metrics do not
+     * carry them: set resource attributes on your OpenTelemetry SDK or Prometheus target instead.
+     * You own these values: do not put a user, a document, or a room name here.
+     */
+    readonly resource?: Attributes;
+    /** Told once per exporter when it throws. Defaults to one `console.warn`. */
+    readonly onExporterError?: (error: unknown, exporter: string) => void;
+    /**
+     * Keys of your own attributes that may also label metrics, such as `tenant.tier` or
+     * `app.region`. Only for values with few distinct values: each value makes a new series.
+     * After {@link MAX_METRIC_LABEL_VALUES} distinct values of one key, later values become
+     * `other`. Never list a user, document, or room id here; put those on events instead.
+     */
+    readonly metricLabels?: readonly string[];
+}
+/** Distinct values one of your metric labels may take before later values become `other`. @public */
+declare const MAX_METRIC_LABEL_VALUES = 50;
+/** The version of the editor packages, or `'development'` when running from source. @public */
+declare const ENGINE_VERSION: string;
+
+export { ENGINE_VERSION as E, MAX_METRIC_LABEL_VALUES as d, METRICS as e, prometheusName as p };
+export type { Attributes as A, MetricRecord as M, TelemetryPipelineOptions as T, TelemetryEvent as a, TelemetryExporter as b, AttributeValue as c, MetricDefinition as f, MetricId as g, MetricKind as h, TelemetryEventContext as i, TelemetryExporterContext as j };

package/dist/pipeline-DbVW7S-K.d.ts

@@ -0,0 +1,223 @@
+import { EditorDiagnostic } from '@docx-editor.dev/core';
+
+/**
+ * The metric catalog: one definition per metric, in OpenTelemetry terms. Prometheus names are
+ * derived from it mechanically by {@link prometheusName}, so the two outputs cannot drift.
+ *
+ * Every label is a bounded enum. No metric carries a room name, a user, or a document.
+ */
+/** How a metric aggregates. @public */
+type MetricKind = 'counter' | 'gauge' | 'histogram';
+/** One metric in the catalog. @public */
+interface MetricDefinition {
+    /** OpenTelemetry name, such as `docx_editor.collab.room.load.duration`. */
+    readonly name: string;
+    readonly kind: MetricKind;
+    /** UCUM unit as OpenTelemetry writes it: `s`, `By`, `1`, or a `{annotation}`. */
+    readonly unit: string;
+    readonly description: string;
+    /** The label keys this metric may carry. Each value is a bounded enum. */
+    readonly labels: readonly string[];
+    /** Histogram bucket upper bounds, in the metric's unit. */
+    readonly buckets?: readonly number[];
+}
+/**
+ * Every metric the package records.
+ *
+ * @example
+ * ```ts
+ * import { METRICS, prometheusName } from '@docx-editor.dev/telemetry';
+ * prometheusName(METRICS.roomLoadDuration); // 'docx_editor_collab_room_load_duration_seconds'
+ * ```
+ *
+ * @public
+ */
+declare const METRICS: Readonly<{
+    documentOpens: MetricDefinition;
+    documentOpenDuration: MetricDefinition;
+    editRejections: MetricDefinition;
+    reviewSkipped: MetricDefinition;
+    fontFailures: MetricDefinition;
+    historyDiagnostics: MetricDefinition;
+    customNodeDiagnostics: MetricDefinition;
+    collabClientStatusTransitions: MetricDefinition;
+    collabClientConnectDuration: MetricDefinition;
+    collabClientParticipants: MetricDefinition;
+    editorInteractionDuration: MetricDefinition;
+    editorLayoutDuration: MetricDefinition;
+    editorPaintDuration: MetricDefinition;
+    droppedEvents: MetricDefinition;
+    roomsActive: MetricDefinition;
+    connectionsActive: MetricDefinition;
+    participantsActive: MetricDefinition;
+    roomParticipants: MetricDefinition;
+    roomParticipantsMax: MetricDefinition;
+    roomMemory: MetricDefinition;
+    roomsMemory: MetricDefinition;
+    roomNodes: MetricDefinition;
+    roomResourceUsage: MetricDefinition;
+    roomAge: MetricDefinition;
+    roomIdle: MetricDefinition;
+    roomLoadDuration: MetricDefinition;
+    roomStoreDuration: MetricDefinition;
+    admissionRejections: MetricDefinition;
+    messageRefusals: MetricDefinition;
+    updates: MetricDefinition;
+    updateBytes: MetricDefinition;
+    roomParticipantsByRoom: MetricDefinition;
+    roomMemoryByRoom: MetricDefinition;
+    migrations: MetricDefinition;
+}>;
+/** A key of {@link METRICS}. @public */
+type MetricId = keyof typeof METRICS;
+/**
+ * The Prometheus name of a metric: dots become underscores, the unit becomes a suffix, and a
+ * counter ends in `_total`, as the OpenTelemetry Prometheus exporter writes it.
+ *
+ * @example
+ * ```ts
+ * prometheusName(METRICS.editRejections); // 'docx_editor_edit_rejections_total'
+ * prometheusName(METRICS.editorInteractionDuration); // 'docx_editor_editor_interaction_duration_seconds'
+ * ```
+ *
+ * @public
+ */
+declare function prometheusName(definition: MetricDefinition): string;
+
+/**
+ * The shared delivery path: consent, the anonymity guard, and exporters that can never throw
+ * into the code they observe. The editor client and the room server both send through it.
+ */
+
+/** A metric attribute or a resource value. @public */
+type AttributeValue = string | number | boolean;
+/** Attributes or resource values, keyed by name. @public */
+type Attributes = Readonly<Record<string, AttributeValue>>;
+/** Context the package adds to every diagnostic before it reaches an exporter. @public */
+interface TelemetryEventContext {
+    /** The fixed hint for the event's code. A constant, never document content. */
+    readonly hint?: string;
+    /** The documentation section for the event's code. */
+    readonly docs?: string;
+    /** The version of the editor packages. Core and this package release together. */
+    readonly engineVersion: string;
+    /**
+     * Present only on a summary: the event that closes a deduplication window repeats the first
+     * one, with the number of identical events folded into it beyond the first. Count it, do not
+     * treat it as a new failure. Its `time` is the first event's. The Sentry exporter records
+     * summaries as breadcrumbs.
+     */
+    readonly repeated?: number;
+    /**
+     * The host's own values from `createTelemetry({ resource })`, such as `service.name`. The
+     * host decides what goes here, and every event carries it.
+     */
+    readonly resource: Attributes;
+    /**
+     * Your identifiers for this event: the client's `attributes`, then the values of the
+     * `moduleFor` module of the editor that sent it, such as a room, a document, or a user.
+     * Empty when you set none. The engine never adds a value here.
+     */
+    readonly attributes: Attributes;
+}
+/** A diagnostic as an exporter receives it. Switch on `kind` to narrow it. @public */
+type TelemetryEvent = EditorDiagnostic & TelemetryEventContext;
+/** One metric measurement. @public */
+interface MetricRecord {
+    readonly definition: MetricDefinition;
+    /** A counter increment, a gauge value, or a histogram sample, in the metric's unit. */
+    readonly value: number;
+    readonly attributes: Attributes;
+}
+/**
+ * Where telemetry goes. Implement `event`, `metric`, or both.
+ *
+ * An exporter never throws into the editor or the server: a failure is caught and reported
+ * once through `onExporterError`.
+ *
+ * @example
+ * ```ts
+ * const toMyLogger: TelemetryExporter = {
+ *   name: 'my-logger',
+ *   event: (event) => myLogger.warn(event.kind, { code: 'code' in event ? event.code : undefined }),
+ * };
+ * ```
+ *
+ * @public
+ */
+interface TelemetryExporter {
+    /** Shown in `onExporterError` reports. */
+    readonly name: string;
+    event?(event: TelemetryEvent): void;
+    metric?(record: MetricRecord): void;
+    /**
+     * Drop a series that no longer exists, such as a closed room's per-room gauge. Optional:
+     * an exporter without it keeps the series until it expires on its own.
+     */
+    forget?(definition: MetricDefinition, attributes: Attributes): void;
+    /**
+     * Start a series at zero before its first measurement. A scraper that sees a counter first
+     * at 1 cannot count that first increase, so the room server declares its known series when
+     * it starts. Optional: an exporter without it creates each series at its first measurement.
+     */
+    declare?(definition: MetricDefinition, attributes: Attributes): void;
+    /** Send anything buffered. Called by `flush()` and when a page is hidden. */
+    flush?(): void | Promise<void>;
+    /** Flush and release resources. Called by `shutdown()`. */
+    shutdown?(): void | Promise<void>;
+    /**
+     * Called once when a telemetry client or room server takes the exporter. An exporter that
+     * holds events, such as a batching one, reads `consented()` before it sends, so events queued
+     * before consent was withdrawn are discarded, not sent.
+     */
+    attach?(context: TelemetryExporterContext): void;
+}
+/** What a telemetry client tells an exporter it takes. @public */
+interface TelemetryExporterContext {
+    /** Whether the host's consent is given, read now. */
+    consented(): boolean;
+    /**
+     * Whether the page is hidden or closing, read now. While it is, a browser exporter sends with
+     * `sendBeacon` or `keepalive`, which still deliver after the page goes away.
+     */
+    pageClosing(): boolean;
+}
+/** Options shared by the editor client and the room server. @public */
+interface TelemetryPipelineOptions {
+    /** Where telemetry goes. Nothing is recorded or sent without at least one exporter. */
+    readonly exporters: readonly TelemetryExporter[];
+    /**
+     * Whether the viewer agreed to telemetry. Read before each event and metric, so a consent
+     * banner can change it at any time. Events before consent are dropped, not buffered.
+     * Defaults to `true`: without this option, events are sent. Pass it whenever your app asks
+     * for consent.
+     *
+     * @example
+     * ```ts
+     * consent: () => window.cookieConsent?.analytics === true
+     * ```
+     */
+    readonly consent?: boolean | (() => boolean);
+    /**
+     * Values added to every event, such as `{ 'service.name': 'contracts-app' }`. Metrics do not
+     * carry them: set resource attributes on your OpenTelemetry SDK or Prometheus target instead.
+     * You own these values: do not put a user, a document, or a room name here.
+     */
+    readonly resource?: Attributes;
+    /** Told once per exporter when it throws. Defaults to one `console.warn`. */
+    readonly onExporterError?: (error: unknown, exporter: string) => void;
+    /**
+     * Keys of your own attributes that may also label metrics, such as `tenant.tier` or
+     * `app.region`. Only for values with few distinct values: each value makes a new series.
+     * After {@link MAX_METRIC_LABEL_VALUES} distinct values of one key, later values become
+     * `other`. Never list a user, document, or room id here; put those on events instead.
+     */
+    readonly metricLabels?: readonly string[];
+}
+/** Distinct values one of your metric labels may take before later values become `other`. @public */
+declare const MAX_METRIC_LABEL_VALUES = 50;
+/** The version of the editor packages, or `'development'` when running from source. @public */
+declare const ENGINE_VERSION: string;
+
+export { ENGINE_VERSION as E, MAX_METRIC_LABEL_VALUES as d, METRICS as e, prometheusName as p };
+export type { Attributes as A, MetricRecord as M, TelemetryPipelineOptions as T, TelemetryEvent as a, TelemetryExporter as b, AttributeValue as c, MetricDefinition as f, MetricId as g, MetricKind as h, TelemetryEventContext as i, TelemetryExporterContext as j };

package/dist/prometheus/index.cjs

@@ -0,0 +1 @@
+'use strict';var chunkMJX3ECH3_cjs=require('../chunk-MJX3ECH3.cjs');require('../chunk-LGNT4I5W.cjs');Object.defineProperty(exports,"PROMETHEUS_CONTENT_TYPE",{enumerable:true,get:function(){return chunkMJX3ECH3_cjs.a}});Object.defineProperty(exports,"fetchMetricsHandler",{enumerable:true,get:function(){return chunkMJX3ECH3_cjs.d}});Object.defineProperty(exports,"metricsHandler",{enumerable:true,get:function(){return chunkMJX3ECH3_cjs.c}});Object.defineProperty(exports,"prometheusRegistry",{enumerable:true,get:function(){return chunkMJX3ECH3_cjs.b}});

package/dist/prometheus/index.d.cts

@@ -0,0 +1,88 @@
+/**
+ * Prometheus: an in-process registry in the text exposition format, and `/metrics` handlers for
+ * Node-style servers ({@link metricsHandler}) and Fetch-style servers
+ * ({@link fetchMetricsHandler}). No dependency on `prom-client`; a `prom-client` registry
+ * merges into the same endpoint.
+ *
+ * @packageDocumentation
+ */
+import { b as TelemetryExporter } from '../pipeline-DbVW7S-K.cjs';
+import '@docx-editor.dev/core';
+
+/** The Prometheus text exposition content type. @public */
+declare const PROMETHEUS_CONTENT_TYPE = "text/plain; version=0.0.4; charset=utf-8";
+/** Anything that renders Prometheus text, such as a `prom-client` `Registry`. @public */
+interface PrometheusTextSource {
+    metrics(): string | Promise<string>;
+}
+/** The exporter returned by {@link prometheusRegistry}. @public */
+interface PrometheusRegistry extends TelemetryExporter, PrometheusTextSource {
+    /** Every recorded metric in the Prometheus text format. */
+    metrics(): string;
+    /** Forget every recorded value. */
+    reset(): void;
+}
+/**
+ * Collect metrics in memory and render them for Prometheus to scrape.
+ *
+ * @example
+ * ```ts
+ * import { prometheusRegistry, metricsHandler } from '@docx-editor.dev/telemetry/prometheus';
+ *
+ * const metrics = prometheusRegistry();
+ * // Pass `metrics` as an exporter, then serve it:
+ * app.get('/metrics', metricsHandler(metrics));
+ * ```
+ *
+ * @public
+ */
+declare function prometheusRegistry(): PrometheusRegistry;
+/** The part of a Node `ServerResponse` the handler writes to. @public */
+interface NodeResponseLike {
+    setHeader(name: string, value: string): unknown;
+    end(body: string): unknown;
+    statusCode?: number;
+}
+/** Options for {@link metricsHandler} and {@link fetchMetricsHandler}. @public */
+interface MetricsHandlerOptions {
+    /**
+     * More sources rendered into the same response, such as your `prom-client` registry:
+     * `merge: [register]`.
+     */
+    readonly merge?: readonly PrometheusTextSource[];
+}
+/**
+ * A Node-style handler, `(request, response)`, for Node `http`, Express, and Koa
+ * (`ctx.res`). For Fastify, hijack the reply and pass `reply.raw`. For Fetch-style servers,
+ * use {@link fetchMetricsHandler}. Protect the route as you protect other operational
+ * endpoints.
+ *
+ * @example
+ * ```ts
+ * app.get('/metrics', metricsHandler(metrics, { merge: [promClient.register] })); // Express
+ *
+ * fastify.get('/metrics', (request, reply) => {
+ *   reply.hijack();
+ *   return metricsHandler(metrics)(request.raw, reply.raw);
+ * });
+ * ```
+ *
+ * @public
+ */
+declare function metricsHandler(registry: PrometheusTextSource, options?: MetricsHandlerOptions): (request: unknown, response: NodeResponseLike) => Promise<void>;
+/**
+ * A Fetch-style handler that returns a `Response`, for Next.js route handlers, Hono, Bun,
+ * Deno, and workers. It ignores its argument, so a Hono context works as well as a `Request`.
+ *
+ * @example
+ * ```ts
+ * // app/metrics/route.ts
+ * export const GET = fetchMetricsHandler(metrics);
+ * ```
+ *
+ * @public
+ */
+declare function fetchMetricsHandler(registry: PrometheusTextSource, options?: MetricsHandlerOptions): (request?: unknown) => Promise<Response>;
+
+export { PROMETHEUS_CONTENT_TYPE, TelemetryExporter, fetchMetricsHandler, metricsHandler, prometheusRegistry };
+export type { MetricsHandlerOptions, NodeResponseLike, PrometheusRegistry, PrometheusTextSource };