Implement runtime telemetry configuration

This is a major rework of PyTango's telemetry code. The main goal is to support runtime configuration, which is available in cppTango since 10.3.0

From the proposed release notes:

Changed

• PyTango requires at least cppTango 10.3.0.
• The telemetry environment variables now match cppTango 10.3.0, using the renamed TANGO_TELEMETRY_TRACING_* and TANGO_TELEMETRY_LOGGING_* variables, while still supporting the deprecated names.
• Device telemetry can now be reconfigured at runtime instead of being treated as an import-time-only setup on the Python side. PyTango recreates or replaces its Python tracer providers when cppTango runtime configuration changes. Note that for pure client scripts, the telemetry configuration will still be based on the environment variables at import time.
• The documented user-facing topic support now focuses on the stable user and all topics.
• Missing OpenTelemetry Python dependencies now warn only when telemetry is actually requested, instead of warning merely at import time.

Added

• Device and DServer telemetry runtime configuration now works end-to-end in PyTango, including start/stop, enable/disable, tracing/logging endpoint changes, and topic changes. See the telemetry runtime configuration how-to, the DeviceProxy API, and the high-level Device API.
• The public telemetry API documentation now includes the tracer-provider factory hooks in other API objects, alongside the telemetry enums and endpoint types.

---

Other notes

• New internal modules, with a leading _ have been added to try and separate internal code from the public API.
• The utils.py module is now a bit simpler, moving the telemetry and instrumentation (forced tracing) into new modules.
• Warnings have their own module, and there is a new "warn once" mechanism to simplify how we warn users, without a flood messages.
• There is a way to build the extension code with telemetry disabled. pixi run install-telemetry-off, which uses a new CMake define PYTANGO_FORCE_DISABLE_TELEMETRY.
• Started the "Explanations" section of the docs with some details about the telemetry implementation.
• New docs were written following the semantic line break convention. This is good for editing, but rather review the rendered docs or markdown.

TODO

• Fix failing build with missing device spans (only occurring in CI). Related to cppTango#1645.
• Hide the new methods on DeviceImpl and high-level Device. Keep the old tracer-related methods.
• Investigate incorrect span parent for a device span when using "user" topic instead of "all" (see images below). Related to cppTango issue above.
• Env vars have changed - PyTango supports the old ones (e.g., TANGO_TELEMETRY_TRACES_EXPORTER) in a deprecated way, but cppTango just ignores the old variables. PyTango must warn, but ignore old variables.
• Fix import failure when telemetry is not compiled in, but TANGO_TELEMETRY_ENABLE=on.
• All device proxy telemetry methods must be available if telemetry not compiled in.

See decisions taken at developers' meeting on 2026-04-02.

Click to expand - incorrect span parent example

Examples of reading the voltage attribute on a PowerSupply Tango device.

Trace with old telemetry (10.1.x)

Trace with new telemetry and "all" topic:

Notice we get the additional traces from BaseDevice (previously the "kernel" traces).

Trace with new telemetry and "user" topic:

Notice how the name of the span in the last row is not indented (wrong parent).

Workflow

The commits were rewritten, so the timestamps are very close together. The initial work took around two weeks.

A large part of this code was co-authored by OpenAI's Codex agent.

Closes: #734 (closed)