pypi / opentelemetry-sdk
opentelemetry-sdk
What changed in opentelemetry-sdk 1, from its official release notes, upgrade guides and advisories. Also covers opentelemetry-exporter-otlp-proto-grpc, opentelemetry-exporter-otlp-proto-http. Sources checked 2026-10-18.
18 breaking1 security4 deprecations57 new APIs and options9 behavior and defaults2 tooling33 fixes and other
See which of these apply to your code, ranked, in your agent:
npx @unstale/cli initopentelemetry-sdk 1124 changes
Breaking changes 18
Views using ExponentialBucketHistogramAggregation for asynchronous instruments are now rejected instead of silently producing no data.
Tracer, meter, and logger configurator scope-name matching is now case-sensitive on every platform.
Values Python considers equal but the data model does not, such as True, 1, and 1.0, are kept in separate metric streams.
Spans ended after shutdown are dropped rather than sent to the exporter, and counted with error.type=already_shutdown.
Removes the deprecated Events API/SDK; use LogRecord with the event_name field instead.
Raises ValueError when boundaries are not strictly increasing or finite.
Declarative configuration moves from opentelemetry.sdk._configuration into the experimentally published opentelemetry-configuration package under the opentelemetry.configuration namespace; the file-configuration extra remains an installation alias.
No longer collects or emits process.command_args and process.command_line by default because the values may contain sensitive information; pass include_command_args=True to include them.
BatchLogRecordProcessor clears Context before buffering, so exported records contain an empty Context instead of the original; custom exporters that access context may be affected.
Declarative configuration rejects unsupported major versions and warns when a newer minor version is used.
The metric name changes with the semantic conventions update.
The metric name changes with the semantic conventions update.
Resource detector entry points are loaded only when configured via this environment variable.
Python 3.9 support is dropped; Python 3.10 or later is now required.
Unused Jaeger exporter environment variables are dropped; the exporter was removed in 1.22.0.
Removed LogData; log exporters and processors should use ReadableLogRecord and ReadWriteLogRecord instead.
Use ReadableLogRecord for log exporter batches and when exporting processed log records.
Use ReadWriteLogRecord for log processing; use ReadableLogRecord for exporting.
Security 1
Newlines in substituted values are emitted as quoted YAML scalars, preventing YAML structure injection and meeting the spec requirement.
Deprecations 4
Logger
minimum_severityandtrace_basedconfiguration fields are unsupported by the Python SDK and are ignored with a warning.LoggingHandler is deprecated in favor of opentelemetry-instrumentation-logging.
The Events API/SDK is deprecated; use the Logs API/SDK instead, representing an event as a LogRecord with event_name set.
Warnings were added for classes that will be deprecated and renamed in 1.39.0.
New APIs and options 57
Adds the stable AlwaysRecordSampler.
Logger API, SDK, and LogRecordProcessor gain enabled() so instrumentation can skip expensive work when logging is disabled; Logger subclasses must implement it.
The host resource detector now adds host.id.
Declarative configuration's top-level log_level maps OTel SeverityNumber to a Python logging level and applies it to the opentelemetry logger.
LoggerProvider now supports log_record_limits.
OTLP HTTP exporters accept max_request_size; serialized requests exceeding the default 64 MiB limit are dropped before sending, measured before compression. Set to 0 to disable.
Exposes ConcurrentMultiLogRecordProcessor publicly.
Adds the record_min_max option, matching ExplicitBucketHistogramAggregation and the specification.
Adds support for configuring the file exporter with declarative configuration.
Can now limit the size of spans stored by the in-memory exporter.
Declarative configuration can activate instrumentors through this section; instrumentors can declare configuration options validated by the SDK component type-coercion pipeline.
Adds a force_flush method to the LogRecordExporter abstract base class.
Adds MissingDependencyError for declarative configuration and missing optional dependency errors.
Adds an environment variable to configure the log record attribute count limit.
Adds an environment variable to configure the log record attribute value length limit.
Adds the ability to refresh process-dependent Resource attributes.
Exposes SynchronousMultiLogRecordProcessor publicly.
Register metric readers at runtime.
Declarative file configuration now supports composite/development samplers.
Adds a single declarative configuration entry point that builds the resource and applies tracer, meter, and logger providers and the propagator globally; it honors the top-level disabled flag.
Introduces experimental entry points for OpAMP agent integration.
When set, the SDK loads and applies the referenced YAML or JSON declarative configuration file instead of using the env-var-based initialization path.
Declarative file configuration now supports pull metric readers, including a Prometheus metric reader configured via prometheus_development.
Unregister metric readers at runtime.
Adds a resource detector for populating service.instance.id.
Declarative file configuration can configure a LoggerProvider without reading environment variables.
Declarative file configuration can instantiate a LoggerProvider without reading environment variables.
Declarative file configuration supports the service resource detector.
IdGenerator implementations that randomly generate the 56 least significant bits should implement this method, which returns True.
Declarative file configuration gains a shared utility for loading plugins via entry points; propagator loading uses it.
Logger emit and LogRecord attributes gain exception support.
Declarative file configuration can load exporter plugins for traces, metrics, and logs through the corresponding entry point groups.
Declarative file configuration can load propagator plugins through this entry point group.
Declarative file configuration can load resource detector plugins through this entry point group.
Declarative file configuration can load sampler plugins through this entry point group.
Selectively enables exporting SDK internal metrics.
Accepts a custom Prometheus registry through the new keyword argument.
Adds declarative file configuration support for creating a MeterProvider without reading environment variables.
Adds declarative file configuration support for creating a Resource and creating or configuring a propagator without reading environment variables.
Adds declarative file configuration support for creating a TracerProvider without reading environment variables.
Adds support for the container resource detector in declarative file configuration, loading it through the contrib package entry point.
Adds support for the host resource detector in declarative file configuration.
Adds support for the process resource detector in declarative file configuration.
Adds YAML/JSON loading, environment variable substitution, and schema validation for SDK file configuration.
Implements the log creation metric.
Implements an experimental Logger configurator.
Implements an experimental Meter configurator.
Implements metric reader metrics.
Implements processor metrics.
An experimental composable rule based sampler is added.
Environment variable carriers are added to the API.
The SDK configurator now makes it possible to override the default processors.
Span start/end metrics are implemented.
An experimental TracerConfigurator is implemented.
SDK log records now include instrumentation scope.
Added as an optional dependency of the OTLP gRPC and HTTP exporters.
Logger.emit now accepts separated keyword arguments.
Behavior and default changes 9
Declarative configuration now wires top-level attribute_limits into per-signal providers.
Attribute values now include None, heterogeneous and nested sequences, and mappings; bytes are passed through instead of decoded to strings.
Logging force_flush timeout defaults are unified to 30000ms.
Declarative configuration now wires id_generator to TracerProvider.
Recursively converts parsed dictionaries into typed dataclass instances, including nested dataclasses, lists of dataclasses, and enum values, enabling end-to-end YAML/JSON configuration through factory functions.
Changes the default schedule delay from 5000ms to 1000ms to comply with the OTel specification; logs may be exported five times more frequently by default.
Adds deepcopy support for BoundedAttributes and BoundedList.
Updates the vendored configuration schema from v1.0.0-rc.3 to v1.0.0, affecting schema validation of file configuration.
Warnings from the events API are silenced for internal users.
Tooling 2
Generated config models support additional properties so plugin and custom component names can flow through typed dataclasses.
Configuration models are automatically generated using the OTel config JSON schema.
Fixes and other changes 33
Fixed a thread leak in resource initialization when using long-running resource detectors.
Fixes a TypeError in os.fork() when a BatchProcessor or PeriodicExportingMetricReader is garbage collected.
Methods on FixedSizeExemplarReservoirABC are now thread safe.
Waiting in get_aggregated_resources() is now bounded by the timeout.
Declarative configurator development fields are now applied when creating providers, so per-instrumentation-scope enabled overrides take effect instead of being discarded.
Declarative configurator development fields are now applied when creating providers, so per-instrumentation-scope enabled overrides take effect instead of being discarded.
Dropped records after shutdown are counted with error.type=already_shutdown for batch span/log and simple log processors.
Processor metrics are counted when records are submitted to the exporter, rather than after export completes; exporter failures are no longer stamped as error.type.
Fixes a TypeError in os.fork() when a BatchProcessor or PeriodicExportingMetricReader is garbage collected.
Resource remains hashable and serialisable when an attribute value is bytes, avoiding TypeError from OTLP encoders.
User-provided service.instance.id values populated through resource detectors are no longer overridden.
Every bucket is filled before random sampling.
Values from synchronous instruments using last-value aggregation are retained across cumulative collections.
Declarative configurator development fields are now applied when creating providers, so per-instrumentation-scope enabled overrides take effect instead of being discarded.
Out-of-range numeric OTEL_TRACES_SAMPLER_ARG values now log a warning and fall back instead of raising ValueError.
Instrument-name matching now applies views configured with the instrument's real mixed-case name; matching is case-insensitive and platform-independent.
Drops NaN and Inf measurements at the instrument level to prevent permanent aggregation poisoning.
The method is now lock free to avoid deadlocks.
Child span creation now preserves the random trace ID flag instead of always setting it based on the available trace ID generator.
Declarative OTLP HTTP exporters now accept
deflatecompression instead of rejecting it as unsupported.A multi-processor force flush no longer skips remaining processors when one returns None.
Attributes passed to instrument
addorrecordare copied, so later mutations do not affect recorded data points.Uses
sys.orig_argvso process attributes reflect the original invocation forpython -m <module>runs.Resource detector ordering is now deterministic.
Maps Python CRITICAL log level to OTel FATAL severity text to comply with the specification.
Fixes an AttributeError when this aggregation is applied to non-Histogram instruments without explicit boundaries.
Fixes type annotations on MetricReader and related types.
ConcurrentMultiSpanProcessor is made fork safe.
Fixes an instrument creation race condition.
Avoids a RuntimeError while iterating the view instrument match dictionary during collection.
Python 3.14 is supported.
Prevents possible endless recursion in on_emit.
Attribute values that are not AnyValue are converted to strings so they can be exported.