{"id":2959,"library":"google-cloud-profiler","title":"Google Cloud Profiler Python Agent","description":"The `google-cloud-profiler` Python agent continuously collects CPU usage and memory-allocation information from Python applications in production. It helps identify resource-intensive parts of the code with low overhead, supporting performance analysis through flame graphs in the Google Cloud console. The library is actively maintained with irregular releases, the latest being v4.1.0, focusing on performance and compatibility with newer Python versions.","status":"active","version":"4.1.0","language":"en","source_language":"en","source_url":"https://github.com/GoogleCloudPlatform/cloud-profiler-python","tags":["google cloud","profiling","performance","observability","metrics","tracing"],"install":[{"cmd":"pip install google-cloud-profiler","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Required for communication with the Profiler service, with specific version bounds mentioned in release notes.","package":"protobuf","optional":false}],"imports":[{"note":"The correct module name to import is `googlecloudprofiler`, not `google.cloud.profiler` or similar common patterns for Google Cloud libraries.","wrong":"from google.cloud import profiler","symbol":"googlecloudprofiler","correct":"import googlecloudprofiler"}],"quickstart":{"code":"import googlecloudprofiler\nimport os\n\ndef my_application_code():\n    # Simulate some work\n    result = 0\n    for i in range(1000000):\n        result += i\n    print(f\"Application is running. Result: {result}\")\n\n# Profiler initialization should happen as early as possible in your application.\ntry:\n    googlecloudprofiler.start(\n        service=os.environ.get('GAE_SERVICE', 'my-python-service'),\n        service_version=os.environ.get('GAE_VERSION', '1.0.0'),\n        # project_id is automatically detected in most GCP environments.\n        # If running outside GCP, uncomment and set your project ID:\n        # project_id=os.environ.get('GOOGLE_CLOUD_PROJECT', 'your-project-id'),\n        # verbose=3  # Uncomment for debug logging\n    )\n    print(\"Cloud Profiler started successfully.\")\nexcept (ValueError, NotImplementedError) as exc:\n    print(f\"Failed to start Cloud Profiler: {exc}\")\n    # Handle errors gracefully, perhaps by logging and continuing without profiling.\n\nmy_application_code()\nprint(\"Application finished.\")\n","lang":"python","description":"This quickstart demonstrates how to initialize the Google Cloud Profiler agent in a Python application. The `googlecloudprofiler.start()` function should be called as early as possible in your application's lifecycle. It requires a `service` name and optionally a `service_version` to categorize profiling data. The `project_id` is often auto-detected in Google Cloud environments but must be explicitly set if running outside GCP."},"warnings":[{"fix":"Enable the Cloud Profiler API via the Google Cloud Console or `gcloud services enable cloudprofiler.googleapis.com`. Grant the `Cloud Profiler Agent` role to your service account.","message":"The Cloud Profiler API must be enabled for your Google Cloud project, and the service account running your application needs the `roles/cloudprofiler.agent` IAM role. Without these, the agent will fail to upload profiles.","severity":"gotcha","affected_versions":"All"},{"fix":"Ensure `googlecloudprofiler.start()` is invoked near the entry point of your application, ideally before any significant application logic, and from the main thread.","message":"The `googlecloudprofiler.start()` function must be called as early as possible in your application's main thread. Calling it too late or from a non-main thread (especially for 'Wall time' profiles) can result in incomplete or missing profiling data.","severity":"gotcha","affected_versions":"All"},{"fix":"Set the `project_id` argument in `googlecloudprofiler.start()` and ensure your environment is authenticated (e.g., via `GOOGLE_APPLICATION_CREDENTIALS` environment variable or `gcloud auth application-default login`).","message":"When running applications outside of Google Cloud, you must explicitly provide the `project_id` parameter to `googlecloudprofiler.start()` and configure appropriate authentication credentials (e.g., Application Default Credentials).","severity":"gotcha","affected_versions":"All"},{"fix":"In your Dockerfile, install `build-base` (e.g., `RUN apk add --update --no-cache build-base`) in a builder stage, then copy the compiled profiler wheels to your final stage.","message":"For applications deployed on Alpine Linux, the Python profiling agent has a native component that requires `build-base` for compilation. Use a multi-stage Docker build to include these dependencies without bloating the final image.","severity":"gotcha","affected_versions":"All"},{"fix":"For full CPU profiles, set `lazy-apps = true` in your uWSGI configuration. For Wall profiles, also set `py-call-osafterfork = true` to enable custom signal handling in forked processes.","message":"When using uWSGI with multiple workers, CPU time and Wall profiles may be incomplete. uWSGI's default behavior can prevent profiling agent initialization in forked worker processes.","severity":"gotcha","affected_versions":"All"},{"fix":"Ensure your application runs on a supported Python version (e.g., 3.7-3.11 for v4.1.0). Upgrade your Python environment or downgrade the `google-cloud-profiler` library if necessary, referring to the official documentation for compatibility.","message":"The `google-cloud-profiler` library supports specific Python versions. As of v4.1.0, it officially supports Python 3.7 through 3.11. Using unsupported or end-of-life Python versions may lead to runtime errors or unexpected behavior.","severity":"breaking","affected_versions":"Versions older than 4.1.0, or newer Python versions as they are released."}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}