@qlever-llc/trellis 0.10.11 → 0.10.12

package/esm/telemetry/core.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../src/telemetry/core.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,OAAO,EACZ,OAAO,EACP,KAAK,IAAI,EACT,QAAQ,EACR,cAAc,EACd,KAAK,EACL,KAAK,MAAM,EACZ,MAAM,oBAAoB,CAAC;AAE5B,wBAAgB,SAAS,CAAC,KAAK,SAAgC,GAAG,MAAM,CAEvE;AAED,wBAAgB,aAAa,IAAI,IAAI,GAAG,SAAS,CAEhD;AAED,wBAAgB,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAEtD;AAED,wBAAsB,aAAa,CAAC,CAAC,EACnC,IAAI,EAAE,IAAI,EACV,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CAEZ;AAED,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC;AACpD,YAAY,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC"}
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../src/telemetry/core.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,OAAO,EACZ,OAAO,EACP,KAAK,IAAI,EACT,QAAQ,EACR,cAAc,EACd,KAAK,EACL,KAAK,MAAM,EACZ,MAAM,oBAAoB,CAAC;AAE5B,wBAAgB,SAAS,CAAC,KAAK,SAAkC,GAAG,MAAM,CAEzE;AAED,wBAAgB,aAAa,IAAI,IAAI,GAAG,SAAS,CAEhD;AAED,wBAAgB,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAEtD;AAED,wBAAsB,aAAa,CAAC,CAAC,EACnC,IAAI,EAAE,IAAI,EACV,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CAEZ;AAED,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC;AACpD,YAAY,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC"}

package/esm/telemetry/core.js

@@ -1,5 +1,5 @@
 import { context, SpanKind, SpanStatusCode, trace, } from "@opentelemetry/api";
-export function getTracer(scope = "@qlever-llc/trellis/tracing") {
+export function getTracer(scope = "@qlever-llc/trellis/telemetry") {
     return trace.getTracer(scope);
 }
 export function getActiveSpan() {

package/esm/telemetry/env.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../src/telemetry/env.ts"],"names":[],"mappings":"AAYA,wBAAgB,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAUtD"}
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../src/telemetry/env.ts"],"names":[],"mappings":"AAYA,wBAAgB,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CActD"}

package/esm/telemetry/env.js

@@ -3,7 +3,12 @@ import * as dntShim from "../_dnt.shims.js";
 export function getEnv(key) {
     const deno = dntShim.dntGlobalThis;
     if (deno.Deno?.env?.get) {
-        return deno.Deno.env.get(key);
+        try {
+            return deno.Deno.env.get(key);
+        }
+        catch {
+            return undefined;
+        }
     }
     const processGlobal = dntShim.dntGlobalThis;
     return processGlobal.process?.env?.[key];

package/esm/telemetry/init.d.ts

@@ -0,0 +1,3 @@
+/** Initializes Trellis telemetry for a service runtime. */
+export declare function initTelemetry(serviceName: string): void;
+//# sourceMappingURL=init.d.ts.map

package/esm/telemetry/init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/telemetry/init.ts"],"names":[],"mappings":"AAGA,2DAA2D;AAC3D,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAGvD"}

package/esm/telemetry/init.js

@@ -0,0 +1,7 @@
+import { configureErrorTraceId } from "./result.js";
+import { initTelemetryRuntime } from "./runtime.js";
+/** Initializes Trellis telemetry for a service runtime. */
+export function initTelemetry(serviceName) {
+    configureErrorTraceId();
+    initTelemetryRuntime(serviceName);
+}

package/esm/telemetry/metrics.d.ts

@@ -0,0 +1,34 @@
+import { type Meter } from "@opentelemetry/api";
+/** Low-cardinality attributes accepted by {@link recordTrellisError}. */
+export type TrellisErrorMetricAttributes = {
+    /** Stable Trellis surface name, such as `rpc`, `jobs`, or `operations`. */
+    surface?: string;
+    /** Stable flow direction such as `client`, `server`, `publish`, or `consume`. */
+    direction?: string;
+    /** Stable operation kind or method name. Do not pass IDs, subjects, or URLs. */
+    operation?: string;
+    /** Stable lifecycle phase such as `encode`, `send`, `auth`, or `handler`. */
+    phase?: string;
+    /** Stable local Trellis error type override when the thrown value does not expose one. */
+    errorType?: string;
+    /** Stable wrapped remote Trellis error type override. */
+    remoteErrorType?: string;
+    /** Stable auth failure reason, such as `missing_session_key`. */
+    authReason?: string;
+    /** Static messaging system name, when already known. */
+    messagingSystem?: string;
+    /** Static messaging operation name, when already known. */
+    messagingOperation?: string;
+};
+/** Returns the shared Trellis OpenTelemetry meter. */
+export declare function getTrellisMeter(): Meter;
+/** Records one Trellis error with only stable, low-cardinality attributes. */
+export declare function recordTrellisError(error: unknown, attributes?: TrellisErrorMetricAttributes): void;
+/**
+ * Builds sanitized, low-cardinality attributes for `trellis.errors`.
+ *
+ * @internal Exported for focused tests; runtime callers should use
+ * {@link recordTrellisError}.
+ */
+export declare function buildTrellisErrorMetricAttributes(error: unknown, attributes?: TrellisErrorMetricAttributes): Record<string, string>;
+//# sourceMappingURL=metrics.d.ts.map

package/esm/telemetry/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../src/telemetry/metrics.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,KAAK,EAAW,MAAM,oBAAoB,CAAC;AAiDzD,yEAAyE;AACzE,MAAM,MAAM,4BAA4B,GAAG;IACzC,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iFAAiF;IACjF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gFAAgF;IAChF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0FAA0F;IAC1F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,iEAAiE;IACjE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wDAAwD;IACxD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,2DAA2D;IAC3D,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B,CAAC;AASF,sDAAsD;AACtD,wBAAgB,eAAe,IAAI,KAAK,CAEvC;AAED,8EAA8E;AAC9E,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,OAAO,EACd,UAAU,GAAE,4BAAiC,GAC5C,IAAI,CAWN;AAED;;;;;GAKG;AACH,wBAAgB,iCAAiC,CAC/C,KAAK,EAAE,OAAO,EACd,UAAU,GAAE,4BAAiC,GAC5C,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAsDxB"}

package/esm/telemetry/metrics.js

@@ -0,0 +1,181 @@
+import { metrics } from "@opentelemetry/api";
+const TRELLIS_METER_NAME = "@qlever-llc/trellis";
+const MAX_ATTRIBUTE_LENGTH = 96;
+const LOW_CARDINALITY_PATTERN = /^[A-Za-z0-9_.:-]+$/;
+const UUID_PATTERN = /(^|[_.:-])[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}($|[_.:-])/i;
+const ULID_PATTERN = /(^|[_.:-])[0-7][0-9A-HJKMNP-TV-Z]{25}($|[_.:-])/i;
+const LONG_HEX_SEGMENT_PATTERN = /(^|[_.:-])[0-9a-f]{12,}($|[_.:-])/i;
+const TRELLIS_SUBJECT_PREFIX_PATTERN = /^(rpc|events|feeds|operations|jobs|state|kv|store|resources|transfer)\.v\d+\./;
+const AUTH_REASONS = new Set([
+    "invalid_request",
+    "missing_session_key",
+    "missing_proof",
+    "session_not_found",
+    "session_expired",
+    "invalid_signature",
+    "user_not_found",
+    "user_already_exists",
+    "username_taken",
+    "identity_already_exists",
+    "identity_not_found",
+    "user_inactive",
+    "unknown_device",
+    "device_deployment_not_found",
+    "device_deployment_disabled",
+    "device_activation_revoked",
+    "unknown_service",
+    "service_disabled",
+    "iat_out_of_range",
+    "invalid_binding_token",
+    "session_corrupted",
+    "session_already_bound",
+    "authtoken_already_used",
+    "oauth_session_key_mismatch",
+    "reply_subject_mismatch",
+    "insufficient_permissions",
+    "forbidden",
+    "last_admin_required",
+    "missing_flow_id",
+    "device_activation_flow_not_found",
+    "device_activation_flow_expired",
+    "device_activation_rejected",
+    "device_identity_key_mismatch",
+    "invalid_device_qr_mac",
+]);
+/** Returns the shared Trellis OpenTelemetry meter. */
+export function getTrellisMeter() {
+    return metrics.getMeter(TRELLIS_METER_NAME);
+}
+/** Records one Trellis error with only stable, low-cardinality attributes. */
+export function recordTrellisError(error, attributes = {}) {
+    getTrellisMeter().createCounter("trellis.errors", {
+        description: "Trellis errors observed by runtime instrumentation.",
+        unit: "{error}",
+    }).add(1, buildTrellisErrorMetricAttributes(error, attributes));
+}
+/**
+ * Builds sanitized, low-cardinality attributes for `trellis.errors`.
+ *
+ * @internal Exported for focused tests; runtime callers should use
+ * {@link recordTrellisError}.
+ */
+export function buildTrellisErrorMetricAttributes(error, attributes = {}) {
+    const serializable = serializableErrorData(error);
+    const metricAttributes = {
+        "exception.type": exceptionType(error),
+        "trellis.error.type": trellisErrorType(error, serializable, attributes.errorType),
+    };
+    const remoteErrorType = lowCardinalityValue(attributes.remoteErrorType) ??
+        remoteSerializableErrorType(serializable);
+    if (remoteErrorType) {
+        metricAttributes["trellis.remote_error.type"] = remoteErrorType;
+    }
+    setLowCardinalityAttribute(metricAttributes, "trellis.surface", attributes.surface);
+    setLowCardinalityAttribute(metricAttributes, "trellis.direction", attributes.direction);
+    setLowCardinalityAttribute(metricAttributes, "trellis.operation", attributes.operation);
+    setLowCardinalityAttribute(metricAttributes, "trellis.phase", attributes.phase);
+    setLowCardinalityAttribute(metricAttributes, "trellis.auth.reason", boundedAuthReason(attributes.authReason) ?? authReason(serializable));
+    setLowCardinalityAttribute(metricAttributes, "messaging.system", attributes.messagingSystem);
+    setLowCardinalityAttribute(metricAttributes, "messaging.operation", attributes.messagingOperation);
+    return metricAttributes;
+}
+function trellisErrorType(error, serializable, override) {
+    const overrideType = lowCardinalityValue(override);
+    if (overrideType)
+        return overrideType;
+    const serializableType = lowCardinalityValue(serializable?.type);
+    if (serializableType)
+        return serializableType;
+    const objectType = objectStringProperty(error, "type");
+    if (objectType)
+        return objectType;
+    return exceptionType(error);
+}
+function exceptionType(error) {
+    if (error instanceof Error) {
+        const name = lowCardinalityValue(error.name);
+        if (name)
+            return name;
+    }
+    const objectType = objectStringProperty(error, "type");
+    if (objectType)
+        return objectType;
+    return "unknown";
+}
+function serializableErrorData(error) {
+    const toSerializable = safeProperty(error, "toSerializable");
+    if (!isSerializableMethod(toSerializable))
+        return undefined;
+    try {
+        const data = toSerializable.call(error);
+        return isRecord(data) ? data : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function remoteSerializableErrorType(serializable) {
+    const remoteError = safeProperty(serializable, "remoteError");
+    if (!isRecord(remoteError))
+        return undefined;
+    return objectStringProperty(remoteError, "type");
+}
+function authReason(serializable) {
+    const type = safeProperty(serializable, "type");
+    if (type === "AuthError") {
+        return boundedAuthReason(safeProperty(serializable, "reason"));
+    }
+    if (type === "RemoteError") {
+        const remoteError = safeProperty(serializable, "remoteError");
+        if (isRecord(remoteError) && objectStringProperty(remoteError, "type") ===
+            "AuthError") {
+            return boundedAuthReason(safeProperty(remoteError, "reason"));
+        }
+    }
+    return undefined;
+}
+function boundedAuthReason(value) {
+    const sanitized = lowCardinalityValue(value);
+    if (!sanitized || !AUTH_REASONS.has(sanitized))
+        return undefined;
+    return sanitized;
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function isSerializableMethod(value) {
+    return typeof value === "function";
+}
+function safeProperty(value, key) {
+    if (!isRecord(value))
+        return undefined;
+    try {
+        return value[key];
+    }
+    catch {
+        return undefined;
+    }
+}
+function objectStringProperty(value, key) {
+    return lowCardinalityValue(safeProperty(value, key));
+}
+function setLowCardinalityAttribute(attributes, key, value) {
+    const sanitized = lowCardinalityValue(value);
+    if (sanitized)
+        attributes[key] = sanitized;
+}
+function lowCardinalityValue(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    if (trimmed.length === 0 ||
+        trimmed.length > MAX_ATTRIBUTE_LENGTH ||
+        !LOW_CARDINALITY_PATTERN.test(trimmed) ||
+        UUID_PATTERN.test(trimmed) ||
+        ULID_PATTERN.test(trimmed) ||
+        LONG_HEX_SEGMENT_PATTERN.test(trimmed) ||
+        TRELLIS_SUBJECT_PREFIX_PATTERN.test(trimmed)) {
+        return undefined;
+    }
+    return trimmed;
+}

package/esm/telemetry/mod.d.ts

@@ -3,6 +3,9 @@ export { createMapCarrier, extractTraceContext, injectTraceContext, } from "./ca
 export type { Context, Span } from "./core.js";
 export { context, getActiveSpan, getTracer, SpanKind, SpanStatusCode, trace, withSpan, withSpanAsync, } from "./core.js";
 export { getEnv } from "./env.js";
+export { initTelemetry } from "./init.js";
+export { buildTrellisErrorMetricAttributes, getTrellisMeter, recordTrellisError, } from "./metrics.js";
+export type { TrellisErrorMetricAttributes } from "./metrics.js";
 export type { NatsHeadersLike } from "./nats.js";
 export { createNatsHeaderCarrier } from "./nats.js";
 export { configureErrorTraceId } from "./result.js";

package/esm/telemetry/mod.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../../src/telemetry/mod.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,EACL,OAAO,EACP,aAAa,EACb,SAAS,EACT,QAAQ,EACR,cAAc,EACd,KAAK,EACL,QAAQ,EACR,aAAa,GACd,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,YAAY,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AACjD,OAAO,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,eAAe,GAChB,MAAM,cAAc,CAAC"}
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../../src/telemetry/mod.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,EACL,OAAO,EACP,aAAa,EACb,SAAS,EACT,QAAQ,EACR,cAAc,EACd,KAAK,EACL,QAAQ,EACR,aAAa,GACd,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EACL,iCAAiC,EACjC,eAAe,EACf,kBAAkB,GACnB,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,4BAA4B,EAAE,MAAM,cAAc,CAAC;AACjE,YAAY,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AACjD,OAAO,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,eAAe,GAChB,MAAM,cAAc,CAAC"}

package/esm/telemetry/mod.js

@@ -1,6 +1,8 @@
 export { createMapCarrier, extractTraceContext, injectTraceContext, } from "./carrier.js";
 export { context, getActiveSpan, getTracer, SpanKind, SpanStatusCode, trace, withSpan, withSpanAsync, } from "./core.js";
 export { getEnv } from "./env.js";
+export { initTelemetry } from "./init.js";
+export { buildTrellisErrorMetricAttributes, getTrellisMeter, recordTrellisError, } from "./metrics.js";
 export { createNatsHeaderCarrier } from "./nats.js";
 export { configureErrorTraceId } from "./result.js";
 export { getTrellisTracer, startClientSpan, startServerSpan, } from "./trellis.js";

package/esm/telemetry/runtime.d.ts

@@ -0,0 +1,2 @@
+export declare function initTelemetryRuntime(serviceName: string): void;
+//# sourceMappingURL=runtime.d.ts.map

package/esm/telemetry/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/telemetry/runtime.ts"],"names":[],"mappings":"AAmNA,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAM9D"}

package/esm/telemetry/runtime.js

@@ -0,0 +1,134 @@
+import { metrics } from "@opentelemetry/api";
+import { getEnv } from "./env.js";
+let initialized = false;
+let provider;
+let metricProvider;
+function runtimeImport(specifier) {
+    const load = new Function("specifier", "return import(specifier);");
+    return load(specifier);
+}
+async function loadTracingRuntime() {
+    const [traceNode, otlp, traceBase, resources, semantic] = await Promise.all([
+        runtimeImport(["@opentelemetry", "sdk-trace-node"].join("/")),
+        runtimeImport(["@opentelemetry", "exporter-trace-otlp-proto"].join("/")),
+        runtimeImport(["@opentelemetry", "sdk-trace-base"].join("/")),
+        runtimeImport(["@opentelemetry", "resources"].join("/")),
+        runtimeImport(["@opentelemetry", "semantic-conventions"].join("/")),
+    ]);
+    return {
+        NodeTracerProvider: traceNode.NodeTracerProvider,
+        OTLPTraceExporter: otlp.OTLPTraceExporter,
+        BatchSpanProcessor: traceBase.BatchSpanProcessor,
+        ConsoleSpanExporter: traceBase.ConsoleSpanExporter,
+        resourceFromAttributes: resources.resourceFromAttributes,
+        ATTR_SERVICE_NAME: semantic.ATTR_SERVICE_NAME,
+    };
+}
+async function loadMetricsRuntime() {
+    const [sdkMetrics, otlp, resources, semantic] = await Promise.all([
+        runtimeImport(["@opentelemetry", "sdk-metrics"].join("/")),
+        runtimeImport(["@opentelemetry", "exporter-metrics-otlp-proto"].join("/")),
+        runtimeImport(["@opentelemetry", "resources"].join("/")),
+        runtimeImport(["@opentelemetry", "semantic-conventions"].join("/")),
+    ]);
+    return {
+        MeterProvider: sdkMetrics.MeterProvider,
+        PeriodicExportingMetricReader: sdkMetrics.PeriodicExportingMetricReader,
+        ConsoleMetricExporter: sdkMetrics.ConsoleMetricExporter,
+        OTLPMetricExporter: otlp.OTLPMetricExporter,
+        resourceFromAttributes: resources.resourceFromAttributes,
+        ATTR_SERVICE_NAME: semantic.ATTR_SERVICE_NAME,
+    };
+}
+async function initTracingRuntime(serviceName) {
+    const endpoint = getEnv("OTEL_EXPORTER_OTLP_ENDPOINT");
+    const consoleTracing = getEnv("OTEL_TRACES_CONSOLE") === "true";
+    if (!endpoint && !consoleTracing) {
+        return;
+    }
+    try {
+        const runtime = await loadTracingRuntime();
+        const spanProcessors = [];
+        if (endpoint) {
+            spanProcessors.push(new runtime.BatchSpanProcessor(new runtime.OTLPTraceExporter({ url: `${endpoint}/v1/traces` })));
+        }
+        if (consoleTracing) {
+            spanProcessors.push(new runtime.BatchSpanProcessor(new runtime.ConsoleSpanExporter()));
+        }
+        const nextProvider = new runtime.NodeTracerProvider({
+            resource: runtime.resourceFromAttributes({
+                [runtime.ATTR_SERVICE_NAME]: serviceName,
+            }),
+            ...(spanProcessors.length > 0 ? { spanProcessors } : {}),
+        });
+        provider = nextProvider;
+        nextProvider.register();
+    }
+    catch (error) {
+        console.warn("Failed to initialize tracing runtime", error);
+    }
+}
+function metricEndpoint() {
+    const metricsEndpoint = getEnv("OTEL_EXPORTER_OTLP_METRICS_ENDPOINT");
+    if (metricsEndpoint)
+        return metricsEndpoint;
+    const endpoint = getEnv("OTEL_EXPORTER_OTLP_ENDPOINT");
+    if (!endpoint)
+        return undefined;
+    return `${endpoint.replace(/\/$/, "")}/v1/metrics`;
+}
+function metricExportIntervalMillis() {
+    const configured = getEnv("OTEL_METRIC_EXPORT_INTERVAL");
+    if (!configured)
+        return undefined;
+    const parsed = Number(configured);
+    if (!Number.isFinite(parsed) || parsed <= 0)
+        return undefined;
+    return Math.trunc(parsed);
+}
+async function initMetricsRuntime(serviceName) {
+    const endpoint = metricEndpoint();
+    const consoleMetrics = getEnv("TRELLIS_METRICS_CONSOLE") === "true";
+    if (!endpoint && !consoleMetrics) {
+        return;
+    }
+    try {
+        const runtime = await loadMetricsRuntime();
+        const readers = [];
+        const exportIntervalMillis = metricExportIntervalMillis();
+        if (endpoint) {
+            readers.push(new runtime.PeriodicExportingMetricReader({
+                exporter: new runtime.OTLPMetricExporter({ url: endpoint }),
+                ...(exportIntervalMillis !== undefined
+                    ? { exportIntervalMillis }
+                    : {}),
+            }));
+        }
+        if (consoleMetrics) {
+            readers.push(new runtime.PeriodicExportingMetricReader({
+                exporter: new runtime.ConsoleMetricExporter(),
+                ...(exportIntervalMillis !== undefined
+                    ? { exportIntervalMillis }
+                    : {}),
+            }));
+        }
+        const nextMetricProvider = new runtime.MeterProvider({
+            resource: runtime.resourceFromAttributes({
+                [runtime.ATTR_SERVICE_NAME]: serviceName,
+            }),
+            ...(readers.length > 0 ? { readers } : {}),
+        });
+        metricProvider = nextMetricProvider;
+        metrics.setGlobalMeterProvider(nextMetricProvider);
+    }
+    catch (error) {
+        console.warn("Failed to initialize metrics runtime", error);
+    }
+}
+export function initTelemetryRuntime(serviceName) {
+    if (initialized)
+        return;
+    initialized = true;
+    void initTracingRuntime(serviceName);
+    void initMetricsRuntime(serviceName);
+}

package/esm/telemetry.d.ts

@@ -0,0 +1,3 @@
+import "./_dnt.polyfills.js";
+export * from "./telemetry/mod.js";
+//# sourceMappingURL=telemetry.d.ts.map

package/esm/telemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../src/telemetry.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAC7B,cAAc,oBAAoB,CAAC"}

package/esm/telemetry.js

@@ -0,0 +1,2 @@
+import "./_dnt.polyfills.js";
+export * from "./telemetry/mod.js";

package/esm/transfer.d.ts.map

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

package/esm/transfer.js

@@ -17,7 +17,7 @@ import { ulid } from "ulid";
 import { buildProofInput, verifyProof } from "./auth/proof.js";
 import { base64urlEncode, sha256 } from "./auth/utils.js";
 import { TransferError } from "./errors/TransferError.js";
-import { createNatsHeaderCarrier, injectTraceContext } from "./tracing.js";
+import { createNatsHeaderCarrier, injectTraceContext, recordTrellisError, } from "./telemetry/mod.js";
 const TRANSFER_SEQUENCE_HEADER = "trellis-transfer-seq";
 const TRANSFER_EOF_HEADER = "trellis-transfer-eof";
 export const FileInfoSchema = Type.Object({
@@ -130,7 +130,7 @@ function deserializeTransferError(msg, operation) {
     try {
         const value = JSON.parse(msg.string());
         return new TransferError({
-            operation: value.operation ?? operation,
+            operation,
             context: value.context,
             cause: value.message ? new Error(value.message) : undefined,
         });
@@ -139,6 +139,16 @@ function deserializeTransferError(msg, operation) {
         return new TransferError({ operation, cause });
     }
 }
+function recordTransferError(error, direction, phase) {
+    recordTrellisError(error, {
+        surface: "transfer",
+        direction,
+        operation: error.operation ?? direction,
+        phase,
+        messagingSystem: "nats",
+    });
+    return error;
+}
 function receiveStream(sub, timeoutMs) {
     const iterator = sub[Symbol.asyncIterator]();
     return new ReadableStream({
@@ -179,9 +189,10 @@ function receiveStream(sub, timeoutMs) {
             }
             catch (cause) {
                 sub.unsubscribe();
-                controller.error(cause instanceof TransferError
+                const error = cause instanceof TransferError
                     ? cause
-                    : new TransferError({ operation: "stream", cause }));
+                    : new TransferError({ operation: "stream", cause });
+                controller.error(recordTransferError(error, "receive", "stream"));
             }
         },
         cancel() {
@@ -283,7 +294,7 @@ export class SendTransferHandle extends BaseTransferHandle {
         return AsyncResult.from((async () => {
             const valid = this.validateGrant(__classPrivateFieldGet(this, _SendTransferHandle_grant, "f"), "send").take();
             if (isErr(valid)) {
-                return Result.err(valid.error);
+                return Result.err(recordTransferError(valid.error, "send", "grant"));
             }
             let sentBytes = 0;
             let seq = 0;
@@ -292,14 +303,14 @@ export class SendTransferHandle extends BaseTransferHandle {
                 sentBytes += chunk.length;
                 if (__classPrivateFieldGet(this, _SendTransferHandle_grant, "f").maxBytes !== undefined &&
                     sentBytes > __classPrivateFieldGet(this, _SendTransferHandle_grant, "f").maxBytes) {
-                    return Result.err(new TransferError({
+                    return Result.err(recordTransferError(new TransferError({
                         operation: "send",
                         context: {
                             reason: "max_bytes_exceeded",
                             maxBytes: __classPrivateFieldGet(this, _SendTransferHandle_grant, "f").maxBytes,
                             attemptedBytes: sentBytes,
                         },
-                    }));
+                    }), "send", "validation"));
                 }
                 const headers = await this.buildHeaders(__classPrivateFieldGet(this, _SendTransferHandle_grant, "f").subject, chunk, seq, false);
                 const response = await AsyncResult.try(() => this.nc.request(__classPrivateFieldGet(this, _SendTransferHandle_grant, "f").subject, chunk, {
@@ -307,11 +318,11 @@ export class SendTransferHandle extends BaseTransferHandle {
                     headers,
                 })).take();
                 if (isErr(response)) {
-                    return Result.err(new TransferError({ operation: "send", cause: response.error }));
+                    return Result.err(recordTransferError(new TransferError({ operation: "send", cause: response.error }), "send", "send"));
                 }
                 const ack = parseTransferAck(response, "send").take();
                 if (isErr(ack)) {
-                    return Result.err(ack.error);
+                    return Result.err(recordTransferError(ack.error, "send", "ack"));
                 }
                 if (ack.status === "complete") {
                     completed = ack.info;
@@ -324,20 +335,20 @@ export class SendTransferHandle extends BaseTransferHandle {
                 headers: finalHeaders,
             })).take();
             if (isErr(finalResponse)) {
-                return Result.err(new TransferError({
+                return Result.err(recordTransferError(new TransferError({
                     operation: "send",
                     cause: finalResponse.error,
-                }));
+                }), "send", "send"));
             }
             const finalAck = parseTransferAck(finalResponse, "send").take();
             if (isErr(finalAck)) {
-                return Result.err(finalAck.error);
+                return Result.err(recordTransferError(finalAck.error, "send", "ack"));
             }
             if (finalAck.status !== "complete") {
-                return Result.err(new TransferError({
+                return Result.err(recordTransferError(new TransferError({
                     operation: "send",
                     context: { reason: "missing_completion" },
-                }));
+                }), "send", "ack"));
             }
             return Result.ok(finalAck.info ?? completed);
         })());
@@ -354,7 +365,7 @@ export class ReceiveTransferHandle extends BaseTransferHandle {
         return AsyncResult.from((async () => {
             const valid = this.validateGrant(__classPrivateFieldGet(this, _ReceiveTransferHandle_grant, "f"), "stream").take();
             if (isErr(valid)) {
-                return Result.err(valid.error);
+                return Result.err(recordTransferError(valid.error, "receive", "grant"));
             }
             const inbox = createInbox(`_INBOX.${this.auth.sessionKey.slice(0, 16)}`);
             const sub = this.nc.subscribe(inbox);
@@ -369,7 +380,7 @@ export class ReceiveTransferHandle extends BaseTransferHandle {
             }
             catch (cause) {
                 sub.unsubscribe();
-                return Result.err(new TransferError({ operation: "stream", cause }));
+                return Result.err(recordTransferError(new TransferError({ operation: "stream", cause }), "receive", "send"));
             }
             return Result.ok(receiveStream(sub, this.timeoutMs));
         })());