pyfect-dev 0.1.0__py3-none-any.whl

pyfect/otel/_wrapper.py

@@ -0,0 +1,92 @@
+"""An OpenTelemetry ``Span`` over a pyfect span the bridge did not make
+(Effect's ``makeOtelSpan``), for ``current_otel_span``."""
+
+from __future__ import annotations
+
+import traceback
+from collections.abc import Mapping
+
+from opentelemetry import trace
+from opentelemetry.trace import SpanContext, Status, StatusCode, TraceFlags
+from opentelemetry.util import types
+
+from pyfect.clock import ClockService
+from pyfect.exit import Exit, Success, die
+from pyfect.otel._span import external_span_of, hex_id
+from pyfect.tracer import Span, SpanLink
+
+
+class EffectSpanView(trace.Span):
+    """Writes through to ``span``: attributes, events, links and the end,
+    with the exit the last ``set_status`` chose (an error status ends it
+    with a defect). Times default to ``clock``'s now."""
+
+    def __init__(self, span: Span, clock: ClockService) -> None:
+        self._span = span
+        self._clock = clock
+        self._exit: Exit[object, object] = Success(None)
+        self._context = SpanContext(
+            hex_id(span.trace_id),
+            hex_id(span.span_id),
+            False,
+            TraceFlags(TraceFlags.SAMPLED if span.sampled else TraceFlags.DEFAULT),
+        )
+
+    def _time(self, nanos: int | None) -> int:
+        return self._clock.now_nanos_unsafe() if nanos is None else nanos
+
+    def get_span_context(self) -> SpanContext:
+        return self._context
+
+    def set_attribute(self, key: str, value: types.AttributeValue) -> None:
+        self._span.attribute(key, value)
+
+    def set_attributes(self, attributes: Mapping[str, types.AttributeValue]) -> None:
+        for key, value in attributes.items():
+            self._span.attribute(key, value)
+
+    def add_event(
+        self, name: str, attributes: types.Attributes = None, timestamp: int | None = None
+    ) -> None:
+        self._span.event(name, self._time(timestamp), attributes)
+
+    def add_link(self, context: SpanContext, attributes: types.Attributes = None) -> None:
+        self._span.add_links([_link(context, attributes)])
+
+    def update_name(self, name: str) -> None:
+        pass
+
+    def is_recording(self) -> bool:
+        return True
+
+    def set_status(self, status: Status | StatusCode, description: str | None = None) -> None:
+        code = status.status_code if isinstance(status, Status) else status
+        if code is StatusCode.ERROR:
+            message = status.description if isinstance(status, Status) else description
+            self._exit = die(Exception(message or "Unknown error"))
+        else:
+            self._exit = Success(None)
+
+    def end(self, end_time: int | None = None) -> None:
+        self._span.end(self._time(end_time), self._exit)
+
+    def record_exception(
+        self,
+        exception: BaseException,
+        attributes: types.Attributes = None,
+        timestamp: int | None = None,
+        escaped: bool = False,
+    ) -> None:
+        self._span.event(
+            str(exception),
+            self._time(timestamp),
+            {
+                "exception.type": type(exception).__name__,
+                "exception.message": str(exception),
+                "exception.stacktrace": "".join(traceback.format_exception(exception)),
+            },
+        )
+
+
+def _link(context: SpanContext, attributes: types.Attributes) -> SpanLink:
+    return SpanLink(external_span_of(context), dict(attributes or {}))

pyfect/otel/logger.py

@@ -0,0 +1,154 @@
+"""pyfect logs as OpenTelemetry log records (Effect's ``OtelLogger``).
+
+``layer()`` installs a logger emitting every log through the
+``OtelLoggerProvider``; ``layer_logger_provider(processors)`` makes an SDK
+logger provider, flushed and shut down when the layer is released. A log
+inside a span carries the span's context, so backends correlate the two.
+"""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+import traceback
+from collections.abc import Sequence
+from datetime import UTC, datetime, timedelta
+from typing import Final, Never
+
+from opentelemetry import context as otel_context
+from opentelemetry._logs import LogRecord, SeverityNumber
+from opentelemetry.sdk import _logs as sdk_logs
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.util.types import AnyValue
+
+from pyfect import layer as _layer
+from pyfect.clock import Clock, ClockService
+from pyfect.context import Tag
+from pyfect.duration import Duration
+from pyfect.effect import gen, sync
+from pyfect.layer import Layer
+from pyfect.logger import CurrentLogAnnotations, CurrentLogSpans, Logger, LogLevel, Options
+from pyfect.logger import layer as logger_layer
+from pyfect.otel._attributes import PYFECT_VERSION, to_attribute_value
+from pyfect.otel._shutdown import DEFAULT_SHUTDOWN_TIMEOUT, flush_and_shut_down
+from pyfect.otel._span import populate_context
+from pyfect.otel.resource import OtelResource
+from pyfect.scope import acquire_release
+from pyfect.tracer import ParentSpan
+
+__all__ = [
+    "OtelLoggerProvider",
+    "layer",
+    "layer_logger_provider",
+    "log_level_to_severity_number",
+    "make",
+]
+
+
+class OtelLoggerProvider(Tag[sdk_logs.LoggerProvider]):
+    """The OpenTelemetry logger provider pyfect logs are emitted through."""
+
+
+_SEVERITIES: Final = {
+    LogLevel.TRACE: SeverityNumber.TRACE,
+    LogLevel.DEBUG: SeverityNumber.DEBUG,
+    LogLevel.INFO: SeverityNumber.INFO,
+    LogLevel.WARN: SeverityNumber.WARN,
+    LogLevel.ERROR: SeverityNumber.ERROR,
+    LogLevel.FATAL: SeverityNumber.FATAL,
+}
+
+
+def log_level_to_severity_number(level: LogLevel) -> SeverityNumber:
+    """The OpenTelemetry severity of a level (1 to 24); ``ALL`` and ``NONE``
+    are ``UNSPECIFIED``."""
+    return _SEVERITIES.get(level, SeverityNumber.UNSPECIFIED)
+
+
+_EPOCH: Final = datetime(1970, 1, 1, tzinfo=UTC)
+_MICROSECOND: Final = timedelta(microseconds=1)
+
+
+def _record(options: Options, observed: int) -> LogRecord:
+    fiber = options.fiber
+    attributes: dict[str, AnyValue] = {
+        key: to_attribute_value(value)
+        for key, value in fiber.get_ref(CurrentLogAnnotations).items()
+    }
+    attributes["effect.fiberId"] = fiber.id
+    span = fiber.get_ref(ParentSpan)
+    context = otel_context.get_current()
+    if span is not None:
+        context = populate_context(context, span, span.annotations)
+        attributes["spanId"] = span.span_id
+        attributes["traceId"] = span.trace_id
+    now = options.millis
+    # Spans are innermost first, so the outermost wins a repeated label.
+    for label, start in fiber.get_ref(CurrentLogSpans):
+        attributes[f"effect.log_span.{label}"] = now - start
+    errors = options.cause.pretty_errors()
+    if errors:
+        attributes["exception.type"] = type(errors[0]).__name__
+        attributes["exception.message"] = str(errors[0])
+        attributes["exception.stacktrace"] = "\n".join(
+            "".join(traceback.format_exception(error)) for error in errors
+        )
+    message = [to_attribute_value(item) for item in options.message]
+    return LogRecord(
+        timestamp=(options.date - _EPOCH) // _MICROSECOND * 1000,
+        observed_timestamp=observed,
+        context=context,
+        severity_text=str(options.log_level),
+        severity_number=log_level_to_severity_number(options.log_level),
+        body=message[0] if len(message) == 1 else message,
+        attributes=attributes,
+    )
+
+
+def _logger(provider: sdk_logs.LoggerProvider, clock: ClockService) -> Logger[None]:
+    otel_logger = provider.get_logger("pyfect", PYFECT_VERSION)
+    return Logger(lambda options: otel_logger.emit(_record(options, clock.now_nanos_unsafe())))
+
+
+@gen
+def make():
+    """A logger emitting each log as a record through the
+    ``OtelLoggerProvider``: the log annotations, ``effect.fiberId``, the
+    span ids, each log span's elapsed milliseconds
+    (``effect.log_span.<label>``) and the cause's first error
+    (``exception.*``) as attributes."""
+    provider = yield from OtelLoggerProvider()
+    clock = yield from Clock()
+    return _logger(provider, clock)
+
+
+def layer(*, merge_with_existing: bool = True) -> Layer[Never, Never, OtelLoggerProvider]:
+    """Installs ``make``'s logger, next to the current loggers (or instead
+    of them, with ``merge_with_existing=False``)."""
+    return logger_layer([make], merge_with_existing=merge_with_existing)
+
+
+def layer_logger_provider(
+    processors: sdk_logs.LogRecordProcessor | Sequence[sdk_logs.LogRecordProcessor],
+    *,
+    shutdown_timeout: Duration = DEFAULT_SHUTDOWN_TIMEOUT,
+) -> Layer[OtelLoggerProvider, Never, OtelResource]:
+    """An SDK logger provider with the ``OtelResource`` and ``processors``,
+    flushed (for at most ``shutdown_timeout``) and shut down when the layer
+    is released."""
+    given = [processors] if isinstance(processors, sdk_logs.LogRecordProcessor) else processors
+
+    def acquire(resource: Resource) -> sdk_logs.LoggerProvider:
+        provider = sdk_logs.LoggerProvider(resource=resource, shutdown_on_exit=False)
+        for processor in given:
+            provider.add_log_record_processor(processor)
+        return provider
+
+    return _layer.effect(
+        OtelLoggerProvider,
+        OtelResource().flat_map(
+            lambda resource: acquire_release(
+                sync(lambda: acquire(resource)),
+                lambda provider, _exit: flush_and_shut_down(provider, shutdown_timeout),
+            )
+        ),
+    )

pyfect/otel/metrics.py

@@ -0,0 +1,126 @@
+"""pyfect metrics as OpenTelemetry metrics (Effect's ``OtelMetrics``).
+
+``layer(lambda: reader)`` hands the current metric registry to an SDK
+``MetricReader`` (a ``PeriodicExportingMetricReader`` exporting over OTLP,
+say), which collects it whenever it reads::
+
+    metrics = otel.metrics.layer(lambda: PeriodicExportingMetricReader(exporter))
+    program.pipe(fx.provide(metrics.pipe(layer.provide(otel.resource.layer_empty))))
+
+Readers are bound to pyfect's producer instead of a ``MeterProvider``; a
+reader can be bound once. Counters, frequencies and summaries become sums,
+gauges gauges, histograms explicit-bucket histograms.
+"""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+import contextlib
+from collections.abc import Callable, Sequence
+from typing import Any, Never, Protocol
+
+from opentelemetry.sdk.metrics.export import MetricReader, MetricsData
+
+from pyfect import layer as _layer
+from pyfect._context_effects import context
+from pyfect._core import Effect
+from pyfect.duration import Duration, to_millis
+from pyfect.effect import die, gen, suspend, sync
+from pyfect.layer import Layer
+from pyfect.otel._producer import MetricProducer, TemporalityPreference
+from pyfect.otel._shutdown import DEFAULT_SHUTDOWN_TIMEOUT
+from pyfect.otel.resource import OtelResource
+from pyfect.scope import Scope, acquire_release
+
+__all__ = [
+    "MetricProducer",
+    "Readers",
+    "TemporalityPreference",
+    "layer",
+    "make_producer",
+    "register_producer",
+]
+
+type Readers = Callable[[], MetricReader | Sequence[MetricReader]]
+"""Makes the readers to bind, when the layer builds."""
+
+
+def make_producer(
+    temporality: TemporalityPreference = "cumulative",
+) -> Effect[MetricProducer, Never, OtelResource]:
+    """A producer of the current metric registry, with the ``OtelResource``."""
+
+    @gen
+    def make():
+        resource = yield from OtelResource()
+        services = yield from context()
+        return MetricProducer(resource, services, temporality)
+
+    return make
+
+
+def _bind(reader: MetricReader, producer: MetricProducer) -> None:
+    if reader._collect is not None:
+        raise RuntimeError(f"MetricReader {reader} has been registered already")
+
+    def collect(_reader: MetricReader, timeout_millis: float = 10_000) -> MetricsData:
+        return producer.collect()
+
+    reader._set_collect_callback(collect)
+
+
+class _ShutsDown(Protocol):
+    def shutdown(self, timeout_millis: float = ...) -> None: ...
+
+
+def _shut_down(readers: Sequence[_ShutsDown], timeout: Duration) -> Effect[None]:
+    """Shut every reader down, ignoring errors, as Effect does."""
+
+    def run() -> None:
+        for reader in readers:
+            with contextlib.suppress(Exception):
+                reader.shutdown(timeout_millis=to_millis(timeout))
+
+    return sync(run)
+
+
+def register_producer(
+    producer: MetricProducer,
+    readers: Readers,
+    *,
+    shutdown_timeout: Duration = DEFAULT_SHUTDOWN_TIMEOUT,
+) -> Effect[list[MetricReader], Never, Scope]:
+    """Bind each reader to its own fork of ``producer``, and shut them down
+    when the scope closes. If a reader cannot be bound (it is bound
+    already), the readers bound so far are shut down and the effect dies."""
+
+    def acquire() -> Effect[list[MetricReader]]:
+        made = readers()
+        given = [made] if isinstance(made, MetricReader) else list(made)
+        bound: list[MetricReader] = []
+        try:
+            for reader in given:
+                _bind(reader, producer.fork())
+                bound.append(reader)
+        except Exception as error:
+            failure = error
+            return _shut_down(bound, shutdown_timeout).flat_map(lambda _: die(failure))
+        return sync(lambda: bound)
+
+    return acquire_release(
+        suspend(acquire), lambda bound, _exit: _shut_down(bound, shutdown_timeout)
+    )
+
+
+def layer(
+    readers: Readers,
+    *,
+    temporality: TemporalityPreference = "cumulative",
+    shutdown_timeout: Duration = DEFAULT_SHUTDOWN_TIMEOUT,
+) -> Layer[Never, Never, OtelResource]:
+    """Bind the readers ``readers()`` makes to a producer of the current
+    registry while the layer is in use."""
+    registered: Effect[Any, Never, OtelResource | Scope] = make_producer(temporality).flat_map(
+        lambda producer: register_producer(producer, readers, shutdown_timeout=shutdown_timeout)
+    )
+    return _layer.effect_discard(registered)

pyfect/otel/resource.py

@@ -0,0 +1,111 @@
+"""The OpenTelemetry resource: what process or service emits the spans,
+logs and metrics (Effect's ``Resource``).
+
+``layer(service_name=...)`` builds one from service metadata;
+``layer_from_env()`` reads ``OTEL_SERVICE_NAME`` and
+``OTEL_RESOURCE_ATTRIBUTES`` through ``Config``; ``layer_empty`` has no
+attributes.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Final
+
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.util.types import AttributeValue
+
+from pyfect import config
+from pyfect import layer as _layer
+from pyfect.context import Tag
+from pyfect.layer import Layer
+from pyfect.option import Option, Some
+from pyfect.otel._attributes import PYFECT_VERSION
+
+__all__ = ["OtelResource", "config_to_attributes", "layer", "layer_empty", "layer_from_env"]
+
+
+class OtelResource(Tag[Resource]):
+    """The resource attached to everything the bridge exports."""
+
+
+def _sdk_attributes() -> dict[str, AttributeValue]:
+    return {
+        "telemetry.sdk.name": "pyfect",
+        "telemetry.sdk.language": "python",
+        "telemetry.sdk.version": PYFECT_VERSION,
+    }
+
+
+def config_to_attributes(
+    *,
+    service_name: str,
+    service_version: str | None = None,
+    attributes: Mapping[str, AttributeValue] | None = None,
+) -> dict[str, AttributeValue]:
+    """The SDK defaults, then ``attributes``, then the service name and
+    version (an empty version counts as none), later ones winning."""
+    merged: dict[str, AttributeValue] = {
+        **_sdk_attributes(),
+        **(attributes or {}),
+        "service.name": service_name,
+    }
+    if service_version:
+        merged["service.version"] = service_version
+    return merged
+
+
+def layer(
+    *,
+    service_name: str,
+    service_version: str | None = None,
+    attributes: Mapping[str, AttributeValue] | None = None,
+) -> Layer[OtelResource]:
+    """A resource made from ``config_to_attributes``."""
+    return _layer.succeed(
+        OtelResource,
+        Resource(
+            config_to_attributes(
+                service_name=service_name,
+                service_version=service_version,
+                attributes=attributes,
+            )
+        ),
+    )
+
+
+def _env_attributes(text: str) -> dict[str, AttributeValue]:
+    """``OTEL_RESOURCE_ATTRIBUTES``: comma-separated ``key=value`` pairs,
+    split at the first ``=``; pairs without one or with an empty key are
+    skipped."""
+    attributes: dict[str, AttributeValue] = {}
+    for pair in text.split(","):
+        key, eq, value = pair.partition("=")
+        if eq and key.strip():
+            attributes[key.strip()] = value.strip()
+    return attributes
+
+
+def layer_from_env(
+    additional_attributes: Mapping[str, AttributeValue] | None = None,
+) -> Layer[OtelResource]:
+    """A resource from the SDK defaults, then ``OTEL_RESOURCE_ATTRIBUTES``
+    and ``OTEL_SERVICE_NAME`` (read through the ``CurrentConfigProvider``
+    when the layer builds; a config error is a defect), then
+    ``additional_attributes``, later ones winning."""
+
+    def make(service_name: Option[str], text: str) -> Resource:
+        attributes = _env_attributes(text)
+        if isinstance(service_name, Some):
+            attributes["service.name"] = service_name.value
+        return Resource({**_sdk_attributes(), **attributes, **(additional_attributes or {})})
+
+    read = config.all(
+        config.option(config.string("OTEL_SERVICE_NAME")),
+        config.string("OTEL_RESOURCE_ATTRIBUTES").with_default(""),
+    )
+    return _layer.effect(OtelResource, read.map(lambda pair: make(*pair)).or_die())
+
+
+layer_empty: Final[Layer[OtelResource]] = _layer.succeed(OtelResource, Resource.get_empty())
+"""A resource with no attributes."""

pyfect/otel/sdk.py

@@ -0,0 +1,195 @@
+"""One layer setting up OpenTelemetry for a pyfect program (Effect's
+``NodeSdk``).
+
+``layer(Configuration(...))`` provides the ``OtelResource`` (from the
+environment and the ``resource`` given) and turns on each signal given
+something to send it to: tracing with span processors, metrics with metric
+readers, logging with log record processors::
+
+    otel_layer = otel.sdk.layer(
+        otel.sdk.Configuration(
+            resource=otel.sdk.ResourceConfig(service_name="api"),
+            span_processor=BatchSpanProcessor(OTLPSpanExporter()),
+        )
+    )
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass
+from typing import Any, Never, cast, overload
+
+from opentelemetry.sdk import _logs as sdk_logs
+from opentelemetry.sdk.metrics.export import MetricReader
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import SpanLimits, SpanProcessor, TracerProvider
+from opentelemetry.sdk.trace.id_generator import IdGenerator
+from opentelemetry.sdk.trace.sampling import Sampler
+from opentelemetry.util.types import AttributeValue
+
+from pyfect import layer as _layer
+from pyfect._core import Effect
+from pyfect.duration import Duration
+from pyfect.effect import sync
+from pyfect.layer import Layer
+from pyfect.otel import logger as otel_logger
+from pyfect.otel import metrics as otel_metrics
+from pyfect.otel import resource as otel_resource
+from pyfect.otel import tracer as otel_tracer
+from pyfect.otel._shutdown import DEFAULT_SHUTDOWN_TIMEOUT, flush_and_shut_down
+from pyfect.otel.resource import OtelResource
+from pyfect.scope import acquire_release
+
+__all__ = [
+    "Configuration",
+    "ResourceConfig",
+    "layer",
+    "layer_empty",
+    "layer_tracer_provider",
+]
+
+
+@dataclass(frozen=True, slots=True)
+class ResourceConfig:
+    """The service the telemetry is about (``resource.config_to_attributes``)."""
+
+    service_name: str
+    service_version: str | None = None
+    attributes: Mapping[str, AttributeValue] | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class Configuration:
+    """What ``layer`` sets up. A signal with nothing to send it to (no span
+    processors, metric readers or log record processors) stays off.
+
+    - ``sampler``, ``id_generator``, ``span_limits``: for the tracer provider
+    - ``metric_temporality``: ``"cumulative"`` (default) or ``"delta"``
+    - ``logger_merge_with_existing``: keep the current loggers (default)
+    - ``shutdown_timeout``: how long each provider may flush when released
+    """
+
+    span_processor: SpanProcessor | Sequence[SpanProcessor] = ()
+    sampler: Sampler | None = None
+    id_generator: IdGenerator | None = None
+    span_limits: SpanLimits | None = None
+    metric_reader: MetricReader | Sequence[MetricReader] = ()
+    metric_temporality: otel_metrics.TemporalityPreference = "cumulative"
+    log_record_processor: sdk_logs.LogRecordProcessor | Sequence[sdk_logs.LogRecordProcessor] = ()
+    logger_merge_with_existing: bool = True
+    resource: ResourceConfig | None = None
+    shutdown_timeout: Duration = DEFAULT_SHUTDOWN_TIMEOUT
+
+
+def _all[T](given: T | Sequence[T], kind: type[T]) -> list[T]:
+    """One item or several, as a list."""
+    if isinstance(given, kind):
+        return [given]
+    return list(cast("Sequence[T]", given))
+
+
+def layer_tracer_provider(
+    processors: SpanProcessor | Sequence[SpanProcessor],
+    *,
+    sampler: Sampler | None = None,
+    id_generator: IdGenerator | None = None,
+    span_limits: SpanLimits | None = None,
+    shutdown_timeout: Duration = DEFAULT_SHUTDOWN_TIMEOUT,
+) -> Layer[otel_tracer.OtelTracerProvider, Never, OtelResource]:
+    """An SDK tracer provider with the ``OtelResource`` and ``processors``,
+    flushed (for at most ``shutdown_timeout``) and shut down when the layer
+    is released."""
+    given = _all(processors, SpanProcessor)
+
+    def make(resource: Resource) -> TracerProvider:
+        provider = TracerProvider(
+            sampler=sampler,
+            resource=resource,
+            shutdown_on_exit=False,
+            id_generator=id_generator,
+            span_limits=span_limits,
+        )
+        for processor in given:
+            provider.add_span_processor(processor)
+        return provider
+
+    return _layer.effect(
+        otel_tracer.OtelTracerProvider,
+        OtelResource().flat_map(
+            lambda resource: acquire_release(
+                sync(lambda: make(resource)),
+                lambda provider, _exit: flush_and_shut_down(provider, shutdown_timeout),
+            )
+        ),
+    )
+
+
+def _signals(config: Configuration) -> Layer[OtelResource]:
+    signals: list[Layer[Never, Never, OtelResource]] = []
+    span_processors = _all(config.span_processor, SpanProcessor)
+    if span_processors:
+        provider = layer_tracer_provider(
+            span_processors,
+            sampler=config.sampler,
+            id_generator=config.id_generator,
+            span_limits=config.span_limits,
+            shutdown_timeout=config.shutdown_timeout,
+        )
+        signals.append(otel_tracer.layer.pipe(_layer.provide(provider)))
+    readers = _all(config.metric_reader, MetricReader)
+    if readers:
+        signals.append(
+            otel_metrics.layer(
+                lambda: readers,
+                temporality=config.metric_temporality,
+                shutdown_timeout=config.shutdown_timeout,
+            )
+        )
+    log_processors = _all(config.log_record_processor, sdk_logs.LogRecordProcessor)
+    if log_processors:
+        logger_provider = otel_logger.layer_logger_provider(
+            log_processors, shutdown_timeout=config.shutdown_timeout
+        )
+        signals.append(
+            otel_logger.layer(merge_with_existing=config.logger_merge_with_existing).pipe(
+                _layer.provide(logger_provider)
+            )
+        )
+    resource = config.resource
+    resource_layer = otel_resource.layer_from_env(
+        None
+        if resource is None
+        else otel_resource.config_to_attributes(
+            service_name=resource.service_name,
+            service_version=resource.service_version,
+            attributes=resource.attributes,
+        )
+    )
+    merged: Layer[Never, Never, OtelResource] = _layer.empty
+    for signal in signals:
+        merged = _layer.merge(merged, signal)
+    return merged.pipe(_layer.provide_merge(resource_layer))
+
+
+@overload
+def layer(config: Configuration | Callable[[], Configuration], /) -> Layer[OtelResource]: ...
+@overload
+def layer[E, R](config: Effect[Configuration, E, R], /) -> Layer[OtelResource, E, R]: ...
+def layer(
+    config: Configuration | Callable[[], Configuration] | Effect[Configuration, Any, Any], /
+) -> Layer[Any, Any, Any]:
+    """Set up OpenTelemetry from ``config``: a configuration, a function
+    making one, or an effect making one when the layer builds."""
+    match config:
+        case Configuration():
+            made: Effect[Configuration, Any, Any] = sync(lambda: config)
+        case Effect():
+            made = config
+        case _:
+            made = sync(config)
+    return _layer.unwrap(made.map(_signals))
+
+
+layer_empty: Layer[OtelResource] = otel_resource.layer_empty
+"""Only an empty ``OtelResource``."""