module pixeltable.telemetry

Dependency-free instrumentation hooks. Core pixeltable reports spans (timed, nested units of work), discrete events attached to spans, and metrics through this module; subscribers (e.g. the bridge in opentelemetry-instrumentation-pixeltable) translate them into a telemetry backend. Metric instruments are declared once at module level (_rows = telemetry.counter(...)) and recorded where the measurement happens (_rows.add(n, table=path)). With no subscribers registered every call is a near-free no-op, but hot loops should still guard with if telemetry.active(): before building attribute dicts (or pass attrs as a callable). In production, run with log export disabled (the bridge’s default; logs=False) or route exports through a collector configured to redact secrets: log records can carry credentials (API keys in error messages, signed URLs, connection strings) that would otherwise leak to the telemetry backend. Spans should cover contiguous units of real computation (a UDF call, a DB insert batch, model loading) or serve as structural containers (operation and exec-node spans). A CPU work span must not contain a yield/await, which would let it cover unrelated interleaved work; awaiting an external call inside a span is fine (the request really is in flight).

func counter()

Signature

counter(name: str, unit: str = '') -> Counter

Declare a counter instrument; module-level, once per metric name.

func emit()

Signature

emit(handle: SpanHandle | None, name: str, **attrs: Any) -> None

Attach a discrete event to the given span; a no-op for None handles. Keyword attrs get a ‘pxt.’ prefix; None values are skipped.

func func_span()

Signature

func_span() -> SpanHandle | None

Handle of the innermost enclosing spanned() span, for use with add_attrs(). None if there is no enclosing spanned() function or its span was suppressed (add_attrs() accepts None).

func histogram()

Signature

histogram(
    name: str,
    unit: str = '',
    boundaries: tuple[float, ...] | None = None
) -> Histogram

Declare a histogram instrument; module-level, once per metric name.

func span()

Signature

span(
    name: str,
    *,
    level: int = 20,
    parent: SpanHandle | None = None,
    set_current: bool = False,
    **attrs: Any
) -> Iterator[SpanHandle | None]

Context-manager sugar for a lexical-block span. Keyword attrs get a ‘pxt.’ prefix; None values are skipped.

func span_end()

Signature

span_end(
    handle: SpanHandle | None,
    *,
    exc: BaseException | None = None,
    attrs: HookAttrs = None
) -> None

End a span started with span_start(); a no-op for None handles.

func span_start()

Signature

span_start(
    name: str,
    *,
    level: int = 20,
    parent: SpanHandle | None = None,
    set_current: bool = False,
    attrs: HookAttrs = None
) -> SpanHandle | None

Start a span and return its handle; None if no subscribers are registered or the span is suppressed. Spans below the level threshold are suppressed, as are non-set_current spans with no ambient ancestor; descendants of a suppressed span parent to the ambient span. set_current=True makes the span the ambient parent (a ContextVar, so it propagates into asyncio tasks) and requires that span_end() runs on the same thread/context; use capture_context()/restore_context()/exit_context() for explicit thread handoffs.

func spanned()

Signature

spanned(
    name: str,
    *,
    level: int = 20,
    set_current: bool = False,
    nest_children: bool = False
) -> Callable[[F], F]

Decorator form of span() for a function whose entire body is one span. The span’s handle isn’t lexically available inside the function; use add_attrs(func_span(), ...) to attach attributes to it. nest_children=True makes spans started inside the function nest under this span, but only inside an operation span, so that this span never becomes a root.

​module pixeltable.telemetry

​func counter()

​func emit()

​func func_span()

​func histogram()

​func span()

​func span_end()

​func span_start()

​func spanned()

module pixeltable.telemetry

func counter()

func emit()

func func_span()

func histogram()

func span()

func span_end()

func span_start()

func spanned()