Telemetry

The restgdf[telemetry] extra integrates with OpenTelemetry for distributed tracing and log correlation. Install it alongside the base package:

pip install "restgdf[telemetry]"

See Observability with OpenTelemetry for a practical integration guide.

restgdf.telemetry

restgdf.telemetry — optional OpenTelemetry integration (BL-32).

This package is importable on a base install (no OTel). Functions that need OTel at runtime raise OptionalDependencyError when the SDK is absent and telemetry is enabled.

Quick-start:

pip install restgdf[telemetry]

from restgdf.telemetry import RestgdfInstrumentor, feature_layer_stream_span
exception restgdf.telemetry.OptionalDependencyError[source]

Bases: ConfigurationError, ModuleNotFoundError

Raised when an optional dependency (pandas/geopandas/pyogrio) is absent.

Multi-inherits ModuleNotFoundError so existing except ImportError / except ModuleNotFoundError call sites keep working when restgdf[geo] is not installed.

class restgdf.telemetry.RestgdfInstrumentor(*args, **kwargs)[source]

Bases: object

Thin restgdf-specific wrapper around AioHttpClientInstrumentor.

Dynamically rebuilds itself as a subclass of opentelemetry.instrumentation.aiohttp_client.AioHttpClientInstrumentor at construction time. This deferred approach avoids import-time failures on a base install that has no OTel packages.

restgdf.telemetry.feature_layer_stream_span(*, layer_url, layer_id=None, out_fields=None, where=None, order=None, extra_attrs=None)[source]

Open an INTERNAL feature_layer.stream span (R-21).

Parameters:

  • layer_url – Full service URL (will be scrubbed).

  • layer_id – ArcGIS layer ID.

  • out_fields – Value of the outFields parameter, if any.

  • where – Value of the where parameter, if any.

  • order – Pagination order hint ("request" or "completion").

  • extra_attrs – Additional span attributes (must already be namespaced).

Yields:

span | None – The opened Span, or None when telemetry is disabled.

Notes

This helper attaches the span to the current asyncio Context via start_as_current_span. It is not safe to wrap an async-generator body whose yield can suspend across the __aexit__ boundary — use start_feature_layer_stream_span() + manual span.end() in those callers instead.

restgdf.telemetry.span_context_fields()[source]

Return {trace_id, span_id} from the current OTel span, or {}.

Safe to call even when opentelemetry is not installed — returns an empty dict.