{"id":3930,"library":"codeguru-profiler-agent","title":"Amazon CodeGuru Profiler Python Agent","description":"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.","status":"active","version":"1.2.6","language":"en","source_language":"en","source_url":"https://github.com/aws/amazon-codeguru-profiler-python-agent","tags":["aws","profiling","codeguru","performance","monitoring","observability"],"install":[{"cmd":"pip install codeguru-profiler-agent","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Requires Python 3.6 or later.","package":"python","optional":false},{"reason":"Used for AWS session management (e.g., custom credentials or region), though often pre-installed in AWS environments.","package":"boto3","optional":true}],"imports":[{"symbol":"Profiler","correct":"from codeguru_profiler_agent import Profiler"}],"quickstart":{"code":"import os\nimport time\nfrom codeguru_profiler_agent import Profiler\n\n# Ensure the profiling group exists in your AWS account and region.\n# It's highly recommended to set CODEGURU_PROFILING_GROUP_NAME via an environment variable.\nPROFILING_GROUP_NAME = os.environ.get('CODEGURU_PROFILING_GROUP_NAME', 'MyProfilingGroup')\nAWS_REGION = os.environ.get('AWS_REGION', 'us-east-1') # Set your target AWS region\n\ndef intensive_task():\n    \"\"\"A dummy function to simulate some CPU-bound work.\"\"\"\n    total = 0\n    for _ in range(1_000_000):\n        total += sum(range(100))\n    return total\n\nif __name__ == '__main__':\n    print(f\"Starting Amazon CodeGuru Profiler agent for group: {PROFILING_GROUP_NAME}\")\n    print(f\"Profiling data will be sent to region: {AWS_REGION}\")\n    try:\n        # Initialize and start the profiler.\n        # The agent will automatically submit profiles in the background.\n        profiler = Profiler(\n            profiling_group_name=PROFILING_GROUP_NAME,\n            region_name=AWS_REGION # Specify region if different from default or env var\n        )\n        profiler.start()\n        print(\"Profiler agent started. Running a simulated intensive task...\")\n        \n        # Simulate your application's main logic\n        for i in range(3):\n            print(f\"Running iteration {i+1}...\")\n            intensive_task()\n            time.sleep(1) # Simulate some work interval\n            \n        print(\"Simulated task finished.\")\n\n    except Exception as e:\n        print(f\"An error occurred: {e}\")\n    finally:\n        # For long-running applications, the agent typically runs until the process exits.\n        # Explicit `profiler.stop()` is generally not required unless you need to\n        # stop profiling within a running process before its natural termination.\n        print(\"Application exiting. Profiling data will continue to be submitted as configured.\")\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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`).","severity":"breaking","affected_versions":"<1.2.6"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"fix":"Attach an IAM role or user policy with the necessary CodeGuru Profiler permissions to the execution environment where your application runs.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"deprecated","affected_versions":"<1.0.6 (fix), >1.0.6 (potential issue for IMDSv1-only setups)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}