# OpenTelemetry v0.148.0

2026-03-17 · [릴리스 노트 원문](https://github.com/open-telemetry/opentelemetry-collector/releases/tag/v0.148.0) · [전체 정리](https://ratatosk.io/ko/releases/opentelemetry/v0.148.0)

호환성 변경 6 · 폐기 예정 1 · 중요 수정 5 · 기능·개선 7 · 의존성 갱신 1 · 기타 2

## 호환성 변경 (6)

### 내부 Prometheus 서비스 레이블에 밑줄 사용

- 영향 대상: Collector의 내부 메트릭 엔드포인트 `:8888`에 대한 Prometheus 리시버 스크레이프

이전에는 이 메트릭의 리소스 및 데이터 포인트 어트리뷰트에 `service.name`, `service.instance.id`, `service.version`을 노출했습니다. 이제 같은 위치에 `service_name`, `service_instance_id`, `service_version`을 노출합니다.

> - `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 메트릭 단위의 단수형 변경

- 영향 대상: 중괄호로 감싼 복수형 단위를 사용하는 Collector 메트릭 (추정)

이전에는 영향을 받는 메트릭의 단위 문자열이 `{requests}`와 같은 복수형이었습니다.

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

### Windows `cmd/builder` 출력 파일명에 `.exe` 확장자 적용

- 영향 대상: Windows에서 `cmd/builder`로 만드는 빌드

이전에는 바이너리 이름에 확장자가 없어 `<distribution name>`이었지만, 이제 Windows 빌드에서는 `<distribution name>.exe`로 생성됩니다.

근거: “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` 필드 식별자 재할당

- 영향 대상: `pdata/pprofile` `Sample` 메시지를 사용하는 구성 (추정)

이전에는 `Values`의 `protoID`가 2, `AttributeIndices`의 `protoID`가 3, `LinkIndex`의 `protoID`가 4였습니다. 이제는 각각 4, 2, 3을 사용합니다.

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

### `pdata/pprofile`의 프로파일 어트리뷰트 문자열 딕셔너리 참조 직렬화

- 영향 대상: 리소스 또는 스코프 어트리뷰트에 문자열 어트리뷰트가 있는 프로파일

역직렬화할 때 참조가 문자열로 복원되므로 pdata API를 투명하게 사용할 수 있습니다.

근거: “// 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)

### 메트릭별 구성 타입으로 `MetricConfig` 대체

- 영향 대상: `reaggregation_enabled: true`인 컴포넌트
- 필요 조치: 업그레이드 전 `MetricConfig` 참조 업데이트

집계할 수 있는 어트리뷰트가 있는 메트릭은 이제 `AggregationStrategy`와 `EnabledAttributes []<MetricName>AttributeKey`를 제공합니다. 그 외 메트릭은 `Enabled`만 제공합니다. 타입이 지정된 어트리뷰트 키 상수가 `[]string`을 대체하고, 런타임 어트리뷰트 슬라이스 할당이 제거되며, 검증 오류에 유효한 어트리뷰트와 전략이 명시됩니다.

> - `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`.

## 폐기 예정 (1)

### 엔티티 메트릭용 루트 `Record<Metric>DataPoint` 및 `EmitForResource` 메서드 지원 중단 예정

- 영향 대상: `cmd/mdatagen`을 사용하고 `metadata.yaml`에 엔티티와 연관 메트릭을 정의한 컴포넌트
- 제거 시점: 미상

기존에는 연관 메트릭을 임의의 리소스에 기록하거나 필수 아이덴티티 어트리뷰트를 생략해도 컴파일 시점이나 런타임에 경고가 발생하지 않았습니다. 이제 생성된 엔티티 스코프 빌더가 컴파일 시점에 메트릭 연관 관계를 강제하며, 빌더의 `Emit()`은 엔티티의 아이덴티티와 설명 어트리뷰트를 리소스에 복사합니다.

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

## 중요 수정 (5)

### [드러나지 않던 결함] `pkg/service` 리포터의 반복 상태 이벤트 전송

- 영향 대상: `pkg/service` 내부 상태 리포터에서 컴포넌트 상태 이벤트를 소비하는 설정 (추정)

이전에는 상태 머신이 유효하지 않다고 판단한 전이(반복된 `Ok` 또는 `RecoverableError` 상태 포함)가 조용히 버려져 소비자에게 전달되지 않았습니다. 이제 메타데이터만 바뀐 경우에도 이러한 이벤트가 소비자에게 전달됩니다.

> - `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.

### `pdata/pprofile` 프로파일 병합 시 딕셔너리 전환 수정

- 영향 대상: 여러 데이터 항목에서 공유하는 딕셔너리 테이블 항목이 있는 프로파일 병합

여러 샘플이 하나의 스택을 공유하면 병합 과정에서 해당 스택의 딕셔너리가 여러 번 전환될 수 있었습니다. 이제 리소스 프로파일을 처리하기 전에 딕셔너리를 한 번만 전환하고, 샘플은 이미 전환된 스택 딕셔너리를 사용합니다.

> - `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.

### `$ref` 해석 중 `cmd/mdatagen`의 로컬 확장 보존

- 영향 대상: `$ref` 노드에 로컬 확장이 있는 `cmd/mdatagen` 스키마

노드가 외부 또는 내부 스키마를 참조할 때 `x-customType`, `x-pointer`, `x-optional`, `default`, `description` 같은 로컬 정의 속성이 덮어써져 사라질 수 있었습니다. 그 결과 잘못된 Go struct가 생성됐습니다.

> - `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의 메트릭 메타데이터 출력 수정

- 영향 대상: 메타데이터가 있는 메트릭에 `verbosity: detailed`를 설정한 `exporter/debug` (추정)

debug exporter는 이전에 Metric Descriptor와 DataPoints를 표시했지만, 메타데이터가 있는 메트릭의 Metadata 필드는 표시하지 않았습니다. 이제 상세 출력에 해당 필드도 포함됩니다.

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

### OTLP gRPC 익스포터 푸시 메서드의 패닉 대신 오류 반환

- 영향 대상: 전송 큐와 재시도가 비활성화된 `exporter/otlp_grpc` 사용 설정

이 수정 전에는 `Start()`가 완료되기 전에 `ConsumeTraces`, `ConsumeMetrics`, `ConsumeLogs` 또는 `ConsumeProfiles`를 호출하면 nil 인터페이스를 역참조해 복구할 수 없는 패닉이 발생할 수 있었습니다.

> - `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.

## 기능·개선 (7)

- `cmd/mdatagen`의 `DeprecatedType` 별칭 생성 (사용 조건: 별칭 생성을 위해 선택적 `deprecated_type` 메타데이터 필드 설정)
- `cmd/mdatagen`에 Go config struct 생성 기능 추가
- `cmd/mdatagen`의 Config JSON 스키마 생성
- `cmd/mdatagen`의 별도 YAML 파일 기반 config 스키마 생성
- `pdata/xpdata/entity`에 `NewEntity` 생성자 추가
- `pdata/xpdata/entity`에 `Entity.CopyToResource` 추가
- `pdata/xpdata/entity`에 `EntityAttributeMap.All` 추가

## 의존성 갱신 (1)

그 외 1건 · 보안 언급 없음

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

## 기타 (2)

- `cmd/mdatagen`의 집계 가능한 어트리뷰트가 없는 메트릭 재집계 옵션 제외
- `exporter/otlp_http` 오류에 실제 대상 URL 표시

---

정리 내용은 AI가 작성하므로 틀릴 수 있으며, 보증 없이 제공합니다.
