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

/**
 * OpenTelemetry resource service and layers.
 *
 * An OpenTelemetry resource identifies the process or service that emits spans,
 * metrics, and logs. This module stores that resource in Effect context and
 * provides layers for creating it from explicit service metadata, from
 * `OTEL_SERVICE_NAME` and `OTEL_RESOURCE_ATTRIBUTES`, or as an empty resource.
 * It also includes `configToAttributes` for turning service metadata into raw
 * OpenTelemetry attributes.
 *
 * @stability unstable
 * @since 4.0.0
 */
import type * as OtelApi from "@opentelemetry/api"
import * as Resources from "@opentelemetry/resources"
import * as OtelSemConv from "@opentelemetry/semantic-conventions"
import * as Config from "effect/Config"
import * as Context from "effect/Context"
import * as Effect from "effect/Effect"
import * as Layer from "effect/Layer"
import * as Schema from "effect/Schema"
import * as Version from "effect/Version"

/**
 * Service tag for OpenTelemetry metadata attached to emitted telemetry.
 *
 * **When to use**
 *
 * Use to provide process, service, and deployment metadata that should be
 * attached to spans, metrics, and logs.
 *
 * @stability unstable
 * @category services
 * @since 4.0.0
 */
export class Resource extends Context.Service<
  Resource,
  Resources.Resource
>()("@effect/opentelemetry/Resource") {}

/**
 * Creates a `Resource` layer from service metadata and additional OpenTelemetry attributes.
 *
 * @stability unstable
 * @category layers
 * @since 4.0.0
 */
export const layer = (config: {
  readonly serviceName: string
  readonly serviceVersion?: string
  readonly attributes?: OtelApi.Attributes
}) =>
  Layer.succeed(
    Resource,
    Resources.resourceFromAttributes(configToAttributes(config))
  )

const sdkAttributes = (): Record<string, string> => ({
  [OtelSemConv.ATTR_TELEMETRY_SDK_NAME]: "@effect/opentelemetry",
  [OtelSemConv.ATTR_TELEMETRY_SDK_LANGUAGE]: typeof (globalThis as any).document === "undefined"
    ? OtelSemConv.TELEMETRY_SDK_LANGUAGE_VALUE_NODEJS
    : OtelSemConv.TELEMETRY_SDK_LANGUAGE_VALUE_WEBJS,
  [OtelSemConv.ATTR_TELEMETRY_SDK_VERSION]: Version.getCurrentVersion()
})

/**
 * Converts service metadata into OpenTelemetry attributes with SDK defaults.
 *
 * **When to use**
 *
 * Use to turn explicit service metadata into a raw OpenTelemetry attribute map
 * for lower-level resource construction or merging with environment-derived
 * attributes via `layerFromEnv`.
 *
 * **Details**
 *
 * Custom attributes override `telemetry.sdk.*` defaults. Service options override
 * matching attributes. An empty `serviceVersion` is treated as absent.
 *
 * @see {@link layer} for creating a `Resource` layer from explicit metadata
 * @see {@link layerFromEnv} for merging attributes with OpenTelemetry environment variables
 *
 * @stability unstable
 * @category converting
 * @since 4.0.0
 */
export const configToAttributes = (options: {
  readonly serviceName: string
  readonly serviceVersion?: string
  readonly attributes?: OtelApi.Attributes
}): Record<string, string> => {
  const attributes: Record<string, string> = {
    ...sdkAttributes(),
    ...(options.attributes ?? undefined),
    [OtelSemConv.ATTR_SERVICE_NAME]: options.serviceName
  }
  if (options.serviceVersion) {
    attributes[OtelSemConv.ATTR_SERVICE_VERSION] = options.serviceVersion
  }
  return attributes
}

/**
 * Creates a `Resource` layer from SDK defaults, then environment variables,
 * then additional attributes (later values take precedence).
 *
 * **Details**
 *
 * `OTEL_RESOURCE_ATTRIBUTES` is read with `Config.Record`, so a structured
 * config value is accepted as well as a `key=value` list. In the list, keys and
 * values are trimmed, then percent-decoded once. Entries with an empty value
 * are kept as `""`; entries without `=` or with an empty key are skipped. When
 * a key is repeated as written, the last entry wins and the earlier ones are
 * not decoded. If any remaining key or value is not valid percent-encoding,
 * the whole variable is discarded and a warning is logged.
 *
 * @stability unstable
 * @category layers
 * @since 4.0.0
 */
export const layerFromEnv = (
  additionalAttributes?:
    | OtelApi.Attributes
    | undefined
): Layer.Layer<Resource> =>
  Layer.effect(
    Resource,
    Effect.gen(function*() {
      const serviceName = yield* Config.option(Config.String("OTEL_SERVICE_NAME"))
      const attributes = yield* Config.Record(
        Schema.StringFromUriComponent,
        Schema.StringFromUriComponent,
        "OTEL_RESOURCE_ATTRIBUTES",
        { trim: true, keepEmptyValues: true }
      ).pipe(
        Config.withDefault({}),
        Effect.catch((error) => Effect.as(Effect.logWarning("Discarding OTEL_RESOURCE_ATTRIBUTES", error), {}))
      )
      return Resources.resourceFromAttributes({
        ...sdkAttributes(),
        ...attributes,
        ...(serviceName._tag === "Some" ? { [OtelSemConv.ATTR_SERVICE_NAME]: serviceName.value } : undefined),
        ...additionalAttributes
      })
    }).pipe(Effect.orDie)
  )

/**
 * Layer that provides an empty OpenTelemetry resource.
 *
 * @stability unstable
 * @category layers
 * @since 4.0.0
 */
export const layerEmpty = Layer.succeed(
  Resource,
  Resources.emptyResource()
)