pyfect-dev 0.1.0__py3-none-any.whl

pyfect/otel/_producer.py

@@ -0,0 +1,322 @@
+"""``MetricProducer``: the pyfect metric registry as OpenTelemetry metric
+data (Effect's ``MetricProducerImpl``)."""
+
+from __future__ import annotations
+
+import math
+import time
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Final, Literal, cast
+
+from opentelemetry.sdk.metrics.export import (
+    AggregationTemporality,
+    DataT,
+    Gauge,
+    Histogram,
+    HistogramDataPoint,
+    Metric,
+    MetricsData,
+    NumberDataPoint,
+    ResourceMetrics,
+    ScopeMetrics,
+    Sum,
+)
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.util.instrumentation import InstrumentationScope
+
+from pyfect._js import js_number
+from pyfect.context import Context
+from pyfect.metric import (
+    CounterState,
+    FrequencyState,
+    GaugeState,
+    HistogramState,
+    Snapshot,
+    SummaryState,
+    snapshot_unsafe,
+)
+
+type TemporalityPreference = Literal["cumulative", "delta"]
+"""``"cumulative"``: totals since the producer started (the default).
+``"delta"``: changes since the producer's last collection."""
+
+_SCOPE: Final = InstrumentationScope("pyfect.otel.metrics")
+
+_NO_EXTREMUM: Final = cast(float, None)
+"""A delta histogram leaves out ``min`` and ``max``, which cannot be
+derived from cumulative ones. The SDK types them as floats; OTLP encodes
+``None`` as an unset optional field."""
+
+type _Kind = Literal["sum", "monotonic_sum", "gauge", "histogram"]
+
+
+@dataclass(slots=True)
+class _Series:
+    """The data points of one metric name, gathered over its series; the
+    first series seen names its description and unit."""
+
+    kind: _Kind
+    description: str
+    unit: str
+    points: list[NumberDataPoint | HistogramDataPoint] = field(
+        default_factory=list[NumberDataPoint | HistogramDataPoint]
+    )
+
+    def data(self, temporality: AggregationTemporality) -> DataT:
+        match self.kind:
+            case "gauge":
+                return Gauge(cast(list[NumberDataPoint], self.points))
+            case "histogram":
+                return Histogram(cast(list[HistogramDataPoint], self.points), temporality)
+            case "sum" | "monotonic_sum":
+                numbers = cast(list[NumberDataPoint], self.points)
+                return Sum(numbers, temporality, self.kind == "monotonic_sum")
+
+
+@dataclass(frozen=True, slots=True)
+class _HistogramTotals:
+    count: int
+    sum: float
+    bucket_counts: list[int]
+
+
+@dataclass(slots=True)
+class _Totals:
+    """What each series held at the last delta collection, by series key."""
+
+    counters: dict[str, float] = field(default_factory=dict[str, float])
+    histograms: dict[str, _HistogramTotals] = field(default_factory=dict[str, _HistogramTotals])
+    frequencies: dict[str, Mapping[str, int]] = field(default_factory=dict[str, Mapping[str, int]])
+    summaries: dict[str, tuple[int, float]] = field(default_factory=dict[str, tuple[int, float]])
+
+
+class MetricProducer:
+    """Collects the registry of ``context`` (captured when the producer was
+    made) as ``MetricsData`` with ``resource``. A delta producer remembers
+    the values of the series it last collected, so give each reader its
+    own ``fork()``."""
+
+    def __init__(
+        self,
+        resource: Resource,
+        context: Context,
+        temporality: TemporalityPreference = "cumulative",
+    ) -> None:
+        self.resource = resource
+        self.context = context
+        self.temporality: TemporalityPreference = temporality
+        self._start_times: dict[str, int] = {}
+        self._start_time = time.time_ns()
+        self._previous_export_time = self._start_time
+        self._totals = _Totals()
+
+    def fork(self) -> MetricProducer:
+        """A fresh producer of the same registry, resource and temporality."""
+        return MetricProducer(self.resource, self.context, self.temporality)
+
+    def collect(self) -> MetricsData:
+        """Every series of the registry now."""
+        delta = self.temporality == "delta"
+        run = _Collection(
+            now=time.time_ns(),
+            delta=delta,
+            start_time=self._start_time,
+            interval_start=self._previous_export_time if delta else self._start_time,
+            start_times=self._start_times,
+            previous=self._totals,
+        )
+        for snapshot in snapshot_unsafe(self.context):
+            run.add(snapshot)
+        # Only series in this snapshot carry their delta state forward, so a
+        # removed series does not report a negative delta when recreated.
+        self._totals = run.totals
+        if delta:
+            self._previous_export_time = run.now
+        return MetricsData(
+            [ResourceMetrics(self.resource, [ScopeMetrics(_SCOPE, run.metrics(), "")], "")]
+        )
+
+
+class _Collection:
+    """One ``collect``: gathers the data points of each metric name."""
+
+    def __init__(
+        self,
+        *,
+        now: int,
+        delta: bool,
+        start_time: int,
+        interval_start: int,
+        start_times: dict[str, int],
+        previous: _Totals,
+    ) -> None:
+        self.now = now
+        self.delta = delta
+        self.start_time = start_time
+        self.interval_start = interval_start
+        self.start_times = start_times
+        self.previous = previous
+        self.totals = _Totals()
+        self.series: dict[str, _Series] = {}
+
+    def metrics(self) -> list[Metric]:
+        temporality = (
+            AggregationTemporality.DELTA if self.delta else AggregationTemporality.CUMULATIVE
+        )
+        return [
+            Metric(name, series.description, series.unit, series.data(temporality))
+            for name, series in self.series.items()
+        ]
+
+    def series_for(
+        self,
+        snapshot: Snapshot,
+        kind: _Kind,
+        attributes: Mapping[str, str],
+        *,
+        name: str | None = None,
+        unit: str | None = None,
+    ) -> _Series:
+        """The series of ``name`` (the snapshot's id unless given), made
+        from this snapshot if it is the first of its name. The unit is the
+        ``unit`` or ``time_unit`` attribute unless given, else ``"1"``."""
+        name = snapshot.id if name is None else name
+        if name not in self.series:
+            if unit is None:
+                unit = attributes.get("unit", attributes.get("time_unit", "1"))
+            self.series[name] = _Series(kind, snapshot.description or "", unit)
+        return self.series[name]
+
+    def started(self, name: str) -> int:
+        """A data point's start: the interval's for delta, else when the
+        metric was first collected."""
+        if self.delta:
+            return self.interval_start
+        return self.start_times.setdefault(name, self.interval_start)
+
+    def add(self, snapshot: Snapshot) -> None:
+        attributes = dict(snapshot.attributes or {})
+        key = _series_key(snapshot)
+        match snapshot.state:
+            case CounterState() as state:
+                self.counter(snapshot, state, key, attributes)
+            case GaugeState() as state:
+                start = self.start_times.setdefault(snapshot.id, self.start_time)
+                self.series_for(snapshot, "gauge", attributes).points.append(
+                    NumberDataPoint(attributes, start, self.now, state.value)
+                )
+            case HistogramState() as state:
+                self.histogram(snapshot, state, key, attributes)
+            case FrequencyState() as state:
+                self.frequency(snapshot, state, key, attributes)
+            case SummaryState() as state:
+                self.summary(snapshot, state, key, attributes)
+
+    def counter(
+        self, snapshot: Snapshot, state: CounterState[float], key: str, attributes: dict[str, str]
+    ) -> None:
+        value = state.count
+        if self.delta:
+            before = self.previous.counters.get(key)
+            if before is not None:
+                value = state.count - before
+                if state.incremental and value < 0:
+                    value = state.count
+            self.totals.counters[key] = state.count
+        kind: _Kind = "monotonic_sum" if state.incremental else "sum"
+        self.series_for(snapshot, kind, attributes).points.append(
+            NumberDataPoint(attributes, self.started(snapshot.id), self.now, value)
+        )
+
+    def histogram(
+        self, snapshot: Snapshot, state: HistogramState, key: str, attributes: dict[str, str]
+    ) -> None:
+        boundaries, counts = _buckets(state)
+        count, total, reported = state.count, state.sum, counts
+        low, high = state.min, state.max
+        if self.delta:
+            before = self.previous.histograms.get(key)
+            if before is not None:
+                count -= before.count
+                total -= before.sum
+                earlier = [*before.bucket_counts, *[0] * len(counts)]
+                reported = [max(0, c - earlier[i]) for i, c in enumerate(counts)]
+                low = high = _NO_EXTREMUM
+            self.totals.histograms[key] = _HistogramTotals(state.count, state.sum, counts)
+        self.series_for(snapshot, "histogram", attributes).points.append(
+            HistogramDataPoint(
+                attributes,
+                self.started(snapshot.id),
+                self.now,
+                count,
+                total,
+                reported,
+                boundaries,
+                low,
+                high,
+            )
+        )
+
+    def frequency(
+        self, snapshot: Snapshot, state: FrequencyState, key: str, attributes: dict[str, str]
+    ) -> None:
+        before = self.previous.frequencies.get(key) if self.delta else None
+        series = self.series_for(snapshot, "monotonic_sum", attributes)
+        for word, seen in state.occurrences.items():
+            reported = seen if before is None else max(0, seen - before.get(word, 0))
+            series.points.append(
+                NumberDataPoint(
+                    {**attributes, "key": word}, self.started(snapshot.id), self.now, reported
+                )
+            )
+        if self.delta:
+            self.totals.frequencies[key] = dict(state.occurrences)
+
+    def summary(
+        self, snapshot: Snapshot, state: SummaryState, key: str, attributes: dict[str, str]
+    ) -> None:
+        count, total = state.count, state.sum
+        if self.delta:
+            before = self.previous.summaries.get(key)
+            if before is not None:
+                count -= before[0]
+                total -= before[1]
+            self.totals.summaries[key] = (state.count, state.sum)
+        start, now = self.interval_start, self.now
+        labelled = [
+            ("min", state.min),
+            *((js_number(q), 0 if v is None else v) for q, v in state.quantiles),
+            ("max", state.max),
+        ]
+        self.series_for(snapshot, "sum", attributes, name=f"{snapshot.id}_quantiles").points.extend(
+            NumberDataPoint({**attributes, "quantile": label}, start, now, value)
+            for label, value in labelled
+        )
+        for suffix, value in (("count", count), ("sum", total)):
+            self.series_for(
+                snapshot, "monotonic_sum", attributes, name=f"{snapshot.id}_{suffix}", unit="1"
+            ).points.append(NumberDataPoint(attributes, start, now, value))
+
+
+def _series_key(snapshot: Snapshot) -> str:
+    """The metric id and its sorted attributes: one series."""
+    if not snapshot.attributes:
+        return snapshot.id
+    return f"{snapshot.id}:{sorted(snapshot.attributes.items())!r}"
+
+
+def _buckets(state: HistogramState) -> tuple[list[float], list[int]]:
+    """The finite boundaries and the count in each bucket (not cumulative),
+    the last bucket holding everything above the last boundary."""
+    boundaries: list[float] = []
+    counts: list[int] = []
+    below = 0
+    for boundary, cumulative in state.buckets:
+        if boundary == math.inf:
+            break
+        boundaries.append(boundary)
+        counts.append(cumulative - below)
+        below = cumulative
+    counts.append(state.count - below)
+    return boundaries, counts

pyfect/otel/_shutdown.py

@@ -0,0 +1,26 @@
+"""Releasing an SDK provider when its layer is released."""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+from pyfect._core import Effect
+from pyfect.duration import Duration, to_millis
+from pyfect.effect import try_
+
+DEFAULT_SHUTDOWN_TIMEOUT: Duration = 3.0
+"""How long a provider may take to flush when released, in seconds."""
+
+
+class Flushable(Protocol):
+    def force_flush(self, timeout_millis: int = ..., /) -> bool: ...
+
+    def shutdown(self) -> object: ...
+
+
+def flush_and_shut_down(provider: Flushable, timeout: Duration) -> Effect[None]:
+    """Flush ``provider`` (waiting at most ``timeout``), then shut it down
+    even if the flush failed. Errors are ignored, as Effect ignores them."""
+    flush = try_(lambda: provider.force_flush(int(to_millis(timeout))))
+    shut_down = try_(provider.shutdown).ignore()
+    return flush.ensuring(shut_down).ignore()

pyfect/otel/_span.py

@@ -0,0 +1,292 @@
+"""``OtelSpan``: a pyfect span backed by an OpenTelemetry span, and the
+conversions between pyfect spans and OpenTelemetry span contexts."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Final
+
+from opentelemetry import context as otel_context
+from opentelemetry import trace
+from opentelemetry.trace import (
+    INVALID_SPAN,
+    Link,
+    NonRecordingSpan,
+    SpanContext,
+    Status,
+    StatusCode,
+    TraceFlags,
+    TraceState,
+    format_span_id,
+    format_trace_id,
+)
+
+from pyfect.context import Context, Tag
+from pyfect.exit import Exit, Success
+from pyfect.otel._attributes import to_attribute_value, to_attributes
+from pyfect.tracer import (
+    AnySpan,
+    DisablePropagation,
+    Ended,
+    ExternalSpan,
+    SpanKind,
+    SpanLink,
+    SpanRequest,
+    SpanStatus,
+    Started,
+)
+
+
+class OtelTraceFlags(Tag[TraceFlags]):
+    """Trace flags carried in a span's annotations, used instead of its
+    ``sampled`` when it becomes an OpenTelemetry parent or link."""
+
+
+class OtelTraceState(Tag[TraceState]):
+    """Trace state carried in a span's annotations, propagated when it
+    becomes an OpenTelemetry parent or link."""
+
+
+class _OtelParentSpanContext(Tag[SpanContext]):
+    """On a parent taken from the active OpenTelemetry span: its context,
+    kept whole (trace state, locality) for the child."""
+
+
+EFFECT_SPAN_KEY: Final = otel_context.create_key("pyfect.otel.effect_span")
+"""Marks the OpenTelemetry span the bridge made active for a pyfect span,
+so a pyfect run entered from inside it does not take it as a parent."""
+
+_KINDS: Final[Mapping[SpanKind, trace.SpanKind]] = {
+    "internal": trace.SpanKind.INTERNAL,
+    "client": trace.SpanKind.CLIENT,
+    "server": trace.SpanKind.SERVER,
+    "producer": trace.SpanKind.PRODUCER,
+    "consumer": trace.SpanKind.CONSUMER,
+}
+
+
+def is_sampled(flags: int) -> bool:
+    return bool(flags & TraceFlags.SAMPLED)
+
+
+class OtelSpan:
+    """A pyfect span recording into ``span``, an OpenTelemetry span started
+    with ``tracer``. With no parent given (and not a root), the active
+    OpenTelemetry span is the parent, unless the bridge made it active for
+    a pyfect span."""
+
+    __slots__ = (
+        "_attributes",
+        "annotations",
+        "kind",
+        "links",
+        "name",
+        "parent",
+        "sampled",
+        "span",
+        "span_id",
+        "status",
+        "trace_id",
+    )
+
+    def __init__(self, tracer: trace.Tracer, request: SpanRequest) -> None:
+        self.name: str = request.name
+        self.annotations: Context = request.annotations
+        self.links: list[SpanLink] = request.links
+        self.kind: SpanKind = request.kind
+        active = otel_context.get_current()
+        from_active = not request.root and request.parent is None
+        self.parent: AnySpan | None = (
+            _otel_parent(active, request.annotations) if from_active else request.parent
+        )
+        if self.parent is None:
+            parent_context = trace.set_span_in_context(INVALID_SPAN, active)
+        elif from_active and not _overrides_trace_context(request.annotations):
+            # Keep the active span object: some SDKs record children on it.
+            parent_context = active
+        else:
+            parent_context = populate_context(active, self.parent, request.annotations)
+        self.span: trace.Span = tracer.start_span(
+            request.name,
+            context=parent_context,
+            kind=_KINDS[request.kind],
+            links=[_link(link) for link in request.links] or None,
+            start_time=request.start_time,
+        )
+        span_context = self.span.get_span_context()
+        self.span_id: str = format_span_id(span_context.span_id)
+        self.trace_id: str = format_trace_id(span_context.trace_id)
+        self.sampled: bool = is_sampled(span_context.trace_flags)
+        self.status: SpanStatus = Started(request.start_time)
+        self._attributes: dict[str, object] = {}
+
+    def __repr__(self) -> str:
+        return f"OtelSpan({self.name!r})"
+
+    @property
+    def attributes(self) -> Mapping[str, object]:
+        return self._attributes
+
+    def attribute(self, key: str, value: object, /) -> None:
+        if isinstance(self.status, Started):
+            self.span.set_attribute(key, to_attribute_value(value))
+            self._attributes[key] = value
+
+    def add_links(self, links: Sequence[SpanLink], /) -> None:
+        if isinstance(self.status, Started):
+            self.links.extend(links)
+            for link in links:
+                self.span.add_link(make_span_context(link.span), to_attributes(link.attributes))
+
+    def event(
+        self, name: str, start_time: int, attributes: Mapping[str, object] | None = None, /
+    ) -> None:
+        if isinstance(self.status, Started):
+            self.span.add_event(
+                name, None if attributes is None else to_attributes(attributes), start_time
+            )
+
+    def end(self, end_time: int, exit: Exit[object, object], /) -> None:
+        if isinstance(self.status, Ended):
+            return
+        self.status = Ended(self.status.start_time, end_time, exit)
+        if isinstance(exit, Success):
+            self.span.set_status(Status(StatusCode.OK))
+        elif exit.cause.has_interrupts_only:
+            self.span.set_attribute("effect.fiber.interrupted", True)
+        else:
+            errors = exit.cause.pretty_errors()
+            for error in errors:
+                self.span.record_exception(error, timestamp=end_time)
+            if errors:
+                self.span.set_status(Status(StatusCode.ERROR, str(errors[0])))
+            else:
+                self.span.set_status(Status(StatusCode.OK))
+        self.span.end(end_time)
+
+
+def _link(link: SpanLink) -> Link:
+    return Link(make_span_context(link.span), to_attributes(link.attributes))
+
+
+def _otel_parent(active: otel_context.Context, annotations: Context) -> ExternalSpan | None:
+    span = trace.get_current_span(active)
+    if span is otel_context.get_value(EFFECT_SPAN_KEY, active):
+        return None
+    parent = span.get_span_context()
+    if not parent.is_valid:
+        return None
+    return ExternalSpan(
+        span_id=format_span_id(parent.span_id),
+        trace_id=format_trace_id(parent.trace_id),
+        sampled=is_sampled(parent.trace_flags),
+        annotations=annotations.add(_OtelParentSpanContext, parent),
+    )
+
+
+def _overrides_trace_context(annotations: Context) -> bool:
+    return annotations.lookup(OtelTraceFlags)[0] or annotations.lookup(OtelTraceState)[0]
+
+
+def _annotation[S](tag: type[Tag[S]], *contexts: Context) -> S | None:
+    """The first of ``contexts`` holding ``tag``'s service, if any."""
+    for context in contexts:
+        found, value = context.lookup(tag)
+        if found:
+            return value
+    return None
+
+
+def hex_id(text: str) -> int:
+    """A pyfect span id as an OpenTelemetry id; a non-hex id (a no-op
+    span's ``"noop"``) is the invalid id 0."""
+    try:
+        return int(text, 16)
+    except ValueError:
+        return 0
+
+
+def make_external_span(
+    *,
+    trace_id: str,
+    span_id: str,
+    trace_flags: int | None = None,
+    trace_state: str | TraceState | None = None,
+) -> ExternalSpan:
+    """A span from another tracing system, to continue its trace with
+    ``eff.with_parent_span``. Its trace flags and state are kept in its
+    annotations; without flags it is sampled. A trace state given as text
+    is parsed as a ``tracestate`` header."""
+    annotations = Context.empty()
+    if trace_flags is not None:
+        annotations = annotations.add(OtelTraceFlags, TraceFlags(trace_flags))
+    if isinstance(trace_state, str):
+        annotations = annotations.add(OtelTraceState, TraceState.from_header([trace_state]))
+    elif trace_state is not None:
+        annotations = annotations.add(OtelTraceState, trace_state)
+    return ExternalSpan(
+        span_id=span_id,
+        trace_id=trace_id,
+        sampled=True if trace_flags is None else is_sampled(trace_flags),
+        annotations=annotations,
+    )
+
+
+def external_span_of(span_context: SpanContext) -> ExternalSpan:
+    """``make_external_span`` from an OpenTelemetry span context."""
+    return make_external_span(
+        trace_id=format_trace_id(span_context.trace_id),
+        span_id=format_span_id(span_context.span_id),
+        trace_flags=span_context.trace_flags,
+        trace_state=span_context.trace_state,
+    )
+
+
+def make_span_context(span: AnySpan, annotations: Context | None = None) -> SpanContext:
+    """``span`` as an OpenTelemetry span context. Given ``annotations``,
+    trace flags and state come from them, then from the span's annotations;
+    flags default to the span's ``sampled``."""
+    contexts = () if annotations is None else (annotations, span.annotations)
+    found, otel_parent = span.annotations.lookup(_OtelParentSpanContext)
+    if found:
+        parent: SpanContext = otel_parent
+        if annotations is None:
+            return parent
+        flags = _annotation(OtelTraceFlags, *contexts)
+        state = _annotation(OtelTraceState, *contexts)
+        return SpanContext(
+            parent.trace_id,
+            parent.span_id,
+            parent.is_remote,
+            parent.trace_flags if flags is None else flags,
+            parent.trace_state if state is None else state,
+        )
+    flags = _annotation(OtelTraceFlags, *contexts)
+    if flags is None:
+        flags = TraceFlags(TraceFlags.SAMPLED if span.sampled else TraceFlags.DEFAULT)
+    return SpanContext(
+        hex_id(span.trace_id),
+        hex_id(span.span_id),
+        isinstance(span, ExternalSpan),
+        flags,
+        _annotation(OtelTraceState, *contexts),
+    )
+
+
+def populate_context(
+    context: otel_context.Context, span: AnySpan, annotations: Context | None = None
+) -> otel_context.Context:
+    """``context`` with ``span`` as its current OpenTelemetry span."""
+    if isinstance(span, OtelSpan):
+        return trace.set_span_in_context(span.span, context)
+    return trace.set_span_in_context(
+        NonRecordingSpan(make_span_context(span, annotations)), context
+    )
+
+
+def propagated_span(span: AnySpan | None) -> AnySpan | None:
+    """``span``, or its nearest ancestor, that does not disable
+    propagation."""
+    while span is not None and span.annotations.get_unsafe(DisablePropagation):
+        span = None if isinstance(span, ExternalSpan) else span.parent
+    return span