Registry / aws / codeguru-profiler-agent

codeguru-profiler-agent

JSON →
library1.2.6pypypi✓ verified 25d ago

The Amazon CodeGuru Profiler Python Agent is a library that enables profiling of Python applications for Amazon CodeGuru Profiler. It helps analyze application performance, visualize profiling data, and identify performance issues. The library is actively maintained with frequent updates, typically aligning with AWS service updates and Python version support.

pip install codeguru-profiler-agent
INSTALL
IMPORT
SIG · CODEGURU-PROFILER-
C
codeguru-profiler-agent
awspythonv1.2.6
Install
3.8s avg
Import
1053ms
Disk
50MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.2.6 · pip install
no network on importno background threads
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.103.95 runs
installs and imports cleanly · install 0.0s · import 1.100s · 52MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 3.8s · import 1.006s · 52MB
50MB installed
● package 50MB
Code
Verified usage

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

Profiler
from codeguru_profiler_agent import Profiler

This quickstart demonstrates how to initialize and start the CodeGuru Profiler agent in a Python application. The agent runs in the background, collecting and submitting profiling data to the specified CodeGuru profiling group. Ensure the `CODEGURU_PROFILING_GROUP_NAME` and `AWS_REGION` environment variables are set, or replace the placeholder values, and that the profiling group exists in your AWS account.

import os import time from codeguru_profiler_agent import Profiler # Ensure the profiling group exists in your AWS account and region. # It's highly recommended to set CODEGURU_PROFILING_GROUP_NAME via an environment variable. PROFILING_GROUP_NAME = os.environ.get('CODEGURU_PROFILING_GROUP_NAME', 'MyProfilingGroup') AWS_REGION = os.environ.get('AWS_REGION', 'us-east-1') # Set your target AWS region def intensive_task(): """A dummy function to simulate some CPU-bound work.""" total = 0 for _ in range(1_000_000): total += sum(range(100)) return total if __name__ == '__main__': print(f"Starting Amazon CodeGuru Profiler agent for group: {PROFILING_GROUP_NAME}") print(f"Profiling data will be sent to region: {AWS_REGION}") try: # Initialize and start the profiler. # The agent will automatically submit profiles in the background. profiler = Profiler( profiling_group_name=PROFILING_GROUP_NAME, region_name=AWS_REGION # Specify region if different from default or env var ) profiler.start() print("Profiler agent started. Running a simulated intensive task...") # Simulate your application's main logic for i in range(3): print(f"Running iteration {i+1}...") intensive_task() time.sleep(1) # Simulate some work interval print("Simulated task finished.") except Exception as e: print(f"An error occurred: {e}") finally: # For long-running applications, the agent typically runs until the process exits. # Explicit `profiler.stop()` is generally not required unless you need to # stop profiling within a running process before its natural termination. print("Application exiting. Profiling data will continue to be submitted as configured.")
Debug
Known issues
breakingEarlier versions of the agent (prior to 1.2.6) may not fully support newer Python versions (3.12, 3.13) or might experience runtime errors (e.g., `TypeError` on Python 3.11 due to `line_no is None`).
fix
Upgrade to agent version 1.2.6 or later to ensure compatibility with Python 3.12 and 3.13. For Python 3.11, upgrade to at least 1.2.5 to address specific `TypeError` issues.
affects: <1.2.6
gotchaThe specified `profiling_group_name` must exist in the AWS account and region where the agent is running. If the profiling group does not exist, the agent will fail to submit data or report `ResourceNotFoundException` errors.
fix
Create the profiling group in the AWS CodeGuru Profiler console or via AWS CLI/SDK before starting the agent. Ensure the name and region passed to the `Profiler` constructor match the created group.
affects: All
gotchaThe agent requires appropriate IAM permissions (e.g., `codeguru-profiler:PostAgentProfile`) to submit profiling data to the profiling group. A lack of permissions will result in `403 Forbidden` errors in the application logs.
fix
Attach an IAM role or user policy with the necessary CodeGuru Profiler permissions to the execution environment where your application runs.
affects: All
gotchaWhen profiling AWS Lambda functions, the profiling group must be configured for the 'AWS Lambda' compute platform. Mismatched configurations can lead to `ValidationException` errors in the agent logs.
fix
Ensure that if you are profiling a Lambda function, the associated profiling group in CodeGuru Profiler is explicitly set for the Lambda compute platform. Consider using AWS Lambda Layers for easier integration.
affects: All
deprecatedVersion 1.0.6 updated the agent to use IMDSv2 (Instance Metadata Service Version 2) instead of IMDSv1 for retrieving EC2 instance metadata. Environments strictly configured for IMDSv1 might encounter issues.
fix
Ensure your EC2 instances are configured to support IMDSv2, or if you must use IMDSv1, be aware that the agent versions 1.0.6 and later will attempt to use IMDSv2 first.
affects: <1.0.6 (fix), >1.0.6 (potential issue for IMDSv1-only setups)
gotchaOnly one `Profiler` object should be started at a time within an application. Attempting to start multiple instances concurrently can lead to unexpected behavior or incorrect profiling data.
fix
Design your application to initialize and start the `Profiler` once, typically during application startup, and allow it to run for the lifetime of the process.
affects: All
Errors
Common errors & fixes
ResourceNotFoundException
The specified profiling group name does not exist in the AWS account and region where the agent is running, or there is a typo in the name.
fix
Create the profiling group in the AWS CodeGuru Profiler console or via AWS CLI/SDK before starting the agent, ensuring the name and region passed to the Profiler constructor match the created group.
403 Forbidden
The IAM role or user running the application and CodeGuru Profiler agent lacks the necessary permissions (e.g., codeguru-profiler:PostAgentProfile, codeguru-profiler:ConfigureAgent) to submit profiling data to the profiling group.
fix
Attach an IAM policy with `codeguru-profiler:ConfigureAgent` and `codeguru-profiler:PostAgentProfile` permissions to the execution role or user associated with the application.
ValidationException: Profiling group is configured for AWS Lambda compute platform, whereas CodeGuru Profiler agent is not running on AWS Lambda.
There is a mismatch between the compute platform configured for the profiling group in CodeGuru Profiler (e.g., set for AWS Lambda) and the environment where the agent is actually running.
fix
Ensure that if you are profiling a Lambda function, the associated profiling group in CodeGuru Profiler is explicitly set for the 'AWS Lambda' compute platform. If not profiling Lambda, ensure the group is set to 'Other' or the correct platform.
I don't see any messages from CodeGuru Profiler in my application logs.
The `Profiler` object's `start()` method was not called, or the agent is not correctly configured to run and initialize within the application.
fix
Ensure that `profiler.start()` is explicitly called during your application's startup routine and that required environment variables like `CODEGURU_PROFILING_GROUP_NAME` and `AWS_REGION` are correctly set.
Upgrade
Version history
1.2.6latest on PyPI · released Dec 11, 2025
Audit
Dependencies
pythonrequiredRequires Python 3.6 or later.
boto3optionalUsed for AWS session management (e.g., custom credentials or region), though often pre-installed in AWS environments.
Agent activity
34 hits · last 30 days
node
28
OpenAI (training)
1
Resources
codeguru-profiler-agent — pip install codeguru-profiler-agent · libregistry