{"id":1851,"library":"opentelemetry-instrumentation-system-metrics","title":"OpenTelemetry System Metrics Instrumentation","description":"OpenTelemetry System Metrics Instrumentation provides an automated way to collect system-level performance metrics such as CPU, memory, network, and disk I/O. It is part of the `opentelemetry-python-contrib` project, currently in beta version `0.61b0`, and packages are released on a roughly monthly cadence.","status":"active","version":"0.61b0","language":"en","source_language":"en","source_url":"https://github.com/open-telemetry/opentelemetry-python-contrib","tags":["opentelemetry","metrics","system","performance","monitoring","instrumentation"],"install":[{"cmd":"pip install opentelemetry-instrumentation-system-metrics opentelemetry-sdk psutil","lang":"bash","label":"Install with core dependencies"}],"dependencies":[{"reason":"Core OpenTelemetry API for defining telemetry.","package":"opentelemetry-api","optional":false},{"reason":"OpenTelemetry SDK for processing and exporting telemetry.","package":"opentelemetry-sdk","optional":false},{"reason":"Required for collecting system and process metrics.","package":"psutil","optional":false}],"imports":[{"symbol":"SystemMetricsInstrumentor","correct":"from opentelemetry.instrumentation.system_metrics import SystemMetricsInstrumentor"},{"symbol":"MeterProvider","correct":"from opentelemetry.sdk.metrics import MeterProvider"},{"symbol":"PeriodicExportingMetricReader","correct":"from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader"},{"symbol":"ConsoleMetricExporter","correct":"from opentelemetry.sdk.metrics.export import ConsoleMetricExporter"},{"symbol":"set_meter_provider","correct":"from opentelemetry.sdk.metrics import set_meter_provider"}],"quickstart":{"code":"import time\n\nfrom opentelemetry.sdk.metrics import MeterProvider, set_meter_provider\nfrom opentelemetry.sdk.metrics.export import ConsoleMetricExporter, PeriodicExportingMetricReader\nfrom opentelemetry.instrumentation.system_metrics import SystemMetricsInstrumentor\n\n# Configure MeterProvider\nexporter = ConsoleMetricExporter()\nreader = PeriodicExportingMetricReader(exporter, export_interval_millis=1000)\nset_meter_provider(MeterProvider([reader]))\n\n# Instrument system metrics\nSystemMetricsInstrumentor().instrument()\n\nprint(\"Collecting system metrics... Press Ctrl+C to exit.\")\ntry:\n    while True:\n        time.sleep(5)  # Metrics are collected asynchronously\nexcept KeyboardInterrupt:\n    print(\"Exiting.\")\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"deprecated","affected_versions":"All versions up to 0.61b0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All beta versions (e.x., <1.0.0)"},{"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\"`).","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"In versions prior to `v0.48b0`, the `process.runtime.cpu.utilization` metric might report values outside the expected range of 0 to 1.","severity":"gotcha","affected_versions":"<0.48b0"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}