Merge branch 'main' into mike/add-to-project-ready-for-review

Author: lzchen

CHANGELOG.md

@@ -12,6 +12,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+- `opentelemetry-sdk`: Add shared `_parse_headers` helper for declarative config OTLP exporters
+  ([#5021](https://github.com/open-telemetry/opentelemetry-python/pull/5021))
 - `opentelemetry-api`: Replace a broad exception in attribute cleaning tests to satisfy pylint in the `lint-opentelemetry-api` CI job
 - `opentelemetry-sdk`: Add `create_resource` and `create_propagator`/`configure_propagator` to declarative file configuration, enabling Resource and propagator instantiation from config files without reading env vars
   ([#4979](https://github.com/open-telemetry/opentelemetry-python/pull/4979))
@@ -41,6 +43,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   ([#4910](https://github.com/open-telemetry/opentelemetry-python/pull/4910))
 - Add configurable `max_export_batch_size` to OTLP HTTP metrics exporter
   ([#4576](https://github.com/open-telemetry/opentelemetry-python/pull/4576))
+- `opentelemetry-exporter-otlp-proto-http`: use consistent protobuf for export request
+  ([#5015](https://github.com/open-telemetry/opentelemetry-python/pull/5015))
+- `opentelemetry-sdk`: cache TracerConfig into the tracer, this changes an internal interface. Only one Tracer with the same instrumentation scope will be created
+  ([#5007](https://github.com/open-telemetry/opentelemetry-python/pull/5007))
 
 ## Version 1.40.0/0.61b0 (2026-03-04)
 

docs/api/index.rst

@@ -1,7 +1,15 @@
 OpenTelemetry Python API
 ========================
 
-.. TODO: what is the API
+The OpenTelemetry Python API provides the core interfaces and no-op
+implementations for instrumenting applications with traces, metrics, and logs.
+It defines the abstract classes and data types that library authors and
+application developers use to collect telemetry data. The API is designed to be
+lightweight with minimal dependencies so that instrumentation libraries can
+depend on it without pulling in the full SDK.
+
+For the concrete implementation of these interfaces, see the
+:doc:`OpenTelemetry Python SDK </sdk/index>`.
 
 .. toctree::
     :maxdepth: 1

docs/conf.py

@@ -228,11 +228,11 @@
 scm_web = "https://github.com/" + REPO + "blob/" + branch
 
 # Store variables in the epilogue so they are globally available.
-rst_epilog = """
-.. |SCM_WEB| replace:: {s}
-.. |SCM_RAW_WEB| replace:: {sr}
-.. |SCM_BRANCH| replace:: {b}
-""".format(s=scm_web, sr=scm_raw_web, b=branch)
+rst_epilog = f"""
+.. |SCM_WEB| replace:: {scm_web}
+.. |SCM_RAW_WEB| replace:: {scm_raw_web}
+.. |SCM_BRANCH| replace:: {branch}
+"""
 
 # used to have links to repo files
 extlinks = {

docs/sdk/environment_variables.rst

@@ -1,7 +1,11 @@
 opentelemetry.sdk.environment_variables
 =======================================
 
-.. TODO: what is the SDK
+The OpenTelemetry Python SDK can be configured through environment variables.
+These variables control behaviors such as exporter selection, resource
+attributes, span limits, and trace sampling. They follow the conventions
+defined by the `OpenTelemetry specification
+<https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/>`_.
 
 .. toctree::
    :maxdepth: 1

docs/sdk/index.rst

@@ -1,7 +1,15 @@
 OpenTelemetry Python SDK
 ========================
 
-.. TODO: what is the SDK
+The OpenTelemetry Python SDK provides the reference implementation of the
+:doc:`OpenTelemetry Python API </api/index>`. It includes the concrete classes
+for managing and exporting traces, metrics, and logs — such as
+``TracerProvider``, ``MeterProvider``, span processors, metric readers, and
+exporters. The SDK is responsible for sampling, batching, and delivering
+telemetry data to backends.
+
+Install the SDK in your application to configure how telemetry is collected,
+processed, and exported.
 
 .. toctree::
     :maxdepth: 1

exporter/opentelemetry-exporter-otlp-proto-common/src/opentelemetry/exporter/otlp/proto/common/_internal/__init__.py

@@ -170,7 +170,7 @@ def _get_resource_data(
             resource_class(
                 **{
                     "resource": collector_resource,
-                    "scope_{}".format(name): scope_data.values(),
+                    f"scope_{name}": scope_data.values(),
                 }
             )
         )

exporter/opentelemetry-exporter-otlp-proto-grpc/src/opentelemetry/exporter/otlp/proto/grpc/exporter.py

@@ -155,9 +155,7 @@
 class InvalidCompressionValueException(Exception):
     def __init__(self, environ_key: str, environ_value: str):
         super().__init__(
-            'Invalid value "{}" for compression envvar {}'.format(
-                environ_value, environ_key
-            )
+            f'Invalid value "{environ_value}" for compression envvar {environ_key}'
         )
 
 

exporter/opentelemetry-exporter-otlp-proto-http/src/opentelemetry/exporter/otlp/proto/http/metric_exporter/__init__.py

@@ -50,7 +50,7 @@
     _is_retryable,
     _load_session_from_envvar,
 )
-from opentelemetry.proto.collector.metrics.v1.metrics_service_pb2 import (  # noqa: F401
+from opentelemetry.proto.collector.metrics.v1.metrics_service_pb2 import (
     ExportMetricsServiceRequest,
 )
 from opentelemetry.proto.common.v1.common_pb2 import (  # noqa: F401
@@ -60,7 +60,7 @@
     KeyValue,
     KeyValueList,
 )
-from opentelemetry.proto.metrics.v1 import metrics_pb2 as pb2  # noqa: F401
+from opentelemetry.proto.metrics.v1 import metrics_pb2 as pb2
 from opentelemetry.proto.resource.v1.resource_pb2 import Resource  # noqa: F401
 from opentelemetry.proto.resource.v1.resource_pb2 import (
     Resource as PB2Resource,
@@ -243,18 +243,19 @@ def _export(
 
     def _export_with_retries(
         self,
-        serialized_data: bytes,
+        export_request: ExportMetricsServiceRequest,
         deadline_sec: float,
     ) -> MetricExportResult:
         """Export serialized data with retry logic until success, non-transient error, or exponential backoff maxed out.
 
         Args:
-            serialized_data: serialized metrics data to export
+            export_request: ExportMetricsServiceRequest object containing metrics data to export
             deadline_sec: timestamp deadline for the export
 
         Returns:
             MetricExportResult: SUCCESS if export succeeded, FAILURE otherwise
         """
+        serialized_data = export_request.SerializeToString()
         for retry_num in range(_MAX_RETRYS):
             # multiplying by a random number between .8 and 1.2 introduces a +/20% jitter to each backoff.
             backoff_seconds = 2**retry_num * random.uniform(0.8, 1.2)
@@ -310,23 +311,21 @@ def export(
             _logger.warning("Exporter already shutdown, ignoring batch")
             return MetricExportResult.FAILURE
 
-        serialized_data = encode_metrics(metrics_data)
+        export_request = encode_metrics(metrics_data)
         deadline_sec = time() + self._timeout
 
         # If no batch size configured, export as single batch with retries as configured
         if self._max_export_batch_size is None:
-            return self._export_with_retries(
-                serialized_data.SerializeToString(), deadline_sec
-            )
+            return self._export_with_retries(export_request, deadline_sec)
 
         # Else, export in batches of configured size
-        split_metrics_batches = list(
-            _split_metrics_data(serialized_data, self._max_export_batch_size)
+        batched_export_requests = _split_metrics_data(
+            export_request, self._max_export_batch_size
         )
 
-        for split_metrics_data in split_metrics_batches:
+        for split_metrics_data in batched_export_requests:
             export_result = self._export_with_retries(
-                split_metrics_data.SerializeToString(),
+                split_metrics_data,
                 deadline_sec,
             )
             if export_result != MetricExportResult.SUCCESS:
@@ -353,18 +352,18 @@ def force_flush(self, timeout_millis: float = 10_000) -> bool:
 
 
 def _split_metrics_data(
-    metrics_data: pb2.MetricsData,
+    metrics_data: ExportMetricsServiceRequest,
     max_export_batch_size: int | None = None,
-) -> Iterable[pb2.MetricsData]:
-    """Splits metrics data into several MetricsData (copies protobuf originals),
+) -> Iterable[ExportMetricsServiceRequest]:
+    """Splits metrics data into several ExportMetricsServiceRequest (copies protobuf originals),
     based on configured data point max export batch size.
 
     Args:
         metrics_data: metrics object based on HTTP protocol buffer definition
 
     Returns:
-        Iterable[pb2.MetricsData]: An iterable of pb2.MetricsData objects containing
-            pb2.ResourceMetrics, pb2.ScopeMetrics, pb2.Metrics, and data points
+        Iterable[ExportMetricsServiceRequest]: An iterable of ExportMetricsServiceRequest objects containing
+            ExportMetricsServiceRequest.ResourceMetrics, ExportMetricsServiceRequest.ScopeMetrics, ExportMetricsServiceRequest.Metrics, and data points
     """
     if not max_export_batch_size:
         return metrics_data
@@ -430,7 +429,7 @@ def _split_metrics_data(
                     batch_size += 1
 
                     if batch_size >= max_export_batch_size:
-                        yield pb2.MetricsData(
+                        yield ExportMetricsServiceRequest(
                             resource_metrics=_get_split_resource_metrics_pb2(
                                 split_resource_metrics
                             )
@@ -491,7 +490,7 @@ def _split_metrics_data(
             split_resource_metrics.pop()
 
     if batch_size > 0:
-        yield pb2.MetricsData(
+        yield ExportMetricsServiceRequest(
             resource_metrics=_get_split_resource_metrics_pb2(
                 split_resource_metrics
             )