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-agentVerified import paths — ran on the pinned version, not inferred.
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.
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.
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.
Attach an IAM role or user policy with the necessary CodeGuru Profiler permissions to the execution environment where your application runs.
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.
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.
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.
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.
Attach an IAM policy with `codeguru-profiler:ConfigureAgent` and `codeguru-profiler:PostAgentProfile` permissions to the execution role or user associated with the application.
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.
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.