@smthrs/observability 0.35.0 → 1.0.0-rc.4

package/dist/esm/Metric.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Effect metric registry for flows runtime signals.
+ *
+ * @since 0.1.0
+ */
+import * as Metric from "effect/Metric";
+/**
+ * Counts flow runs that reached a terminal state.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export declare const runThroughput: Metric.Counter<number>;
+/**
+ * The number of execution seats currently held.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export declare const activeSeats: Metric.Gauge<number>;
+/**
+ * Counts runs parked because a quota was exhausted.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export declare const quotaParks: Metric.Counter<number>;
+/**
+ * Counts agent answers refused by their declared output schema.
+ *
+ * @category metrics
+ * @since 1.0.0-rc.1
+ */
+export declare const structuredOutputRejections: Metric.Counter<number>;
+/**
+ * Counts agent steps that failed after spending every output correction.
+ *
+ * @category metrics
+ * @since 1.0.0-rc.1
+ */
+export declare const structuredOutputExhausted: Metric.Counter<number>;
+/**
+ * Counts operational log records lost before durable delivery.
+ *
+ * Advances once per record dropped by a saturated forwarding queue, once per
+ * journal delivery failure, and once per defect the forwarding worker recovers
+ * from, so telemetry loss is distinguishable from an idle logger.
+ *
+ * @category metrics
+ * @since 1.0.0-rc.0
+ */
+export declare const droppedLogRecords: Metric.Counter<number>;
+/**
+ * All metrics declared by this package.
+ *
+ * @category registry
+ * @since 0.1.0
+ */
+export declare const registry: {
+    readonly runThroughput: Metric.Counter<number>;
+    readonly activeSeats: Metric.Gauge<number>;
+    readonly quotaParks: Metric.Counter<number>;
+    readonly structuredOutputRejections: Metric.Counter<number>;
+    readonly structuredOutputExhausted: Metric.Counter<number>;
+    readonly droppedLogRecords: Metric.Counter<number>;
+};
+//# sourceMappingURL=Metric.d.ts.map

package/dist/esm/Metric.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Metric.d.ts","sourceRoot":"","sources":["../../src/Metric.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAIvC;;;;;GAKG;AACH,eAAO,MAAM,aAAa,wBAExB,CAAA;AAEF;;;;;GAKG;AACH,eAAO,MAAM,WAAW,sBAEtB,CAAA;AAEF;;;;;GAKG;AACH,eAAO,MAAM,UAAU,wBAErB,CAAA;AAEF;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,wBAErC,CAAA;AAEF;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,wBAEpC,CAAA;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,wBAE5B,CAAA;AAEF;;;;;GAKG;AACH,eAAO,MAAM,QAAQ;;;;;;;CAOX,CAAA"}

package/dist/esm/Metric.js

@@ -0,0 +1,80 @@
+/**
+ * Effect metric registry for flows runtime signals.
+ *
+ * @since 0.1.0
+ */
+import * as Metric from "effect/Metric";
+const prefix = "flows_";
+/**
+ * Counts flow runs that reached a terminal state.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export const runThroughput = Metric.counter(`${prefix}run_throughput`, {
+    description: "Completed flow runs"
+});
+/**
+ * The number of execution seats currently held.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export const activeSeats = Metric.gauge(`${prefix}seat_active`, {
+    description: "Currently active execution seats"
+});
+/**
+ * Counts runs parked because a quota was exhausted.
+ *
+ * @category metrics
+ * @since 0.1.0
+ */
+export const quotaParks = Metric.counter(`${prefix}quota_park`, {
+    description: "Runs parked by quota enforcement"
+});
+/**
+ * Counts agent answers refused by their declared output schema.
+ *
+ * @category metrics
+ * @since 1.0.0-rc.1
+ */
+export const structuredOutputRejections = Metric.counter(`${prefix}agent_structured_output_rejections`, {
+    description: "Agent answers refused by their declared output schema"
+});
+/**
+ * Counts agent steps that failed after spending every output correction.
+ *
+ * @category metrics
+ * @since 1.0.0-rc.1
+ */
+export const structuredOutputExhausted = Metric.counter(`${prefix}agent_structured_output_exhausted`, {
+    description: "Agent steps whose output corrections were exhausted"
+});
+/**
+ * Counts operational log records lost before durable delivery.
+ *
+ * Advances once per record dropped by a saturated forwarding queue, once per
+ * journal delivery failure, and once per defect the forwarding worker recovers
+ * from, so telemetry loss is distinguishable from an idle logger.
+ *
+ * @category metrics
+ * @since 1.0.0-rc.0
+ */
+export const droppedLogRecords = Metric.counter(`${prefix}observability_log_dropped`, {
+    description: "Operational log records dropped before durable delivery"
+});
+/**
+ * All metrics declared by this package.
+ *
+ * @category registry
+ * @since 0.1.0
+ */
+export const registry = {
+    runThroughput,
+    activeSeats,
+    quotaParks,
+    structuredOutputRejections,
+    structuredOutputExhausted,
+    droppedLogRecords
+};
+//# sourceMappingURL=Metric.js.map

package/dist/esm/Metric.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Metric.js","sourceRoot":"","sources":["../../src/Metric.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC,MAAM,MAAM,GAAG,QAAQ,CAAA;AAEvB;;;;;GAKG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,MAAM,gBAAgB,EAAE;IACrE,WAAW,EAAE,qBAAqB;CACnC,CAAC,CAAA;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,MAAM,aAAa,EAAE;IAC9D,WAAW,EAAE,kCAAkC;CAChD,CAAC,CAAA;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,MAAM,YAAY,EAAE;IAC9D,WAAW,EAAE,kCAAkC;CAChD,CAAC,CAAA;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,MAAM,oCAAoC,EAAE;IACtG,WAAW,EAAE,uDAAuD;CACrE,CAAC,CAAA;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,MAAM,mCAAmC,EAAE;IACpG,WAAW,EAAE,qDAAqD;CACnE,CAAC,CAAA;AAEF;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,MAAM,2BAA2B,EAAE;IACpF,WAAW,EAAE,yDAAyD;CACvE,CAAC,CAAA;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB,aAAa;IACb,WAAW;IACX,UAAU;IACV,0BAA0B;IAC1B,yBAAyB;IACzB,iBAAiB;CACT,CAAA"}

package/dist/esm/NodeOtel.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Node-only OTLP/HTTP OpenTelemetry setup.
+ *
+ * @since 0.1.0
+ */
+import type * as Duration from "effect/Duration";
+import * as Layer from "effect/Layer";
+import * as Endpoint from "./Endpoint.ts";
+import * as Resource from "./Resource.ts";
+import type { Configuration as ResourceConfiguration } from "./Resource.ts";
+/**
+ * Node OTLP/HTTP layer options.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Options {
+    /**
+     * The collector base URL. It must be an absolute `http:` or `https:` URL
+     * without credentials and free of spaces and control characters; anything
+     * else fails layer acquisition with
+     * {@link Endpoint.InvalidExporterEndpoint}.
+     */
+    readonly endpoint: string;
+    readonly resource: ResourceConfiguration;
+    readonly shutdownTimeout?: Duration.Input | undefined;
+    readonly exportIntervalMillis?: number | undefined;
+}
+/**
+ * Builds a scoped Node OTLP/HTTP layer for all three telemetry signals.
+ * Exporter objects are created only when this layer is built.
+ * Resource metadata is explicit: ambient OTEL resource configuration cannot
+ * enlarge it after validation. The OpenTelemetry exporters still read the
+ * standard `OTEL_EXPORTER_OTLP_*` transport variables (headers, timeout,
+ * compression, TLS files) from the process environment and send them to the
+ * explicit endpoint, which always wins over `OTEL_EXPORTER_OTLP_ENDPOINT`.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layerOtel: (options: Options) => Layer.Layer<never, Resource.InvalidResourceConfiguration | Endpoint.InvalidExporterEndpoint>;
+//# sourceMappingURL=NodeOtel.d.ts.map

package/dist/esm/NodeOtel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NodeOtel.d.ts","sourceRoot":"","sources":["../../src/NodeOtel.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAUH,OAAO,KAAK,KAAK,QAAQ,MAAM,iBAAiB,CAAA;AAEhD,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AACrC,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAA;AACzC,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAA;AACzC,OAAO,KAAK,EAAE,aAAa,IAAI,qBAAqB,EAAE,MAAM,eAAe,CAAA;AAE3E;;;;;GAKG;AACH,MAAM,WAAW,OAAO;IACtB;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,QAAQ,EAAE,qBAAqB,CAAA;IACxC,QAAQ,CAAC,eAAe,CAAC,EAAE,QAAQ,CAAC,KAAK,GAAG,SAAS,CAAA;IACrD,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CACnD;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,SAAS,GACpB,SAAS,OAAO,KACf,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,QAAQ,CAAC,4BAA4B,GAAG,QAAQ,CAAC,uBAAuB,CAmC3F,CAAA"}

package/dist/esm/NodeOtel.js

@@ -0,0 +1,56 @@
+/**
+ * Node-only OTLP/HTTP OpenTelemetry setup.
+ *
+ * @since 0.1.0
+ */
+import * as NodeSdk from "@effect/opentelemetry/NodeSdk";
+import { OTLPLogExporter } from "@opentelemetry/exporter-logs-otlp-http";
+import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+import { BatchLogRecordProcessor } from "@opentelemetry/sdk-logs";
+import { PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
+import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
+import * as ConfigProvider from "effect/ConfigProvider";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Endpoint from "./Endpoint.js";
+import * as Resource from "./Resource.js";
+/**
+ * Builds a scoped Node OTLP/HTTP layer for all three telemetry signals.
+ * Exporter objects are created only when this layer is built.
+ * Resource metadata is explicit: ambient OTEL resource configuration cannot
+ * enlarge it after validation. The OpenTelemetry exporters still read the
+ * standard `OTEL_EXPORTER_OTLP_*` transport variables (headers, timeout,
+ * compression, TLS files) from the process environment and send them to the
+ * explicit endpoint, which always wins over `OTEL_EXPORTER_OTLP_ENDPOINT`.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layerOtel = (options) => Layer.unwrap(Effect.map(Effect.all([Resource.decode(options.resource), Endpoint.decode(options.endpoint, "endpoint")]), ([decoded, endpoint]) => NodeSdk.layer(() => {
+    const resource = Resource.toOpenTelemetryConfiguration(decoded);
+    const spanProcessor = new BatchSpanProcessor(new OTLPTraceExporter({ url: Endpoint.signalUrl(endpoint, "traces") }));
+    const logRecordProcessor = new BatchLogRecordProcessor({
+        exporter: new OTLPLogExporter({ url: Endpoint.signalUrl(endpoint, "logs") })
+    });
+    const metricReader = options.exportIntervalMillis === undefined
+        ? new PeriodicExportingMetricReader({
+            exporter: new OTLPMetricExporter({ url: Endpoint.signalUrl(endpoint, "metrics") })
+        })
+        : new PeriodicExportingMetricReader({
+            exporter: new OTLPMetricExporter({ url: Endpoint.signalUrl(endpoint, "metrics") }),
+            exportIntervalMillis: options.exportIntervalMillis
+        });
+    return {
+        resource,
+        spanProcessor,
+        logRecordProcessor,
+        metricReader,
+        shutdownTimeout: options.shutdownTimeout
+    };
+}).pipe(
+// NodeSdk merges Resource.layerFromEnv after our admission check.
+// Isolate that lookup so only the validated explicit resource and
+// the SDK metadata already included in its budget reach exporters.
+Layer.provide(ConfigProvider.layer(ConfigProvider.fromUnknown({}))))));
+//# sourceMappingURL=NodeOtel.js.map

package/dist/esm/NodeOtel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"NodeOtel.js","sourceRoot":"","sources":["../../src/NodeOtel.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,OAAO,MAAM,+BAA+B,CAAA;AACxD,OAAO,EAAE,eAAe,EAAE,MAAM,wCAAwC,CAAA;AACxE,OAAO,EAAE,kBAAkB,EAAE,MAAM,2CAA2C,CAAA;AAC9E,OAAO,EAAE,iBAAiB,EAAE,MAAM,yCAAyC,CAAA;AAC3E,OAAO,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAA;AACjE,OAAO,EAAE,6BAA6B,EAAE,MAAM,4BAA4B,CAAA;AAC1E,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAA;AAClE,OAAO,KAAK,cAAc,MAAM,uBAAuB,CAAA;AAEvD,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AACrC,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAA;AACzC,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAA;AAsBzC;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CACvB,OAAgB,EAC8E,EAAE,CAChG,KAAK,CAAC,MAAM,CACV,MAAM,CAAC,GAAG,CACR,MAAM,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC,CAAC,EAC9F,CAAC,CAAC,OAAO,EAAE,QAAQ,CAAC,EAAE,EAAE,CACtB,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE;IACjB,MAAM,QAAQ,GAAG,QAAQ,CAAC,4BAA4B,CAAC,OAAO,CAAC,CAAA;IAC/D,MAAM,aAAa,GAAG,IAAI,kBAAkB,CAC1C,IAAI,iBAAiB,CAAC,EAAE,GAAG,EAAE,QAAQ,CAAC,SAAS,CAAC,QAAQ,EAAE,QAAQ,CAAC,EAAE,CAAC,CACvE,CAAA;IACD,MAAM,kBAAkB,GAAG,IAAI,uBAAuB,CAAC;QACrD,QAAQ,EAAE,IAAI,eAAe,CAAC,EAAE,GAAG,EAAE,QAAQ,CAAC,SAAS,CAAC,QAAQ,EAAE,MAAM,CAAC,EAAE,CAAC;KAC7E,CAAC,CAAA;IACF,MAAM,YAAY,GAAG,OAAO,CAAC,oBAAoB,KAAK,SAAS;QAC7D,CAAC,CAAC,IAAI,6BAA6B,CAAC;YAClC,QAAQ,EAAE,IAAI,kBAAkB,CAAC,EAAE,GAAG,EAAE,QAAQ,CAAC,SAAS,CAAC,QAAQ,EAAE,SAAS,CAAC,EAAE,CAAC;SACnF,CAAC;QACF,CAAC,CAAC,IAAI,6BAA6B,CAAC;YAClC,QAAQ,EAAE,IAAI,kBAAkB,CAAC,EAAE,GAAG,EAAE,QAAQ,CAAC,SAAS,CAAC,QAAQ,EAAE,SAAS,CAAC,EAAE,CAAC;YAClF,oBAAoB,EAAE,OAAO,CAAC,oBAAoB;SACnD,CAAC,CAAA;IACJ,OAAO;QACL,QAAQ;QACR,aAAa;QACb,kBAAkB;QAClB,YAAY;QACZ,eAAe,EAAE,OAAO,CAAC,eAAe;KACzC,CAAA;AACH,CAAC,CAAC,CAAC,IAAI;AACL,kEAAkE;AAClE,kEAAkE;AAClE,mEAAmE;AACnE,KAAK,CAAC,OAAO,CAAC,cAAc,CAAC,KAAK,CAAC,cAAc,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC,CACpE,CACJ,CACF,CAAA"}

package/dist/esm/Otel.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Provider-neutral composition for injected OpenTelemetry providers.
+ *
+ * @since 0.1.0
+ */
+import * as OtelMetrics from "@effect/opentelemetry/OtelMetrics";
+import type * as Api from "@opentelemetry/api";
+import type { LoggerProvider } from "@opentelemetry/sdk-logs";
+import type { MetricReader } from "@opentelemetry/sdk-metrics";
+import * as Layer from "effect/Layer";
+import { type Configuration as ResourceConfiguration, type InvalidResourceConfiguration, Resource } from "./Resource.ts";
+/**
+ * Injected providers used by the provider-neutral OTEL layer.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Options {
+    /** Validated resource for metrics, tracer scope, and provider factories. */
+    readonly resource: ResourceConfiguration;
+    /**
+     * Borrowed: the layer bridges onto this provider and never flushes or shuts
+     * it down, including a provider a factory returns. Existing providers retain
+     * their resource. Factories must pass the supplied resource to the SDK.
+     */
+    readonly tracerProvider?: Api.TracerProvider | ((resource: typeof Resource.Service) => Api.TracerProvider) | undefined;
+    /** Borrowed on the same terms as `tracerProvider`. */
+    readonly loggerProvider?: LoggerProvider | ((resource: typeof Resource.Service) => LoggerProvider) | undefined;
+    /**
+     * Owned: the factory runs once during layer acquisition, after resource
+     * validation, and every reader it returns is shut down when the scope
+     * closes. Build the readers inside the factory rather than returning one a
+     * longer-lived composition still exports through, which that shutdown would
+     * disable. An empty array registers no reader at all.
+     */
+    readonly metricReader?: (() => MetricReader | ReadonlyArray<MetricReader>) | undefined;
+    readonly loggerMergeWithExisting?: boolean | undefined;
+    readonly metricTemporality?: OtelMetrics.TemporalityPreference | undefined;
+}
+/**
+ * Composes Effect tracer, logger, and metric bridges from already-created
+ * OpenTelemetry providers or provider factories, and from metric readers this
+ * layer acquires. Factories run during layer acquisition after resource
+ * validation, and the provider factories receive the metric resource.
+ * Already-created providers keep the resource captured at construction; the
+ * resource option only sets metrics and tracer instrumentation scope for them.
+ * Ownership splits: callers own provider flushing and shutdown, including
+ * factory-built providers, while the layer scope shuts down every reader the
+ * `metricReader` factory returned. No exporter is allocated by this module.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layerOtel: (options: Options) => Layer.Layer<never, InvalidResourceConfiguration>;
+/**
+ * A no-op OTEL layer for callers that want an explicit optional slot.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layerNoop: Layer.Layer<never>;
+//# sourceMappingURL=Otel.d.ts.map

package/dist/esm/Otel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Otel.d.ts","sourceRoot":"","sources":["../../src/Otel.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,WAAW,MAAM,mCAAmC,CAAA;AAEhE,OAAO,KAAK,KAAK,GAAG,MAAM,oBAAoB,CAAA;AAC9C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAA;AAC7D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAA;AAE9D,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AACrC,OAAO,EACL,KAAK,aAAa,IAAI,qBAAqB,EAC3C,KAAK,4BAA4B,EAEjC,QAAQ,EACT,MAAM,eAAe,CAAA;AAEtB;;;;;GAKG;AACH,MAAM,WAAW,OAAO;IACtB,4EAA4E;IAC5E,QAAQ,CAAC,QAAQ,EAAE,qBAAqB,CAAA;IACxC;;;;OAIG;IACH,QAAQ,CAAC,cAAc,CAAC,EACpB,GAAG,CAAC,cAAc,GAClB,CAAC,CAAC,QAAQ,EAAE,OAAO,QAAQ,CAAC,OAAO,KAAK,GAAG,CAAC,cAAc,CAAC,GAC3D,SAAS,CAAA;IACb,sDAAsD;IACtD,QAAQ,CAAC,cAAc,CAAC,EACpB,cAAc,GACd,CAAC,CAAC,QAAQ,EAAE,OAAO,QAAQ,CAAC,OAAO,KAAK,cAAc,CAAC,GACvD,SAAS,CAAA;IACb;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,MAAM,YAAY,GAAG,aAAa,CAAC,YAAY,CAAC,CAAC,GAAG,SAAS,CAAA;IACtF,QAAQ,CAAC,uBAAuB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IACtD,QAAQ,CAAC,iBAAiB,CAAC,EAAE,WAAW,CAAC,qBAAqB,GAAG,SAAS,CAAA;CAC3E;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,SAAS,GAAI,SAAS,OAAO,KAAG,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,4BAA4B,CAsC3F,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,SAAS,EAAE,KAAK,CAAC,KAAK,CAAC,KAAK,CAAe,CAAA"}

package/dist/esm/Otel.js

@@ -0,0 +1,51 @@
+/**
+ * Provider-neutral composition for injected OpenTelemetry providers.
+ *
+ * @since 0.1.0
+ */
+import * as OtelLogger from "@effect/opentelemetry/OtelLogger";
+import * as OtelMetrics from "@effect/opentelemetry/OtelMetrics";
+import * as OtelTracer from "@effect/opentelemetry/OtelTracer";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import { layer as resourceLayer, Resource } from "./Resource.js";
+/**
+ * Composes Effect tracer, logger, and metric bridges from already-created
+ * OpenTelemetry providers or provider factories, and from metric readers this
+ * layer acquires. Factories run during layer acquisition after resource
+ * validation, and the provider factories receive the metric resource.
+ * Already-created providers keep the resource captured at construction; the
+ * resource option only sets metrics and tracer instrumentation scope for them.
+ * Ownership splits: callers own provider flushing and shutdown, including
+ * factory-built providers, while the layer scope shuts down every reader the
+ * `metricReader` factory returned. No exporter is allocated by this module.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layerOtel = (options) => {
+    const resource = resourceLayer(options.resource);
+    const tracerProvider = options.tracerProvider;
+    const loggerProvider = options.loggerProvider;
+    const tracer = tracerProvider === undefined
+        ? Layer.empty
+        : Layer.provide(OtelTracer.layer, Layer.effect(OtelTracer.OtelTracerProvider, Effect.map(Resource, (resource) => typeof tracerProvider === "function" ? tracerProvider(resource) : tracerProvider)));
+    const logger = loggerProvider === undefined
+        ? Layer.empty
+        : Layer.provide(OtelLogger.layer({ mergeWithExisting: options.loggerMergeWithExisting }), Layer.effect(OtelLogger.OtelLoggerProvider, Effect.map(Resource, (resource) => typeof loggerProvider === "function" ? loggerProvider(resource) : loggerProvider)));
+    const acquireMetricReader = options.metricReader;
+    const metrics = acquireMetricReader === undefined
+        ? Layer.empty
+        : OtelMetrics.layer(() => acquireMetricReader(), {
+            temporality: options.metricTemporality
+        });
+    return Layer.mergeAll(tracer, logger, metrics).pipe(Layer.provideMerge(resource));
+};
+/**
+ * A no-op OTEL layer for callers that want an explicit optional slot.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layerNoop = Layer.empty;
+//# sourceMappingURL=Otel.js.map

package/dist/esm/Otel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Otel.js","sourceRoot":"","sources":["../../src/Otel.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,UAAU,MAAM,kCAAkC,CAAA;AAC9D,OAAO,KAAK,WAAW,MAAM,mCAAmC,CAAA;AAChE,OAAO,KAAK,UAAU,MAAM,kCAAkC,CAAA;AAI9D,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AACrC,OAAO,EAGL,KAAK,IAAI,aAAa,EACtB,QAAQ,EACT,MAAM,eAAe,CAAA;AAqCtB;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,OAAgB,EAAoD,EAAE;IAC9F,MAAM,QAAQ,GAAG,aAAa,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAA;IAChD,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc,CAAA;IAC7C,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc,CAAA;IAC7C,MAAM,MAAM,GAAG,cAAc,KAAK,SAAS;QACzC,CAAC,CAAC,KAAK,CAAC,KAAK;QACb,CAAC,CAAC,KAAK,CAAC,OAAO,CACb,UAAU,CAAC,KAAK,EAChB,KAAK,CAAC,MAAM,CACV,UAAU,CAAC,kBAAkB,EAC7B,MAAM,CAAC,GAAG,CACR,QAAQ,EACR,CAAC,QAAQ,EAAE,EAAE,CAAC,OAAO,cAAc,KAAK,UAAU,CAAC,CAAC,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,cAAc,CAC/F,CACF,CACF,CAAA;IACH,MAAM,MAAM,GAAG,cAAc,KAAK,SAAS;QACzC,CAAC,CAAC,KAAK,CAAC,KAAK;QACb,CAAC,CAAC,KAAK,CAAC,OAAO,CACb,UAAU,CAAC,KAAK,CAAC,EAAE,iBAAiB,EAAE,OAAO,CAAC,uBAAuB,EAAE,CAAC,EACxE,KAAK,CAAC,MAAM,CACV,UAAU,CAAC,kBAAkB,EAC7B,MAAM,CAAC,GAAG,CACR,QAAQ,EACR,CAAC,QAAQ,EAAE,EAAE,CAAC,OAAO,cAAc,KAAK,UAAU,CAAC,CAAC,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,cAAc,CAC/F,CACF,CACF,CAAA;IACH,MAAM,mBAAmB,GAAG,OAAO,CAAC,YAAY,CAAA;IAChD,MAAM,OAAO,GAAG,mBAAmB,KAAK,SAAS;QAC/C,CAAC,CAAC,KAAK,CAAC,KAAK;QACb,CAAC,CAAC,WAAW,CAAC,KAAK,CACjB,GAAG,EAAE,CAAC,mBAAmB,EAA+E,EACxG;YACE,WAAW,EAAE,OAAO,CAAC,iBAAiB;SACvC,CACF,CAAA;IACH,OAAO,KAAK,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC,CAAA;AACnF,CAAC,CAAA;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,SAAS,GAAuB,KAAK,CAAC,KAAK,CAAA"}

package/dist/esm/Otlp.d.ts

@@ -0,0 +1,200 @@
+/**
+ * Default OTLP export wiring for flows telemetry.
+ *
+ * The store packages already open spans through Effect's tracer and update
+ * `Metric` counters on their hot paths; what they deliberately do not do is
+ * ship an exporter. This module is that exporter: one layer that installs
+ * Effect's own OTLP logger, metrics exporter, and tracer
+ * (`effect/unstable/observability/Otlp`) against a collector endpoint, with
+ * the flows service identity filled in. Nothing beyond `effect` is involved;
+ * no OpenTelemetry SDK dependency.
+ *
+ * Browser support is met by construction rather than by a no-op variant:
+ * export happens over Effect's `HttpClient`, and {@link layerFetch} binds the
+ * `fetch` implementation the host already has, so no entry point here ever
+ * resolves a `node:` built-in. See the
+ * {@link https://smithers.sh/docs/reference/api/observability | observability API contract}.
+ *
+ * @since 0.1.0
+ */
+import type * as Duration from "effect/Duration";
+import * as Layer from "effect/Layer";
+import * as Headers from "effect/unstable/http/Headers";
+import * as HttpClient from "effect/unstable/http/HttpClient";
+import * as Endpoint from "./Endpoint.ts";
+import * as Resource from "./Resource.ts";
+/**
+ * The `service.name` resource attribute installed when the caller supplies
+ * none: the flows distribution itself. Override it per application with
+ * {@link Options.serviceName}.
+ *
+ * @category resource
+ * @since 0.1.0
+ */
+export declare const defaultServiceName = "flows";
+/**
+ * The `service.version` resource attribute installed when the caller supplies
+ * none. Mirrors the release version in this package's `package.json`.
+ *
+ * A published package cannot read its own manifest on every runtime it
+ * supports, so the version lives here as a literal.
+ * `scripts/set-release-version.mjs` rewrites this declaration with the
+ * manifests, and its `--check` mode reports drift, so a release bump cannot
+ * leave it behind.
+ *
+ * @category resource
+ * @since 0.1.0
+ */
+export declare const defaultServiceVersion = "1.0.0-rc.4";
+/**
+ * Maximum encoded export request size, in bytes.
+ * @category transport
+ * @since 1.0.0-rc.0
+ */
+export declare const maxRequestBytes: number;
+/**
+ * Reserved bytes for request wrappers and the escaped instrumentation scope.
+ * @category transport
+ * @since 1.0.0-rc.0
+ */
+export declare const maximumEnvelopeBytes: number;
+/**
+ * Bytes of every export request kept free for the signal batch itself.
+ *
+ * The transport discards a request over 1 MiB, and the resource rides in every
+ * request, so the largest resource `Resource.decode` admits
+ * (`Resource.maximumResourceBytes`, 128 KiB) and the envelope that repeats the
+ * service name (under 8 KiB) come off the top. The 888 KiB left gives each
+ * record of a full 1,000-record logger or tracer batch about 900 bytes, three
+ * to four times a bare log record or span, and gives the metrics snapshot room
+ * for several thousand series. Every resource the decoder accepts therefore
+ * leaves an ordinary batch of any signal exportable; what this reserve does
+ * not bound is a single application record or a registry large enough to
+ * exceed it on its own.
+ *
+ * @category transport
+ * @since 1.0.0-rc.0
+ */
+export declare const reservedBatchBytes: number;
+/**
+ * Configuration for the default OTLP wiring.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Options {
+    /**
+     * The collector base URL, for example `http://localhost:4318`. Signals are
+     * posted below it at `/v1/logs`, `/v1/metrics`, and `/v1/traces`. It must be
+     * an absolute `http://` or `https://` URL without credentials, a query,
+     * fragment, backslashes, spaces, or controls. A base path is allowed. Invalid
+     * values fail acquisition with {@link Endpoint.InvalidExporterEndpoint}.
+     * Use {@link Options.headers} for authentication.
+     */
+    readonly baseUrl: string;
+    /** Overrides {@link defaultServiceName} as the `service.name` attribute. */
+    readonly serviceName?: string | undefined;
+    /** Overrides {@link defaultServiceVersion} as the `service.version` attribute. */
+    readonly serviceVersion?: string | undefined;
+    /**
+     * Additional resource attributes attached to every exported signal, decoded
+     * by `Resource.Attributes`. The whole resource must encode to at most
+     * `Resource.maximumResourceBytes`; a larger one fails acquisition with
+     * {@link Resource.InvalidResourceConfiguration} rather than making every
+     * request oversized.
+     */
+    readonly attributes?: Record<string, unknown> | undefined;
+    /**
+     * Headers sent with every export request, for example vendor auth. A header
+     * whose name names a credential (`authorization`, `x-api-key`, anything
+     * `Redaction.isSensitiveKey` recognizes, plus `x-honeycomb-team`) requires
+     * an `https://` baseUrl unless the host is loopback; otherwise acquisition
+     * fails with
+     * {@link Endpoint.InvalidExporterEndpoint}.
+     */
+    readonly headers?: Headers.Input | undefined;
+    /** Export cadence for all three signals; each signal's Effect default applies when omitted. */
+    readonly exportInterval?: Duration.Input | undefined;
+    /** Upper bound on the shutdown flush when the layer's scope closes. */
+    readonly shutdownTimeout?: Duration.Input | undefined;
+}
+/**
+ * Creates the OTLP logs, metrics, and traces layer with flows resource
+ * defaults, JSON-serialized. Exports share a four-request limit with no waiting
+ * queue. Requests larger than 1 MiB or stalled for ten seconds are discarded;
+ * `flows_observability_otlp_dropped` counts discarded batches, and at most
+ * once a minute a `Warn` record with code `otlp_export_discarded` names the
+ * reason, the request size, and the running total through the loggers that
+ * were installed when the layer was acquired, never through this exporter.
+ *
+ * **Details**
+ *
+ * The layer still requires an `HttpClient`, which is how it stays
+ * platform-neutral: a Node host may hand it `@effect/platform-node`'s Undici
+ * client (re-exported by `@smthrs/platform-node`), a browser or test
+ * hands it something else. Use {@link layerFetch} when the host's global
+ * `fetch` is good enough. On Node 26 and every browser it is.
+ * Fetch redirects are refused. Supply `FetchHttpClient.RequestInit` around
+ * the whole exporting effect to retain other fetch options; options scoped
+ * only to the supplied client's layer are replaced by the redirect policy.
+ * Other HTTP transports must independently refuse automatic redirects.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layer: (options: Options) => Layer.Layer<never, Resource.InvalidResourceConfiguration | Endpoint.InvalidExporterEndpoint, HttpClient.HttpClient>;
+/**
+ * Provides {@link layer} over the host's global `fetch`, the default wiring
+ * for a Node host, and browser-safe by construction because it never touches
+ * a `node:` built-in.
+ *
+ * **Example**
+ *
+ * ```ts
+ * import * as Otlp from "@smthrs/observability/Otlp"
+ *
+ * const Telemetry = Otlp.layerFetch({ baseUrl: "http://localhost:4318" })
+ * ```
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layerFetch: (options: Options) => Layer.Layer<never, Resource.InvalidResourceConfiguration | Endpoint.InvalidExporterEndpoint>;
+/**
+ * Why an OTLP layer refused to start.
+ *
+ * @category errors
+ * @since 1.0.0
+ */
+export type LayerError = Resource.InvalidResourceConfiguration | Endpoint.InvalidExporterEndpoint;
+/**
+ * Parses `OTEL_EXPORTER_OTLP_HEADERS`: comma-separated `key=value` pairs whose
+ * values are percent-decoded, as the OpenTelemetry exporter specification
+ * defines. A pair without `=` or with an empty key is skipped.
+ *
+ * @category environment
+ * @since 1.0.0
+ */
+export declare const parseHeaders: (value: string | undefined) => Record<string, string>;
+/**
+ * {@link layerFetch} when the environment names a collector, otherwise
+ * {@link layerNoop}.
+ *
+ * `OTEL_EXPORTER_OTLP_ENDPOINT` is the collector base URL and
+ * `OTEL_EXPORTER_OTLP_HEADERS` the headers sent with every export. An unset or
+ * empty endpoint installs no exporter at all.
+ *
+ * @category layers
+ * @since 1.0.0
+ */
+export declare const layerEnvironment: (environment: Readonly<Record<string, string | undefined>>, options?: Omit<Options, "baseUrl" | "headers">) => Layer.Layer<never, LayerError>;
+/**
+ * Exports nothing. The explicit stand-in for hosts with no collector, such as
+ * a development shell, a test, or a browser deployment that has not opted in, so
+ * wiring code can switch layers rather than branch.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layerNoop: Layer.Layer<never>;
+//# sourceMappingURL=Otlp.d.ts.map

package/dist/esm/Otlp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Otlp.d.ts","sourceRoot":"","sources":["../../src/Otlp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAMH,OAAO,KAAK,KAAK,QAAQ,MAAM,iBAAiB,CAAA;AAGhD,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AASrC,OAAO,KAAK,OAAO,MAAM,8BAA8B,CAAA;AAEvD,OAAO,KAAK,UAAU,MAAM,iCAAiC,CAAA;AAI7D,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAA;AACzC,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAA;AAEzC;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,UAAU,CAAA;AAEzC;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,qBAAqB,eAAe,CAAA;AAMjD;;;;GAIG;AACH,eAAO,MAAM,eAAe,QAAc,CAAA;AAM1C;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,QAAW,CAAA;AAE5C;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,kBAAkB,QAAyE,CAAA;AA2KxG;;;;;GAKG;AACH,MAAM,WAAW,OAAO;IACtB;;;;;;;OAOG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,4EAA4E;IAC5E,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACzC,kFAAkF;IAClF,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC5C;;;;;;OAMG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAA;IACzD;;;;;;;OAOG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,KAAK,GAAG,SAAS,CAAA;IAC5C,+FAA+F;IAC/F,QAAQ,CAAC,cAAc,CAAC,EAAE,QAAQ,CAAC,KAAK,GAAG,SAAS,CAAA;IACpD,uEAAuE;IACvE,QAAQ,CAAC,eAAe,CAAC,EAAE,QAAQ,CAAC,KAAK,GAAG,SAAS,CAAA;CACtD;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,KAAK,GAChB,SAAS,OAAO,KACf,KAAK,CAAC,KAAK,CACZ,KAAK,EACL,QAAQ,CAAC,4BAA4B,GAAG,QAAQ,CAAC,uBAAuB,EACxE,UAAU,CAAC,UAAU,CAyCpB,CAAA;AAEH;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,UAAU,GACrB,SAAS,OAAO,KACf,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,QAAQ,CAAC,4BAA4B,GAAG,QAAQ,CAAC,uBAAuB,CACnC,CAAA;AAE3D;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,QAAQ,CAAC,4BAA4B,GAAG,QAAQ,CAAC,uBAAuB,CAAA;AAEjG;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,GAAI,OAAO,MAAM,GAAG,SAAS,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAc7E,CAAA;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gBAAgB,GAC3B,aAAa,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,EACzD,UAAS,IAAI,CAAC,OAAO,EAAE,SAAS,GAAG,SAAS,CAAM,KACjD,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,UAAU,CAI/B,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,SAAS,EAAE,KAAK,CAAC,KAAK,CAAC,KAAK,CAAe,CAAA"}