Add Pressure Stall Information (PSI) metrics (reopened #2996)

[alpineQ]

Closes #2995

Changes

This PR adds support for Linux Pressure Stall Information (PSI) metrics to the system semantic conventions.

PSI is a Linux kernel feature (available since kernel 4.20) that identifies and quantifies resource contention by measuring the time impact that CPU, memory, and I/O resource crunches have on workloads.

New Metrics

• system.linux.psi.pressure (Gauge): Measures resource pressure as a percentage of time that tasks were stalled over a time window (10s, 60s, or 300s)
• system.linux.psi.total_time (Counter): Tracks the total cumulative stall time in microseconds since system boot

New Attributes

• system.psi.resource: The resource type (cpu, memory, io)
• system.psi.stall_type: The stall severity (some for partial stalls, full for complete stalls where all non-idle tasks are blocked)
• system.psi.window: The time window for pressure calculation (10s, 60s, 300s)

Use Cases

PSI metrics enable:

• Sizing workloads to hardware or provisioning hardware according to workload demand
• Detecting productivity losses caused by resource scarcity
• Dynamic system management (load shedding, job migration, strategic pausing)
• Maximizing hardware utilization without sacrificing workload health

References

• Linux kernel PSI documentation
• /proc/pressure/* interface

Relevant issues and PRs

There are issues on this matter in:

• [receiver/hostmetrics] Pressure Stall Information (PSI) from linux hosts opentelemetry-collector-contrib#42779
• [Feature]: Pressure Stall Information (PSI) from linux hosts opentelemetry-go-contrib#8082

And 2 PRs that I am proposing to address these issues:

• [receiver/hostmetrics] Add Pressure Stall Information (PSI) scraper opentelemetry-collector-contrib#43823
• feat: add pressure stall information (PSI) to host instrumentation opentelemetry-go-contrib#8083

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)
  • Prometheus node exporter has PSI metrics enabled by default

Reopened #2996

[github-actions]

This PR was marked stale due to lack of activity. It will be closed in 7 days.

[alpineQ]

@thompson-tomo @braydonk @trask
Issue #2996 was reopened here. If any additional changes are needed, I'm open to suggestions.

[thompson-tomo]

@alpineQ can you rebase/merge in master as the doc templates have been updated.

[alpineQ]

@thompson-tomo any updates on this?

[thompson-tomo]

Docs and definitions look good to me based on published guidance & clarification.

[trask]

hi @alpineQ, this will need review and approval from @open-telemetry/semconv-system-approvers

[alpineQ]

@trask do these @open-telemetry/semconv-system-approvers really exist or only you can see them? 🤣

[github-actions]

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.

[rogercoll]

@alpineQ Apologies for the delayed response. The group has been focused on delivering the first stable release of a subset of system metrics, and unfortunately this PR slipped through the cracks.

I’ve also noticed that we’re attempting to add a memory pressure metric for Darwin as well (open-telemetry/opentelemetry-collector-contrib#45154). This made me wonder whether we could agree on a cross-platform, generic naming scheme for pressure metrics (for example, system.cpu.pressure).

Since I’m not very familiar with how this concept is handled across other platforms, I’ve added this topic to the agenda for our next SIG meeting (08/01/2026) so we can discuss it together.

[thompson-tomo]

@alpineQ in light of open-telemetry/opentelemetry-collector-contrib#45154 it appears memory pressure is also applicable to macos.

Should we split based on resource type which would mean we end up with:

• system.cpu.pressure.linux.ratio
• system.cpu.pressure.linux.total_time
• system.memory.pressure.linux.ratio
• system.memory.pressure.linux.total_time

Io would become disk, network or other depending on what it refers to.

This way these metrics are complementing

• system.memory.pressure.darwin.status

We then describe it in the description that it comes from psi.