Metadata-Version: 2.5
Name: dash0-opentelemetry-configuration
Version: 0.65b0.post1
Summary: Declarative configuration for the Dash0 OpenTelemetry distribution
License-Expression: Apache-2.0
Requires-Python: >=3.10
Requires-Dist: opentelemetry-api==1.44.0
Requires-Dist: opentelemetry-sdk==1.44.0
Requires-Dist: pyyaml
Description-Content-Type: text/x-rst

Dash0 OpenTelemetry Declarative Configuration
=============================================

Declarative (file-based) SDK configuration for the Dash0 OpenTelemetry Python
distribution, read from ``OTEL_CONFIG_FILE``.

The package is experimental, tracking a configuration format that is still at
``1.0-rc.1``.

Do not edit this package by hand
--------------------------------

Everything under ``src/`` and the whole of ``pyproject.toml`` are generated by
``scripts/vendor_configuration.py`` from the ``dash0`` branch of
https://github.com/dash0hq/opentelemetry-python. The ``UPSTREAM`` file records
the exact commit. A hand edit here is reverted by the next run of that script,
and the ``vendored-configuration`` job in CI fails while it is still present.

Two files are exempt, because the script leaves them alone: this README, and
``src/opentelemetry/_configuration/version/__init__.py``, which holds the
released version and is advanced by ``scripts/bump_for_release.py``.

Where a change belongs
----------------------

Changes to how configuration files are parsed, validated or applied go on the
fork's ``dash0`` branch, as commits on top of an upstream commit. That is what
makes them survive upstream moving: rebase the branch onto the new upstream
commit, then run::

    python3 scripts/vendor_configuration.py --commit <new sha>

Changes to how the code is packaged for this distribution go in
``scripts/vendor_configuration.py``. It owns the rename from
``opentelemetry.configuration`` to ``opentelemetry._configuration``, the
re-export shims at the path the SDK imports, and the dependency pins, which it
copies from the distribution's own pins rather than repeating them.

Why the implementation sits at a private path
---------------------------------------------

The implementation is installed as ``opentelemetry._configuration``, a path
upstream does not own, and ``opentelemetry.configuration`` holds only star
re-export shims. ``opentelemetry/sdk/_configuration/__init__.py`` imports
``opentelemetry.configuration`` by name, so the shims are what make
``OTEL_CONFIG_FILE`` work, while the private path means installing this
alongside a future published ``opentelemetry-configuration`` cannot collide
file for file. The pyproto exporter packages in this workspace use the same
arrangement.

What the fork changes
---------------------

Upstream validates configuration files with ``jsonschema``, which brings
``attrs``, ``referencing``, ``jsonschema-specifications`` and ``rpds-py``. All
four would land in the tree the injector adds to an application's
``sys.path``, and ``rpds-py`` is a compiled extension, so that tree would stop
being pure Python. The fork compiles the schema to plain Python with
``fastjsonschema`` at development time instead, leaving a validator that
imports ``decimal`` and nothing else. The fork's own test suite checks that
validator against ``jsonschema`` document by document.
