{"id":7485,"library":"osprofiler","title":"OpenStack Profiler Library","description":"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.","status":"active","version":"4.3.0","language":"en","source_language":"en","source_url":"https://github.com/openstack/osprofiler","tags":["profiling","openstack","performance","tracing","distributed-tracing"],"install":[{"cmd":"pip install osprofiler","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core utility for concurrency in OpenStack projects.","package":"python3-oslo.concurrency","optional":false},{"reason":"Core utility for configuration management in OpenStack projects.","package":"python3-oslo.config","optional":false},{"reason":"Core utility for serialization, particularly JSON, in OpenStack projects.","package":"python3-oslo.serialization","optional":false},{"reason":"Collection of utility functions commonly used across OpenStack projects.","package":"python3-oslo.utils","optional":false}],"imports":[{"note":"The main API is exposed through the 'profiler' object within the osprofiler package, not the package itself directly.","wrong":"import osprofiler","symbol":"profiler","correct":"from osprofiler import profiler"},{"note":"Used for integrating OSProfiler with WSGI applications for HTTP request tracing.","symbol":"WsgiMiddleware","correct":"from osprofiler.web import WsgiMiddleware"}],"quickstart":{"code":"import os\nfrom osprofiler import profiler\n\n# In a production OpenStack environment, HMAC_KEY would be a shared secret.\n# For local testing, a simple key suffices.\nHMAC_KEY = os.environ.get('OSPROFILER_HMAC_KEY', 'my-very-secret-key-for-profiling')\n\n# Initialize the profiler with a base host, project, and HMAC key.\n# This is crucial; without initialization, profiling calls are ignored.\nprofiler.init('local-host', 'my-test-project', HMAC_KEY)\n\n@profiler.trace('my_outer_operation', info={'type': 'application_logic'})\ndef perform_complex_task(input_data):\n    print(f\"Starting complex task with: {input_data}\")\n    # Simulate some work\n    import time\n    time.sleep(0.01)\n\n    with profiler.Trace('inner_computation', info={'stage': 'data_processing'}):\n        intermediate_result = input_data * 2\n        time.sleep(0.005)\n    \n    print(f\"Intermediate result: {intermediate_result}\")\n    return intermediate_result + 10\n\nif profiler.is_active():\n    final_output = perform_complex_task(5)\n    print(f\"Final output: {final_output}\")\n    print(\"Profiler is active and trace points would be generated.\")\n    # In a real setup, trace data would be sent to a collector (e.g., Ceilometer)\n    # and retrieved via the `osprofiler` CLI (e.g., `osprofiler trace show <trace_id>`).\nelse:\n    print(\"Profiler is not active. Check initialization and configuration.\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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).","message":"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.","severity":"breaking","affected_versions":"4.0.0+"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure you are importing `profiler` explicitly: `from osprofiler import profiler`. Then, use `profiler.start()`, `profiler.trace()`, etc.","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`.","error":"TypeError: 'module' object is not callable (from osprofiler import profiler; profiler.start(...))"},{"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.","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.","error":"NameError: name 'OSProfile' is not defined (or similar error when trying to use 'osprofile')"},{"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.","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.","error":"osprofiler CLI command not found (e.g., `osprofiler trace show <id>`)"}]}