Amazon CodeGuru Profiler Python Agent

Warnings

• breaking Earlier 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.
• gotcha The 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.
• gotcha The 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.
• gotcha When 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.
• deprecated Version 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.
• gotcha Only 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.

Install

• pip install codeguru-profiler-agent Install latest version

Imports

• Profiler

  from codeguru_profiler_agent import Profiler

Quickstart

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