vgi.otel

Module overview

VGI application-level OpenTelemetry and Sentry instrumentation.

Provides VgiTracer — a thin wrapper that enriches both OTel spans and Sentry scopes with VGI-level attributes (function name, attach_opaque_data, etc.) and creates vgi.execute.* per-batch records (OTel spans + Sentry spans + Sentry breadcrumbs).

All OTel and Sentry imports are deferred to VgiTracer.create() so that import vgi.otel works even when neither dependency is installed. When both backends are disabled, all operations are zero-cost no-ops.

Despite the module name, this is the central instrumentation hook for both backends. vgi-rpc’s own Sentry auto-attach handles RPC-layer fields (method name, server id, auth principal); the helpers here add VGI-layer fields (function name, function type, attach id, transaction id, per-batch row counts) on top.

Sentry spans: every exchange creates a child span op=vgi.execute, name=<function_name> under the active RPC transaction. Row counts and byte sizes land as vgi.execute.* span attributes — searchable in Trace Explorer (e.g. span.op:vgi.execute vgi.function.name:scan_orders -> p99(span.duration) GROUP BY vgi.execute.input_rows). Breadcrumbs are still emitted for the Issues-side chronological view of recent batches when an exception fires later. High-volume streams may hit Sentry’s per-transaction span cap (~1000); use traces_sample_rate to scale.

function get_noop_tracer

source

get_noop_tracer() -> VgiTracer

Return the module-level noop tracer singleton.

class VgiTracer

source

Description

Wraps OTel tracer + meter or acts as no-op.

Use VgiTracer.create(otel_config) to build. When otel_config is None, returns the module-level _NOOP_TRACER singleton — all methods become zero-cost no-ops.

Attributes

attribute enabled

bool

Return whether OTel instrumentation is active.

attribute sentry_enabled

bool

Return whether Sentry enrichment is active.

Methods

method create

source

create(otel_config: OtelConfig | None) -> VgiTracer

Create a VgiTracer from an OtelConfig.

When otel_config is None and Sentry is not initialised, returns the module-level noop tracer. When Sentry is initialised, returns a tracer with Sentry enrichment active even if OTel is disabled, so VGI scope context still flows into Sentry events.

method start_span

source

start_span(name: str, attributes: dict[str, Any] | None = None) -> Any

Start a child span. Returns _NOOP_SPAN when disabled.

method set_current_span_attributes

source

set_current_span_attributes(attributes: dict[str, Any]) -> None

Enrich the active OTel span and Sentry scope with VGI attributes.

Each non-None value is set as both an OTel span attribute and (when Sentry is initialised) a Sentry tag. Tags are merged into the current scope, so calling this multiple times during a dispatch accumulates context rather than overwriting it.

method record_execute_metrics

source

record_execute_metrics(
*,
function_name: str,
function_type: str,
duration_s: float,
input_rows: int | None = None,
output_rows: int | None = None,
input_bytes: int | None = None,
output_bytes: int | None = None,
) -> None

Record per-batch execution metrics.