Google Cloud Profiler Python Agent

4.1.0 · active · verified Sat Apr 11

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.

Warnings

gotcha 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.
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.
gotcha 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.
Fix: Ensure `googlecloudprofiler.start()` is invoked near the entry point of your application, ideally before any significant application logic, and from the main thread.
gotcha 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).
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`).
gotcha 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.
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.
gotcha 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.
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.
breaking 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.
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.

Install

pip install google-cloud-profiler Install with pip

Imports

googlecloudprofiler
```
import googlecloudprofiler
```
The correct module name to import is `googlecloudprofiler`, not `google.cloud.profiler` or similar common patterns for Google Cloud libraries.

Quickstart

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.

import googlecloudprofiler
import os

def my_application_code():
    # Simulate some work
    result = 0
    for i in range(1000000):
        result += i
    print(f"Application is running. Result: {result}")

# Profiler initialization should happen as early as possible in your application.
try:
    googlecloudprofiler.start(
        service=os.environ.get('GAE_SERVICE', 'my-python-service'),
        service_version=os.environ.get('GAE_VERSION', '1.0.0'),
        # project_id is automatically detected in most GCP environments.
        # If running outside GCP, uncomment and set your project ID:
        # project_id=os.environ.get('GOOGLE_CLOUD_PROJECT', 'your-project-id'),
        # verbose=3  # Uncomment for debug logging
    )
    print("Cloud Profiler started successfully.")
except (ValueError, NotImplementedError) as exc:
    print(f"Failed to start Cloud Profiler: {exc}")
    # Handle errors gracefully, perhaps by logging and continuing without profiling.

my_application_code()
print("Application finished.")

view raw JSON →