@oatscenter/trellis 0.100.0-rc.1

package/telemetry/init.d.ts

@@ -0,0 +1,2 @@
+/** Initializes Trellis telemetry for a service runtime. */
+export declare function initTelemetry(serviceName: string): void;

package/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/telemetry/metrics.d.ts

@@ -0,0 +1,81 @@
+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;
+};
+/** Duration metric names accepted by {@link recordTrellisDuration}. */
+export type TrellisDurationMetricName = "trellis.connect.duration" | "trellis.auth.flow.duration" | "trellis.auth.approval_resolution.duration" | "trellis.auth.callout.duration" | "trellis.admin.workflow.duration" | "trellis.contract.analysis.duration";
+/** Low-cardinality attributes accepted by {@link recordTrellisDuration}. */
+export type TrellisDurationMetricAttributes = {
+    /** Stable Trellis surface name, such as `rpc`, `jobs`, or `operations`. */
+    surface?: string;
+    /** Stable operation kind or method name. Do not pass IDs, subjects, or URLs. */
+    operation?: string;
+    /** Stable lifecycle phase such as `bootstrap`, `encode`, or `total`. */
+    phase?: string;
+    /** Stable outcome label such as `ok` or `error`. */
+    outcome?: string;
+    /** Participant kind such as `admin`, `client`, `service`, or `device`. */
+    participantKind?: string;
+    /** Session kind such as `user`, `service`, or `device`. */
+    sessionKind?: string;
+    /** Auth flow such as `local`, `oauth`, `device`, or `bootstrap`. */
+    authFlow?: string;
+    /** Auth approval outcome such as `approved`, `denied`, `required`, or `none`. */
+    authApproval?: string;
+    /** Whether a deployment authority is present. */
+    authorityPresent?: boolean;
+    /** Plan classification such as `install`, `update`, `migration`, `noop`, or `unknown`. */
+    planClassification?: string;
+    /** Contract kind such as `app`, `service`, `device`, `builtin`, or `unknown`. */
+    contractKind?: 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;
+/**
+ * Records one duration measurement on the given Trellis histogram.
+ *
+ * Converts `durationMs` to seconds. Negative, NaN, and infinite values are
+ * silently ignored.
+ *
+ * Histogram instruments are cached by metric name so `createHistogram` is
+ * called at most once per metric name.
+ *
+ * @param name - The duration metric name.
+ * @param durationMs - The measured duration in milliseconds.
+ * @param attributes - Optional low-cardinality attributes. Only values that
+ *   pass sanitization are included.
+ *
+ * @example
+ * ```ts
+ * recordTrellisDuration("trellis.connect.duration", 42.5, {
+ *   phase: "nats_connect",
+ *   outcome: "ok",
+ *   participantKind: "client",
+ * });
+ * ```
+ */
+export declare function recordTrellisDuration(name: TrellisDurationMetricName, durationMs: number, attributes?: TrellisDurationMetricAttributes): void;

package/telemetry/metrics.js

@@ -0,0 +1,267 @@
+import { metrics } from "@opentelemetry/api";
+const TRELLIS_METER_NAME = "@oatscenter/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",
+]);
+const DURATION_HISTOGRAM_CACHE = new Map();
+/** 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;
+}
+/**
+ * Builds sanitized, low-cardinality attributes for duration histograms.
+ *
+ * @internal Exported for focused tests; runtime callers should use
+ * {@link recordTrellisDuration}.
+ */
+export function buildTrellisDurationMetricAttributes(attributes = {}) {
+    const metricAttributes = {};
+    setLowCardinalityAttribute(metricAttributes, "trellis.surface", attributes.surface);
+    setLowCardinalityAttribute(metricAttributes, "trellis.operation", attributes.operation);
+    setLowCardinalityAttribute(metricAttributes, "trellis.phase", attributes.phase);
+    setLowCardinalityAttribute(metricAttributes, "trellis.outcome", attributes.outcome);
+    setLowCardinalityAttribute(metricAttributes, "trellis.participant.kind", attributes.participantKind);
+    setLowCardinalityAttribute(metricAttributes, "trellis.session.kind", attributes.sessionKind);
+    setLowCardinalityAttribute(metricAttributes, "trellis.auth.flow", attributes.authFlow);
+    setLowCardinalityAttribute(metricAttributes, "trellis.auth.approval", attributes.authApproval);
+    setLowCardinalityAttribute(metricAttributes, "trellis.plan.classification", attributes.planClassification);
+    setLowCardinalityAttribute(metricAttributes, "trellis.contract.kind", attributes.contractKind);
+    setLowCardinalityAttribute(metricAttributes, "messaging.system", attributes.messagingSystem);
+    setLowCardinalityAttribute(metricAttributes, "messaging.operation", attributes.messagingOperation);
+    if (attributes.authorityPresent !== undefined) {
+        setLowCardinalityAttribute(metricAttributes, "trellis.authority.present", String(attributes.authorityPresent));
+    }
+    return metricAttributes;
+}
+/**
+ * Records one duration measurement on the given Trellis histogram.
+ *
+ * Converts `durationMs` to seconds. Negative, NaN, and infinite values are
+ * silently ignored.
+ *
+ * Histogram instruments are cached by metric name so `createHistogram` is
+ * called at most once per metric name.
+ *
+ * @param name - The duration metric name.
+ * @param durationMs - The measured duration in milliseconds.
+ * @param attributes - Optional low-cardinality attributes. Only values that
+ *   pass sanitization are included.
+ *
+ * @example
+ * ```ts
+ * recordTrellisDuration("trellis.connect.duration", 42.5, {
+ *   phase: "nats_connect",
+ *   outcome: "ok",
+ *   participantKind: "client",
+ * });
+ * ```
+ */
+export function recordTrellisDuration(name, durationMs, attributes) {
+    if (typeof durationMs !== "number" ||
+        durationMs < 0 ||
+        !Number.isFinite(durationMs)) {
+        return;
+    }
+    const histogram = getDurationHistogram(name);
+    const metricAttributes = buildTrellisDurationMetricAttributes(attributes);
+    histogram.record(durationMs / 1000, metricAttributes);
+}
+function getDurationHistogram(name) {
+    let histogram = DURATION_HISTOGRAM_CACHE.get(name);
+    if (!histogram) {
+        histogram = getTrellisMeter().createHistogram(name, {
+            description: histogramDescription(name),
+            unit: "s",
+        });
+        DURATION_HISTOGRAM_CACHE.set(name, histogram);
+    }
+    return histogram;
+}
+function histogramDescription(name) {
+    switch (name) {
+        case "trellis.connect.duration":
+            return "Duration of connection lifecycle phases.";
+        case "trellis.auth.flow.duration":
+            return "Duration of auth flow phases.";
+        case "trellis.auth.approval_resolution.duration":
+            return "Duration of approval resolution phases.";
+        case "trellis.auth.callout.duration":
+            return "Duration of NATS auth callout phases.";
+        case "trellis.admin.workflow.duration":
+            return "Duration of admin workflow phases.";
+        case "trellis.contract.analysis.duration":
+            return "Duration of contract analysis phases.";
+    }
+}
+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/telemetry/mod.d.ts

@@ -0,0 +1,13 @@
+export type { HeaderCarrier } from "./carrier.ts";
+export { createMapCarrier, extractTraceContext, injectTraceContext, } from "./carrier.ts";
+export type { Context, Span } from "./core.ts";
+export { context, getActiveSpan, getTracer, SpanKind, SpanStatusCode, trace, withSpan, withSpanAsync, } from "./core.ts";
+export { getEnv } from "./env.ts";
+export { initTelemetry } from "./init.ts";
+export { buildTrellisDurationMetricAttributes, buildTrellisErrorMetricAttributes, getTrellisMeter, recordTrellisDuration, recordTrellisError, } from "./metrics.ts";
+export type { TrellisDurationMetricAttributes, TrellisDurationMetricName, } from "./metrics.ts";
+export type { TrellisErrorMetricAttributes } from "./metrics.ts";
+export type { NatsHeadersLike } from "./nats.ts";
+export { createNatsHeaderCarrier } from "./nats.ts";
+export { configureErrorTraceId } from "./result.ts";
+export { getTrellisTracer, startClientSpan, startServerSpan, } from "./trellis.ts";

package/telemetry/mod.js

@@ -0,0 +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 { buildTrellisDurationMetricAttributes, buildTrellisErrorMetricAttributes, getTrellisMeter, recordTrellisDuration, recordTrellisError, } from "./metrics.js";
+export { createNatsHeaderCarrier } from "./nats.js";
+export { configureErrorTraceId } from "./result.js";
+export { getTrellisTracer, startClientSpan, startServerSpan, } from "./trellis.js";

package/telemetry/nats.d.ts

@@ -0,0 +1,6 @@
+import type { HeaderCarrier } from "./carrier.ts";
+export interface NatsHeadersLike {
+    get(key: string): string | undefined;
+    set(key: string, value: string): void;
+}
+export declare function createNatsHeaderCarrier(headers: NatsHeadersLike): HeaderCarrier;

package/telemetry/nats.js

@@ -0,0 +1,6 @@
+export function createNatsHeaderCarrier(headers) {
+    return {
+        get: (key) => headers.get(key),
+        set: (key, value) => headers.set(key, value),
+    };
+}

package/telemetry/result.d.ts

@@ -0,0 +1 @@
+export declare function configureErrorTraceId(): void;

package/telemetry/result.js

@@ -0,0 +1,18 @@
+import { trace } from "@opentelemetry/api";
+import { BaseError } from "@oatscenter/result";
+let traceIdGetterConfigured = false;
+export function configureErrorTraceId() {
+    if (traceIdGetterConfigured)
+        return;
+    traceIdGetterConfigured = true;
+    BaseError.traceIdGetter = () => {
+        const span = trace.getActiveSpan();
+        if (!span)
+            return undefined;
+        const spanContext = span.spanContext();
+        if (spanContext.traceId === "00000000000000000000000000000000") {
+            return undefined;
+        }
+        return spanContext.traceId;
+    };
+}

package/telemetry/runtime.d.ts

@@ -0,0 +1 @@
+export declare function initTelemetryRuntime(serviceName: string): void;

package/telemetry/runtime.js

@@ -0,0 +1,141 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { metrics } from "@opentelemetry/api";
+import { getEnv } from "./env.js";
+let initialized = false;
+let provider;
+let metricProvider;
+function runtimeImport(specifier) {
+    return import(__rewriteRelativeImportExtension(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/telemetry/trace.d.ts

@@ -0,0 +1,4 @@
+import type { Context, Span } from "@opentelemetry/api";
+export declare function getTrellisTracer(): import("@opentelemetry/api").Tracer;
+export declare function startClientSpan(method: string, subject: string): Span;
+export declare function startServerSpan(method: string, subject: string, parentContext?: Context): Span;

package/telemetry/trace.js

@@ -0,0 +1,26 @@
+import { SpanKind } from "@opentelemetry/api";
+import { getTracer } from "./core.js";
+const TRELLIS_INSTRUMENTATION_SCOPE = "@oatscenter/trellis";
+export function getTrellisTracer() {
+    return getTracer(TRELLIS_INSTRUMENTATION_SCOPE);
+}
+export function startClientSpan(method, subject) {
+    return getTrellisTracer().startSpan(`rpc.client.${method}`, {
+        kind: SpanKind.CLIENT,
+        attributes: {
+            "rpc.system": "nats",
+            "rpc.method": method,
+            "messaging.destination": subject,
+        },
+    });
+}
+export function startServerSpan(method, subject, parentContext) {
+    return getTrellisTracer().startSpan(`rpc.server.${method}`, {
+        kind: SpanKind.SERVER,
+        attributes: {
+            "rpc.system": "nats",
+            "rpc.method": method,
+            "messaging.destination": subject,
+        },
+    }, parentContext);
+}

package/telemetry/trellis.d.ts

@@ -0,0 +1 @@
+export { getTrellisTracer, startClientSpan, startServerSpan } from "./trace.ts";

package/telemetry/trellis.js

@@ -0,0 +1 @@
+export { getTrellisTracer, startClientSpan, startServerSpan } from "./trace.js";

package/telemetry.d.ts

@@ -0,0 +1 @@
+export * from "./telemetry/mod.ts";

package/telemetry.js

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