camusdb 0.6.0 → 0.8.0

package/dist/telemetry.d.ts

@@ -0,0 +1,199 @@
+/**
+ * This file is part of CamusDB
+ *
+ * For the full copyright and license information, please view the LICENSE.txt
+ * file that was distributed with this source code.
+ */
+/**
+ * Traces and metrics through `@opentelemetry/api`.
+ *
+ * The package is an optional peer dependency, as the gRPC packages are. When it is installed, the
+ * driver reports through the global tracer and meter that it names `camusdb`. When it is not
+ * installed, every function here returns at once and the driver reports nothing. Install an
+ * OpenTelemetry SDK and register it as usual to collect the data. The driver needs no plugin.
+ *
+ * The span and metric names and attributes are those of the .NET driver, and they follow the
+ * OpenTelemetry database conventions. See the README for the list.
+ */
+/** The instrumentation scope that the driver's tracer and meter report under. */
+export declare const CAMUS_TELEMETRY_NAME = "camusdb";
+/** The `camusdb.retry.kind` values: what the driver sent again. */
+export declare const CamusRetryKind: {
+    /** A commit or a rollback sent again after `CADB0509`. */
+    readonly Finalize: "finalize";
+    /** A unit of work of `withRetry` run again after a serializable conflict. */
+    readonly Autocommit: "autocommit";
+    /** A unit of work of `client.transaction` run again, from `BEGIN`, after a serializable conflict. */
+    readonly Transaction: "transaction";
+    /** A call sent again with a new token after the server refused the old one. */
+    readonly TokenRenewal: "token_renewal";
+    /** A `CREATE DATABASE` or a branch creation sent again after a transient failure. */
+    readonly CreateDatabase: "create_database";
+};
+export type CamusRetryKind = (typeof CamusRetryKind)[keyof typeof CamusRetryKind];
+/** The `camusdb.prepared_statement.result` values. */
+export declare const PreparedResult: {
+    readonly Hit: "hit";
+    readonly Registered: "registered";
+    readonly Miss: "miss";
+    readonly Success: "success";
+    readonly Refused: "refused";
+    readonly Unsupported: "unsupported";
+};
+type AttributeValue = string | number | boolean;
+type Attributes = Record<string, AttributeValue | undefined>;
+interface OtelSpan {
+    isRecording(): boolean;
+    setAttribute(key: string, value: AttributeValue): unknown;
+    setStatus(status: {
+        code: number;
+        message?: string;
+    }): unknown;
+    recordException(exception: unknown): void;
+    addEvent(name: string, attributes?: Attributes): unknown;
+    end(): void;
+}
+interface OtelTracer {
+    startSpan(name: string, options?: {
+        kind?: number;
+        attributes?: Attributes;
+    }, context?: unknown): OtelSpan;
+}
+interface OtelObservableResult {
+    observe(value: number, attributes?: Attributes): void;
+}
+interface OtelObservable {
+    addCallback(callback: (result: OtelObservableResult) => void): void;
+}
+interface OtelInstrumentOptions {
+    description?: string;
+    unit?: string;
+    advice?: {
+        explicitBucketBoundaries?: number[];
+    };
+}
+interface OtelMeter {
+    createHistogram(name: string, options?: OtelInstrumentOptions): {
+        record(value: number, attributes?: Attributes): void;
+    };
+    createCounter(name: string, options?: OtelInstrumentOptions): {
+        add(value: number, attributes?: Attributes): void;
+    };
+    createObservableGauge(name: string, options?: OtelInstrumentOptions): OtelObservable;
+    createObservableUpDownCounter(name: string, options?: OtelInstrumentOptions): OtelObservable;
+}
+/** @internal The subset of `@opentelemetry/api` the driver uses. */
+export interface OtelApi {
+    readonly trace: {
+        getTracer(name: string, version?: string): OtelTracer;
+        setSpan(context: unknown, span: OtelSpan): unknown;
+        getActiveSpan(): OtelSpan | undefined;
+    };
+    readonly context: {
+        active(): unknown;
+        with<T>(context: unknown, fn: () => T): T;
+    };
+    readonly metrics: {
+        getMeterProvider(): unknown;
+        getMeter(name: string, version?: string): OtelMeter;
+    };
+    readonly SpanKind: {
+        readonly CLIENT: number;
+    };
+    readonly SpanStatusCode: {
+        readonly ERROR: number;
+    };
+}
+/**
+ * @internal Test hook: replaces the API, or with `null` plays a process without the package.
+ * `undefined` loads it again on the next operation.
+ */
+export declare function setTelemetryApi(replacement: OtelApi | null | undefined): void;
+/** What an operation reads from the client it runs for. `ClientRuntime` has this shape. */
+export interface TelemetryScope {
+    readonly database: string;
+    readonly config: {
+        readonly protocol: string;
+        readonly traceQueryText: boolean;
+    };
+}
+/** What one operation reports about itself. */
+export interface OperationInit {
+    /** `SELECT`, `BEGIN`, `BATCH`, and so on. See `operationName`. */
+    readonly operationName?: string | undefined;
+    /** The table, when the driver knows it without a parse of the SQL text. */
+    readonly collection?: string | undefined;
+    /** The SQL text. It goes on the span only with `traceQueryText`. */
+    readonly queryText?: string | undefined;
+    /** The statement count of a pipeline exchange. */
+    readonly batchSize?: number | undefined;
+}
+/**
+ * One instrumented operation: its span, and its start time for the duration histogram.
+ *
+ * It ends once. The first `complete` or `fail` ends it, and later calls do nothing.
+ */
+export declare class CamusOperation {
+    private readonly otel;
+    private readonly span;
+    private readonly startedAt;
+    private readonly database;
+    private readonly operationName;
+    private ended;
+    private serverAddress;
+    private serverPort;
+    /** @internal Use `startOperation`. */
+    constructor(otel: OtelApi, span: OtelSpan, startedAt: number, database: string, operationName: string | undefined);
+    /** Records the server the operation goes to, as `server.address` and `server.port`. */
+    setEndpoint(endpoint: string): void;
+    setAttribute(key: string, value: AttributeValue): void;
+    /**
+     * Runs `fn` with this operation's span as the active span, so the HTTP or gRPC spans of the
+     * transport are its children.
+     */
+    run<T>(fn: () => T): T;
+    /** Adds a `camusdb.retry` event to this operation's span. */
+    addRetryEvent(kind: CamusRetryKind, errorType: string | undefined): void;
+    /** Ends the operation as a success. */
+    complete(): void;
+    /** Ends the operation as a failure. */
+    fail(error: unknown): void;
+    private end;
+}
+/**
+ * Starts an operation, or reports `undefined` when `@opentelemetry/api` is not installed.
+ *
+ * The span is a child of the active span. Its name is `{operation} {target}`, where the target is
+ * the table when it is known, and the database if not.
+ */
+export declare function startOperation(scope: TelemetryScope, init: OperationInit): CamusOperation | undefined;
+/**
+ * Runs one operation under a span, and ends the span with the operation's outcome.
+ *
+ * Without `@opentelemetry/api`, it only calls `run`.
+ */
+export declare function traced<T>(scope: TelemetryScope, init: OperationInit, run: (operation: CamusOperation | undefined) => Promise<T>): Promise<T>;
+/**
+ * The operation name of a statement: its first keyword in upper case when that keyword is a known
+ * verb, and `undefined` if not. Leading white space and opening parentheses are skipped.
+ */
+export declare function operationName(sql: string): string | undefined;
+/**
+ * Counts one retry, and adds a `camusdb.retry` event to the driver span of the operation, or to the
+ * active span when it is one of the driver's.
+ */
+export declare function recordRetry(kind: CamusRetryKind, error: unknown, details?: {
+    database?: string;
+    operationName?: string;
+    operation?: CamusOperation | undefined;
+}): void;
+/** Counts one endpoint set aside after a transport failure. */
+export declare function recordQuarantine(endpoint: string): void;
+/** Counts one execution of a preparable statement: `hit`, `registered`, or `miss`. */
+export declare function recordPreparedLookup(database: string, result: string): void;
+/** Counts one request to prepare a statement: `success`, `refused`, or `unsupported`. */
+export declare function recordPreparedRegistration(database: string, result: string, error?: unknown): void;
+/** Counts one prepared statement released to make room for one used more recently. */
+export declare function recordPreparedEviction(database: string): void;
+export {};
+//# sourceMappingURL=telemetry.d.ts.map

package/dist/telemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../src/telemetry.ts"],"names":[],"mappings":"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"}

package/dist/telemetry.js

@@ -0,0 +1,423 @@
+/**
+ * This file is part of CamusDB
+ *
+ * For the full copyright and license information, please view the LICENSE.txt
+ * file that was distributed with this source code.
+ */
+import { createRequire } from 'node:module';
+import { CamusEndpointPool } from './endpoint-pool.js';
+import { CamusError } from './errors.js';
+import { CamusPreparedStatementPolicy } from './prepared/policy.js';
+/**
+ * Traces and metrics through `@opentelemetry/api`.
+ *
+ * The package is an optional peer dependency, as the gRPC packages are. When it is installed, the
+ * driver reports through the global tracer and meter that it names `camusdb`. When it is not
+ * installed, every function here returns at once and the driver reports nothing. Install an
+ * OpenTelemetry SDK and register it as usual to collect the data. The driver needs no plugin.
+ *
+ * The span and metric names and attributes are those of the .NET driver, and they follow the
+ * OpenTelemetry database conventions. See the README for the list.
+ */
+/** The instrumentation scope that the driver's tracer and meter report under. */
+export const CAMUS_TELEMETRY_NAME = 'camusdb';
+/** The `db.system.name` of every span and measurement. */
+const SYSTEM_NAME = 'camusdb';
+/** The `camusdb.retry.kind` values: what the driver sent again. */
+export const CamusRetryKind = {
+    /** A commit or a rollback sent again after `CADB0509`. */
+    Finalize: 'finalize',
+    /** A unit of work of `withRetry` run again after a serializable conflict. */
+    Autocommit: 'autocommit',
+    /** A unit of work of `client.transaction` run again, from `BEGIN`, after a serializable conflict. */
+    Transaction: 'transaction',
+    /** A call sent again with a new token after the server refused the old one. */
+    TokenRenewal: 'token_renewal',
+    /** A `CREATE DATABASE` or a branch creation sent again after a transient failure. */
+    CreateDatabase: 'create_database',
+};
+/** The `camusdb.prepared_statement.result` values. */
+export const PreparedResult = {
+    Hit: 'hit',
+    Registered: 'registered',
+    Miss: 'miss',
+    Success: 'success',
+    Refused: 'refused',
+    Unsupported: 'unsupported',
+};
+// ─── Loading ────────────────────────────────────────────────────────────────
+/** `undefined` until the first try, `null` when the package is not installed. */
+let loadedApi;
+let packageVersion;
+/**
+ * The API, or `undefined` when the package is not installed.
+ *
+ * It is loaded with `require`, so the first operation is instrumented too: a dynamic `import` would
+ * leave every operation before it settles without a span. The API keeps its registrations in a
+ * process-wide global, so the copy that `require` loads sees the SDK that an ES module registered.
+ */
+function api() {
+    if (loadedApi === undefined) {
+        const require = createRequire(import.meta.url);
+        try {
+            loadedApi = require('@opentelemetry/api');
+        }
+        catch {
+            loadedApi = null;
+        }
+        try {
+            packageVersion = require('../package.json').version;
+        }
+        catch {
+            packageVersion = undefined;
+        }
+    }
+    return loadedApi ?? undefined;
+}
+/**
+ * @internal Test hook: replaces the API, or with `null` plays a process without the package.
+ * `undefined` loads it again on the next operation.
+ */
+export function setTelemetryApi(replacement) {
+    loadedApi = replacement;
+    tracer = undefined;
+    instruments = undefined;
+}
+let tracer;
+/** The global tracer. The API hands out a proxy, so a provider registered later still gets the spans. */
+function tracerFor(otel) {
+    if (tracer?.api !== otel)
+        tracer = { api: otel, tracer: otel.trace.getTracer(CAMUS_TELEMETRY_NAME, packageVersion) };
+    return tracer.tracer;
+}
+let instruments;
+/**
+ * The instruments, made on the meter of the current global provider.
+ *
+ * The metrics API has no proxy provider, so an instrument made before the SDK registered stays a
+ * no-op for good. The instruments are made again whenever the global provider changes.
+ */
+function instrumentsFor(otel) {
+    const provider = otel.metrics.getMeterProvider();
+    if (instruments?.api === otel && instruments.provider === provider)
+        return instruments;
+    const meter = otel.metrics.getMeter(CAMUS_TELEMETRY_NAME, packageVersion);
+    const quarantined = meter.createObservableGauge('camusdb.client.endpoint.quarantined', {
+        unit: '{endpoint}',
+        description: '1 while the endpoint is set aside after a transport failure, 0 while it takes traffic.',
+    });
+    quarantined.addCallback((result) => {
+        for (const [endpoint, isQuarantined] of CamusEndpointPool.collectQuarantine()) {
+            result.observe(isQuarantined ? 1 : 0, endpointAttributes(endpoint));
+        }
+    });
+    const preparedCount = meter.createObservableUpDownCounter('camusdb.client.prepared_statement.count', {
+        unit: '{statement}',
+        description: 'Statements kept prepared now.',
+    });
+    preparedCount.addCallback((result) => {
+        for (const [database, count] of CamusPreparedStatementPolicy.collectPreparedCounts()) {
+            result.observe(count, { 'db.namespace': database });
+        }
+    });
+    instruments = {
+        api: otel,
+        provider,
+        duration: meter.createHistogram('db.client.operation.duration', {
+            unit: 's',
+            description: 'Duration of database client operations.',
+            advice: { explicitBucketBoundaries: [0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1, 5, 10] },
+        }),
+        retries: meter.createCounter('camusdb.client.operation.retries', {
+            unit: '{retry}',
+            description: 'Operations the driver sent again after a failure it knows to be safe to retry.',
+        }),
+        quarantines: meter.createCounter('camusdb.client.endpoint.quarantines', {
+            unit: '{quarantine}',
+            description: 'Times an endpoint failed at the transport level and was set aside for 30 seconds.',
+        }),
+        lookups: meter.createCounter('camusdb.client.prepared_statement.lookups', {
+            unit: '{lookup}',
+            description: 'Executions of a preparable statement, by whether the statement went as a prepared handle.',
+        }),
+        registrations: meter.createCounter('camusdb.client.prepared_statement.registrations', {
+            unit: '{registration}',
+            description: 'Requests to the server to prepare a statement.',
+        }),
+        evictions: meter.createCounter('camusdb.client.prepared_statement.evictions', {
+            unit: '{eviction}',
+            description: 'Prepared statements released to make room for a statement used more recently.',
+        }),
+    };
+    return instruments;
+}
+/** The spans this driver started, so a retry adds its event only to one of them. */
+const ownSpans = new WeakSet();
+/**
+ * One instrumented operation: its span, and its start time for the duration histogram.
+ *
+ * It ends once. The first `complete` or `fail` ends it, and later calls do nothing.
+ */
+export class CamusOperation {
+    otel;
+    span;
+    startedAt;
+    database;
+    operationName;
+    ended = false;
+    serverAddress;
+    serverPort = 0;
+    /** @internal Use `startOperation`. */
+    constructor(otel, span, startedAt, database, operationName) {
+        this.otel = otel;
+        this.span = span;
+        this.startedAt = startedAt;
+        this.database = database;
+        this.operationName = operationName;
+    }
+    /** Records the server the operation goes to, as `server.address` and `server.port`. */
+    setEndpoint(endpoint) {
+        const { host, port } = parseEndpoint(endpoint);
+        this.serverAddress = host;
+        this.serverPort = port;
+        if (this.span.isRecording()) {
+            this.span.setAttribute('server.address', host);
+            if (port > 0)
+                this.span.setAttribute('server.port', port);
+        }
+    }
+    setAttribute(key, value) {
+        if (this.span.isRecording())
+            this.span.setAttribute(key, value);
+    }
+    /**
+     * Runs `fn` with this operation's span as the active span, so the HTTP or gRPC spans of the
+     * transport are its children.
+     */
+    run(fn) {
+        return this.otel.context.with(this.otel.trace.setSpan(this.otel.context.active(), this.span), fn);
+    }
+    /** Adds a `camusdb.retry` event to this operation's span. */
+    addRetryEvent(kind, errorType) {
+        this.span.addEvent('camusdb.retry', defined({ 'camusdb.retry.kind': kind, 'error.type': errorType }));
+    }
+    /** Ends the operation as a success. */
+    complete() {
+        this.end(undefined, false);
+    }
+    /** Ends the operation as a failure. */
+    fail(error) {
+        this.end(error, true);
+    }
+    end(error, failed) {
+        if (this.ended)
+            return;
+        this.ended = true;
+        // The conventions use the database status code as the error type when there is one.
+        const statusCode = failed && CamusError.is(error) ? error.code : undefined;
+        const errorType = failed ? (statusCode ?? errorTypeName(error)) : undefined;
+        if (failed) {
+            if (this.span.isRecording()) {
+                this.span.setAttribute('error.type', errorType);
+                if (statusCode !== undefined)
+                    this.span.setAttribute('db.response.status_code', statusCode);
+                this.span.recordException(error instanceof Error ? error : String(error));
+            }
+            this.span.setStatus({
+                code: this.otel.SpanStatusCode.ERROR,
+                message: error instanceof Error ? error.message : String(error),
+            });
+        }
+        this.span.end();
+        instrumentsFor(this.otel).duration.record((performance.now() - this.startedAt) / 1000, defined({
+            'db.system.name': SYSTEM_NAME,
+            'db.namespace': this.database,
+            'db.operation.name': this.operationName,
+            'server.address': this.serverAddress,
+            'server.port': this.serverPort > 0 ? this.serverPort : undefined,
+            'error.type': errorType,
+            'db.response.status_code': statusCode,
+        }));
+    }
+}
+/**
+ * Starts an operation, or reports `undefined` when `@opentelemetry/api` is not installed.
+ *
+ * The span is a child of the active span. Its name is `{operation} {target}`, where the target is
+ * the table when it is known, and the database if not.
+ */
+export function startOperation(scope, init) {
+    const otel = api();
+    if (otel === undefined)
+        return undefined;
+    const database = scope.database;
+    const target = init.collection ?? database;
+    const name = init.operationName === undefined ? target : `${init.operationName} ${target}`;
+    const span = tracerFor(otel).startSpan(name, { kind: otel.SpanKind.CLIENT }, otel.context.active());
+    ownSpans.add(span);
+    if (span.isRecording()) {
+        span.setAttribute('db.system.name', SYSTEM_NAME);
+        span.setAttribute('db.namespace', database);
+        if (init.operationName !== undefined)
+            span.setAttribute('db.operation.name', init.operationName);
+        if (init.collection !== undefined)
+            span.setAttribute('db.collection.name', init.collection);
+        if (init.batchSize !== undefined && init.batchSize > 0) {
+            span.setAttribute('db.operation.batch.size', init.batchSize);
+        }
+        if (init.queryText !== undefined && scope.config.traceQueryText) {
+            span.setAttribute('db.query.text', init.queryText);
+        }
+        span.setAttribute('camusdb.transport', scope.config.protocol);
+    }
+    return new CamusOperation(otel, span, performance.now(), database, init.operationName);
+}
+/**
+ * Runs one operation under a span, and ends the span with the operation's outcome.
+ *
+ * Without `@opentelemetry/api`, it only calls `run`.
+ */
+export async function traced(scope, init, run) {
+    const operation = startOperation(scope, init);
+    if (operation === undefined)
+        return run(undefined);
+    try {
+        const result = await operation.run(() => run(operation));
+        operation.complete();
+        return result;
+    }
+    catch (error) {
+        operation.fail(error);
+        throw error;
+    }
+}
+/**
+ * The statement verbs that become `db.operation.name`. A first keyword that is not in this list
+ * gives no operation name, so the metric keeps a small set of values.
+ */
+const KNOWN_OPERATIONS = new Set([
+    'SELECT',
+    'INSERT',
+    'UPDATE',
+    'DELETE',
+    'CREATE',
+    'ALTER',
+    'DROP',
+    'TRUNCATE',
+    'EXPLAIN',
+    'SHOW',
+    'REFRESH',
+    'COMMENT',
+    'GRANT',
+    'REVOKE',
+    'SET',
+    'CALL',
+]);
+/**
+ * The operation name of a statement: its first keyword in upper case when that keyword is a known
+ * verb, and `undefined` if not. Leading white space and opening parentheses are skipped.
+ */
+export function operationName(sql) {
+    const match = /^[\s(]*([A-Za-z]+)/.exec(sql);
+    const keyword = match?.[1]?.toUpperCase();
+    return keyword !== undefined && KNOWN_OPERATIONS.has(keyword) ? keyword : undefined;
+}
+// ─── Driver metrics ─────────────────────────────────────────────────────────
+/**
+ * Counts one retry, and adds a `camusdb.retry` event to the driver span of the operation, or to the
+ * active span when it is one of the driver's.
+ */
+export function recordRetry(kind, error, details = {}) {
+    const otel = api();
+    if (otel === undefined)
+        return;
+    const errorType = CamusError.is(error) ? error.code : errorTypeName(error);
+    if (details.operation !== undefined) {
+        details.operation.addRetryEvent(kind, errorType);
+    }
+    else {
+        const active = otel.trace.getActiveSpan();
+        if (active !== undefined && ownSpans.has(active)) {
+            active.addEvent('camusdb.retry', defined({ 'camusdb.retry.kind': kind, 'error.type': errorType }));
+        }
+    }
+    instrumentsFor(otel).retries.add(1, defined({
+        'camusdb.retry.kind': kind,
+        'error.type': errorType,
+        'db.namespace': details.database,
+        'db.operation.name': details.operationName,
+    }));
+}
+/** Counts one endpoint set aside after a transport failure. */
+export function recordQuarantine(endpoint) {
+    const otel = api();
+    if (otel === undefined)
+        return;
+    instrumentsFor(otel).quarantines.add(1, endpointAttributes(endpoint));
+}
+/** Counts one execution of a preparable statement: `hit`, `registered`, or `miss`. */
+export function recordPreparedLookup(database, result) {
+    const otel = api();
+    if (otel === undefined)
+        return;
+    instrumentsFor(otel).lookups.add(1, {
+        'db.namespace': database,
+        'camusdb.prepared_statement.result': result,
+    });
+}
+/** Counts one request to prepare a statement: `success`, `refused`, or `unsupported`. */
+export function recordPreparedRegistration(database, result, error) {
+    const otel = api();
+    if (otel === undefined)
+        return;
+    instrumentsFor(otel).registrations.add(1, defined({
+        'db.namespace': database,
+        'camusdb.prepared_statement.result': result,
+        'error.type': error === undefined ? undefined : CamusError.is(error) ? error.code : errorTypeName(error),
+    }));
+}
+/** Counts one prepared statement released to make room for one used more recently. */
+export function recordPreparedEviction(database) {
+    const otel = api();
+    if (otel === undefined)
+        return;
+    instrumentsFor(otel).evictions.add(1, { 'db.namespace': database });
+}
+// ─── Helpers ────────────────────────────────────────────────────────────────
+/** The parsed host and port of each endpoint. Endpoints come from configuration, so the map stays small. */
+const parsedEndpoints = new Map();
+function parseEndpoint(endpoint) {
+    let parsed = parsedEndpoints.get(endpoint);
+    if (parsed === undefined) {
+        try {
+            const url = new URL(endpoint);
+            const port = url.port.length > 0 ? Number(url.port) : url.protocol === 'https:' ? 443 : 80;
+            parsed = { host: url.hostname, port };
+        }
+        catch {
+            parsed = { host: endpoint, port: 0 };
+        }
+        if (parsedEndpoints.size < 1024)
+            parsedEndpoints.set(endpoint, parsed);
+    }
+    return parsed;
+}
+function endpointAttributes(endpoint) {
+    const { host, port } = parseEndpoint(endpoint);
+    return port > 0 ? { 'server.address': host, 'server.port': port } : { 'server.address': host };
+}
+/** The attributes without the keys whose value is unknown. The SDK warns about an `undefined` value. */
+function defined(attributes) {
+    const result = {};
+    for (const [key, value] of Object.entries(attributes)) {
+        if (value !== undefined)
+            result[key] = value;
+    }
+    return result;
+}
+function errorTypeName(error) {
+    if (error instanceof Error)
+        return error.name.length > 0 ? error.name : 'Error';
+    return '_OTHER';
+}
+//# sourceMappingURL=telemetry.js.map

package/dist/telemetry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.js","sourceRoot":"","sources":["../src/telemetry.ts"],"names":[],"mappings":"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"}