@smthrs/observability 0.35.0 → 1.0.0-rc.12

package/src/Logger.ts

@@ -0,0 +1,107 @@
+/**
+ * Effect logger layers used by flows.
+ *
+ * @since 0.1.0
+ */
+
+import * as Layer from "effect/Layer"
+import * as Logger from "effect/Logger"
+import type * as LogLevel from "effect/LogLevel"
+import * as References from "effect/References"
+
+/**
+ * Options shared by the built-in logger layers.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Options {
+  /**
+   * Pins `References.MinimumLogLevel` for the whole application. Omitted, the
+   * layer leaves that reference alone and Effect's own `Info` default applies.
+   */
+  readonly minimumLogLevel?: LogLevel.LogLevel | undefined
+  /**
+   * Keeps the ambient loggers alongside this one. Defaults to `false`, which
+   * replaces the ambient logger set, matching Effect's own `Logger.layer`.
+   */
+  readonly mergeWithExisting?: boolean | undefined
+}
+
+/**
+ * Installs the minimum-level reference only when the caller named a level, so
+ * a layer that adds a sink does not pin the level an application chose
+ * elsewhere. Effect's own default for the reference is already `Info`.
+ */
+const withMinimumLogLevel = (
+  layer: Layer.Layer<never>,
+  minimumLogLevel: LogLevel.LogLevel | undefined
+): Layer.Layer<never> =>
+  minimumLogLevel === undefined
+    ? layer
+    : Layer.merge(layer, Layer.succeed(References.MinimumLogLevel, minimumLogLevel))
+
+const optionsWithDefaults = (options?: Options): {
+  readonly minimumLogLevel: LogLevel.LogLevel | undefined
+  readonly mergeWithExisting: boolean
+} => ({
+  minimumLogLevel: options?.minimumLogLevel,
+  mergeWithExisting: options?.mergeWithExisting ?? false
+})
+
+/**
+ * Provides a human-readable development logger.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layerPrettyDev = (options?: Options): Layer.Layer<never> => {
+  const resolved = optionsWithDefaults(options)
+  return withMinimumLogLevel(
+    Logger.layer([Logger.consolePretty({ colors: "auto", mode: "auto" })], {
+      mergeWithExisting: resolved.mergeWithExisting
+    }),
+    resolved.minimumLogLevel
+  )
+}
+
+/**
+ * Provides one structured JSON object per log line.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layerStructuredJson = (options?: Options): Layer.Layer<never> => {
+  const resolved = optionsWithDefaults(options)
+  return withMinimumLogLevel(
+    Logger.layer([Logger.consoleJson], { mergeWithExisting: resolved.mergeWithExisting }),
+    resolved.minimumLogLevel
+  )
+}
+
+/**
+ * Removes the active logger set and pins the minimum level to `None` unless
+ * `options.minimumLogLevel` explicitly selects another level.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layerNoop = (options?: Pick<Options, "minimumLogLevel">): Layer.Layer<never> =>
+  withMinimumLogLevel(
+    Logger.layer([]),
+    options?.minimumLogLevel ?? "None"
+  )
+
+/**
+ * A logger layer that can be composed without requiring a runtime service.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layer = (logger: Logger.Logger<unknown, unknown>, options?: Options): Layer.Layer<never> => {
+  const resolved = optionsWithDefaults(options)
+  return withMinimumLogLevel(
+    Logger.layer([logger], { mergeWithExisting: resolved.mergeWithExisting }),
+    resolved.minimumLogLevel
+  )
+}

package/src/Metric.ts

@@ -0,0 +1,88 @@
+/**
+ * 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
+} as const

package/src/NodeOtel.ts

@@ -0,0 +1,90 @@
+/**
+ * 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 type * as Duration from "effect/Duration"
+import * as Effect from "effect/Effect"
+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 const layerOtel = (
+  options: Options
+): Layer.Layer<never, Resource.InvalidResourceConfiguration | Endpoint.InvalidExporterEndpoint> =>
+  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({})))
+        )
+    )
+  )

package/src/Otel.ts

@@ -0,0 +1,118 @@
+/**
+ * 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 type * as Api from "@opentelemetry/api"
+import type { LoggerProvider } from "@opentelemetry/sdk-logs"
+import type { MetricReader } from "@opentelemetry/sdk-metrics"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import {
+  type Configuration as ResourceConfiguration,
+  type InvalidResourceConfiguration,
+  layer as resourceLayer,
+  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 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 the metric resource for them. Spans and log
+ * records carry the instrumentation scope `effect` with the Effect version.
+ * 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: Options): Layer.Layer<never, InvalidResourceConfiguration> => {
+  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() as unknown as MetricReader | readonly [MetricReader, ...Array<MetricReader>],
+      {
+        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.Layer<never> = Layer.empty