OpenTelemetry System Metrics Instrumentation

Warnings

• deprecated Out-of-spec `process.runtime` prefixed metrics are deprecated and will be removed in future versions. Users are encouraged to migrate to standard process metrics.
  Fix: Review your metric consumers for usage of `process.runtime.*` metrics and update to the recommended standard process metrics. Refer to OpenTelemetry semantic conventions for current metric names.
• gotcha The instrumentation library is still in beta, indicating that its API and collected telemetry might undergo breaking changes in future releases as the OpenTelemetry specification evolves.
  Fix: Monitor release notes of `opentelemetry-python-contrib` for breaking changes and adjust your code and configurations accordingly. Consider pinning to specific minor versions for stability.
• gotcha Specific system and process metrics can be excluded from collection using the `OTEL_PYTHON_SYSTEM_METRICS_EXCLUDED_METRICS` environment variable. This is useful for reducing telemetry cardinality or focusing on specific metrics.
  Fix: Set the `OTEL_PYTHON_SYSTEM_METRICS_EXCLUDED_METRICS` environment variable with a comma-separated list of glob patterns matching metric names to exclude (e.g., `export OTEL_PYTHON_SYSTEM_METRICS_EXCLUDED_METRICS="system.cpu.*,process.memory.usage"`).
• gotcha In versions prior to `v0.48b0`, the `process.runtime.cpu.utilization` metric might report values outside the expected range of 0 to 1.
  Fix: Upgrade to `opentelemetry-instrumentation-system-metrics` version `0.48b0` or newer to ensure `process.runtime.cpu.utilization` values are correctly normalized to the 0-1 range.

Install

• pip install opentelemetry-instrumentation-system-metrics opentelemetry-sdk psutil Install with core dependencies

Imports

• SystemMetricsInstrumentor

  from opentelemetry.instrumentation.system_metrics import SystemMetricsInstrumentor

• MeterProvider

  from opentelemetry.sdk.metrics import MeterProvider

• PeriodicExportingMetricReader

  from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader

• ConsoleMetricExporter

  from opentelemetry.sdk.metrics.export import ConsoleMetricExporter

• set_meter_provider

  from opentelemetry.sdk.metrics import set_meter_provider

Quickstart

This quickstart demonstrates how to set up the OpenTelemetry SDK with a `MeterProvider` and a `ConsoleMetricExporter` to print collected metrics to the console. It then instruments system metrics using `SystemMetricsInstrumentor().instrument()`, which starts collecting CPU, memory, disk, and network metrics asynchronously.

import time

from opentelemetry.sdk.metrics import MeterProvider, set_meter_provider
from opentelemetry.sdk.metrics.export import ConsoleMetricExporter, PeriodicExportingMetricReader
from opentelemetry.instrumentation.system_metrics import SystemMetricsInstrumentor

# Configure MeterProvider
exporter = ConsoleMetricExporter()
reader = PeriodicExportingMetricReader(exporter, export_interval_millis=1000)
set_meter_provider(MeterProvider([reader]))

# Instrument system metrics
SystemMetricsInstrumentor().instrument()

print("Collecting system metrics... Press Ctrl+C to exit.")
try:
    while True:
        time.sleep(5)  # Metrics are collected asynchronously
except KeyboardInterrupt:
    print("Exiting.")