@smthrs/observability 0.35.0 → 1.0.0-rc.3

package/dist/esm/Resource.js

@@ -0,0 +1,237 @@
+/**
+ * Explicit, validated OpenTelemetry resource metadata for Smithers.
+ *
+ * @since 0.1.0
+ */
+import * as OtelResource from "@effect/opentelemetry/Resource";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Schema from "effect/Schema";
+import * as OtlpResource from "effect/unstable/observability/OtlpResource";
+import { schemaIssueMessage, schemaIssuePath } from "./internal/schemaIssuePath.js";
+/**
+ * Largest service-name or service-version field accepted by a resource.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export const maximumIdentityLength = 1_024;
+/**
+ * Largest attribute key accepted by a resource.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export const maximumAttributeKeyLength = 1_024;
+/**
+ * Largest string value accepted by one resource attribute.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export const maximumAttributeStringLength = 65_536;
+/**
+ * Largest number of elements accepted in one array attribute value.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export const maximumAttributeArrayLength = 256;
+/**
+ * Largest number of attributes accepted by one resource.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export const maximumAttributes = 256;
+/**
+ * Largest OTLP/JSON encoding accepted for one whole resource, in UTF-8 bytes.
+ *
+ * The measure is the OTLP `Resource` message the exporters place in every
+ * request, `{"attributes":[{"key":…,"value":{…}}],"droppedAttributesCount":0}`
+ * with service identity and SDK-added `telemetry.sdk.name` and
+ * `telemetry.sdk.language` included, after JSON escaping and UTF-8 encoding.
+ * These SDK fields are conservatively reserved even for the default Effect
+ * exporter. Caller attributes overwritten by SDK identity or metadata are
+ * still counted. It is the bound the per-field limits cannot express: 256
+ * attributes at the string ceiling would encode to 16 MiB, and the resource
+ * rides in every export request, so the default transport, which discards a
+ * request over 1 MiB, would deliver nothing at all. 128 KiB admits one
+ * ASCII attribute at the string ceiling and leaves that transport 888 KiB of every
+ * request for the signal batch; see `Otlp.reservedBatchBytes`.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export const maximumResourceBytes = 131_072;
+const loneSurrogate = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
+const embeddedNul = new RegExp(String.fromCharCode(0));
+const isWellFormed = (value) => !loneSurrogate.test(value) && !embeddedNul.test(value);
+const identity = Schema.NonEmptyString.check(Schema.isMaxLength(maximumIdentityLength), Schema.makeFilter((value) => isWellFormed(value), { title: "wellFormedResourceIdentity" }));
+const attributeString = Schema.String.check(Schema.isMaxLength(maximumAttributeStringLength), Schema.makeFilter((value) => isWellFormed(value), { title: "wellFormedAttributeString" }));
+const attributeNumber = Schema.Number.check(Schema.makeFilter((value) => Number.isFinite(value), { title: "finiteAttributeNumber" }));
+/**
+ * Runtime schema for one OpenTelemetry resource attribute value.
+ *
+ * @category schemas
+ * @since 1.0.0-rc.0
+ */
+export const AttributeValue = Schema.Union([
+    attributeString,
+    attributeNumber,
+    Schema.Boolean,
+    Schema.Array(attributeString),
+    Schema.Array(attributeNumber),
+    Schema.Array(Schema.Boolean)
+]).check(Schema.makeFilter((value) => !Array.isArray(value) || value.length <= maximumAttributeArrayLength || {
+    path: [],
+    issue: `holds ${value.length} elements, over the ${maximumAttributeArrayLength} element limit`
+}, { title: "boundedResourceAttributeArrays" }));
+/**
+ * Runtime schema for OpenTelemetry resource attributes.
+ *
+ * @category schemas
+ * @since 1.0.0-rc.0
+ */
+export const Attributes = Schema.Record(Schema.String, AttributeValue).check(Schema.makeFilter((attributes) => Object.keys(attributes).length <= maximumAttributes, { title: "boundedResourceAttributes" }), Schema.makeFilter((attributes) => Object.keys(attributes).every((key) => key.length > 0 && key.length <= maximumAttributeKeyLength && isWellFormed(key)), { title: "wellFormedResourceAttributeKeys" }));
+const encoder = new TextEncoder();
+/**
+ * Counts OTLP JSON fragments, including keys, wrappers, escaping and UTF-8.
+ * Stops at the first fragment over budget: the refusal reports a lower bound.
+ * A configuration may reuse one large string in thousands of array slots, so
+ * serializing the whole resource before checking could allocate gigabytes.
+ */
+const encodedResourceBytes = (configuration) => {
+    const bytes = (value) => encoder.encode(JSON.stringify(value)).byteLength;
+    const identityAttributes = OtelResource.configToAttributes({
+        serviceName: configuration.serviceName,
+        ...(configuration.serviceVersion === undefined ? {} : { serviceVersion: configuration.serviceVersion })
+    });
+    // Use the pinned SDK projection so its added metadata cannot escape the
+    // complete-resource ceiling. Both exporters use these OTLP AnyValue shapes.
+    let total = bytes({
+        attributes: OtlpResource.entriesToAttributes(Object.entries(identityAttributes)),
+        droppedAttributesCount: 0
+    });
+    for (const [key, value] of Object.entries(configuration.attributes ?? {})) {
+        // An identity attribute is always present, so every addition needs a comma.
+        total += 1 + bytes({ key, value: Array.isArray(value) ? { arrayValue: { values: [] } } : null });
+        if (Array.isArray(value)) {
+            for (const [index, element] of value.entries()) {
+                total += (index === 0 ? 0 : 1) + bytes(OtlpResource.unknownToAttributeValue(element));
+                if (total > maximumResourceBytes)
+                    return total;
+            }
+        }
+        else {
+            total += bytes(OtlpResource.unknownToAttributeValue(value)) - 4; // replace JSON null
+        }
+        if (total > maximumResourceBytes)
+            return total;
+    }
+    return total;
+};
+/**
+ * Runtime schema for the service identity attached to exported telemetry.
+ *
+ * @category schemas
+ * @since 1.0.0-rc.0
+ */
+export const Configuration = Schema.Struct({
+    serviceName: identity,
+    serviceVersion: Schema.optional(identity),
+    attributes: Schema.optional(Attributes)
+}).check(Schema.makeFilter((configuration) => {
+    const bytes = encodedResourceBytes(configuration);
+    // Only attributes can carry a resource past the budget: the two identity
+    // fields encode to at most 6 KiB each, so the refusal points there.
+    return bytes <= maximumResourceBytes || {
+        path: ["attributes"],
+        issue: `bring the resource to at least ${bytes} bytes of OTLP JSON, over the ${maximumResourceBytes} byte limit`
+    };
+}, { title: "boundedResourceBytes" }));
+/**
+ * Stable resource-configuration refusal shared by every OTEL layer.
+ *
+ * @category errors
+ * @since 1.0.0-rc.0
+ */
+export class InvalidResourceConfiguration extends Schema.TaggedError()("@smthrs/observability/InvalidResourceConfiguration", {
+    code: Schema.Literal("invalid_resource_configuration"),
+    path: Schema.String,
+    message: Schema.String
+}) {
+}
+const invalid = (cause) => {
+    const path = schemaIssuePath(cause, "resource");
+    return new InvalidResourceConfiguration({
+        code: "invalid_resource_configuration",
+        path,
+        message: `OpenTelemetry resource ${path} ${schemaIssueMessage(cause) ?? "is invalid"}`
+    });
+};
+/**
+ * Decodes one resource configuration without retaining rejected values.
+ *
+ * @category decoding
+ * @since 1.0.0-rc.0
+ */
+export const decode = (configuration) => Schema.decodeUnknownEffect(Configuration)(configuration).pipe(Effect.mapError(invalid));
+/**
+ * Decodes one resource configuration for the package's pure projection API.
+ *
+ * @category decoding
+ * @since 1.0.0-rc.0
+ */
+export const decodeSync = (configuration) => {
+    try {
+        return Schema.decodeUnknownSync(Configuration)(configuration);
+    }
+    catch (cause) {
+        throw invalid(cause);
+    }
+};
+/**
+ * Projects a decoded resource into the exact optional-property shape expected
+ * by the OpenTelemetry SDK.
+ *
+ * @category conversions
+ * @since 1.0.0-rc.0
+ */
+export const toOpenTelemetryConfiguration = (configuration) => ({
+    serviceName: configuration.serviceName,
+    ...(configuration.serviceVersion === undefined ? {} : { serviceVersion: configuration.serviceVersion }),
+    ...(configuration.attributes === undefined
+        ? {}
+        : {
+            attributes: Object.fromEntries(Object.entries(configuration.attributes).map(([key, value]) => [
+                key,
+                Array.isArray(value) ? [...value] : value
+            ]))
+        })
+});
+/**
+ * Converts explicit service metadata into OpenTelemetry resource attributes.
+ *
+ * No environment variables are read. Invalid metadata throws the same typed
+ * {@link InvalidResourceConfiguration} every layer returns during acquisition.
+ *
+ * @category conversions
+ * @since 1.0.0-rc.0
+ */
+export const configToAttributes = (configuration) => OtelResource.configToAttributes(toOpenTelemetryConfiguration(decodeSync(configuration)));
+/**
+ * Provides an explicitly validated OpenTelemetry resource.
+ *
+ * @category layers
+ * @since 1.0.0-rc.0
+ */
+export const layer = (configuration) => Layer.unwrap(Effect.map(decode(configuration), (decoded) => OtelResource.layer(toOpenTelemetryConfiguration(decoded))));
+/**
+ * The OpenTelemetry resource service.
+ *
+ * @category services
+ * @since 1.0.0-rc.0
+ */
+export const Resource = OtelResource.Resource;
+//# sourceMappingURL=Resource.js.map

package/dist/esm/Resource.js.map

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

package/dist/esm/index.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Observability for flows: the default OTLP export wiring plus the
+ * Effect-native logger, metric, and OpenTelemetry resource layers.
+ *
+ * The store packages define and update their own metric handles
+ * (`JournalMetrics`, `RunStoreMetrics`, `CacheStoreMetrics`,
+ * `ArtifactStoreMetrics`, `DatabaseMetrics`) and open spans through Effect's
+ * tracer; this package is the exporter they deliberately leave out. `Otlp`
+ * only composes what `effect` already ships, so it is browser-bundleable. The
+ * remaining modules are the fuller stack folded in from the agent workspace:
+ * a structured `Logger`, a `JournalLogger` that mirrors log events into the
+ * run journal, `Metric` helpers, the `Resource` descriptor, and the `Otel`
+ * layer the OpenTelemetry SDK wiring installs behind.
+ *
+ * `NodeOtel` and `BrowserOtel` are deliberately NOT re-exported here. Each
+ * resolves a host-specific OpenTelemetry SDK. `NodeOtel` reaches Node-only
+ * host modules through `@effect/opentelemetry/NodeSdk` and
+ * `@opentelemetry/sdk-trace-node`, including the bare `async_hooks` specifier
+ * `@opentelemetry/context-async-hooks` imports, so re-exporting it would put a
+ * module a browser bundler cannot resolve in the root entry and break the
+ * browser bundle this package guarantees. Import them by subpath instead:
+ * `@smthrs/observability/NodeOtel`.
+ *
+ * @since 0.1.0
+ */
+/**
+ * @category layers
+ * @since 0.1.0
+ */
+export * as Otlp from "./Otlp.ts";
+/**
+ * @category observability
+ * @since 1.0.0-rc.0
+ */
+export * as Endpoint from "./Endpoint.ts";
+/**
+ * @category observability
+ * @since 0.1.0
+ */
+export * as JournalLogger from "./JournalLogger.ts";
+/**
+ * @category observability
+ * @since 0.1.0
+ */
+export * as Logger from "./Logger.ts";
+/**
+ * @category observability
+ * @since 0.1.0
+ */
+export * as Metric from "./Metric.ts";
+/**
+ * @category observability
+ * @since 0.1.0
+ */
+export * as Otel from "./Otel.ts";
+/**
+ * @category observability
+ * @since 0.1.0
+ */
+export * as Resource from "./Resource.ts";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH;;;GAGG;AACH,OAAO,KAAK,IAAI,MAAM,WAAW,CAAA;AAEjC;;;GAGG;AACH,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAA;AAEzC;;;GAGG;AACH,OAAO,KAAK,aAAa,MAAM,oBAAoB,CAAA;AAEnD;;;GAGG;AACH,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AAErC;;;GAGG;AACH,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AAErC;;;GAGG;AACH,OAAO,KAAK,IAAI,MAAM,WAAW,CAAA;AAEjC;;;GAGG;AACH,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAA"}

package/dist/esm/index.js

@@ -0,0 +1,61 @@
+/**
+ * Observability for flows: the default OTLP export wiring plus the
+ * Effect-native logger, metric, and OpenTelemetry resource layers.
+ *
+ * The store packages define and update their own metric handles
+ * (`JournalMetrics`, `RunStoreMetrics`, `CacheStoreMetrics`,
+ * `ArtifactStoreMetrics`, `DatabaseMetrics`) and open spans through Effect's
+ * tracer; this package is the exporter they deliberately leave out. `Otlp`
+ * only composes what `effect` already ships, so it is browser-bundleable. The
+ * remaining modules are the fuller stack folded in from the agent workspace:
+ * a structured `Logger`, a `JournalLogger` that mirrors log events into the
+ * run journal, `Metric` helpers, the `Resource` descriptor, and the `Otel`
+ * layer the OpenTelemetry SDK wiring installs behind.
+ *
+ * `NodeOtel` and `BrowserOtel` are deliberately NOT re-exported here. Each
+ * resolves a host-specific OpenTelemetry SDK. `NodeOtel` reaches Node-only
+ * host modules through `@effect/opentelemetry/NodeSdk` and
+ * `@opentelemetry/sdk-trace-node`, including the bare `async_hooks` specifier
+ * `@opentelemetry/context-async-hooks` imports, so re-exporting it would put a
+ * module a browser bundler cannot resolve in the root entry and break the
+ * browser bundle this package guarantees. Import them by subpath instead:
+ * `@smthrs/observability/NodeOtel`.
+ *
+ * @since 0.1.0
+ */
+/**
+ * @category layers
+ * @since 0.1.0
+ */
+export * as Otlp from "./Otlp.js";
+/**
+ * @category observability
+ * @since 1.0.0-rc.0
+ */
+export * as Endpoint from "./Endpoint.js";
+/**
+ * @category observability
+ * @since 0.1.0
+ */
+export * as JournalLogger from "./JournalLogger.js";
+/**
+ * @category observability
+ * @since 0.1.0
+ */
+export * as Logger from "./Logger.js";
+/**
+ * @category observability
+ * @since 0.1.0
+ */
+export * as Metric from "./Metric.js";
+/**
+ * @category observability
+ * @since 0.1.0
+ */
+export * as Otel from "./Otel.js";
+/**
+ * @category observability
+ * @since 0.1.0
+ */
+export * as Resource from "./Resource.js";
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH;;;GAGG;AACH,OAAO,KAAK,IAAI,MAAM,WAAW,CAAA;AAEjC;;;GAGG;AACH,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAA;AAEzC;;;GAGG;AACH,OAAO,KAAK,aAAa,MAAM,oBAAoB,CAAA;AAEnD;;;GAGG;AACH,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AAErC;;;GAGG;AACH,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AAErC;;;GAGG;AACH,OAAO,KAAK,IAAI,MAAM,WAAW,CAAA;AAEjC;;;GAGG;AACH,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAA"}

package/dist/esm/internal/schemaIssuePath.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The decoder-issue walk shared by this package's refusals.
+ *
+ * `JournalLogger` and `Resource` both publish the path of the option a decode
+ * rejected, and `Resource` also publishes the measured size a budget filter
+ * attached to its refusal. Effect's issues nest the same way for both, so the
+ * traversal lives once and a decoder change is followed once.
+ *
+ * @private
+ * @since 1.0.0-rc.0
+ */
+/**
+ * Walks a decode failure to the dotted path of the value it refused.
+ *
+ * Returns the caller's domain name when the failure carries no path at all.
+ *
+ * @private
+ * @since 1.0.0-rc.0
+ */
+export declare const schemaIssuePath: (error: unknown, fallback: string) => string;
+/**
+ * Reads the message a filter attached to the value a decode refused, when the
+ * filter attached one. None of the Effect checks this package composes attach
+ * one, so a refusal only ever carries text this package wrote, never the
+ * rejected value.
+ *
+ * @private
+ * @since 1.0.0-rc.0
+ */
+export declare const schemaIssueMessage: (error: unknown) => string | undefined;
+//# sourceMappingURL=schemaIssuePath.d.ts.map

package/dist/esm/internal/schemaIssuePath.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemaIssuePath.d.ts","sourceRoot":"","sources":["../../../src/internal/schemaIssuePath.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AA+BH;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,GAAI,OAAO,OAAO,EAAE,UAAU,MAAM,KAAG,MAAoD,CAAA;AAEvH;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,GAAI,OAAO,OAAO,KAAG,MAAM,GAAG,SAI5D,CAAA"}

package/dist/esm/internal/schemaIssuePath.js

@@ -0,0 +1,59 @@
+/**
+ * The decoder-issue walk shared by this package's refusals.
+ *
+ * `JournalLogger` and `Resource` both publish the path of the option a decode
+ * rejected, and `Resource` also publishes the measured size a budget filter
+ * attached to its refusal. Effect's issues nest the same way for both, so the
+ * traversal lives once and a decoder change is followed once.
+ *
+ * @private
+ * @since 1.0.0-rc.0
+ */
+/**
+ * Walks a decode failure to its first offending leaf, collecting the path
+ * segments passed on the way. The walk is bounded so a self-referential issue
+ * tree cannot spin.
+ */
+const walk = (error) => {
+    let issue = error?.issue;
+    const segments = [];
+    for (let depth = 0; depth < 64 && typeof issue === "object" && issue !== null; depth++) {
+        const node = issue;
+        if (Array.isArray(node.path))
+            segments.push(...node.path.map(String));
+        if (node.issue !== undefined) {
+            issue = node.issue;
+            continue;
+        }
+        if (Array.isArray(node.issues) && node.issues[0] !== undefined) {
+            issue = node.issues[0];
+            continue;
+        }
+        break;
+    }
+    return { segments, leaf: issue };
+};
+/**
+ * Walks a decode failure to the dotted path of the value it refused.
+ *
+ * Returns the caller's domain name when the failure carries no path at all.
+ *
+ * @private
+ * @since 1.0.0-rc.0
+ */
+export const schemaIssuePath = (error, fallback) => walk(error).segments.join(".") || fallback;
+/**
+ * Reads the message a filter attached to the value a decode refused, when the
+ * filter attached one. None of the Effect checks this package composes attach
+ * one, so a refusal only ever carries text this package wrote, never the
+ * rejected value.
+ *
+ * @private
+ * @since 1.0.0-rc.0
+ */
+export const schemaIssueMessage = (error) => {
+    const leaf = walk(error).leaf;
+    const message = leaf?.annotations?.message;
+    return typeof message === "string" ? message : undefined;
+};
+//# sourceMappingURL=schemaIssuePath.js.map

package/dist/esm/internal/schemaIssuePath.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemaIssuePath.js","sourceRoot":"","sources":["../../../src/internal/schemaIssuePath.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAOH;;;;GAIG;AACH,MAAM,IAAI,GAAG,CAAC,KAAc,EAAa,EAAE;IACzC,IAAI,KAAK,GAAI,KAA6C,EAAE,KAAK,CAAA;IACjE,MAAM,QAAQ,GAAkB,EAAE,CAAA;IAClC,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,EAAE,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACvF,MAAM,IAAI,GAAG,KAAyF,CAAA;QACtG,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC;YAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAA;QACrE,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;YAC7B,KAAK,GAAG,IAAI,CAAC,KAAK,CAAA;YAClB,SAAQ;QACV,CAAC;QACD,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,SAAS,EAAE,CAAC;YAC/D,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAA;YACtB,SAAQ;QACV,CAAC;QACD,MAAK;IACP,CAAC;IACD,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,CAAA;AAClC,CAAC,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,KAAc,EAAE,QAAgB,EAAU,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,QAAQ,CAAA;AAEvH;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,KAAc,EAAsB,EAAE;IACvE,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,IAAoF,CAAA;IAC7G,MAAM,OAAO,GAAG,IAAI,EAAE,WAAW,EAAE,OAAO,CAAA;IAC1C,OAAO,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAA;AAC1D,CAAC,CAAA"}

package/docs/README.md

@@ -0,0 +1,162 @@
+---
+title: "@smthrs/observability"
+description: "Send an Effect program's logs, metrics, and traces to an OpenTelemetry collector with one layer, no OpenTelemetry SDK, and a collector endpoint that is validated before anything exports."
+---
+
+`@smthrs/observability` sends an Effect program's logs, metrics, and traces to
+an OpenTelemetry collector. You add one layer to turn delivery on, and delete
+that one line to turn it off; nothing else in the program changes.
+
+## What it solves
+
+An Effect program already produces telemetry without an exporter.
+`Effect.withSpan` opens a span on Effect's tracer, `Metric.update` advances a
+counter in Effect's metric registry, and `Effect.logInfo` writes a log record.
+With nothing installed to deliver them, all three are collected and discarded.
+
+The usual way to deliver them is an OpenTelemetry SDK: several packages, a
+provider for each signal, and a bundle a browser build cannot carry. This
+package is the smaller answer for the common case. `Otlp` composes only what
+`effect` itself ships, so it pulls in no OpenTelemetry SDK, runs unchanged in
+Node, Bun, and a browser, and posts all three signals to a collector over the
+host's global `fetch`.
+
+Two behaviors matter beyond the delivery itself:
+
+- **A bad endpoint is refused at startup.** Export failure is absorbed by
+  design, so an exporter pointed at `collector:4318` or at a URL with a
+  trailing newline behaves exactly like a healthy one and delivers nothing
+  forever. Endpoints and service identities are decoded when the layer is
+  built, and a bad one fails there with a typed error.
+- **Log records can also go somewhere durable.** `JournalLogger` mirrors a
+  run's log records into a run journal, so an operator reads them back in
+  process without standing up a collector at all.
+
+When one layer is not enough, `NodeOtel`, `BrowserOtel`, and `Otel` wire a real
+OpenTelemetry SDK, and every builder attaches the same validated service
+identity, so `service.name` means the same thing whichever one you pick.
+
+## Install
+
+Not on npm yet; see [Installation](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/flow/docs/installation.md#use-the-libraries).
+
+Node.js 26.4.0 or later. For the import forms and the browser rule, see
+[Installation](./installation.md).
+
+## Export all three signals
+
+```ts
+import * as Otlp from "@smthrs/observability/Otlp"
+import * as Effect from "effect/Effect"
+import * as Metric from "effect/Metric"
+
+const deployments = Metric.counter("deployments")
+
+const program = Effect.gen(function*() {
+  yield* Effect.logInfo("deploying the API")
+  yield* Metric.update(deployments, 1)
+}).pipe(Effect.withSpan("deploy"))
+
+const telemetry = Otlp.layerFetch({
+  baseUrl: "http://localhost:4318",
+  serviceName: "deploy-status"
+})
+
+await Effect.runPromise(
+  program.pipe(Effect.provide(telemetry), Effect.orDie, Effect.scoped)
+)
+```
+
+The span posts to the collector's `/v1/traces` path, the log record to
+`/v1/logs`, and the counter to `/v1/metrics`, all tagged `service.name:
+deploy-status`. The exporters batch, so closing the layer's scope is what
+flushes them: that is why the program ends in `Effect.scoped`. The
+[Quickstart](./quickstart.md) runs this against a twelve-line collector
+stand-in so you can watch each signal land.
+
+## How this fits with @smthrs/flows
+
+Smithers is a durable flow engine: a flow records each step as it completes, so
+a process that dies replays what already finished and resumes at the first step
+that did not. [`@smthrs/flows`](/api/flows) is the single npm package that
+carries that whole engine, and it re-exports this one as its `Observability`
+namespace. A program that already depends on `@smthrs/flows` has these layers
+available without adding a dependency:
+
+```ts
+import { Observability } from "@smthrs/flows"
+
+const telemetry = Observability.Otlp.layerFetch({
+  baseUrl: "http://localhost:4318",
+  serviceName: "deploy-status"
+})
+```
+
+That relationship is also why this package ships more than an exporter. The
+engine packages under `@smthrs/flows` instrument themselves: they open spans on
+Effect's tracer and update their own metric handles on their hot paths, and
+none of them allocates an exporter. Providing one layer from this package turns
+delivery on for all of that instrumentation at once. The `JournalLogger` and
+`Metric` modules exist for the same reason: a run journal and a shared set of
+runtime metric handles are what a durable engine needs and a standalone
+exporter does not.
+
+You do not need the engine to use this package. `Otlp`, `Logger`, `Resource`,
+`Otel`, `NodeOtel`, and `BrowserOtel` work in any Effect program. Only
+`JournalLogger` requires a journal, from [`@smthrs/journal`](/api/journal).
+
+Above `@smthrs/flows` sits [`smithers`](/api/cli), the command-line interface
+that runs, resumes, and inspects flows. Start there if you want to run flows
+rather than embed the engine in your own program.
+
+## Who uses this package
+
+Host and CLI authors install the exporter, a logger, and, for a control-plane
+run, the journal forwarder. Operators read the result: spans and metric series
+in a collector, `telemetry.log` rows on a run's journal. Authors of the engine
+packages use `Metric` to update a shared runtime handle, and touch nothing else
+here.
+
+## The package at a glance
+
+The root entry point exports these namespaces, and each is also importable from
+`@smthrs/observability/<Module>`:
+
+| Namespace       | What it is                                                                                            |
+| --------------- | ----------------------------------------------------------------------------------------------------- |
+| `Otlp`          | The default exporter: one layer that posts logs, metrics, and traces to a collector, no SDK involved. |
+| `Endpoint`      | The validated collector endpoint every OTLP builder decodes before it exports anything.               |
+| `Resource`      | The validated service identity attached to every exported signal.                                     |
+| `Logger`        | Effect logger layers: pretty for development, one JSON object per line for production, and silence.   |
+| `JournalLogger` | A bounded, drop-on-overflow forwarder that mirrors log records into a run's durable journal.          |
+| `Metric`        | The four runtime metric handles the engine packages update, and their exported identifiers.           |
+| `Otel`          | The provider-neutral bridge for an OpenTelemetry SDK the application already built.                   |
+
+Two more modules are subpath-only, because each resolves a host-specific
+OpenTelemetry SDK:
+
+| Import                              | What it is                                                              |
+| ----------------------------------- | ----------------------------------------------------------------------- |
+| `@smthrs/observability/NodeOtel`    | Node OTLP/HTTP wiring over the OpenTelemetry SDK. Node only.            |
+| `@smthrs/observability/BrowserOtel` | Browser OpenTelemetry wiring over processors and readers you construct. |
+
+Every export, with signatures and failure types, is on the
+[API reference](./api.md).
+
+## Where to go next
+
+- [Installation](./installation.md): requirements, import forms, and which
+  packages a real composition adds.
+- [Quickstart](./quickstart.md): export a trace, a log record, and a metric
+  series to a collector you can watch, in about thirty lines.
+- Guides: [export to a collector](./guides/export-to-a-collector.md),
+  [wire an OpenTelemetry SDK](./guides/wire-an-opentelemetry-sdk.md),
+  [forward logs to the journal](./guides/forward-logs-to-the-journal.md),
+  [install a logger](./guides/install-a-logger.md),
+  [read the runtime metrics](./guides/read-runtime-metrics.md), and
+  [test telemetry without a collector](./guides/testing.md).
+- Concepts: [instrumentation and export](./concepts/instrumentation-and-export.md),
+  [the layer map](./concepts/layer-map.md), and
+  [validation at layer acquisition](./concepts/validated-acquisition.md).
+- [Troubleshooting](./troubleshooting.md): the typed refusals this package
+  reports, and the silent cases that are not refusals at all.