Opentelemetry Knowledge Patch

OpenTelemetry Knowledge Patch

Use this skill when implementing, configuring, upgrading, or reviewing OpenTelemetry specifications, semantic conventions, SDKs, or Collector components. Start with the migration-critical changes, then open the topic reference that matches the work.

Reference index

Breaking changes and deprecations

Specification and SDK

• Treat the Jaeger and OT Trace propagators as deprecated and optional to implement.
• Treat the Zipkin exporter specification as deprecated and optional to implement.
• OpenTracing and OpenCensus compatibility requirements are deprecated.
• TraceIdRatioBased exists again, but it has a deprecation timeline. Do not confuse restoration with a long-term stability guarantee.
• Declarative signal configuration uses enabled, not disabled, in TracerConfig, MeterConfig, and LoggerConfig.
• Rename ComponentProvider to PluginComponentProvider and CreatePlugin to CreateComponent.
• Use these Prometheus exporter property names: scope_info_enabled, target_info_enabled, and resource_constant_labels. The older negative-form names are replaced.

Semantic conventions

• Generative-AI attributes, metrics, events, and spans have moved out of the main semantic-conventions repository. Use the dedicated repository and its corresponding schema_url.
• RPC duration metrics are rpc.client.call.duration and rpc.server.call.duration; both are required and measured in seconds.
• Replace rpc.service plus a short rpc.method with one fully qualified rpc.method.
• Rename RPC metadata and status attributes to rpc.request.metadata, rpc.response.metadata, and rpc.response.status_code.
• Rename rpc.system to rpc.system.name; normalized values include connectrpc and dubbo.
• RPC spans and metrics no longer carry network.type, network.protocol.name, network.protocol.version, or network.transport.
• RPC server spans also drop client.address and client.port.
• RPC request/response size metrics and rpc.message are deprecated.
• Generic exception span events are deprecated. Use exception log records and the domain-specific exception events while migrating.
• graphql.document is Opt-In because it may expose sensitive, unbounded, high-cardinality input; sanitize it when capture is enabled.
• Replace peer.service with service.peer.name and, where needed, service.peer.namespace.
• Use process.unix.file_descriptor.count or process.windows.handle.count, not process.open_file_descriptor.count.
• Paging-fault metrics are k8s.pod.paging.faults, k8s.node.paging.faults, and container.paging.faults; the old names had a .memory segment.
• Use the singularized and reordered system and Kubernetes metric names documented in the references; several old plural or word-order variants no longer match the conventions.

Collector

• In Go code, replace configgrpc.BalancerName with configgrpc.DefaultBalancerName.
• Replace deprecated xconfmap.WithForceUnmarshaler with confmap.WithForceUnmarshaler.
• Do not rely on promoted fields from embedded confighttp.ServerConfig in zpages Config or embedded configauth.Config in confighttp.AuthConfig; use their named fields.
• The failover connector no longer accepts retry_gap or max_retries.
• The JMX receiver and kafkatopicsobserver have been removed. Replace Kafka topic-observer rules with kafkareceiver topic regex support.
• Rename component types awsecsattributes to aws_ecs_attributes, azuremonitor to azure_monitor, and sqlquery to sql_query. Only the old sqlquery name has a deprecated alias.
• cumulativetodelta and spanpruning survive only as deprecated aliases for cumulative_to_delta and span_pruning.
• Routing, filter, and transform processing now default top-level error_mode to ignore. The routing beta gate can temporarily restore propagate; filter and transform compatibility gates are scheduled for removal.
• Host Metrics now aggregates CPU time and utilization across logical CPUs by default, omits the cpu attribute, and enables system.cpu.logical.count.
• File Log ordering_criteria.top_n: 0 now means all files. Set 1 explicitly for the old behavior and prepare for explicit top_n when sort_by is used.
• File exporter output is mode 0644, including rotated files.
• Queue dashboards must separate post-batch otelcol_exporter_queue_batch_send_size* from enqueue-time otelcol_exporter_enqueue_size*; the former exists only with sending_queue.batch.
• Histogram dashboards must account for power-of-two buckets from 128 B through 16 MiB for both core batch-send-size metrics.

High-value specification behavior

Context and sampling

• Environment-variable carriers are Release Candidate. Normalize requested, carrier, and returned keys, read and return only normalized environment names, and normalize an empty name to _.
• Carrier caching is deliberately unspecified.
• Context propagation requires the W3C randomness flag.
• AlwaysRecord is stable.
• The Dynamic Sampling and Tail Sampling processors can consume W3C ot=th thresholds and ot=rv randomness; read the gate requirements before enabling Tail Sampling tracestate behavior.

APIs and signals

• Stable enablement checks include Tracer enabled, synchronous instrument Enabled, and LogRecordProcessor.Enabled.
• Synchronous instruments have an in-development Bind API.
• Periodic exporting MetricReader has an in-development maxExportBatchSize.
• A View-provided metric stream name is exempt from instrument-name syntax validation.
• Logs add an optional ergonomic API. Logger Emit has a stable optional Exception parameter, and logger configuration adds minimum_severity and trace_based.
• Logs can bridge an event into a span event and can represent entity information as structured events.
• Profiles have a signal specification, data model, and supplementary pprof guidance.
• Entity is defined in the specification and supported by the Resource SDK; OTLP exporter configuration includes request- and response-size limits.

Resources and attributes

• A Resource describes the observed entity, not necessarily the component that emitted the telemetry.
• Complex AnyValue attributes and their limits are stable.
• For non-OTLP paths, follow the specific guidance for byte arrays, empty values, arrays, maps, and nesting.
• JSON-object string representations for attributes and attribute collections remain in development.

High-value Collector configuration

Self-telemetry resource detection

Use the experimental resource-detection block under the Collector's own telemetry. Supported detectors are container, host, process, and service.

service:
  telemetry:
    resource:
      detection/development:
        detectors:
          - host: {}

Restore per-CPU Host Metrics

Select both cpu and state explicitly for each CPU metric:

receivers:
  hostmetrics:
    scrapers:
      cpu:
        metrics:
          system.cpu.time:
            attributes: [cpu, state]
          system.cpu.utilization:
            attributes: [cpu, state]

Partial reload

• Enable --feature-gates=service.partialReload for the alpha partial-reload path.
• service.partialReloadReceivers is beta.
• A reload restarts only receivers when processors, exporters, extensions, and all other non-receiver configuration are unchanged.

Queue and delivery constraints

• With exporter.kafka.useRequestType, all signals become Kafka records when the exporter request is created, and queue_batch.sizer: items counts those records.
• Persistent sending_queue.storage is a startup error in Kafka request mode.
• With datadog.serializerexporter.UseSyncForwarder, serializer 4xx/5xx failures flow through exporterhelper; retry, queue-overflow, and failed-point telemetry then apply to that path.
• Elasticsearch document-level retries use retry::retry_on_document_status, independently of request-level retries.
• OpenSearch managed templates are accepted only in otel-v1 mapping mode and are created idempotently without replacing existing templates.

Implementation checklist

1. Identify whether the change targets the specification, semantic conventions, an SDK, Collector core, or Contrib.
2. Check stability labels and feature-gate defaults before treating a feature as generally available.
3. Audit renamed attributes, metrics, component types, configuration keys, and Go embedded-field access before an upgrade.
4. Recheck metric units, instrument kinds, aggregation, required attributes, and cardinality; several receiver and convention changes affect dashboards and alerts.
5. For sensitive fields such as exception messages, query parameters, and GraphQL documents, make capture an explicit and sanitized choice.
6. For Collector gates, distinguish default-on from default-off behavior and confirm mutually exclusive gates before deployment.
7. Open the matching reference for complete conditions, allowed values, and receiver- or exporter-specific details.