docs: add declarative configuration guide and example

docs/examples/declarative-config/README.rst

@@ -0,0 +1,96 @@
+Declarative Configuration
+=========================
+
+This example configures the OpenTelemetry SDK from a single YAML file using
+:doc:`declarative configuration </sdk/configuration>` instead of environment
+variables or hand-written provider setup.
+
+The source files of this example are available :scm_web:`here
+<docs/examples/declarative-config/>`.
+
+Install the SDK with the ``file-configuration`` extra (it pulls in ``pyyaml``
+and ``jsonschema``) along with the OTLP/HTTP exporter:
+
+.. code-block:: sh
+
+    pip install "opentelemetry-sdk[file-configuration]" \
+        opentelemetry-exporter-otlp-proto-http
+
+Start an OTLP-capable backend locally so there is somewhere to send data. Write
+the following file:
+
+.. code-block:: yaml
+
+    # otel-collector-config.yaml
+    receivers:
+      otlp:
+        protocols:
+          http:
+            endpoint: 0.0.0.0:4318
+
+    exporters:
+      debug:
+        verbosity: detailed
+
+    service:
+        pipelines:
+            traces:
+                receivers: [otlp]
+                exporters: [debug]
+            metrics:
+                receivers: [otlp]
+                exporters: [debug]
+            logs:
+                receivers: [otlp]
+                exporters: [debug]
+
+Then start the Collector:
+
+.. code-block:: sh
+
+    docker run \
+        -p 4318:4318 \
+        -v $(pwd)/otel-collector-config.yaml:/etc/otel-collector-config.yaml \
+        otel/opentelemetry-collector:latest \
+        --config=/etc/otel-collector-config.yaml
+
+Apply the configuration programmatically
+----------------------------------------
+
+``app.py`` loads ``otel-config.yaml`` and applies it with ``configure_sdk``:
+
+.. code-block:: python
+
+    from opentelemetry.sdk.configuration import configure_sdk, load_config_file
+
+    configure_sdk(load_config_file("otel-config.yaml"))
+
+Run it:
+
+.. code-block:: sh
+
+    python app.py
+
+You should see the exported span in the Collector's debug output.
+
+Apply the configuration with an environment variable
+----------------------------------------------------
+
+Alternatively, point the SDK at the file with ``OTEL_CONFIG_FILE`` and let
+auto-instrumentation apply it — no configuration code in your application:
+
+.. code-block:: sh
+
+    export OTEL_CONFIG_FILE=$(pwd)/otel-config.yaml
+    opentelemetry-instrument python app.py
+
+Environment variable substitution
+----------------------------------
+
+``otel-config.yaml`` uses ``${DEPLOYMENT_ENVIRONMENT:-development}`` to read the
+deployment environment from the environment, defaulting to ``development``. Set
+it before running to override:
+
+.. code-block:: sh
+
+    export DEPLOYMENT_ENVIRONMENT=staging

docs/examples/declarative-config/app.py

@@ -0,0 +1,22 @@
+# Copyright The OpenTelemetry Authors
+# SPDX-License-Identifier: Apache-2.0
+
+"""Configure the OpenTelemetry SDK from a declarative configuration file.
+
+Run an OTLP-capable backend (for example the OpenTelemetry Collector) on
+localhost:4318, then run this script to emit a span using the configuration
+in ``otel-config.yaml``.
+"""
+
+from pathlib import Path
+
+from opentelemetry import trace
+from opentelemetry.sdk.configuration import configure_sdk, load_config_file
+
+config_path = Path(__file__).parent / "otel-config.yaml"
+configure_sdk(load_config_file(config_path))
+
+tracer = trace.get_tracer("declarative-config-example")
+
+with tracer.start_as_current_span("hello"):
+    print("Hello from a declaratively configured SDK!")

docs/examples/declarative-config/otel-config.yaml

@@ -0,0 +1,34 @@
+file_format: "1.0"
+
+resource:
+  attributes:
+    - name: service.name
+      value: my-service
+    - name: deployment.environment.name
+      value: ${DEPLOYMENT_ENVIRONMENT:-development}
+
+tracer_provider:
+  processors:
+    - batch:
+        exporter:
+          otlp_http:
+            endpoint: http://localhost:4318/v1/traces
+  sampler:
+    parent_based:
+      root:
+        always_on: {}
+
+meter_provider:
+  readers:
+    - periodic:
+        interval: 60000
+        exporter:
+          otlp_http:
+            endpoint: http://localhost:4318/v1/metrics
+
+logger_provider:
+  processors:
+    - batch:
+        exporter:
+          otlp_http:
+            endpoint: http://localhost:4318/v1/logs

docs/sdk/configuration.rst

@@ -0,0 +1,139 @@
+Declarative Configuration
+=========================
+
+Declarative configuration lets you configure the OpenTelemetry SDK from a
+single YAML (or JSON) file instead of setting many individual ``OTEL_*``
+environment variables or writing provider-construction code by hand. The file
+format is defined by the `OpenTelemetry configuration specification
+<https://opentelemetry.io/docs/specs/otel/configuration/>`_.
+
+A single file describes your resource, providers, processors, exporters,
+samplers, and propagators. The SDK reads the file, validates it against the
+configuration schema, and applies it globally.
+
+Installing
+----------
+
+File configuration relies on optional dependencies (``pyyaml`` and
+``jsonschema``). Install them with the ``file-configuration`` extra:
+
+.. code-block:: sh
+
+    pip install "opentelemetry-sdk[file-configuration]"
+
+Enabling with an environment variable
+-------------------------------------
+
+The simplest way to use declarative configuration is to point the SDK at a
+file with the ``OTEL_CONFIG_FILE`` environment variable. When it is set, the
+file is the sole source of configuration and other ``OTEL_*`` variables are
+ignored (except where referenced inside the file — see
+`Environment variable substitution`_).
+
+.. code-block:: sh
+
+    export OTEL_CONFIG_FILE=/etc/otel/otel-config.yaml
+    opentelemetry-instrument python app.py
+
+Configuring programmatically
+----------------------------
+
+You can also load and apply a configuration file directly. This is useful when
+you want to construct or inspect the configuration in code:
+
+.. code-block:: python
+
+    from opentelemetry.sdk.configuration import configure_sdk, load_config_file
+
+    config = load_config_file("otel-config.yaml")
+    configure_sdk(config)
+
+``load_config_file`` parses and validates the file and returns a typed
+``OpenTelemetryConfiguration`` object; ``configure_sdk`` applies it to the
+global tracer, meter, and logger providers and the global propagator. A failure
+to read, parse, or validate the file raises ``ConfigurationError``.
+
+Example configuration
+---------------------
+
+The following file configures traces, metrics, and logs to be exported over
+OTLP/HTTP. The source is available :scm_web:`here
+<docs/examples/declarative-config/>`.
+
+.. code-block:: yaml
+
+    file_format: "1.0"
+
+    resource:
+      attributes:
+        - name: service.name
+          value: my-service
+        - name: deployment.environment.name
+          value: ${DEPLOYMENT_ENVIRONMENT:-development}
+
+    tracer_provider:
+      processors:
+        - batch:
+            exporter:
+              otlp_http:
+                endpoint: https://example.com:4318/v1/traces
+                headers:
+                  - name: api-key
+                    value: ${OTLP_API_KEY}
+      sampler:
+        parent_based:
+          root:
+            always_on: {}
+
+    meter_provider:
+      readers:
+        - periodic:
+            interval: 60000
+            exporter:
+              otlp_http:
+                endpoint: https://example.com:4318/v1/metrics
+                headers:
+                  - name: api-key
+                    value: ${OTLP_API_KEY}
+
+    logger_provider:
+      processors:
+        - batch:
+            exporter:
+              otlp_http:
+                endpoint: https://example.com:4318/v1/logs
+                headers:
+                  - name: api-key
+                    value: ${OTLP_API_KEY}
+
+Environment variable substitution
+----------------------------------
+
+Values in the file may reference environment variables, which keeps secrets
+such as API keys out of the file itself. Substitution happens before the file
+is parsed.
+
+* ``${VAR}`` — replaced with the value of ``VAR``. If ``VAR`` is unset, loading
+  fails with an error.
+* ``${VAR:-default}`` — replaced with ``VAR`` if set, otherwise ``default``.
+* ``$$`` — a literal ``$``.
+
+In the example above, ``${OTLP_API_KEY}`` is required, while
+``${DEPLOYMENT_ENVIRONMENT:-development}`` falls back to ``development`` when
+unset.
+
+Behavior notes
+--------------
+
+* When ``OTEL_CONFIG_FILE`` is set, the file is authoritative; other ``OTEL_*``
+  environment variables are not consulted.
+* Sections omitted from the file leave the corresponding global provider
+  unset (a no-op provider), per the specification.
+* Setting ``disabled: true`` at the top level turns the SDK into a no-op.
+
+See also
+--------
+
+* `OpenTelemetry configuration specification
+  <https://opentelemetry.io/docs/specs/otel/configuration/>`_
+* :doc:`environment_variables` — the environment-variable configuration path

docs/sdk/index.rst

@@ -20,3 +20,4 @@ processed, and exported.
     metrics
     error_handler
     environment_variables
+    configuration