Registry / observability / osprofiler

osprofiler

JSON →
library4.4.0pypypi✓ verified 84d ago

OSProfiler is a Python library used by OpenStack projects and clients for cross-service profiling. It enables the generation of a single trace per request across multiple services, forming a tree of calls to help identify performance bottlenecks. It is actively maintained by the OpenStack community and provides API and CLI tools for trace management.

pip install osprofiler
INSTALL
IMPORT
SIG · OSPROFILER
O
osprofiler
observabilitypythonv4.4.0
Install
5.0s avg
Import
1082ms
Disk
54MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v4.4.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.920 runs
installs and imports cleanly · install 0.0s · import 1.118s · 52.1MB
glibc
py 3.103.920 runs
installs and imports cleanly · install 5.0s · import 1.045s · 54MB
54MB installed
● package 54MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

profiler
from osprofiler import profiler
import osprofiler
The main API is exposed through the 'profiler' object within the osprofiler package, not the package itself directly.
WsgiMiddleware
from osprofiler.web import WsgiMiddleware
Used for integrating OSProfiler with WSGI applications for HTTP request tracing.

This quickstart demonstrates how to initialize OSProfiler and add trace points using both the `@profiler.trace` decorator and the `with profiler.Trace` context manager. It highlights the importance of `profiler.init()` for activating profiling. The `HMAC_KEY` is essential for security and validating trace information, especially in distributed OpenStack environments.

import os from osprofiler import profiler # In a production OpenStack environment, HMAC_KEY would be a shared secret. # For local testing, a simple key suffices. HMAC_KEY = os.environ.get('OSPROFILER_HMAC_KEY', 'my-very-secret-key-for-profiling') # Initialize the profiler with a base host, project, and HMAC key. # This is crucial; without initialization, profiling calls are ignored. profiler.init('local-host', 'my-test-project', HMAC_KEY) @profiler.trace('my_outer_operation', info={'type': 'application_logic'}) def perform_complex_task(input_data): print(f"Starting complex task with: {input_data}") # Simulate some work import time time.sleep(0.01) with profiler.Trace('inner_computation', info={'stage': 'data_processing'}): intermediate_result = input_data * 2 time.sleep(0.005) print(f"Intermediate result: {intermediate_result}") return intermediate_result + 10 if profiler.is_active(): final_output = perform_complex_task(5) print(f"Final output: {final_output}") print("Profiler is active and trace points would be generated.") # In a real setup, trace data would be sent to a collector (e.g., Ceilometer) # and retrieved via the `osprofiler` CLI (e.g., `osprofiler trace show <trace_id>`). else: print("Profiler is not active. Check initialization and configuration.")
osprofiler --version
Debug
Known issues
gotchaCalls to `profiler.start()` and `profiler.stop()` or uses of `@profiler.trace` and `with profiler.Trace` will be silently ignored if `osprofiler.profiler.init()` has not been called beforehand. Ensure proper initialization at application startup.
fix
Ensure `profiler.init(host, project, hmac_key)` is called once at the beginning of your application's lifecycle. Provide a valid `hmac_key` (even a dummy one for local testing) and appropriate host/project names.
affects: All versions
gotchaFor cross-service profiling, `hmac_keys` must be correctly configured and trace headers (`X-Trace-Info`, `X-Trace-HMAC`) must be propagated between services (e.g., via WSGI middleware). Misconfiguration will lead to traces being dropped or not correctly correlated across services.
fix
When integrating with OpenStack services or any distributed system, use `osprofiler.web.WsgiMiddleware` or manually ensure `X-Trace-Info` and `X-Trace-HMAC` headers are signed and passed between calls. Verify `hmac_keys` in configuration match across all participating services.
affects: All versions
breakingMajor version 4.0.0 (released June 21, 2023) required Python >=3.9. Projects on older Python versions must upgrade their Python environment to use osprofiler 4.x.
fix
Upgrade your Python environment to 3.9 or newer. If stuck on an older Python version, you may need to pin `osprofiler<4.0.0` (e.g., `osprofiler==3.3.0` for Python 3.6-3.8).
affects: 4.0.0+
Errors
Common errors & fixes
TypeError: 'module' object is not callable (from osprofiler import profiler; profiler.start(...))
Attempting to call methods directly on the `osprofiler` module instead of the `profiler` object imported from it. The main API is exposed via `osprofiler.profiler`.
fix
Ensure you are importing `profiler` explicitly: `from osprofiler import profiler`. Then, use `profiler.start()`, `profiler.trace()`, etc.
NameError: name 'OSProfile' is not defined (or similar error when trying to use 'osprofile')
Confusing `osprofiler` (the OpenStack profiler library) with a different library or concept named `osprofile` (e.g., Informatica's OS Profile feature). These are entirely separate and unrelated.
fix
Verify that you intend to use `osprofiler` for OpenStack-style request tracing. If so, ensure your imports and calls correctly reference `osprofiler` and its `profiler` object. If you are looking for operating system profile management, `osprofiler` is not the correct library.
osprofiler CLI command not found (e.g., `osprofiler trace show <id>`)
The `osprofiler` CLI entry point might not be in your system's PATH, or the package might not be installed in an environment where CLI tools are automatically exposed.
fix
Ensure `osprofiler` is installed in your active virtual environment. If the issue persists, you might need to run it via `python -m osprofiler.cmd.cli <command>` or check your shell's PATH configuration.
Upgrade
Version history
4.4.0latest on PyPI · released May 5, 2026
Audit
Dependencies
python3-oslo.concurrencyrequiredCore utility for concurrency in OpenStack projects.
python3-oslo.configrequiredCore utility for configuration management in OpenStack projects.
python3-oslo.serializationrequiredCore utility for serialization, particularly JSON, in OpenStack projects.
python3-oslo.utilsrequiredCollection of utility functions commonly used across OpenStack projects.
Agent activity
10 hits · last 30 days
node
8
OpenAI (training)
2
Resources
osprofiler — pip install osprofiler · libregistry