@smthrs/observability 0.35.0 → 1.0.0-rc.12

package/package.json

@@ -1,48 +1,237 @@
 {
   "name": "@smthrs/observability",
-  "version": "0.35.0",
-  "description": "Concrete Smithers metrics, logging, tracing, and observability integrations",
   "type": "module",
-  "sideEffects": false,
+  "version": "1.0.0-rc.12",
+  "license": "MIT",
+  "smthrs": {
+    "group": "engine"
+  },
+  "description": "Observability for flows: default OTLP export wiring plus Effect-native logger, metric, and OpenTelemetry SDK layers",
+  "homepage": "https://github.com/smithersai/smithers",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/smithersai/smithers.git",
+    "directory": "packages/smithers/flows/observability"
+  },
+  "bugs": {
+    "url": "https://github.com/smithersai/smithers/issues"
+  },
+  "tags": [
+    "typescript",
+    "effect",
+    "observability",
+    "opentelemetry"
+  ],
+  "keywords": [
+    "typescript",
+    "effect",
+    "observability",
+    "opentelemetry"
+  ],
+  "engines": {
+    "node": ">=26.4.0"
+  },
+  "sideEffects": [],
   "exports": {
+    "./package.json": "./package.json",
     ".": {
-      "types": "./src/index.d.ts",
-      "import": "./src/index.js",
-      "default": "./src/index.js"
-    },
-    "./metrics": {
-      "types": "./src/metrics/index.d.ts",
-      "import": "./src/metrics/index.js",
-      "default": "./src/metrics/index.js"
-    },
-    "./*": {
-      "types": "./src/index.d.ts",
-      "import": "./src/*.js",
-      "default": "./src/*.js"
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./BrowserOtel": {
+      "import": {
+        "types": "./dist/esm/BrowserOtel.d.ts",
+        "default": "./dist/esm/BrowserOtel.js"
+      },
+      "require": {
+        "types": "./dist/cjs/BrowserOtel.d.ts",
+        "default": "./dist/cjs/BrowserOtel.js"
+      }
+    },
+    "./Endpoint": {
+      "import": {
+        "types": "./dist/esm/Endpoint.d.ts",
+        "default": "./dist/esm/Endpoint.js"
+      },
+      "require": {
+        "types": "./dist/cjs/Endpoint.d.ts",
+        "default": "./dist/cjs/Endpoint.js"
+      }
+    },
+    "./JournalLogger": {
+      "import": {
+        "types": "./dist/esm/JournalLogger.d.ts",
+        "default": "./dist/esm/JournalLogger.js"
+      },
+      "require": {
+        "types": "./dist/cjs/JournalLogger.d.ts",
+        "default": "./dist/cjs/JournalLogger.js"
+      }
+    },
+    "./Logger": {
+      "import": {
+        "types": "./dist/esm/Logger.d.ts",
+        "default": "./dist/esm/Logger.js"
+      },
+      "require": {
+        "types": "./dist/cjs/Logger.d.ts",
+        "default": "./dist/cjs/Logger.js"
+      }
+    },
+    "./Metric": {
+      "import": {
+        "types": "./dist/esm/Metric.d.ts",
+        "default": "./dist/esm/Metric.js"
+      },
+      "require": {
+        "types": "./dist/cjs/Metric.d.ts",
+        "default": "./dist/cjs/Metric.js"
+      }
+    },
+    "./NodeOtel": {
+      "import": {
+        "types": "./dist/esm/NodeOtel.d.ts",
+        "default": "./dist/esm/NodeOtel.js"
+      },
+      "require": {
+        "types": "./dist/cjs/NodeOtel.d.ts",
+        "default": "./dist/cjs/NodeOtel.js"
+      }
+    },
+    "./Otel": {
+      "import": {
+        "types": "./dist/esm/Otel.d.ts",
+        "default": "./dist/esm/Otel.js"
+      },
+      "require": {
+        "types": "./dist/cjs/Otel.d.ts",
+        "default": "./dist/cjs/Otel.js"
+      }
+    },
+    "./Otlp": {
+      "import": {
+        "types": "./dist/esm/Otlp.d.ts",
+        "default": "./dist/esm/Otlp.js"
+      },
+      "require": {
+        "types": "./dist/cjs/Otlp.d.ts",
+        "default": "./dist/cjs/Otlp.js"
+      }
+    },
+    "./Resource": {
+      "import": {
+        "types": "./dist/esm/Resource.d.ts",
+        "default": "./dist/esm/Resource.js"
+      },
+      "require": {
+        "types": "./dist/cjs/Resource.d.ts",
+        "default": "./dist/cjs/Resource.js"
+      }
+    },
+    "./index": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
     }
   },
   "files": [
-    "src/",
-    "docker-compose.otel.yml",
-    "otel-collector-config.yml",
-    "prometheus/",
-    "tempo/",
-    "loki/",
-    "grafana/"
+    "src/**/*.ts",
+    "dist/**/*.js",
+    "dist/**/*.js.map",
+    "dist/**/*.d.ts",
+    "dist/**/*.d.ts.map",
+    "dist/**/package.json",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md",
+    "docs/"
   ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true,
+    "tag": "next"
+  },
   "dependencies": {
-    "@effect/opentelemetry": "4.0.0-beta.105",
-    "@effect/platform-bun": "4.0.0-beta.105",
-    "@effect/platform-node-shared": "4.0.0-beta.105",
-    "effect": "4.0.0-beta.105"
+    "@opentelemetry/sdk-logs": "0.222.0",
+    "@opentelemetry/sdk-metrics": "2.11.0",
+    "@smthrs/journal": "1.0.0-rc.12",
+    "@effect/opentelemetry": "4.0.4"
   },
   "devDependencies": {
-    "@types/bun": "latest",
-    "typescript": "~6.0.3"
+    "@effect/language-service": "0.87.2",
+    "@effect/opentelemetry": "4.0.4",
+    "@effect/vitest": "4.0.4",
+    "@eslint/js": "9.39.5",
+    "@opentelemetry/api": "1.9.1",
+    "@opentelemetry/exporter-logs-otlp-http": "0.222.0",
+    "@opentelemetry/exporter-metrics-otlp-http": "0.222.0",
+    "@opentelemetry/exporter-trace-otlp-http": "0.222.0",
+    "@opentelemetry/sdk-trace-base": "2.11.0",
+    "@opentelemetry/sdk-trace-node": "2.11.0",
+    "@opentelemetry/sdk-trace-web": "2.11.0",
+    "@types/node": "26.4.1",
+    "@vitest/coverage-v8": "5.0.0",
+    "dprint": "0.57.1",
+    "effect": "4.0.4",
+    "esbuild": "0.28.2",
+    "eslint": "9.39.5",
+    "eslint-import-resolver-typescript": "4.4.5",
+    "eslint-plugin-import": "2.32.0",
+    "eslint-plugin-jsdoc": "64.3.4",
+    "eslint-plugin-unicorn": "65.0.0",
+    "madge": "8.0.0",
+    "typescript": "5.9.3",
+    "typescript-eslint": "8.69.0",
+    "vitest": "5.0.0"
+  },
+  "peerDependencies": {
+    "@opentelemetry/api": ">=1.9.1 <2.0.0",
+    "@opentelemetry/exporter-logs-otlp-http": ">=0.222.0 <0.300.0",
+    "@opentelemetry/exporter-metrics-otlp-http": ">=0.222.0 <0.300.0",
+    "@opentelemetry/exporter-trace-otlp-http": ">=0.222.0 <0.300.0",
+    "@opentelemetry/sdk-trace-base": ">=2.11.0 <3.0.0",
+    "@opentelemetry/sdk-trace-node": ">=2.11.0 <3.0.0",
+    "@opentelemetry/sdk-trace-web": ">=2.11.0 <3.0.0",
+    "effect": "^4.0.4"
+  },
+  "peerDependenciesMeta": {
+    "@opentelemetry/exporter-logs-otlp-http": {
+      "optional": true
+    },
+    "@opentelemetry/exporter-metrics-otlp-http": {
+      "optional": true
+    },
+    "@opentelemetry/exporter-trace-otlp-http": {
+      "optional": true
+    },
+    "@opentelemetry/sdk-trace-base": {
+      "optional": true
+    },
+    "@opentelemetry/sdk-trace-node": {
+      "optional": true
+    },
+    "@opentelemetry/sdk-trace-web": {
+      "optional": true
+    }
   },
   "scripts": {
-    "build": "rm -f src/index.d.ts src/metrics/index.d.ts src/*-*.d.ts && tsup --dts-only",
-    "test": "bun test tests",
-    "typecheck": "tsc -p tsconfig.json --noEmit"
+    "lint": "eslint src --max-warnings=0 && dprint check",
+    "format": "dprint fmt",
+    "build": "node scripts/build.mjs",
+    "check": "tsc -b tsconfig.json && tsc -p tsconfig.test.json --noEmit",
+    "circular": "node scripts/circular.mjs",
+    "test": "vitest",
+    "coverage": "vitest --coverage"
   }
 }

package/src/BrowserOtel.ts

@@ -0,0 +1,51 @@
+/**
+ * Browser OpenTelemetry setup with explicitly injected providers/readers.
+ *
+ * @since 0.1.0
+ */
+
+import * as WebSdk from "@effect/opentelemetry/WebSdk"
+import type { LogRecordProcessor } from "@opentelemetry/sdk-logs"
+import type { MetricReader } from "@opentelemetry/sdk-metrics"
+import type { SpanProcessor } from "@opentelemetry/sdk-trace-base"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import * as Resource from "./Resource.ts"
+import type { Configuration as ResourceConfiguration } from "./Resource.ts"
+
+/**
+ * Browser OTEL layer options. Processors and readers are created by the
+ * caller's factories, which keeps this module free of Node imports and browser
+ * exporter policy. Every factory is owned: it runs once during layer
+ * acquisition, after resource validation, and the layer scope shuts down
+ * everything it returned. An empty array installs nothing for that signal.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Options {
+  readonly resource: ResourceConfiguration
+  readonly spanProcessor?: (() => SpanProcessor | ReadonlyArray<SpanProcessor>) | undefined
+  readonly logRecordProcessor?: (() => LogRecordProcessor | ReadonlyArray<LogRecordProcessor>) | undefined
+  readonly metricReader?: (() => MetricReader | ReadonlyArray<MetricReader>) | undefined
+  readonly loggerMergeWithExisting?: boolean | undefined
+}
+
+/**
+ * Builds a scoped browser OpenTelemetry layer. The web SDK owns every
+ * processor and reader the factories return and shuts them down on release.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layerOtel = (options: Options): Layer.Layer<never, Resource.InvalidResourceConfiguration> =>
+  Layer.unwrap(
+    Effect.map(Resource.decode(options.resource), (decoded) =>
+      WebSdk.layer(() => ({
+        resource: Resource.toOpenTelemetryConfiguration(decoded),
+        spanProcessor: options.spanProcessor?.(),
+        logRecordProcessor: options.logRecordProcessor?.(),
+        metricReader: options.metricReader?.(),
+        loggerMergeWithExisting: options.loggerMergeWithExisting
+      })))
+  )

package/src/Endpoint.ts

@@ -0,0 +1,131 @@
+/**
+ * Validated collector endpoints for the OTLP exporters.
+ *
+ * The endpoint is the field an operator most often gets wrong, and a wrong one
+ * is invisible: Effect's exporter absorbs export failure by design, so a layer
+ * built against `""` or `"localhost:4318"` looks identical to a working one and
+ * simply never delivers. Every builder therefore decodes its endpoint during
+ * layer acquisition, the same posture `Resource` already takes.
+ *
+ * @since 1.0.0-rc.0
+ */
+
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+
+/**
+ * Largest collector endpoint accepted by a builder.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export const maximumEndpointLength = 2_048
+
+/** The largest code unit the WHATWG URL parser repairs away: the space. */
+const largestRepairedCodeUnit = 0x20
+
+/**
+ * Reports whether the URL parser would repair the value rather than parse it
+ * as written. It strips leading and trailing C0 controls and spaces and
+ * removes tab, newline, and carriage return from anywhere in its input, and
+ * every one of those sits at or below {@link largestRepairedCodeUnit}.
+ */
+const repairedByUrlParser = (value: string): boolean => {
+  for (let index = 0; index < value.length; index++) {
+    if (value.charCodeAt(index) <= largestRepairedCodeUnit) return true
+  }
+  return false
+}
+
+const isAbsoluteHttpUrl = (value: string): boolean => {
+  // `new URL` alone is not a validator here. It strips padding and inline
+  // control characters before parsing, so it reports a copy-pasted
+  // `"http://collector:4318\n"` as well formed while the untrimmed original is
+  // what a builder would hand its exporter: either an unusable URL or a
+  // request to a host nobody typed. No legal collector endpoint carries one of
+  // these, so refusing them costs nothing and closes the silent case.
+  if (repairedByUrlParser(value)) return false
+  // Exporters append /v1/<signal> to this base. A query or fragment would
+  // swallow that suffix instead of changing the request path. Also refuse
+  // missing authority separators and backslashes that WHATWG silently repairs.
+  if (!/^https?:\/\/[^/]/i.test(value) || /[?#\\]/.test(value)) return false
+  let url: URL
+  try {
+    url = new URL(value)
+  } catch {
+    return false
+  }
+  return url.username === "" && url.password === ""
+}
+
+/**
+ * Runtime schema for an absolute `http:` or `https:` collector endpoint that
+ * carries no credentials, query, fragment, backslashes, spaces, or controls.
+ * A base path is allowed; authentication belongs in exporter headers.
+ *
+ * @category schemas
+ * @since 1.0.0-rc.0
+ */
+export const Endpoint = Schema.String.check(
+  Schema.isMaxLength(maximumEndpointLength),
+  Schema.makeFilter((value: string) => isAbsoluteHttpUrl(value), { title: "absoluteCollectorEndpoint" })
+)
+
+/**
+ * Stable exporter-endpoint refusal shared by every OTLP builder.
+ *
+ * @category errors
+ * @since 1.0.0-rc.0
+ */
+export class InvalidExporterEndpoint extends Schema.TaggedError<InvalidExporterEndpoint>()(
+  "@smthrs/observability/InvalidExporterEndpoint",
+  {
+    code: Schema.Literal("invalid_exporter_endpoint"),
+    path: Schema.String,
+    message: Schema.String
+  }
+) {}
+
+/**
+ * Removes the repeated trailing separators that would otherwise produce a
+ * double slash in a signal URL.
+ *
+ * @category conversions
+ * @since 1.0.0-rc.0
+ */
+export const normalize = (endpoint: string): string => endpoint.replace(/\/+$/, "")
+
+/**
+ * Decodes one collector endpoint into its normalized form without retaining
+ * the rejected value.
+ *
+ * `path` names the option the endpoint arrived on, so the refusal points at the
+ * caller's own field rather than at a shared internal name.
+ *
+ * @category decoding
+ * @since 1.0.0-rc.0
+ */
+export const decode = (
+  endpoint: unknown,
+  path: string
+): Effect.Effect<string, InvalidExporterEndpoint> =>
+  Schema.decodeUnknownEffect(Endpoint)(endpoint).pipe(
+    Effect.map(normalize),
+    Effect.mapError(() =>
+      new InvalidExporterEndpoint({
+        code: "invalid_exporter_endpoint",
+        path,
+        message:
+          `OTLP collector ${path} must be an absolute http:// or https:// base URL without credentials, query, fragment, backslashes, spaces, or control characters`
+      })
+    )
+  )
+
+/**
+ * Builds the OTLP/HTTP URL one signal is posted to below a decoded endpoint.
+ *
+ * @category conversions
+ * @since 1.0.0-rc.0
+ */
+export const signalUrl = (endpoint: string, signal: "traces" | "metrics" | "logs"): string =>
+  `${normalize(endpoint)}/v1/${signal}`