encore-dev 2.0.0a7__py3-none-any.whl

encore/tracing/_encode.py

@@ -0,0 +1,351 @@
+"""Encoding spans as packed buffers.
+
+The decoder documents the layouts in crates/encore_telemetry/src/packed.rs.
+"""
+
+from __future__ import annotations
+
+import struct
+from typing import Any, Mapping, NamedTuple, Optional, Sequence
+
+from opentelemetry.trace import Link, SpanContext
+
+VERSION = 1
+HEADER_LEN = 120
+ATTR_LEN = 24
+ITEM_LEN = 8
+EVENT_LEN = 24
+LINK_LEN = 48
+
+#: Length of a span context buffer: trace id, span id, flags.
+CTX_LEN = 25
+
+#: Bounds the buffer; the runtime enforces the real limits.
+MAX_COUNT = 128
+
+TYPE_STR = 0
+TYPE_BOOL = 1
+TYPE_I64 = 2
+TYPE_F64 = 3
+TYPE_STR_ARRAY = 4
+TYPE_BOOL_ARRAY = 5
+TYPE_I64_ARRAY = 6
+TYPE_F64_ARRAY = 7
+
+_I64_MAX = (1 << 63) - 1
+_I64_MIN = -(1 << 63)
+
+_U32 = struct.Struct("<I")
+_U64 = struct.Struct("<Q")
+_I64 = struct.Struct("<q")
+_F64 = struct.Struct("<d")
+
+Attributes = Optional[Mapping[str, Any]]
+
+
+class Scope(NamedTuple):
+    """An instrumentation scope; an empty version is none."""
+
+    name: str
+    version: str = ""
+
+
+class Value(NamedTuple):
+    t: int
+    v: Any
+
+
+def _clamp(v: int) -> int:
+    return _I64_MAX if v > _I64_MAX else _I64_MIN if v < _I64_MIN else v
+
+
+def to_value(v: object) -> Value | None:
+    """An attribute value as a packed value; ``None`` when unsupported."""
+    if isinstance(v, str):
+        return Value(TYPE_STR, v)
+    if isinstance(v, bool):
+        return Value(TYPE_BOOL, v)
+    if isinstance(v, int):
+        return Value(TYPE_I64, _clamp(v))
+    if isinstance(v, float):
+        return Value(TYPE_F64, v)
+    if isinstance(v, (list, tuple)):
+        return _array_value(v)
+    return None
+
+
+def _array_value(arr: Sequence[object]) -> Value | None:
+    """Typed by the first non-None item; items of other types are dropped."""
+    first = next((x for x in arr if x is not None), None)
+    if first is None or isinstance(first, str):
+        return Value(TYPE_STR_ARRAY, [x for x in arr if isinstance(x, str)])
+    if isinstance(first, bool):
+        return Value(TYPE_BOOL_ARRAY, [x for x in arr if isinstance(x, bool)])
+    if isinstance(first, (int, float)):
+        nums = [
+            x for x in arr if isinstance(x, (int, float)) and not isinstance(x, bool)
+        ]
+        if all(isinstance(x, int) for x in nums):
+            return Value(TYPE_I64_ARRAY, [_clamp(int(x)) for x in nums])
+        return Value(TYPE_F64_ARRAY, [float(x) for x in nums])
+    return None
+
+
+class _Event(NamedTuple):
+    name: str
+    time_unix_nanos: int
+    first: int
+    count: int
+
+
+class _Link(NamedTuple):
+    ctx: bytes
+    tracestate: str
+    first: int
+    count: int
+
+
+class PackedWriter:
+    """A builder for one packed span buffer.
+
+    Write span attributes first, then events and links in any order, and
+    finally call finish().
+    """
+
+    def __init__(self) -> None:
+        self._attrs: list[tuple[str, Value]] = []
+        self._span_attr_count = 0
+        self._events: list[_Event] = []
+        self._links: list[_Link] = []
+
+    def span_attrs(self, attrs: Attributes) -> PackedWriter:
+        if self._attrs or self._events or self._links:
+            raise ValueError("span attributes must be written first")
+        self._push_attrs(attrs)
+        self._span_attr_count = len(self._attrs)
+        return self
+
+    def event(
+        self, name: str, time_unix_nanos: int, attrs: Attributes = None
+    ) -> PackedWriter:
+        if len(self._events) >= MAX_COUNT:
+            return self
+        first, count = self._push_attrs(attrs)
+        self._events.append(_Event(name, time_unix_nanos, first, count))
+        return self
+
+    def link(
+        self, ctx: bytes, tracestate: str, attrs: Attributes = None
+    ) -> PackedWriter:
+        """``ctx``: 25 bytes."""
+        if len(self._links) >= MAX_COUNT:
+            return self
+        first, count = self._push_attrs(attrs)
+        self._links.append(_Link(ctx, tracestate, first, count))
+        return self
+
+    def _push_attrs(self, attrs: Attributes) -> tuple[int, int]:
+        first = len(self._attrs)
+        if attrs:
+            n = 0
+            for key, raw in attrs.items():
+                if n >= MAX_COUNT:
+                    break
+                value = to_value(raw)
+                if value is None:
+                    continue
+                self._attrs.append((key, value))
+                n += 1
+        return first, len(self._attrs) - first
+
+    def finish(
+        self,
+        *,
+        scope: Scope,
+        name: str,
+        kind: int,
+        status_code: int,
+        status_message: str = "",
+        tracestate: str = "",
+        ctx: bytes | None = None,
+        parent_span_id: bytes | None = None,
+        start_unix_nanos: int = 0,
+        start_mono_nanos: int = 0,
+        end_unix_nanos: int = 0,
+    ) -> bytes:
+        attrs = self._attrs
+        attrs_off = HEADER_LEN
+        items_off = attrs_off + len(attrs) * ATTR_LEN
+        events_off = items_off + _item_count(attrs) * ITEM_LEN
+        links_off = events_off + len(self._events) * EVENT_LEN
+        t = _Buffer(links_off + len(self._links) * LINK_LEN)
+        fixed = t.fixed
+
+        fixed[0] = VERSION
+        fixed[1] = kind
+        fixed[2] = status_code
+        fixed[3] = ctx[24] if ctx else 0
+        _U32.pack_into(fixed, 4, self._span_attr_count)
+        _U32.pack_into(fixed, 8, len(attrs))
+        _U32.pack_into(fixed, 12, _item_count(attrs))
+        _U32.pack_into(fixed, 16, len(self._events))
+        _U32.pack_into(fixed, 20, len(self._links))
+        t.ref(24, name)
+        t.ref(32, status_message)
+        t.ref(40, tracestate)
+        t.ref(104, scope.name)
+        t.ref(112, scope.version)
+        if ctx:
+            fixed[48:72] = ctx[:24]
+        if parent_span_id:
+            fixed[72:80] = parent_span_id[:8]
+        _U64.pack_into(fixed, 80, start_unix_nanos)
+        _U64.pack_into(fixed, 88, start_mono_nanos)
+        _U64.pack_into(fixed, 96, end_unix_nanos)
+
+        t.attrs(attrs, attrs_off, items_off)
+
+        for i, e in enumerate(self._events):
+            off = events_off + i * EVENT_LEN
+            t.ref(off, e.name)
+            _U64.pack_into(fixed, off + 8, e.time_unix_nanos)
+            _U32.pack_into(fixed, off + 16, e.first)
+            _U32.pack_into(fixed, off + 20, e.count)
+
+        for i, link in enumerate(self._links):
+            off = links_off + i * LINK_LEN
+            fixed[off : off + CTX_LEN] = link.ctx[:CTX_LEN]
+            t.ref(off + 28, link.tracestate)
+            _U32.pack_into(fixed, off + 36, link.first)
+            _U32.pack_into(fixed, off + 40, link.count)
+
+        return t.finish()
+
+
+def _item_count(attrs: Sequence[tuple[str, Value]]) -> int:
+    return sum(len(v.v) for _, v in attrs if v.t >= TYPE_STR_ARRAY)
+
+
+class _Buffer:
+    """The fixed sections of a buffer, then its data table."""
+
+    def __init__(self, fixed_len: int) -> None:
+        self.fixed = bytearray(fixed_len)
+        self._table: list[bytes] = []
+        self._table_len = 0
+
+    def ref(self, off: int, data: str) -> None:
+        """Write a string reference and append its data to the table."""
+        b = data.encode("utf-8")
+        _U32.pack_into(self.fixed, off, self._table_len)
+        _U32.pack_into(self.fixed, off + 4, len(b))
+        if b:
+            self._table.append(b)
+            self._table_len += len(b)
+
+    def attrs(
+        self, attrs: Sequence[tuple[str, Value]], attrs_off: int, items_off: int
+    ) -> None:
+        fixed = self.fixed
+        item = 0
+        for i, (key, value) in enumerate(attrs):
+            off = attrs_off + i * ATTR_LEN
+            self.ref(off, key)
+            fixed[off + 8] = value.t
+            v = off + 16
+            t = value.t
+            if t == TYPE_STR:
+                self.ref(v, value.v)
+            elif t == TYPE_BOOL:
+                fixed[v] = 1 if value.v else 0
+            elif t == TYPE_I64:
+                _I64.pack_into(fixed, v, value.v)
+            elif t == TYPE_F64:
+                _F64.pack_into(fixed, v, value.v)
+            else:
+                _U32.pack_into(fixed, v, item)
+                _U32.pack_into(fixed, v + 4, len(value.v))
+                for x in value.v:
+                    o = items_off + item * ITEM_LEN
+                    item += 1
+                    if t == TYPE_STR_ARRAY:
+                        self.ref(o, x)
+                    elif t == TYPE_BOOL_ARRAY:
+                        fixed[o] = 1 if x else 0
+                    elif t == TYPE_I64_ARRAY:
+                        _I64.pack_into(fixed, o, x)
+                    else:
+                        _F64.pack_into(fixed, o, x)
+
+    def finish(self) -> bytes:
+        return bytes(self.fixed) + b"".join(self._table)
+
+
+def ctx_bytes(sc: SpanContext) -> bytes:
+    """The 25-byte buffer of a span context."""
+    return (
+        sc.trace_id.to_bytes(16, "big")
+        + sc.span_id.to_bytes(8, "big")
+        + bytes([sc.trace_flags & 0xFF])
+    )
+
+
+def _write_links(w: PackedWriter, links: Sequence[Link] | None) -> None:
+    for link in links or ():
+        w.link(
+            ctx_bytes(link.context),
+            link.context.trace_state.to_header(),
+            link.attributes,
+        )
+
+
+def encode_start(
+    scope: Scope, attrs: Attributes, links: Sequence[Link] | None
+) -> bytes:
+    """The start buffer: scope, attributes, and links; other fields zero."""
+    w = PackedWriter().span_attrs(attrs)
+    _write_links(w, links)
+    return w.finish(scope=scope, name="", kind=0, status_code=0)
+
+
+class Event(NamedTuple):
+    name: str
+    time_unix_nanos: int
+    attributes: Attributes = None
+
+
+def encode_end(
+    *,
+    scope: Scope,
+    name: str,
+    kind: int,
+    status_code: int,
+    status_message: str,
+    tracestate: str,
+    ctx: bytes,
+    parent_span_id: bytes | None,
+    start_unix_nanos: int,
+    start_mono_nanos: int,
+    end_unix_nanos: int,
+    attributes: Attributes,
+    events: Sequence[Event],
+    links: Sequence[Link],
+) -> bytes:
+    """The end buffer of a finished span."""
+    w = PackedWriter().span_attrs(attributes)
+    for e in events:
+        w.event(e.name, e.time_unix_nanos, e.attributes)
+    _write_links(w, links)
+    return w.finish(
+        scope=scope,
+        name=name,
+        kind=kind,
+        status_code=status_code,
+        status_message=status_message,
+        tracestate=tracestate,
+        ctx=ctx,
+        parent_span_id=parent_span_id,
+        start_unix_nanos=start_unix_nanos,
+        start_mono_nanos=start_mono_nanos,
+        end_unix_nanos=end_unix_nanos,
+    )

encore/tracing/_provider.py

@@ -0,0 +1,62 @@
+"""The ``opentelemetry.trace.TracerProvider`` the runtime installs."""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Optional
+
+from opentelemetry import propagate, trace
+from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator
+from opentelemetry.util import types
+
+from ._encode import Scope
+from ._span import Backend
+from ._tracer import Tracer
+
+logger = logging.getLogger(__name__)
+
+
+class TracerProvider(trace.TracerProvider):
+    """One tracer per instrumentation scope."""
+
+    def __init__(self, backend: Backend) -> None:
+        self._backend = backend
+        self._tracers: dict[Scope, Tracer] = {}
+
+    def get_tracer(
+        self,
+        instrumenting_module_name: str,
+        instrumenting_library_version: Optional[str] = None,
+        schema_url: Optional[str] = None,
+        attributes: types.Attributes = None,
+    ) -> Tracer:
+        scope = Scope(instrumenting_module_name, instrumenting_library_version or "")
+        tracer = self._tracers.get(scope)
+        if tracer is None:
+            tracer = self._tracers.setdefault(scope, Tracer(self._backend, scope))
+        return tracer
+
+
+_installed = False
+
+
+def install(backend: Backend) -> None:
+    """Register the tracer provider and W3C propagator globally.
+
+    Repeated calls leave the installed OpenTelemetry globals unchanged.
+    """
+    global _installed
+    if _installed:
+        return
+    _installed = True
+    # Instrumentations read this at import; Encore records stable semconv (ADR 0004).
+    os.environ.setdefault("OTEL_SEMCONV_STABILITY_OPT_IN", "http")
+    provider = TracerProvider(backend)
+    trace.set_tracer_provider(provider)
+    if trace.get_tracer_provider() is not provider:
+        logger.error(
+            "encore: a tracer provider was already registered; "
+            "spans from opentelemetry-api are not recorded"
+        )
+    propagate.set_global_textmap(TraceContextTextMapPropagator())

encore/tracing/_span.py

@@ -0,0 +1,226 @@
+"""A recording span with Python-owned state.
+
+Ending a span crosses to the native runtime once.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+import time
+import traceback
+from typing import Any, Mapping, Optional, Protocol, Sequence
+
+from opentelemetry import trace
+from opentelemetry.trace import (
+    Link,
+    SpanContext,
+    SpanKind,
+    Status,
+    StatusCode,
+    TraceFlags,
+    TraceState,
+)
+from opentelemetry.util import types
+
+from ._encode import MAX_COUNT, Event, Scope, encode_end
+
+logger = logging.getLogger(__name__)
+
+
+class Backend(Protocol):
+    """The runtime's span lifecycle calls (the native ``Pipeline``)."""
+
+    def start_span(
+        self,
+        name: str,
+        kind: int,
+        parent: Optional[bytes],
+        tracestate: Optional[str],
+        start_unix_nanos: Optional[int],
+        packed: bytes,
+    ) -> tuple[bytes, str, int, int]: ...
+
+    def end_span(self, packed: bytes) -> None: ...
+
+
+class Span(trace.Span):
+    """A recording span: identity plus accumulated data."""
+
+    def __init__(
+        self,
+        *,
+        backend: Backend,
+        scope: Scope,
+        ctx_bytes: bytes,
+        tracestate: str,
+        name: str,
+        kind: SpanKind,
+        parent_span_id: bytes | None,
+        start_unix_nanos: int,
+        start_mono_nanos: int,
+        attributes: types.Attributes = None,
+        links: Sequence[Link] | None = None,
+    ) -> None:
+        self.ctx_bytes = ctx_bytes
+        self._backend = backend
+        self._scope = scope
+        self._tracestate = tracestate
+        self._name = name
+        self._kind = kind
+        self._parent_span_id = parent_span_id
+        self._start_unix_nanos = start_unix_nanos
+        self._start_mono_nanos = start_mono_nanos
+        self._attrs: dict[str, Any] = {}
+        self._links: list[Link] = list(links or ())[:MAX_COUNT]
+        self._events: list[Event] = []
+        self._status = Status(StatusCode.UNSET)
+        self._ended = False
+        self._lock = threading.Lock()
+        self._ctx: SpanContext | None = None
+        self._sampled = bool(ctx_bytes[24] & TraceFlags.SAMPLED)
+        if attributes:
+            self.set_attributes(attributes)
+
+    # `name` and `kind` mirror the SDK's `ReadableSpan`; instrumentations read them.
+    @property
+    def name(self) -> str:
+        return self._name
+
+    @property
+    def kind(self) -> SpanKind:
+        return self._kind
+
+    def get_span_context(self) -> SpanContext:
+        if self._ctx is None:
+            b = self.ctx_bytes
+            self._ctx = SpanContext(
+                trace_id=int.from_bytes(b[0:16], "big"),
+                span_id=int.from_bytes(b[16:24], "big"),
+                is_remote=False,
+                trace_flags=TraceFlags(b[24]),
+                trace_state=TraceState.from_header([self._tracestate])
+                if self._tracestate
+                else TraceState(),
+            )
+        return self._ctx
+
+    def is_recording(self) -> bool:
+        """Return whether the span is sampled and has not ended."""
+        return self._sampled and not self._ended
+
+    def _mutable(self, op: str) -> bool:
+        if self._ended:
+            logger.warning("encore: %s on ended span %s", op, self._name)
+            return False
+        return True
+
+    def set_attribute(self, key: str, value: types.AttributeValue) -> None:
+        if not self._mutable("set_attribute"):
+            return
+        if not key or value is None:
+            return
+        if key not in self._attrs and len(self._attrs) >= MAX_COUNT:
+            return
+        self._attrs[key] = value
+
+    def set_attributes(self, attributes: Mapping[str, types.AttributeValue]) -> None:
+        for k, v in attributes.items():
+            self.set_attribute(k, v)
+
+    def add_event(
+        self,
+        name: str,
+        attributes: types.Attributes = None,
+        timestamp: int | None = None,
+    ) -> None:
+        if not self._mutable("add_event"):
+            return
+        if len(self._events) >= MAX_COUNT:
+            return
+        self._events.append(
+            Event(name, time.time_ns() if timestamp is None else timestamp, attributes)
+        )
+
+    def add_link(
+        self, context: SpanContext, attributes: types.Attributes = None
+    ) -> None:
+        if not self._mutable("add_link"):
+            return
+        if not context.is_valid:
+            return
+        if len(self._links) < MAX_COUNT:
+            self._links.append(Link(context, attributes))
+
+    def update_name(self, name: str) -> None:
+        if not self._mutable("update_name"):
+            return
+        self._name = name
+
+    def set_status(
+        self, status: Status | StatusCode, description: str | None = None
+    ) -> None:
+        if not self._mutable("set_status"):
+            return
+        if isinstance(status, StatusCode):
+            status = Status(status, description)
+        # OK is final; UNSET never overrides.
+        if status.status_code is StatusCode.UNSET:
+            return
+        if self._status.status_code is StatusCode.OK:
+            return
+        self._status = status
+
+    def record_exception(
+        self,
+        exception: BaseException,
+        attributes: types.Attributes = None,
+        timestamp: int | None = None,
+        escaped: bool = False,
+    ) -> None:
+        attrs: dict[str, Any] = {
+            "exception.type": type(exception).__qualname__,
+            "exception.message": str(exception),
+            "exception.stacktrace": "".join(
+                traceback.format_exception(
+                    type(exception), exception, exception.__traceback__
+                )
+            ),
+        }
+        if attributes:
+            attrs.update(attributes)
+        self.add_event("exception", attrs, timestamp)
+
+    def end(self, end_time: int | None = None) -> None:
+        with self._lock:
+            if self._ended:
+                logger.warning("encore: end called twice on span %s", self._name)
+                return
+            self._ended = True
+        status = self._status
+        try:
+            self._backend.end_span(
+                encode_end(
+                    scope=self._scope,
+                    name=self._name,
+                    kind=self._kind.value,
+                    status_code=status.status_code.value,
+                    status_message=(status.description or "")
+                    if status.status_code is StatusCode.ERROR
+                    else "",
+                    tracestate=self._tracestate,
+                    ctx=self.ctx_bytes,
+                    parent_span_id=self._parent_span_id,
+                    start_unix_nanos=self._start_unix_nanos,
+                    start_mono_nanos=self._start_mono_nanos,
+                    end_unix_nanos=0 if end_time is None else end_time,
+                    attributes=self._attrs,
+                    events=self._events,
+                    links=self._links,
+                )
+            )
+        except Exception:
+            logger.exception("encore: failed to end span %s", self._name)
+
+    def __repr__(self) -> str:
+        return f"Span(name={self._name!r}, ctx={self.ctx_bytes.hex()})"