pyfect-dev 0.1.0__py3-none-any.whl

pyfect/tracer/_model.py

@@ -0,0 +1,176 @@
+"""The span model: ``Span``, ``ExternalSpan``, links, statuses, kinds, and
+the ``Tracer`` that makes spans.
+
+Times are whole nanoseconds since the epoch, read from the fiber's
+``Clock`` (Effect's ``bigint`` nanoseconds).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Literal, Protocol, TypedDict
+
+from pyfect._stack_frame import CaptureStackTrace
+from pyfect.context import Context
+from pyfect.exit import Exit
+
+if TYPE_CHECKING:
+    from pyfect._fiber import Fiber
+    from pyfect.logger import LogLevel
+
+type SpanKind = Literal["internal", "server", "client", "producer", "consumer"]
+"""The OpenTelemetry role of the operation a span records."""
+
+
+@dataclass(frozen=True, slots=True)
+class Started:
+    """A span that has not ended yet."""
+
+    start_time: int
+
+
+@dataclass(frozen=True, slots=True)
+class Ended:
+    """A span that has ended, with the exit of what it recorded."""
+
+    start_time: int
+    end_time: int
+    exit: Exit[object, object]
+
+
+type SpanStatus = Started | Ended
+
+
+def _no_annotations() -> Context:
+    return Context.empty()
+
+
+@dataclass(frozen=True, slots=True)
+class ExternalSpan:
+    """A span made outside pyfect (by another tracing system), usable as a
+    parent or a link."""
+
+    span_id: str
+    trace_id: str
+    sampled: bool = True
+    annotations: Context = field(default_factory=_no_annotations)
+
+
+class Span(Protocol):
+    """A span made by a ``Tracer``. Once it has ended, ``end``,
+    ``attribute``, ``event`` and ``add_links`` do nothing; an ended span
+    can still be read and used as a parent."""
+
+    @property
+    def name(self) -> str: ...
+    @property
+    def span_id(self) -> str: ...
+    @property
+    def trace_id(self) -> str: ...
+    @property
+    def parent(self) -> AnySpan | None: ...
+    @property
+    def annotations(self) -> Context: ...
+    @property
+    def status(self) -> SpanStatus: ...
+    @property
+    def attributes(self) -> Mapping[str, object]: ...
+    @property
+    def links(self) -> Sequence[SpanLink]: ...
+    @property
+    def sampled(self) -> bool: ...
+    @property
+    def kind(self) -> SpanKind: ...
+
+    def end(self, end_time: int, exit: Exit[object, object], /) -> None: ...
+
+    def attribute(self, key: str, value: object, /) -> None: ...
+
+    def event(
+        self, name: str, start_time: int, attributes: Mapping[str, object] | None = None, /
+    ) -> None: ...
+
+    def add_links(self, links: Sequence[SpanLink], /) -> None: ...
+
+
+type AnySpan = Span | ExternalSpan
+"""A span pyfect made, or one from another tracing system. Tell them
+apart with ``isinstance(span, ExternalSpan)``."""
+
+
+@dataclass(frozen=True, slots=True)
+class SpanLink:
+    """A link from one span to another that is not its parent."""
+
+    span: AnySpan
+    attributes: Mapping[str, object] = field(default_factory=dict[str, object])
+
+
+class SpanOptions(TypedDict, total=False):
+    """What every span-making function takes as keyword arguments.
+
+    - ``attributes``: set on the span when it starts
+    - ``links``: added after the links ``link_spans`` put in scope
+    - ``parent``: the parent, instead of the current span
+    - ``root``: no parent (``parent`` still wins)
+    - ``annotations``: a ``Context`` the span carries (``DisablePropagation``)
+    - ``kind``: ``"internal"`` unless given
+    - ``sampled``: decided here instead of from the levels and the parent
+    - ``level``: the span's trace level, instead of ``CurrentTraceLevel``
+    """
+
+    attributes: Mapping[str, object]
+    links: Sequence[SpanLink]
+    parent: AnySpan
+    root: bool
+    annotations: Context
+    kind: SpanKind
+    sampled: bool
+    level: LogLevel
+
+
+class TracedSpanOptions(SpanOptions, total=False):
+    """``SpanOptions`` for the functions that also run inside the span's
+    stack frame (``with_span``, ``with_span_scoped``, ``Layer.with_span``).
+
+    - ``capture_stack_trace``: ``True`` (the default) records the call
+      site, ``False`` records no location, a function gives it lazily
+    """
+
+    capture_stack_trace: CaptureStackTrace
+
+
+@dataclass(frozen=True, slots=True)
+class SpanRequest:
+    """What a ``Tracer`` gets to make a span from. The links are a fresh
+    list the span may keep."""
+
+    name: str
+    parent: AnySpan | None
+    annotations: Context
+    links: list[SpanLink]
+    start_time: int
+    kind: SpanKind
+    root: bool
+    sampled: bool
+
+
+class ContextHook(Protocol):
+    """Runs one step of a fiber: call ``run()`` and return what it returns.
+    A tracer bridge sets its own context (the active span) around it."""
+
+    def __call__[T](self, run: Callable[[], T], fiber: Fiber[Any, Any], /) -> T: ...
+
+
+@dataclass(frozen=True, slots=True)
+class Tracer:
+    """A tracing backend: ``span`` makes each span. ``context``, when given,
+    runs every step of a fiber whose context holds this tracer."""
+
+    span: Callable[[SpanRequest], Span]
+    context: ContextHook | None = None
+
+    @staticmethod
+    def make(span: Callable[[SpanRequest], Span], context: ContextHook | None = None) -> Tracer:
+        return Tracer(span, context)

pyfect/tracer/_native.py

@@ -0,0 +1,172 @@
+"""The built-in spans: ``NativeSpan`` (the native tracer's, kept in memory)
+and the no-op span made where propagation is disabled."""
+
+from __future__ import annotations
+
+import random
+from collections.abc import Mapping, Sequence
+from typing import Final
+
+from pyfect.context import Context
+from pyfect.exit import Exit, Success
+from pyfect.tracer._model import (
+    AnySpan,
+    Ended,
+    SpanKind,
+    SpanLink,
+    SpanRequest,
+    SpanStatus,
+    Started,
+    Tracer,
+)
+
+type SpanEvent = tuple[str, int, Mapping[str, object]]
+"""An event recorded on a span: its name, time and attributes."""
+
+
+def _hex_id(digits: int) -> str:
+    return f"{random.getrandbits(digits * 4):0{digits}x}"
+
+
+class NativeSpan:
+    """The native tracer's span: it records its attributes, events and
+    links in memory and exports nothing. Its trace id is its parent's, and
+    its ids are made when first read."""
+
+    __slots__ = (
+        "_attributes",
+        "_events",
+        "_span_id",
+        "_trace_id",
+        "annotations",
+        "kind",
+        "links",
+        "name",
+        "parent",
+        "sampled",
+        "start_time",
+        "status",
+    )
+
+    def __init__(self, request: SpanRequest) -> None:
+        self.name: str = request.name
+        self.parent: AnySpan | None = request.parent
+        self.annotations: Context = request.annotations
+        self.links: list[SpanLink] = request.links
+        self.start_time: int = request.start_time
+        self.kind: SpanKind = request.kind
+        self.sampled: bool = request.sampled
+        self.status: SpanStatus = Started(request.start_time)
+        self._trace_id: str | None = None
+        self._span_id: str | None = None
+        self._attributes: dict[str, object] | None = None
+        self._events: list[SpanEvent] | None = None
+
+    def __repr__(self) -> str:
+        return f"NativeSpan({self.name!r})"
+
+    @property
+    def trace_id(self) -> str:
+        if self._trace_id is None:
+            self._trace_id = _hex_id(32) if self.parent is None else self.parent.trace_id
+        return self._trace_id
+
+    @property
+    def span_id(self) -> str:
+        if self._span_id is None:
+            self._span_id = _hex_id(16)
+        return self._span_id
+
+    @property
+    def attributes(self) -> dict[str, object]:
+        if self._attributes is None:
+            self._attributes = {}
+        return self._attributes
+
+    @property
+    def events(self) -> list[SpanEvent]:
+        if self._events is None:
+            self._events = []
+        return self._events
+
+    def end(self, end_time: int, exit: Exit[object, object], /) -> None:
+        if isinstance(self.status, Started):
+            self.status = Ended(self.status.start_time, end_time, exit)
+
+    def attribute(self, key: str, value: object, /) -> None:
+        if isinstance(self.status, Started):
+            self.attributes[key] = value
+
+    def event(
+        self, name: str, start_time: int, attributes: Mapping[str, object] | None = None, /
+    ) -> None:
+        if isinstance(self.status, Started):
+            self.events.append((name, start_time, {} if attributes is None else attributes))
+
+    def add_links(self, links: Sequence[SpanLink], /) -> None:
+        if isinstance(self.status, Started):
+            self.links.extend(links)
+
+
+native_tracer: Final = Tracer(NativeSpan)
+"""The default tracer: it makes ``NativeSpan``s and exports nothing."""
+
+_NOOP_STATUS: Final = Ended(0, 0, Success(None))
+_NO_ATTRIBUTES: Final[Mapping[str, object]] = {}
+
+
+class NoopSpan:
+    """A span that records nothing, made where propagation is disabled or
+    the tracer is off. Its ids are ``"noop"`` and it starts out ended."""
+
+    __slots__ = ("annotations", "name", "parent")
+
+    @property
+    def span_id(self) -> str:
+        return "noop"
+
+    @property
+    def trace_id(self) -> str:
+        return "noop"
+
+    @property
+    def sampled(self) -> bool:
+        return False
+
+    @property
+    def kind(self) -> SpanKind:
+        return "internal"
+
+    @property
+    def status(self) -> SpanStatus:
+        return _NOOP_STATUS
+
+    @property
+    def attributes(self) -> Mapping[str, object]:
+        return _NO_ATTRIBUTES
+
+    @property
+    def links(self) -> Sequence[SpanLink]:
+        return ()
+
+    def __init__(self, name: str, parent: AnySpan | None, annotations: Context) -> None:
+        self.name = name
+        self.parent = parent
+        self.annotations = annotations
+
+    def __repr__(self) -> str:
+        return f"NoopSpan({self.name!r})"
+
+    def end(self, end_time: int, exit: Exit[object, object], /) -> None:
+        pass
+
+    def attribute(self, key: str, value: object, /) -> None:
+        pass
+
+    def event(
+        self, name: str, start_time: int, attributes: Mapping[str, object] | None = None, /
+    ) -> None:
+        pass
+
+    def add_links(self, links: Sequence[SpanLink], /) -> None:
+        pass

pyfect/tracer/_refs.py

@@ -0,0 +1,87 @@
+"""The references tracing reads (Effect's ``Tracer`` and ``References``
+tracing references)."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from types import MappingProxyType
+from typing import TYPE_CHECKING
+
+from pyfect.context import Reference
+from pyfect.tracer._model import AnySpan, SpanLink
+
+if TYPE_CHECKING:
+    from pyfect.logger import LogLevel
+
+
+class ParentSpan(Reference[AnySpan | None]):
+    """The span new spans are children of: the innermost ``with_span``, or
+    ``None`` outside every span."""
+
+    @classmethod
+    def default(cls) -> AnySpan | None:
+        return None
+
+
+class DisablePropagation(Reference[bool]):
+    """When true in a span's annotations, the span is a no-op span and is
+    never used as a parent; ``False`` by default."""
+
+    @classmethod
+    def default(cls) -> bool:
+        return False
+
+
+class CurrentTraceLevel(Reference["LogLevel"]):
+    """The trace level of spans that do not give one. ``INFO`` by default."""
+
+    @classmethod
+    def default(cls) -> LogLevel:
+        from pyfect.logger import LogLevel
+
+        return LogLevel.INFO
+
+
+class MinimumTraceLevel(Reference["LogLevel"]):
+    """Spans below this trace level are not sampled. ``ALL`` by default."""
+
+    @classmethod
+    def default(cls) -> LogLevel:
+        from pyfect.logger import LogLevel
+
+        return LogLevel.ALL
+
+
+class TracerEnabled(Reference[bool]):
+    """When false, every span made is a no-op span. ``True`` by default."""
+
+    @classmethod
+    def default(cls) -> bool:
+        return True
+
+
+class TracerTimingEnabled(Reference[bool]):
+    """When false, spans start and end at time 0. ``True`` by default."""
+
+    @classmethod
+    def default(cls) -> bool:
+        return True
+
+
+_NO_ANNOTATIONS: Mapping[str, object] = MappingProxyType({})
+
+
+class TracerSpanAnnotations(Reference[Mapping[str, object]]):
+    """Attributes set on every span made in scope (``annotate_spans``)."""
+
+    @classmethod
+    def default(cls) -> Mapping[str, object]:
+        return _NO_ANNOTATIONS
+
+
+class TracerSpanLinks(Reference[tuple[SpanLink, ...]]):
+    """Links added to every span made in scope (``link_spans``)."""
+
+    @classmethod
+    def default(cls) -> tuple[SpanLink, ...]:
+        return ()

pyfect/tracer/_spans.py

@@ -0,0 +1,269 @@
+"""Making spans: the effects that start, end and read them.
+
+A span made by ``use_span`` / ``with_span`` ends when the effect it wraps
+ends, however it ends: the frame that ends it is pushed in the same step
+that makes the span, so an interrupt cannot land between the two.
+"""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from typing import Any, Never, Unpack, final, overload
+
+from pyfect._core import Effect, Frame, Step, _FailCause, _Locally, _Succeed, _WithFiber
+from pyfect._fiber import Fiber
+from pyfect._stack_frame import CurrentStackFrame, StackFrame
+from pyfect._tracer_ref import CurrentTracer
+from pyfect.cause import Cause
+from pyfect.cause import fail as fail_cause
+from pyfect.clock import Clock, ClockService
+from pyfect.context import Context
+from pyfect.errors import NoSuchElementException
+from pyfect.exit import Exit, Failure, Success
+from pyfect.scope import Scope
+from pyfect.tracer._model import (
+    AnySpan,
+    Ended,
+    ExternalSpan,
+    Span,
+    SpanOptions,
+    SpanRequest,
+)
+from pyfect.tracer._native import NoopSpan
+from pyfect.tracer._refs import (
+    CurrentTraceLevel,
+    DisablePropagation,
+    MinimumTraceLevel,
+    ParentSpan,
+    TracerEnabled,
+    TracerSpanAnnotations,
+    TracerSpanLinks,
+    TracerTimingEnabled,
+)
+
+_VOID: Effect[None] = _Succeed(None)
+
+
+def _propagating(span: AnySpan | None) -> AnySpan | None:
+    """``span``, or the nearest ancestor of it whose annotations do 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
+
+
+def make_span_unsafe(fiber: Fiber[Any, Any], name: str, options: SpanOptions) -> Span:
+    """A new span, started now, a child of the fiber's current span unless
+    ``options`` say otherwise."""
+    annotations = options.get("annotations")
+    disabled = not fiber.get_ref(TracerEnabled) or (
+        annotations is not None and annotations.get_unsafe(DisablePropagation)
+    )
+    parent = options.get("parent")
+    if parent is None and not options.get("root", False):
+        parent = _propagating(fiber.get_ref(ParentSpan))
+    if annotations is None:
+        annotations = Context.empty()
+    if disabled:
+        return NoopSpan(name, parent, annotations.add(DisablePropagation, True))
+    level = options.get("level")
+    if level is None:
+        level = fiber.get_ref(CurrentTraceLevel)
+    sampled = options.get("sampled")
+    if sampled is None:
+        sampled = (parent is None or parent.sampled) and not (
+            fiber.get_ref(MinimumTraceLevel) > level
+        )
+    timing = fiber.get_ref(TracerTimingEnabled)
+    span = fiber.get_ref(CurrentTracer).span(
+        SpanRequest(
+            name=name,
+            parent=parent,
+            annotations=annotations,
+            links=[*fiber.get_ref(TracerSpanLinks), *options.get("links", ())],
+            start_time=fiber.get_ref(Clock).now_nanos_unsafe() if timing else 0,
+            kind=options.get("kind", "internal"),
+            root=options.get("root", False),
+            sampled=sampled,
+        )
+    )
+    for key, value in fiber.get_ref(TracerSpanAnnotations).items():
+        span.attribute(key, value)
+    for key, value in options.get("attributes", {}).items():
+        span.attribute(key, value)
+    return span
+
+
+def make_span(name: str, **options: Unpack[SpanOptions]) -> Effect[Span]:
+    """A new span, started now. Nothing ends it: end it yourself, or use
+    ``use_span`` / ``make_span_scoped``."""
+    return _WithFiber(lambda fiber: _Succeed(make_span_unsafe(fiber, name, options)))
+
+
+def make_span_scoped(name: str, **options: Unpack[SpanOptions]) -> Effect[Span, Never, Scope]:
+    """A new span, ended when the current scope closes, with the scope's
+    exit."""
+    return span_scoped(name, options)
+
+
+def span_scoped(name: str, options: SpanOptions) -> Effect[Span, Never, Scope]:
+    """``make_span_scoped`` taking its options as a dict."""
+
+    def body(fiber: Fiber[Any, Any]) -> Effect[Span]:
+        span = make_span_unsafe(fiber, name, options)
+        end = _SpanEnder(span, fiber.get_ref(Clock), fiber.get_ref(TracerTimingEnabled))
+
+        def finalizer(ex: Exit[Any, Any]) -> Effect[None]:
+            end(ex)
+            return _VOID
+
+        return fiber._context.get_unsafe(Scope).add_finalizer(finalizer).as_(span)
+
+    return _WithFiber(body).uninterruptible()
+
+
+def use_span[A, E = Never, R = Never](
+    name: str, f: Callable[[Span], Effect[A, E, R]], /, **options: Unpack[SpanOptions]
+) -> Effect[A, E, R]:
+    """Run ``f(span)`` with a new span, ended when the effect ``f`` returns
+    ends (or when ``f`` raises). The span is not made the parent of spans
+    inside; ``with_span`` does that."""
+    return _UseSpan(name, f, options)
+
+
+def span_using[A, E, R](
+    name: str, f: Callable[[Span], Effect[A, E, R]], options: SpanOptions
+) -> Effect[A, E, R]:
+    """``use_span`` taking its options as a dict."""
+    return _UseSpan(name, f, options)
+
+
+def in_parent_span[A, E, R](eff: Effect[A, E, R], span: AnySpan) -> Effect[A, E, R]:
+    """Run ``eff`` with ``span`` as the parent of the spans made inside."""
+    return _Locally(eff, lambda ctx: ctx.add(ParentSpan, span))
+
+
+def in_span_frame[A, E, R](
+    eff: Effect[A, E, R], span: AnySpan, stack: Callable[[], str | None]
+) -> Effect[A, E, R]:
+    """``in_parent_span``, also inside a stack frame named after ``span``
+    at ``stack`` (an external span adds no frame), as Effect's
+    ``withParentSpan``."""
+    if isinstance(span, ExternalSpan):
+        return in_parent_span(eff, span)
+    name = span.name
+
+    def enter(ctx: Context) -> Context:
+        frame = StackFrame(name, stack, ctx.lookup(CurrentStackFrame)[1])
+        return ctx.add(ParentSpan, span).add(CurrentStackFrame, frame)
+
+    return _Locally(eff, enter)
+
+
+@final
+class _SpanEnder:
+    """Ends a span with an exit, at the time of the clock the span started
+    with, unless it has ended already."""
+
+    __slots__ = ("clock", "span", "timing")
+
+    def __init__(self, span: Span, clock: ClockService, timing: bool) -> None:
+        self.span = span
+        self.clock = clock
+        self.timing = timing
+
+    def __call__(self, ex: Exit[object, object]) -> None:
+        if not isinstance(self.span.status, Ended):
+            self.span.end(self.clock.now_nanos_unsafe() if self.timing else 0, ex)
+
+
+@final
+class _UseSpan[A, E, R](Effect[A, E, R]):
+    __slots__ = ("f", "name", "options")
+
+    def __init__(
+        self, name: str, f: Callable[[Span], Effect[A, E, R]], options: SpanOptions
+    ) -> None:
+        self.name = name
+        self.f = f
+        self.options = options
+
+    def _step(self, fiber: Fiber[Any, Any]) -> Step:
+        span = make_span_unsafe(fiber, self.name, self.options)
+        fiber._push(
+            _EndSpan(_SpanEnder(span, fiber.get_ref(Clock), fiber.get_ref(TracerTimingEnabled)))
+        )
+        return self.f(span)
+
+
+@final
+class _EndSpan(Frame):
+    __slots__ = ("end",)
+
+    def __init__(self, end: _SpanEnder) -> None:
+        self.end = end
+
+    def _on_success(self, value: Any, fiber: Fiber[Any, Any]) -> Step:
+        ex = Success(value)
+        self.end(ex)
+        return ex
+
+    def _on_failure(self, cause: Cause[Any], fiber: Fiber[Any, Any]) -> Step:
+        ex = Failure(cause)
+        self.end(ex)
+        return ex
+
+
+def local_span(fiber: Fiber[Any, Any]) -> Span | None:
+    """The fiber's current span, unless there is none or it is external."""
+    span = fiber.get_ref(ParentSpan)
+    return None if span is None or isinstance(span, ExternalSpan) else span
+
+
+def current_span() -> Effect[Span, NoSuchElementException]:
+    """The current span; fails when there is none or it is external."""
+
+    def body(fiber: Fiber[Any, Any]) -> Effect[Span, NoSuchElementException]:
+        span = local_span(fiber)
+        if span is None:
+            return _FailCause(fail_cause(NoSuchElementException()))
+        return _Succeed(span)
+
+    return _WithFiber(body)
+
+
+def current_parent_span() -> Effect[AnySpan, NoSuchElementException]:
+    """The current span, external or not; fails outside every span."""
+
+    def body(fiber: Fiber[Any, Any]) -> Effect[AnySpan, NoSuchElementException]:
+        span = fiber.get_ref(ParentSpan)
+        if span is None:
+            return _FailCause(fail_cause(NoSuchElementException()))
+        return _Succeed(span)
+
+    return _WithFiber(body)
+
+
+_MISSING: Any = object()
+
+
+@overload
+def annotate_current_span(key: str, value: object, /) -> Effect[None]: ...
+@overload
+def annotate_current_span(values: Mapping[str, object], /) -> Effect[None]: ...
+def annotate_current_span(
+    key_or_values: str | Mapping[str, object], value: object = _MISSING, /
+) -> Effect[None]:
+    """Set attributes on the current span, unless there is none or it has
+    ended."""
+    added = {key_or_values: value} if isinstance(key_or_values, str) else key_or_values
+
+    def body(fiber: Fiber[Any, Any]) -> Effect[None]:
+        span = local_span(fiber)
+        if span is not None and not isinstance(span.status, Ended):
+            for k, v in added.items():
+                span.attribute(k, v)
+        return _VOID
+
+    return _WithFiber(body)