Document every hand-written module, class, function and method in opentelemetry-sdk

.changelog/5869.added

@@ -0,0 +1 @@
+`opentelemetry-sdk`: document every hand-written module, class and callable

docs/conf.py

@@ -117,6 +117,34 @@
         "py:class",
         "opentelemetry.sdk.metrics._internal.instrument._Asynchronous",
     ),
+    (
+        "py:class",
+        "opentelemetry.sdk.trace._TracerConfig",
+    ),
+    (
+        "py:class",
+        "opentelemetry.sdk.metrics._internal._MeterConfig",
+    ),
+    (
+        "py:class",
+        "opentelemetry.sdk.metrics._internal._ProxyMeterConfig",
+    ),
+    (
+        "py:class",
+        "opentelemetry.sdk.metrics._internal.measurement_consumer.MeasurementConsumer",
+    ),
+    (
+        "py:class",
+        "opentelemetry.sdk._logs._internal._LoggerConfig",
+    ),
+    (
+        "py:class",
+        "opentelemetry.sdk._logs._internal._logger_metrics.LoggerMetricsT",
+    ),
+    (
+        "py:class",
+        "opentelemetry.semconv._incubating.attributes.otel_attributes.OtelComponentTypeValues",
+    ),
     # Even if wrapt is added to intersphinx_mapping, sphinx keeps failing
     # with "class reference target not found: ObjectProxy".
     ("py:class", "ObjectProxy"),

opentelemetry-sdk/src/opentelemetry/sdk/_logs/__init__.py

@@ -1,5 +1,17 @@
 # Copyright The OpenTelemetry Authors
 # SPDX-License-Identifier: Apache-2.0
+"""Public names of the OpenTelemetry logs SDK.
+
+This module re-exports the two log record wrappers, the attribute limits, the
+log record processor interface with its two multiplexing implementations, the
+``logging`` module bridge and ``LoggerProvider``. The implementation of all of
+them lives in ``opentelemetry.sdk._logs._internal``. Import from here instead:
+the layout of the private package may change between releases, while the names
+listed in ``__all__`` are the ones the SDK supports.
+
+``LogDroppedAttributesWarning`` and ``LogLimits`` are deprecated aliases kept
+for callers written against the older spelling.
+"""
 
 from opentelemetry.sdk._logs._internal import (
     ConcurrentMultiLogRecordProcessor,

opentelemetry-sdk/src/opentelemetry/sdk/_logs/_internal/_exceptions.py

@@ -1,5 +1,17 @@
 # Copyright The OpenTelemetry Authors
 # SPDX-License-Identifier: Apache-2.0
+"""Turning an exception attached to a log record into attributes.
+
+``LogRecord`` carries an ``exception`` field holding a live ``BaseException``.
+Nothing downstream can serialise that, so before a record reaches a processor
+the SDK derives the three ``exception.*`` semantic convention attributes from
+it. The helpers here do that derivation in the three shapes ``Logger.emit``
+needs: build a fresh record, copy an existing one, or edit one in place.
+
+An attribute the caller set by hand always wins over the derived value, in
+every one of those shapes.
+"""
+
 from __future__ import annotations
 
 import traceback
@@ -13,6 +25,23 @@
 def _get_exception_attributes(
     exception: BaseException,
 ) -> dict[str, AnyValue]:
+    """Derive the three ``exception.*`` attributes from an exception.
+
+    The type is qualified with the defining module, so a ``ValueError`` comes
+    out as ``ValueError`` while a custom class comes out as
+    ``mypackage.mymodule.MyError``. Builtins are left unqualified.
+
+    Args:
+        exception: The exception to describe. Its ``__traceback__`` supplies
+            the stack trace, and an exception that was never raised has none,
+            which yields a one-line trace holding only the exception itself.
+
+    Returns:
+        A mapping with ``exception.type``, ``exception.message`` and
+        ``exception.stacktrace``. The message is ``str(exception)``, which is
+        the empty string for an exception constructed with no arguments. All
+        three keys are always present.
+    """
     stacktrace = "".join(traceback.format_exception(type(exception), value=exception, tb=exception.__traceback__))
     module = type(exception).__module__
     qualname = type(exception).__qualname__
@@ -28,6 +57,29 @@ def _get_attributes_with_exception(
     attributes: Attributes,
     exception: BaseException | None,
 ) -> Attributes:
+    """Merge the derived exception attributes under the caller's attributes.
+
+    A key the caller already set is never overwritten, so passing
+    ``exception.message`` explicitly keeps that text and discards the one
+    derived from the exception.
+
+    Args:
+        attributes: The attributes already on the record. ``None`` is treated
+            as an empty mapping.
+        exception: The exception to describe, or ``None`` to leave
+            ``attributes`` untouched.
+
+    Returns:
+        ``attributes`` itself, unchanged and possibly ``None``, when
+        ``exception`` is ``None``. A new ``BoundedAttributes`` carrying the
+        same ``maxlen`` and ``max_value_len`` when ``attributes`` was one,
+        which means the exception attributes are themselves subject to those
+        limits and can be dropped or truncated. Its ``dropped`` count starts
+        from the input's and is then raised by however many of the three
+        exception attributes the count limit refused, so it is at least the
+        input's count rather than equal to it. A plain ``dict`` otherwise.
+        The input mapping is never modified.
+    """
     if exception is None:
         return attributes
 
@@ -58,6 +110,21 @@ def _copy_log_record(
     record: LogRecord,
     attributes: Attributes,
 ) -> LogRecord:
+    """Shallow-copy a log record, swapping in a different attribute mapping.
+
+    Every other field is carried over by reference. ``trace_id``, ``span_id``
+    and ``trace_flags`` are reassigned after construction because the
+    ``LogRecord`` constructor otherwise re-derives them from ``context``, which
+    would lose the values a caller set by hand.
+
+    Args:
+        record: The record to copy. It is not modified.
+        attributes: The attribute mapping the copy gets. Passing the mapping of
+            ``record`` makes the two records share it.
+
+    Returns:
+        The new record.
+    """
     copied_record = LogRecord(
         timestamp=record.timestamp,
         observed_timestamp=record.observed_timestamp,
@@ -76,13 +143,39 @@ def _copy_log_record(
 
 
 def _copy_log_record_with_exception(record: LogRecord) -> LogRecord:
+    """Copy a log record with its exception rendered into attributes.
+
+    ``Logger.emit`` uses this when the caller hands it a record it does not
+    own, so that the caller's record keeps the attribute mapping it had.
+
+    Args:
+        record: The record to copy. It is not modified, including its
+            attributes.
+
+    Returns:
+        A new record whose attributes carry ``exception.type``,
+        ``exception.message`` and ``exception.stacktrace``. When
+        ``record.exception`` is ``None`` the copy shares the original attribute
+        mapping rather than getting one of its own.
+    """
     return _copy_log_record(
         record,
         _get_attributes_with_exception(record.attributes, record.exception),
     )
 
 
 def _set_log_record_exception_attributes(record: LogRecord) -> None:
+    """Render a log record's exception into its attributes, in place.
+
+    ``Logger.emit`` uses this on a ``ReadWriteLogRecord``, which the SDK built
+    itself and is free to edit. The attribute mapping is replaced rather than
+    added to, so a ``BoundedAttributes`` mapping is swapped for a new one that
+    inherits its limits and its dropped count.
+
+    Args:
+        record: The record to edit. Nothing happens when its ``exception`` is
+            ``None``.
+    """
     record.attributes = _get_attributes_with_exception(
         record.attributes,
         record.exception,
@@ -101,6 +194,37 @@ def _create_log_record_with_exception(
     event_name: str | None = None,
     exception: BaseException | None = None,
 ) -> LogRecord:
+    """Build a log record from loose arguments, folding in an exception.
+
+    ``Logger.emit`` uses this on the path where the caller passed individual
+    keyword arguments instead of a ready-made record.
+
+    Args:
+        timestamp: When the event happened, in nanoseconds since the Unix
+            epoch. ``None`` leaves the field unset, and a consumer is then
+            expected to fall back to ``observed_timestamp``.
+        observed_timestamp: When the SDK saw the event, in nanoseconds since
+            the Unix epoch. ``None`` makes ``LogRecord`` fill it with the
+            current time.
+        context: The context to take the trace id, span id and trace flags
+            from. ``None`` makes ``LogRecord`` use the current context.
+        severity_number: The severity as an ``opentelemetry._logs``
+            ``SeverityNumber``, or ``None`` to leave it unset.
+        severity_text: The original severity label of the logging system the
+            record came from, or ``None``.
+        body: The payload of the event. Any attribute value type is accepted,
+            including a mapping or a sequence.
+        attributes: Attributes to attach. A key given here survives even when
+            the derived exception attributes use the same key.
+        event_name: The name identifying the class of event, or ``None`` for an
+            unnamed log record.
+        exception: The exception to describe in ``exception.*`` attributes. It
+            is also stored on the returned record, so the field still holds the
+            live exception object afterwards.
+
+    Returns:
+        The new record.
+    """
     return LogRecord(
         timestamp=timestamp,
         observed_timestamp=observed_timestamp,

opentelemetry-sdk/src/opentelemetry/sdk/_logs/_internal/_logger_metrics.py

@@ -1,5 +1,12 @@
 # Copyright The OpenTelemetry Authors
 # SPDX-License-Identifier: Apache-2.0
+"""Self-observability counters for the logs SDK.
+
+Holds the one metric the ``Logger`` records about itself, the count of log
+records it has created, and a do-nothing stand-in used when self-observability
+is switched off. ``Logger.emit`` calls ``emit_log`` once per record, so the
+stand-in exists to keep that call cheap in the default configuration.
+"""
 
 from typing import Protocol
 
@@ -10,27 +17,78 @@
 
 
 class LoggerMetricsT(Protocol):
-    def emit_log(self) -> None: ...
+    """What ``Logger`` requires of the object it reports its own counts to."""
+
+    def emit_log(self) -> None:
+        """Record that one log record has been created."""
 
 
 class NoOpLoggerMetrics:
+    """Implementation of ``LoggerMetricsT`` that records nothing.
+
+    Used when ``OTEL_PYTHON_SDK_INTERNAL_METRICS_ENABLED`` is not set to true,
+    which is the default. No instrument is created, so no meter provider is
+    touched.
+    """
+
     def emit_log(self) -> None:
-        pass
+        """Do nothing.
+
+        Present so that ``Logger`` can call it unconditionally instead of
+        testing whether self-observability is switched on.
+        """
 
 
 class LoggerMetrics:
+    """Implementation of ``LoggerMetricsT`` backed by a real counter.
+
+    Creates the ``otel.sdk.log.created`` counter on a meter named
+    ``opentelemetry-sdk`` when it is built, so the instrument exists even
+    before the first log record is emitted.
+
+    Args:
+        meter_provider: The provider to obtain the meter from. Pointing it at
+            the same provider that exports application metrics is what makes
+            these counts show up alongside them.
+    """
+
     def __init__(self, meter_provider: metrics_api.MeterProvider) -> None:
+        """Build the instance and create the counter.
+
+        Every parameter is documented on the class itself, since that is the
+        form the API reference renders.
+        """
         meter = meter_provider.get_meter("opentelemetry-sdk")
         self._created_logs = create_otel_sdk_log_created(meter)
 
     def emit_log(self) -> None:
+        """Add one to the ``otel.sdk.log.created`` counter.
+
+        Counts records the ``Logger`` accepted for processing. A record the
+        processors later drop, because the queue was full or the processor was
+        already shut down, has still been counted here.
+        """
         self._created_logs.add(1)
 
 
 def create_logger_metrics(
     meter_provider: metrics_api.MeterProvider,
     enabled: bool,
 ) -> LoggerMetricsT:
+    """Pick the recording or the do-nothing implementation.
+
+    Args:
+        meter_provider: The provider the counter is created on. Ignored when
+            ``enabled`` is false, so passing a provider costs nothing in the
+            default configuration.
+        enabled: Whether to record at all. ``LoggerProvider`` passes the parsed
+            value of ``OTEL_PYTHON_SDK_INTERNAL_METRICS_ENABLED``.
+
+    Returns:
+        A ``LoggerMetrics`` when ``enabled`` is true, otherwise a
+        ``NoOpLoggerMetrics``. The choice is made once, at ``LoggerProvider``
+        construction, and cannot be changed afterwards.
+    """
     if not enabled:
         return NoOpLoggerMetrics()