sailfork / t3code-github / .repos/ effect/ packages/ opentelemetry/ src/ OtelMetrics.ts

/**
 * OpenTelemetry support for Effect metrics.
 *
 * This module exposes Effect metrics as an OpenTelemetry `MetricProducer`.
 * `makeProducer` creates the producer, `registerProducer` attaches it to one
 * or more SDK `MetricReader`s, and `layer` manages that setup in a scoped
 * layer. The `TemporalityPreference` type lets callers choose cumulative or
 * delta metric values.
 *
 * @stability unstable
 * @since 4.0.0
 */
import type { MetricProducer, MetricReader } from "@opentelemetry/sdk-metrics"
import type * as Arr from "effect/Array"
import type * as Duration from "effect/Duration"
import * as Effect from "effect/Effect"
import type { LazyArg } from "effect/Function"
import * as Layer from "effect/Layer"
import type * as Scope from "effect/Scope"
import { MetricProducerImpl } from "./internal/metrics.ts"
import { Resource } from "./Resource.ts"

/**
 * Determines how metric values relate to the time interval over which they
 * are aggregated.
 *
 * **Details**
 *
 * `cumulative` reports total since a fixed start time. Each data point depends
 * on all previous measurements. This is the default behavior. `delta` reports
 * changes since the last export. Each interval is independent with no
 * dependency on previous measurements.
 *
 * @stability unstable
 * @category models
 * @since 4.0.0
 */
export type TemporalityPreference = "cumulative" | "delta"

/**
 * Creates an OpenTelemetry metric producer from Effect metrics.
 *
 * **When to use**
 *
 * Use when you need a `MetricProducer` for manually wiring Effect metrics into
 * OpenTelemetry instead of using the scoped `layer` helper.
 *
 * **Details**
 *
 * Requires the current OpenTelemetry `Resource`, captures the current Effect
 * context, and uses cumulative temporality by default. Pass `"delta"` for
 * interval-based values.
 *
 * @see {@link registerProducer} for attaching a producer to metric readers
 * @see {@link layer} for creating and registering a producer in a scoped layer
 *
 * @stability unstable
 * @category constructors
 * @since 4.0.0
 */
export const makeProducer = (temporality?: TemporalityPreference): Effect.Effect<MetricProducer, never, Resource> =>
  Effect.gen(function*() {
    const resource = yield* Resource
    const services = yield* Effect.context<never>()
    return new MetricProducerImpl(resource, services, temporality)
  })

/**
 * Registers a metric producer with one or more metric readers.
 *
 * @stability unstable
 * @category resource management
 * @since 4.0.0
 */
export const registerProducer = (
  self: MetricProducer,
  metricReader: LazyArg<MetricReader | Arr.NonEmptyReadonlyArray<MetricReader>>,
  options?: {
    readonly shutdownTimeout?: Duration.Input | undefined
  }
): Effect.Effect<Array<any>, never, Scope.Scope> =>
  Effect.acquireRelease(
    Effect.suspend(() => {
      const reader = metricReader()
      const readers: Array<MetricReader> = Array.isArray(reader) ? reader : [reader] as any
      const bound: Array<MetricReader> = []
      try {
        for (const reader of readers) {
          reader.setMetricProducer(self instanceof MetricProducerImpl ? self.fork() : self)
          bound.push(reader)
        }
        return Effect.succeed(bound)
      } catch (error) {
        // Roll back only the readers bound by this acquisition.
        return Effect.andThen(Effect.ignoreCause(shutdownReaders(bound, options)), Effect.die(error))
      }
    }),
    (readers) => shutdownReaders(readers, options)
  )

const shutdownReaders = (
  readers: ReadonlyArray<MetricReader>,
  options?: { readonly shutdownTimeout?: Duration.Input | undefined }
) =>
  Effect.promise(() => Promise.all(readers.map((reader) => reader.shutdown()))).pipe(
    Effect.ignore,
    Effect.interruptible,
    Effect.timeoutOption(options?.shutdownTimeout ?? 3000)
  )

/**
 * Creates a Layer that registers a metric producer with metric readers.
 *
 * **Example** (Exporting delta metrics)
 *
 * ```ts import.meta.vitest
 * import { OtelMetrics, Resource } from "@effect/opentelemetry"
 * import {
 *   AggregationTemporality,
 *   InMemoryMetricExporter,
 *   PeriodicExportingMetricReader
 * } from "@opentelemetry/sdk-metrics"
 * import { Effect, Layer, Metric } from "effect"
 *
 * const exporter = new InMemoryMetricExporter(AggregationTemporality.DELTA)
 * const reader = new PeriodicExportingMetricReader({
 *   exporter,
 *   exportIntervalMillis: 60_000
 * })
 * const metricsLayer = OtelMetrics.layer(() => reader, { temporality: "delta" }).pipe(
 *   Layer.provide(Resource.layerEmpty)
 * )
 *
 * const program = Effect.gen(function*() {
 *   yield* Metric.update(Metric.counter("docs.requests", { incremental: true }), 2)
 *   yield* Effect.promise(() => reader.forceFlush())
 *
 *   const metric = exporter.getMetrics()[0]?.scopeMetrics[0]?.metrics.find(
 *     (metric) => metric.descriptor.name === "docs.requests"
 *   )
 *   return [metric?.descriptor.name, metric?.aggregationTemporality, metric?.dataPoints[0]?.value] as const
 * }).pipe(
 *   Effect.provide(metricsLayer),
 *   Effect.provideService(Metric.MetricRegistry, new Map())
 * )
 *
 * await Effect.runPromise(program) // => ["docs.requests", AggregationTemporality.DELTA, 2]
 * ```
 *
 * @stability unstable
 * @category layers
 * @since 4.0.0
 */
export const layer = (
  evaluate: LazyArg<MetricReader | Arr.NonEmptyReadonlyArray<MetricReader>>,
  options?: {
    readonly shutdownTimeout?: Duration.Input | undefined
    readonly temporality?: TemporalityPreference | undefined
  }
): Layer.Layer<never, never, Resource> =>
  Layer.effectDiscard(Effect.flatMap(
    makeProducer(options?.temporality),
    (producer) => registerProducer(producer, evaluate, options)
  ))