# OpenTelemetry v0.148.0

2026-03-17 · [Original release notes](https://github.com/open-telemetry/opentelemetry-collector/releases/tag/v0.148.0) · [Full summary](https://ratatosk.io/en/releases/opentelemetry/v0.148.0)

Breaking changes 6 · Deprecations 1 · Important fixes 5 · Enhancements 7 · Dependency updates 1 · Other changes 2

## Breaking changes (6)

### Internal Prometheus service labels now use underscores

- Affects: Prometheus receiver scrapes of the collector’s internal metrics endpoint at `:8888`

Previously, these metrics exposed `service.name`, `service.instance.id` and `service.version` in resource and datapoint attributes. They now expose `service_name`, `service_instance_id` and `service_version` there instead.

> - `service`: The collector's internal Prometheus metrics endpoint (`:8888`) now emits OTel service labels with underscore
>   names (`service_name`, `service_instance_id`, `service_version`) instead of dot-notation names (`service.name`,
>   `service.instance.id`, `service.version`). Users scraping this endpoint with the Prometheus receiver will see these renamed
>   labels in resource and datapoint attributes. As a workaround, add the following `metric_relabel_configs` to your scrape
>   config in prometheus receiver:
>   ```yaml
>   metric_relabel_configs:
>     - source_labels: [service_name]
>       target_label: service.name
>     - source_labels: [service_instance_id]
>       target_label: service.instance.id
>     - source_labels: [service_version]
>       target_label: service.version
>     - regex: service_name|service_instance_id|service_version
>       action: labeldrop
>   ```
>   See https://github.com/open-telemetry/opentelemetry-collector/issues/14814 for details and updates.

### Collector metric units changed to singular forms

- Affects: Collector metrics with plural units in curly braces (Inferred)

Previously, affected metrics used plural unit strings such as `{requests}`.

> - `all`: Change metric units to be singular to match OTel specification, e.g. `{requests}` -> `{request}` (#14753)

### Windows `cmd/builder` outputs now use `.exe` filenames

- Affects: Windows builds made with `cmd/builder`

Previously, the binary was named `<distribution name>` without an extension; Windows builds now produce `<distribution name>.exe`.

Evidence: “If you use the builder to build a Windows binary, that binary will not have a `.exe` extension.” https://github.com/open-telemetry/opentelemetry-collector/issues/12591

> - `cmd/builder`: Add `.exe` to output binary names when building for Windows targets. (#12591)

### `pdata/pprofile` `Sample` field identifiers reassigned

- Affects: setups using the `pdata/pprofile` `Sample` message (Inferred)

Previously, `Values` used `protoID` 2, `AttributeIndices` used 3, and `LinkIndex` used 4. They now use 4, 2, and 3, respectively.

> - `pdata/pprofile`: Update protoID for message Sample fields (#14652)

### `pdata/pprofile` serializes profile attribute strings as dictionary references

- Affects: profiles with string attributes in resource or scope attributes

Unmarshaling resolves the references back to strings, so the pdata API works transparently.

Evidence: “// Resolve all string_value_ref and key_ref to their actual strings” https://github.com/open-telemetry/opentelemetry-collector/pull/14546

> - `pdata/pprofile`: Implement reference based attributes in Profiles (#14546)

### Per-metric configuration types replace `MetricConfig`

- Affects: components with `reaggregation_enabled: true`
- Action required: Update references to `MetricConfig` before upgrading.

Metrics with aggregatable attributes now expose `AggregationStrategy` and `EnabledAttributes []<MetricName>AttributeKey`; other metrics expose only `Enabled`. Typed attribute key constants replace `[]string`, runtime attribute-slice allocations are eliminated, and validation errors name valid attributes and strategies.

> - `cmd/mdatagen`: Generate a per-metric config type `<MetricName>Config` for each metric when `reaggregation_enabled: true` (#14689)
>   Metrics with aggregatable attributes get `AggregationStrategy` and `EnabledAttributes []<MetricName>AttributeKey`
>   fields; others get `Enabled` only. Typed attribute key constants (e.g. `DefaultMetricAttributeKeyStringAttr`)
>   replace `[]string`, eliminating runtime attribute slice allocations. Validation errors now list valid attributes
>   and strategies by name. Components using `reaggregation_enabled: true` will need to update references to `MetricConfig`.

## Deprecations (1)

### Root `Record<Metric>DataPoint` and `EmitForResource` methods deprecated for entity metrics

- Affects: components using `cmd/mdatagen` with entities and associated metrics defined in `metadata.yaml`
- Removed in: not stated

Previously, associated metrics could be recorded against arbitrary resources or omit required identity attributes, with no compile-time or runtime warning. The generated entity-scoped builder now enforces metric associations at compile time, and its `Emit()` copies the entity's identity and description attributes to the resource.

> - `cmd/mdatagen`: Generate entity-scoped MetricsBuilder API that enforces entity-metric associations at compile time (#14659)

## Important fixes (5)

### [Silent failure] `pkg/service` reporter emits repeated status events

- Affects: setups consuming component status events from the `pkg/service` internal status reporter (Inferred)

Previously, transitions the state machine deemed illegal—including repeated `Ok` or `RecoverableError` statuses—were silently dropped, so consumers did not receive them. Those events now reach consumers even when only their metadata changes.

> - `pkg/service`: The internal status reporter no longer drops repeated Ok and RecoverableError statuses (#14282)
>   Status events can now carry metadata and there's value in allowing them to be emitted despite the status value itself
>   not changing.
> - `pkg/service`: The internal status reporter no longer drops repeated Ok and RecoverableError statuses (#14282)
>   Status events can now carry metadata and there's value in allowing them to be emitted despite the status value itself
>   not changing.

### Dictionary switching fixed in `pdata/pprofile` profile merging

- Affects: profile merges with dictionary-table entries shared by multiple data items

When several samples shared a stack, merging could switch its dictionary multiple times. Dictionaries are now switched once before resource profiles, and samples use the already-switched stack dictionaries.

> - `pdata/pprofile`: Switch the dictionary of dictionary tables entries only once when merging profiles (#14709)
>   For dictionary table data, we used to switch their dictionaries when doing
>   the switch for the data that uses them.
>   However, when an entry is associated with multiple other data (several
>   samples can use the same stack), we would have been switching the
>   dictionaries of the entry multiple times.
>   We now switch dictionaries for dictionary table data only once, before
>   switching the resource profiles.

### `cmd/mdatagen` preserves local extensions during `$ref` resolution

- Affects: `cmd/mdatagen` schemas with local extensions on `$ref` nodes

When a node referenced an external or internal schema, locally defined properties such as `x-customType`, `x-pointer`, `x-optional`, `default`, and `description` could be overwritten and lost, resulting in incorrect generated Go structs.

> - `cmd/mdatagen`: Preserve custom extensions (e.g., `x-customType`, `x-pointer`) during schema reference resolution. (#14713, #14565)
>   Fixes an issue where custom properties defined locally on a node were
>   overwritten and lost when resolving a `$ref` to an external/internal schema.

### Debug exporter metric metadata printing fixed

- Affects: `exporter/debug` with `verbosity: detailed` for metrics with metadata (Inferred)

The debug exporter previously showed the Metric Descriptor and DataPoints but omitted the Metadata field for metrics that had metadata. Its detailed output now includes that field.

> - `exporter/debug`: Add printing of metric metadata in detailed verbosity. (#14667)

### OTLP gRPC exporter push methods return errors instead of panicking

- Affects: setups using `exporter/otlp_grpc` with sending queue and retry disabled

Before this fix, calling `ConsumeTraces`, `ConsumeMetrics`, `ConsumeLogs`, or `ConsumeProfiles` before `Start()` completed could dereference a nil interface and cause an unrecoverable panic.

> - `exporter/otlp_grpc`: Prevent nil pointer panic when push methods are called before the OTLP exporter initializes its gRPC clients. (#14663)
>   When the sending queue and retry are disabled, calling ConsumeTraces,
>   ConsumeMetrics, ConsumeLogs, or ConsumeProfiles before the OTLP exporter
>   initializes its gRPC clients could cause a nil pointer dereference panic.
>   The push methods now return an error instead of panicking.

## Enhancements (7)

- `cmd/mdatagen` generates `DeprecatedType` aliases (To use: Set the optional `deprecated_type` metadata field to generate the alias.)
- Go config struct generation added to `cmd/mdatagen`
- Config JSON schema generation in `cmd/mdatagen`
- `cmd/mdatagen` generates config schemas in a separate YAML file
- `NewEntity` constructor added to `pdata/xpdata/entity`
- `Entity.CopyToResource` added to `pdata/xpdata/entity`
- `EntityAttributeMap.All` added to `pdata/xpdata/entity`

## Dependency updates (1)

1 more, none mentioning security

- `` - `pkg/pdata`: Upgrade the OTLP protobuf definitions to version 1.10.0 (#14766) ``

## Other changes (2)

- cmd/mdatagen skips reaggregation options for metrics without aggregatable attributes
- `exporter/otlp_http` errors show the actual destination URL

---

Summaries are produced by AI, so they can be wrong, and they are provided without warranty.
