Registry / gcp / google-cloud-profiler

google-cloud-profiler

library4.1.0pypypiunverified

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.

gcp observability

pip install google-cloud-profiler

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GOOGLE-CLOUD-PROFI

google-cloud-profiler

gcppythonv4.1.0

Install

—

Import

—

Disk

—

Pass rate

0/ 10

Env Coverage0 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v? · pip install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

build_error

glibc

py 3.10–3.95 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

googlecloudprofiler

✓ import googlecloudprofiler

✗ from google.cloud import profiler

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

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

Debug

Known issues

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

affects: All

gotchaThe `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.

affects: All

gotchaWhen 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`).

affects: All

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

affects: All

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

affects: All

breakingThe `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.

affects: Versions older than 4.1.0, or newer Python versions as they are released.

Errors

Common errors & fixes

rpc error: code = PermissionDenied desc = Cloud Profiler API has not been used in project 012345 before or it is disabled.

The Cloud Profiler API is not enabled for your Google Cloud project.

fix

Enable the Cloud Profiler API for your Google Cloud project via the Cloud Console or by running `gcloud services enable cloudprofiler.googleapis.com`.

rpc error: code = PermissionDenied desc = The caller does not have permission.

The service account or user running the application lacks the necessary IAM permissions to write profiling data to the Google Cloud project.

fix

Grant the `Cloud Profiler Agent` (roles/cloudprofiler.agent) IAM role to the service account or user associated with your application on the target Google Cloud project.

ValueError: Service name and version are required.

The `service` and `service_version` parameters were not provided or were invalid in the `googlecloudprofiler.start()` function call.

fix

Ensure `service` and `service_version` are explicitly provided as string arguments to `googlecloudprofiler.start()`, e.g., `googlecloudprofiler.start(service='my-service', service_version='1.0.0')`.

ModuleNotFoundError: No module named 'googlecloudprofiler'

The `google-cloud-profiler` package is not installed in the Python environment where the application is running.

fix

Install the package using pip: `pip install google-cloud-profiler`. If running on Alpine Linux, ensure `build-base` is installed before installing the profiler package: `apk add --update --no-cache build-base && pip install google-cloud-profiler`.

No profiling data is found for project ...

Profiles are not appearing in the Cloud Profiler UI, which can be due to the service running for a short duration, authentication issues, or incorrect `project_id` configuration outside of Google Cloud.

fix

Ensure your service runs continuously for at least 3 minutes, verify the `Cloud Profiler API` is enabled and the service account has the `Cloud Profiler Agent` role. If running outside of Google Cloud, explicitly pass the `project_id` parameter to `googlecloudprofiler.start()`.

Upgrade

Version history

4.1.0latest on PyPI · released Aug 16, 2023

Audit

Dependencies

protobufrequiredRequired for communication with the Profiler service, with specific version bounds mentioned in release notes.

Agent activity

31 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/GoogleCloudPlatform/cloud-profiler-python ↗

packagehttps://pypi.org/project/google-cloud-profiler/ ↗

homepagehttps://cloud.google.com/profiler ↗