[k8s] add k8s.persistentvolume and k8s.persistentvolumeclaim entities & metrics by jinja2 · Pull Request #3376 · open-telemetry/semantic-conventions

jinja2 · 2026-02-02T23:18:04Z

Changes

Adds semantic conventions for Kubernetes storage resources - PersistentVolumes (pv) and PersistentVolumeClaims (pvc).
More details available in linked issue.

Important

Pull requests acceptance are subject to the triage process as described in Issue and PR Triage Management.
PRs that do not follow the guidance above, may be automatically rejected and closed.

Merge requirement checklist

CONTRIBUTING.md guidelines followed.
Change log entry added, according to the guidelines in When to add a changelog entry.
- If your PR does not need a change log, start the PR title with [chore]
Links to the prototypes or existing instrumentations (when adding or changing conventions)

github-actions · 2026-03-18T04:05:28Z

This PR has been labeled as stale due to lack of activity. It will be automatically closed if there is no further activity over the next 7 days.

jinja2 · 2026-03-23T23:52:01Z

@ChrsMark @dashpole I've addressed the review comments. Do you mind taking another look when you have a minute? Thanks!

jinja2 · 2026-04-06T16:04:39Z

@open-telemetry/specs-semconv-approvers this one is approved by the SIG, please take a look. Thank you!

trask · 2026-04-13T15:18:44Z

@open-telemetry/semconv-k8s-approvers is this good to be merged? thanks

dashpole · 2026-04-13T15:23:44Z

yes, good to merge

#### Description Adds Kubernetes PersistentVolume (PV) and PersistentVolumeClaim (PVC) support to the k8s_cluster receiver, including metrics, entity events, and metadata. **New metrics** (all disabled by default, `development` stability): | Metric | Type | Unit | Description | |--------|------|------|-------------| | `k8s.persistentvolume.status.phase` | Sum (non-monotonic) | `{persistentvolume}` | Current phase (1 for active, 0 for others). Phases: Pending, Available, Bound, Released, Failed | | `k8s.persistentvolume.storage.capacity` | Sum (non-monotonic) | `By` | Storage capacity in bytes | | `k8s.persistentvolumeclaim.status.phase` | Sum (non-monotonic) | `{persistentvolumeclaim}` | Current phase (1 for active, 0 for others). Phases: Pending, Bound, Lost | | `k8s.persistentvolumeclaim.storage.request` | Sum (non-monotonic) | `By` | Requested storage in bytes | | `k8s.persistentvolumeclaim.storage.capacity` | Sum (non-monotonic) | `By` | Provisioned capacity in bytes (only when bound) | References for enums - - **PV phase:** [`PersistentVolumePhase`](https://pkg.go.dev/k8s.io/[email protected]/core/v1#PersistentVolumePhase) - Pending, Available, Bound, Released, Failed (noticed that the [concepts doc](https://kubernetes.io/docs/concepts/storage/persistent-volumes#phase) omits Pending, but it is defined in the API) - **PVC phase:** [`PersistentVolumeClaimPhase`](https://pkg.go.dev/k8s.io/[email protected]/core/v1#PersistentVolumeClaimPhase) - Pending, Bound, Lost - **PV reclaim policy:** [`PersistentVolumeReclaimPolicy`](https://pkg.go.dev/k8s.io/[email protected]/core/v1#PersistentVolumeReclaimPolicy) - Delete, Recycle, Retain **New entities** (`development` stability): - `k8s.persistentvolume` - identity: `uid`, description: name, storageclass, reclaim_policy - `k8s.persistentvolumeclaim` - identity: `uid`, description: name, extra: namespace, storageclass **RBAC:** Requires `persistentvolumes` and `persistentvolumeclaims` verbs `get`, `list`, `watch` in the collector's ClusterRole. Semantic conventions: open-telemetry/semantic-conventions#3376 Additional implementation details - - Labels, annotations, and creation timestamp are emitted as entity event attributes and via metadata, not as metric resource attributes - following the existing pattern for other resource types. PVC entities also include `k8s.persistentvolume.name` when bound. - Informers are only activated when at least one metric is enabled or metadata/entity exporters are configured. - `storage.capacity` for PVC is only emitted when bound (`Status.Capacity` is populated). - `k8s.storageclass.name` is omitted when no StorageClass is set (e.g., manually provisioned static PVs or stuck/pending PVCs in clusters without a default StorageClass). - `Transform()` strips the `kubectl.kubernetes.io/last-applied-configuration` annotation (contains a full JSON copy of the manifest). #### Link to tracking issue Fixes #47453 #### Testing - **Unit tests:** Golden file tests for PV (default, optional attrs with `reclaim_policy`, no-capacity) and PVC (default bound, pending). `RecordMetrics` and `GetMetadata` coverage for all phases and edge cases. - **Watcher tests:** `TestObjMetadata` entries for PV and PVC. `TestSyncMetadataAndEmitEntityEventsForPV` and `TestSyncMetadataAndEmitEntityEventsForPVC` verify entity_state/entity_delete lifecycle. - **E2E metrics:** PV/PVC metrics validated in `TestE2EClusterScoped` (cluster-wide: PV + PVC) and `TestE2ENamespaceScoped` (namespace-scoped: PVC only) against golden files. - **E2E entities:** `TestE2EPVCEntity` creates a PVC in Kind and validates entity event log output against a golden file. #### Documentation - `documentation.md` updated automatically by mdatagen with new metrics, resource attributes, and entity definitions. - `README.md` updated with PV/PVC RBAC requirements.

…metry#47555) #### Description Adds Kubernetes PersistentVolume (PV) and PersistentVolumeClaim (PVC) support to the k8s_cluster receiver, including metrics, entity events, and metadata. **New metrics** (all disabled by default, `development` stability): | Metric | Type | Unit | Description | |--------|------|------|-------------| | `k8s.persistentvolume.status.phase` | Sum (non-monotonic) | `{persistentvolume}` | Current phase (1 for active, 0 for others). Phases: Pending, Available, Bound, Released, Failed | | `k8s.persistentvolume.storage.capacity` | Sum (non-monotonic) | `By` | Storage capacity in bytes | | `k8s.persistentvolumeclaim.status.phase` | Sum (non-monotonic) | `{persistentvolumeclaim}` | Current phase (1 for active, 0 for others). Phases: Pending, Bound, Lost | | `k8s.persistentvolumeclaim.storage.request` | Sum (non-monotonic) | `By` | Requested storage in bytes | | `k8s.persistentvolumeclaim.storage.capacity` | Sum (non-monotonic) | `By` | Provisioned capacity in bytes (only when bound) | References for enums - - **PV phase:** [`PersistentVolumePhase`](https://pkg.go.dev/k8s.io/[email protected]/core/v1#PersistentVolumePhase) - Pending, Available, Bound, Released, Failed (noticed that the [concepts doc](https://kubernetes.io/docs/concepts/storage/persistent-volumes#phase) omits Pending, but it is defined in the API) - **PVC phase:** [`PersistentVolumeClaimPhase`](https://pkg.go.dev/k8s.io/[email protected]/core/v1#PersistentVolumeClaimPhase) - Pending, Bound, Lost - **PV reclaim policy:** [`PersistentVolumeReclaimPolicy`](https://pkg.go.dev/k8s.io/[email protected]/core/v1#PersistentVolumeReclaimPolicy) - Delete, Recycle, Retain **New entities** (`development` stability): - `k8s.persistentvolume` - identity: `uid`, description: name, storageclass, reclaim_policy - `k8s.persistentvolumeclaim` - identity: `uid`, description: name, extra: namespace, storageclass **RBAC:** Requires `persistentvolumes` and `persistentvolumeclaims` verbs `get`, `list`, `watch` in the collector's ClusterRole. Semantic conventions: open-telemetry/semantic-conventions#3376 Additional implementation details - - Labels, annotations, and creation timestamp are emitted as entity event attributes and via metadata, not as metric resource attributes - following the existing pattern for other resource types. PVC entities also include `k8s.persistentvolume.name` when bound. - Informers are only activated when at least one metric is enabled or metadata/entity exporters are configured. - `storage.capacity` for PVC is only emitted when bound (`Status.Capacity` is populated). - `k8s.storageclass.name` is omitted when no StorageClass is set (e.g., manually provisioned static PVs or stuck/pending PVCs in clusters without a default StorageClass). - `Transform()` strips the `kubectl.kubernetes.io/last-applied-configuration` annotation (contains a full JSON copy of the manifest). #### Link to tracking issue Fixes open-telemetry#47453 #### Testing - **Unit tests:** Golden file tests for PV (default, optional attrs with `reclaim_policy`, no-capacity) and PVC (default bound, pending). `RecordMetrics` and `GetMetadata` coverage for all phases and edge cases. - **Watcher tests:** `TestObjMetadata` entries for PV and PVC. `TestSyncMetadataAndEmitEntityEventsForPV` and `TestSyncMetadataAndEmitEntityEventsForPVC` verify entity_state/entity_delete lifecycle. - **E2E metrics:** PV/PVC metrics validated in `TestE2EClusterScoped` (cluster-wide: PV + PVC) and `TestE2ENamespaceScoped` (namespace-scoped: PVC only) against golden files. - **E2E entities:** `TestE2EPVCEntity` creates a PVC in Kind and validates entity event log output against a golden file. #### Documentation - `documentation.md` updated automatically by mdatagen with new metrics, resource attributes, and entity definitions. - `README.md` updated with PV/PVC RBAC requirements.

github-actions Bot added enhancement New feature or request area:k8s labels Feb 2, 2026

github-project-automation Bot added this to K8s SemConv SIG Feb 2, 2026

jinja2 force-pushed the k8s-persistentvolume branch from 0f00880 to ab57f7c Compare February 2, 2026 23:26

jinja2 commented Feb 2, 2026

View reviewed changes

Comment thread model/k8s/metrics.yaml Outdated

jinja2 marked this pull request as ready for review February 2, 2026 23:46

jinja2 requested review from a team as code owners February 2, 2026 23:47

jinja2 commented Feb 3, 2026

View reviewed changes

Comment thread model/k8s/entities.yaml

dmitryax reviewed Feb 6, 2026

View reviewed changes

Comment thread model/k8s/entities.yaml

jinja2 force-pushed the k8s-persistentvolume branch from af1c841 to 906eaaa Compare February 6, 2026 22:14

dmitryax reviewed Feb 17, 2026

View reviewed changes

Comment thread model/k8s/entities.yaml Outdated

jinja2 force-pushed the k8s-persistentvolume branch from 906eaaa to 597ea3a Compare February 24, 2026 20:47

dmitryax approved these changes Feb 24, 2026

View reviewed changes

dashpole reviewed Feb 25, 2026

View reviewed changes

Comment thread model/k8s/metrics.yaml Outdated

dashpole reviewed Feb 25, 2026

View reviewed changes

Comment thread model/k8s/metrics.yaml Outdated

dashpole reviewed Feb 25, 2026

View reviewed changes

Comment thread model/k8s/metrics.yaml Outdated

ChrsMark reviewed Feb 25, 2026

View reviewed changes

Comment thread model/k8s/entities.yaml

Comment thread model/k8s/entities.yaml

Comment thread model/k8s/metrics.yaml Outdated

Comment thread model/k8s/metrics.yaml Outdated

Comment thread model/k8s/metrics.yaml Outdated

jinja2 force-pushed the k8s-persistentvolume branch from 8aeb4ad to bc8d7bc Compare March 3, 2026 06:11

github-actions Bot added the Stale label Mar 18, 2026

jinja2 added 6 commits March 23, 2026 16:36

[k8s] add k8s.pv and k8s.pvc

32d8ded

rm k8s.ns from descriptive attr

d171aaf

fix tables

4477f8d

update to updowncounter

a972748

update pv/pvc mapping to entity attr

072fc94

rm cross mapping

04db772

jinja2 force-pushed the k8s-persistentvolume branch from bc8d7bc to 04db772 Compare March 23, 2026 23:38

github-actions Bot removed the Stale label Mar 24, 2026

dashpole approved these changes Apr 1, 2026

View reviewed changes

ChrsMark approved these changes Apr 7, 2026

View reviewed changes

jinja2 mentioned this pull request Apr 7, 2026

[receiver/k8s_cluster] Add PersistentVolume and PersistentVolumeClaim metrics open-telemetry/opentelemetry-collector-contrib#47453

Closed

jinja2 moved this to Approved by K8s SIG in K8s SemConv SIG Apr 8, 2026

jinja2 mentioned this pull request Apr 11, 2026

[receiver/k8s_cluster] Add K8s PV/PVC metrics and entities open-telemetry/opentelemetry-collector-contrib#47555

Merged

kamphaus changed the title ~~[k8s] add k8s.persistentvolume and k8s.persistentvolumeclaim entities~~ [k8s] add k8s.persistentvolume and k8s.persistentvolumeclaim entities & metrics Apr 11, 2026

github-project-automation Bot added this to Semantic Conventions Triage Apr 11, 2026

github-project-automation Bot moved this to Untriaged in Semantic Conventions Triage Apr 11, 2026

kamphaus approved these changes Apr 11, 2026

View reviewed changes

github-project-automation Bot moved this from Untriaged to Needs More Approval in Semantic Conventions Triage Apr 11, 2026

trask added this pull request to the merge queue Apr 13, 2026

Merged via the queue into open-telemetry:main with commit 99e91d9 Apr 13, 2026
21 checks passed

github-project-automation Bot moved this from Approved by K8s SIG to Done in K8s SemConv SIG Apr 13, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[k8s] add k8s.persistentvolume and k8s.persistentvolumeclaim entities & metrics#3376

[k8s] add k8s.persistentvolume and k8s.persistentvolumeclaim entities & metrics#3376
trask merged 6 commits intoopen-telemetry:mainfrom
jinja2:k8s-persistentvolume

jinja2 commented Feb 2, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Mar 18, 2026

Uh oh!

jinja2 commented Mar 23, 2026

Uh oh!

jinja2 commented Apr 6, 2026

Uh oh!

trask commented Apr 13, 2026

Uh oh!

dashpole commented Apr 13, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

Conversation

jinja2 commented Feb 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Merge requirement checklist

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Mar 18, 2026

Uh oh!

jinja2 commented Mar 23, 2026

Uh oh!

jinja2 commented Apr 6, 2026

Uh oh!

trask commented Apr 13, 2026

Uh oh!

dashpole commented Apr 13, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

jinja2 commented Feb 2, 2026 •

edited

Loading