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
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 1.118s · 52.1MB
glibcpy 3.10–3.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
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`.
fixEnsure 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.
fixVerify 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.
fixEnsure `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.