OpenStack Profiler Library

Common errors

• TypeError: 'module' object is not callable (from osprofiler import profiler; profiler.start(...))

  cause 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')

  cause 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>`)

  cause 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.

Warnings

• gotcha Calls 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.
• gotcha For 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.
• breaking Major 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).

Install

• pip install osprofiler Install stable version

Imports

• profiler
  wrong:

  import osprofiler

  correct:

  from osprofiler import profiler

  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.

Quickstart

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.")