awslabs.cloudwatch-applicationsignals-mcp-server 0.1.21__py3-none-any.whl

awslabs/cloudwatch_applicationsignals_mcp_server/enablement_guides/templates/lambda/lambda-python-enablement.md

@@ -0,0 +1,336 @@
+# Task: Enable AWS Application Signals for Python on AWS Lambda
+
+Your task is to modify Infrastructure as Code (IaC) files to enable AWS Application Signals for Python Lambda functions. You will:
+
+1. Add IAM permissions for Application Signals
+2. Configure X-Ray tracing
+3. Add the ADOT Lambda layer
+4. Set the required environment variables.
+
+If you cannot determine a value (such as AWS Region): Ask the user for clarification before proceeding. Do not guess or make up values.
+
+## Region-Specific Layer ARNs
+
+Select the correct ARN for your region:
+
+```json
+{
+  "af-south-1": "arn:aws:lambda:af-south-1:904233096616:layer:AWSOpenTelemetryDistroPython:13",
+  "ap-east-1": "arn:aws:lambda:ap-east-1:888577020596:layer:AWSOpenTelemetryDistroPython:13",
+  "ap-northeast-1": "arn:aws:lambda:ap-northeast-1:615299751070:layer:AWSOpenTelemetryDistroPython:16",
+  "ap-northeast-2": "arn:aws:lambda:ap-northeast-2:615299751070:layer:AWSOpenTelemetryDistroPython:16",
+  "ap-northeast-3": "arn:aws:lambda:ap-northeast-3:615299751070:layer:AWSOpenTelemetryDistroPython:15",
+  "ap-south-1": "arn:aws:lambda:ap-south-1:615299751070:layer:AWSOpenTelemetryDistroPython:16",
+  "ap-south-2": "arn:aws:lambda:ap-south-2:796973505492:layer:AWSOpenTelemetryDistroPython:13",
+  "ap-southeast-1": "arn:aws:lambda:ap-southeast-1:615299751070:layer:AWSOpenTelemetryDistroPython:15",
+  "ap-southeast-2": "arn:aws:lambda:ap-southeast-2:615299751070:layer:AWSOpenTelemetryDistroPython:16",
+  "ap-southeast-3": "arn:aws:lambda:ap-southeast-3:039612877180:layer:AWSOpenTelemetryDistroPython:13",
+  "ap-southeast-4": "arn:aws:lambda:ap-southeast-4:713881805771:layer:AWSOpenTelemetryDistroPython:13",
+  "ap-southeast-5": "arn:aws:lambda:ap-southeast-5:152034782359:layer:AWSOpenTelemetryDistroPython:4",
+  "ap-southeast-7": "arn:aws:lambda:ap-southeast-7:980416031188:layer:AWSOpenTelemetryDistroPython:4",
+  "ca-central-1": "arn:aws:lambda:ca-central-1:615299751070:layer:AWSOpenTelemetryDistroPython:16",
+  "ca-west-1": "arn:aws:lambda:ca-west-1:595944127152:layer:AWSOpenTelemetryDistroPython:4",
+  "cn-north-1": "arn:aws-cn:lambda:cn-north-1:440179912924:layer:AWSOpenTelemetryDistroPython:4",
+  "cn-northwest-1": "arn:aws-cn:lambda:cn-northwest-1:440180067931:layer:AWSOpenTelemetryDistroPython:4",
+  "eu-central-1": "arn:aws:lambda:eu-central-1:615299751070:layer:AWSOpenTelemetryDistroPython:16",
+  "eu-central-2": "arn:aws:lambda:eu-central-2:156041407956:layer:AWSOpenTelemetryDistroPython:13",
+  "eu-north-1": "arn:aws:lambda:eu-north-1:615299751070:layer:AWSOpenTelemetryDistroPython:16",
+  "eu-south-1": "arn:aws:lambda:eu-south-1:257394471194:layer:AWSOpenTelemetryDistroPython:13",
+  "eu-south-2": "arn:aws:lambda:eu-south-2:490004653786:layer:AWSOpenTelemetryDistroPython:13",
+  "eu-west-1": "arn:aws:lambda:eu-west-1:615299751070:layer:AWSOpenTelemetryDistroPython:16",
+  "eu-west-2": "arn:aws:lambda:eu-west-2:615299751070:layer:AWSOpenTelemetryDistroPython:16",
+  "eu-west-3": "arn:aws:lambda:eu-west-3:615299751070:layer:AWSOpenTelemetryDistroPython:16",
+  "il-central-1": "arn:aws:lambda:il-central-1:746669239226:layer:AWSOpenTelemetryDistroPython:13",
+  "me-central-1": "arn:aws:lambda:me-central-1:739275441131:layer:AWSOpenTelemetryDistroPython:13",
+  "me-south-1": "arn:aws:lambda:me-south-1:980921751758:layer:AWSOpenTelemetryDistroPython:13",
+  "mx-central-1": "arn:aws:lambda:mx-central-1:610118373846:layer:AWSOpenTelemetryDistroPython:4",
+  "sa-east-1": "arn:aws:lambda:sa-east-1:615299751070:layer:AWSOpenTelemetryDistroPython:16",
+  "us-east-1": "arn:aws:lambda:us-east-1:615299751070:layer:AWSOpenTelemetryDistroPython:19",
+  "us-east-2": "arn:aws:lambda:us-east-2:615299751070:layer:AWSOpenTelemetryDistroPython:16",
+  "us-west-1": "arn:aws:lambda:us-west-1:615299751070:layer:AWSOpenTelemetryDistroPython:23",
+  "us-west-2": "arn:aws:lambda:us-west-2:615299751070:layer:AWSOpenTelemetryDistroPython:23",
+  "us-gov-east-1": "arn:aws-us-gov:lambda:us-gov-east-1:399711857375:layer:AWSOpenTelemetryDistroPython:1",
+  "us-gov-west-1": "arn:aws-us-gov:lambda:us-gov-west-1:399727141365:layer:AWSOpenTelemetryDistroPython:1"
+}
+```
+
+## Instructions
+
+### Step 1: Add IAM Permissions
+
+Add the AWS managed policy `CloudWatchLambdaApplicationSignalsExecutionRolePolicy` to the Lambda function's execution role.
+
+**CDK:**
+```typescript
+const role = new iam.Role(this, 'LambdaRole', {
+  assumedBy: new iam.ServicePrincipal('lambda.amazonaws.com'),
+  managedPolicies: [
+    iam.ManagedPolicy.fromAwsManagedPolicyName('service-role/AWSLambdaBasicExecutionRole'),
+    iam.ManagedPolicy.fromAwsManagedPolicyName('CloudWatchLambdaApplicationSignalsExecutionRolePolicy'),
+    // ... keep existing policies
+  ],
+});
+
+const myFunction = new lambda.Function(this, 'MyFunction', {
+  // ... existing configuration
+  role: role,
+});
+```
+
+**Terraform:**
+```hcl
+resource "aws_iam_role" "lambda_role" {
+  name = "lambda-role"
+  assume_role_policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [
+      {
+        Action = "sts:AssumeRole"
+        Effect = "Allow"
+        Principal = {
+          Service = "lambda.amazonaws.com"
+        }
+      }
+    ]
+  })
+}
+
+resource "aws_iam_role_policy_attachment" "lambda_basic" {
+  role       = aws_iam_role.lambda_role.name
+  policy_arn = "arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole"
+}
+
+resource "aws_iam_role_policy_attachment" "application_signals" {
+  role       = aws_iam_role.lambda_role.name
+  policy_arn = "arn:aws:iam::aws:policy/CloudWatchLambdaApplicationSignalsExecutionRolePolicy"
+}
+
+resource "aws_lambda_function" "my_function" {
+  # ... existing configuration
+  role = aws_iam_role.lambda_role.arn
+}
+```
+
+**CloudFormation:**
+```yaml
+LambdaRole:
+  Type: AWS::IAM::Role
+  Properties:
+    AssumeRolePolicyDocument:
+      Version: '2012-10-17'
+      Statement:
+        - Effect: Allow
+          Principal:
+            Service: lambda.amazonaws.com
+          Action: sts:AssumeRole
+    ManagedPolicyArns:
+      - arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole
+      - arn:aws:iam::aws:policy/CloudWatchLambdaApplicationSignalsExecutionRolePolicy
+      # ... keep existing policies
+
+MyFunction:
+  Type: AWS::Lambda::Function
+  Properties:
+    # ... existing configuration
+    Role: !GetAtt LambdaRole.Arn
+```
+
+### Step 2: Enable X-Ray Active Tracing
+
+**CDK:**
+```typescript
+const myFunction = new lambda.Function(this, 'MyFunction', {
+  // ... existing configuration
+  tracing: lambda.Tracing.ACTIVE,
+});
+```
+
+**Terraform:**
+```hcl
+resource "aws_lambda_function" "my_function" {
+  # ... existing configuration
+  tracing_config {
+    mode = "Active"
+  }
+}
+```
+
+**CloudFormation:**
+```yaml
+MyFunction:
+  Type: AWS::Lambda::Function
+  Properties:
+    # ... existing configuration
+    TracingConfig:
+      Mode: Active
+```
+
+### Step 3: Add ADOT Python Lambda Layer
+
+Use the layer name `AWSOpenTelemetryDistroPython` with automatic region detection. The code below includes a complete mapping that will automatically select the correct layer ARN based on your deployment region.
+
+**CDK:**
+```typescript
+const layerArns: { [region: string]: string } = {
+  'af-south-1': 'arn:aws:lambda:af-south-1:904233096616:layer:AWSOpenTelemetryDistroPython:13',
+  'ap-east-1': 'arn:aws:lambda:ap-east-1:888577020596:layer:AWSOpenTelemetryDistroPython:13',
+  // ... (see Region-Specific Layer ARNs section above for complete mapping)
+};
+
+const myFunction = new lambda.Function(this, 'MyFunction', {
+  // ... existing configuration
+  layers: [
+    // ... keep existing layers
+    lambda.LayerVersion.fromLayerVersionArn(
+      this,
+      'AdotLayer',
+      layerArns[this.region]
+    ),
+  ],
+});
+```
+
+**Terraform:**
+```hcl
+locals {
+  layer_arns = {
+    "af-south-1"     = "arn:aws:lambda:af-south-1:904233096616:layer:AWSOpenTelemetryDistroPython:13"
+    "ap-east-1"      = "arn:aws:lambda:ap-east-1:888577020596:layer:AWSOpenTelemetryDistroPython:13"
+    # ... (see Region-Specific Layer ARNs section above for complete mapping)
+  }
+}
+
+data "aws_region" "current" {}
+
+resource "aws_lambda_function" "my_function" {
+  # ... existing configuration
+  layers = [
+    # ... keep existing layers
+    local.layer_arns[data.aws_region.current.name]
+  ]
+}
+```
+
+**CloudFormation:**
+```yaml
+Mappings:
+  LayerArns:
+    af-south-1:
+      arn: arn:aws:lambda:af-south-1:904233096616:layer:AWSOpenTelemetryDistroPython:13
+    ap-east-1:
+      arn: arn:aws:lambda:ap-east-1:888577020596:layer:AWSOpenTelemetryDistroPython:13
+    # ... (see Region-Specific Layer ARNs section above for complete mapping)
+
+Resources:
+  MyFunction:
+    Type: AWS::Lambda::Function
+    Properties:
+      # ... existing configuration
+      Layers:
+        # ... keep existing layers
+        - !FindInMap [LayerArns, !Ref 'AWS::Region', arn]
+```
+
+### Step 4: Set Environment Variable
+
+Add the `AWS_LAMBDA_EXEC_WRAPPER` environment variable with value `/opt/otel-instrument`.
+
+**CDK:**
+```typescript
+const myFunction = new lambda.Function(this, 'MyFunction', {
+  // ... existing configuration
+  environment: {
+    // ... keep existing environment variables
+    AWS_LAMBDA_EXEC_WRAPPER: '/opt/otel-instrument',
+  },
+});
+```
+
+**Terraform:**
+```hcl
+resource "aws_lambda_function" "my_function" {
+  # ... existing configuration
+  environment {
+    variables = {
+      # ... keep existing environment variables
+      AWS_LAMBDA_EXEC_WRAPPER = "/opt/otel-instrument"
+    }
+  }
+}
+```
+
+**CloudFormation:**
+```yaml
+MyFunction:
+  Type: AWS::Lambda::Function
+  Properties:
+    # ... existing configuration
+    Environment:
+      Variables:
+        # ... keep existing environment variables
+        AWS_LAMBDA_EXEC_WRAPPER: /opt/otel-instrument
+```
+
+## Complete Example
+
+**CDK:**
+```typescript
+const layerArns: { [region: string]: string } = {
+  'af-south-1': 'arn:aws:lambda:af-south-1:904233096616:layer:AWSOpenTelemetryDistroPython:13',
+  'ap-east-1': 'arn:aws:lambda:ap-east-1:888577020596:layer:AWSOpenTelemetryDistroPython:13',
+  // ... (see Region-Specific Layer ARNs section above for complete mapping)
+};
+
+const pythonFunction = new lambda.Function(this, 'PythonFunction', {
+  runtime: lambda.Runtime.PYTHON_3_11,
+  handler: 'app.handler',
+  code: lambda.Code.fromAsset('src'),
+  tracing: lambda.Tracing.ACTIVE,
+  layers: [
+    lambda.LayerVersion.fromLayerVersionArn(
+      this,
+      'AdotLayer',
+      layerArns[this.region]
+    ),
+  ],
+  environment: {
+    AWS_LAMBDA_EXEC_WRAPPER: '/opt/otel-instrument',
+  },
+});
+```
+
+## Completion
+
+**Tell the user:**
+
+"I've completed the Application Signals enablement for your Python Lambda function. Here's what I modified:
+
+**Configuration Changes:**
+- IAM Permissions: Added CloudWatchLambdaApplicationSignalsExecutionRolePolicy
+- X-Ray Tracing: Enabled active tracing
+- ADOT Layer: Added AWSOpenTelemetryDistroPython layer
+- Environment Variable: Set AWS_LAMBDA_EXEC_WRAPPER=/opt/otel-instrument
+
+**Next Steps:**
+1. Ensure that [Application Signals is enabled in AWS account](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Signals-Enable.html).
+2. Review the changes I made using `git diff`
+3. Deploy your infrastructure:
+   - For CDK: `cdk deploy`
+   - For Terraform: `terraform apply`
+   - For CloudFormation: Deploy your stack
+4. After deployment, invoke your Lambda function to generate telemetry data
+
+**Verification:**
+Once deployed, you can verify Application Signals is working by:
+- Opening the AWS CloudWatch Console
+- Navigating to Application Signals → Services
+- Looking for your Lambda function service
+- Checking that traces and metrics are being collected
+
+**Monitor Application Health:**
+After enablement, you can monitor your Lambda function's operational health using Application Signals dashboards. For more information, see [Monitor the operational health of your applications with Application Signals](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Services.html).
+
+**Troubleshooting**
+If you encounter any other issues, refer to the [CloudWatch APM troubleshooting guide](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Signals-Enable-Troubleshoot.html).
+
+Let me know if you'd like me to make any adjustments before you deploy!"

awslabs/cloudwatch_applicationsignals_mcp_server/enablement_tools.py

@@ -0,0 +1,147 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""CloudWatch Application Signals MCP Server - Enablement Tools."""
+
+from loguru import logger
+from pathlib import Path
+
+
+async def get_enablement_guide(
+    service_platform: str,
+    service_language: str,
+    iac_directory: str,
+    app_directory: str,
+) -> str:
+    """Get enablement guide for AWS Application Signals.
+
+    Use this tool when the user wants to:
+    - Enable observability, monitoring, or Application Signals for their AWS service
+    - Set up automatic instrumentation for their application on AWS
+    - Instrument their service running on EC2, ECS, Lambda, or EKS
+
+    This tool returns step-by-step enablement instructions that guide you through
+    modifying your infrastructure and application code to enable Application Signals,
+    which is the preferred way to enable automatic instrumentation for services on AWS.
+
+    Before calling this tool:
+    1. Ensure you know where the application code is located and that you have read/write permissions
+    2. Ensure you know where the IaC code is located and that you have read/write permissions
+    3. If the user provides relative paths or descriptions (e.g., "./infrastructure", "in the root"):
+       - Use the Bash tool to run 'pwd' to get the current working directory
+       - Use file exploration tools to locate the directories
+       - Convert relative paths to absolute paths before calling this tool
+    4. This tool REQUIRES absolute paths for both iac_directory and app_directory parameters
+
+    After calling this tool, you should:
+    1. Review the enablement guide and create a visible, trackable checklist of required changes
+       - Use your system's task tracking mechanism (todo lists, markdown checklists, etc.)
+       - Each item should be granular enough to complete in one step
+       - Mark items as complete as you finish them to track progress
+       - This allows you to resume work if the context window fills up
+    2. Work through the checklist systematically, one item at a time:
+       - Identify the specific file(s) that need modification for this step
+       - Read only the relevant file(s) (DO NOT load all IaC and app files at once)
+       - Apply the changes as specified in the guide
+    3. Keep context focused: Only load files needed for the current checklist item
+
+    Important guidelines:
+    - Use ABSOLUTE PATHS when reading and writing files
+    - Do NOT modify actual application logic files (.py, .js, .java source code), only
+      modify IaC code, Dockerfiles, and dependency files (requirements.txt, pyproject.toml,
+      package.json, pom.xml, build.gradle, *.csproj, etc.) as instructed by the guide.
+    - Read application files if needed to understand the setup, but avoid modifying them
+
+    Args:
+        service_platform: The AWS platform where the service runs.
+            MUST be one of: 'ec2', 'ecs', 'lambda', 'eks' (lowercase, exact match).
+            To help user determine: check their IaC for ECS services, Lambda functions, EKS deployments, or EC2 instances.
+        service_language: The service's programming language.
+            MUST be one of: 'python', 'nodejs', 'java', 'dotnet' (lowercase, exact match).
+            IMPORTANT: Use 'nodejs' (not 'js', 'node', or 'javascript'), 'dotnet' (not 'csharp' or 'c#').
+            To help user determine: check for package.json (nodejs), requirements.txt (python), pom.xml (java), or .csproj (dotnet).
+        iac_directory: ABSOLUTE path to the Infrastructure as Code (IaC) directory (e.g., /home/user/project/infrastructure)
+        app_directory: ABSOLUTE path to the application code directory (e.g., /home/user/project/app)
+
+    Returns:
+        Markdown-formatted enablement guide with step-by-step instructions
+    """
+    logger.debug(
+        f'get_enablement_guide called: service_platform={service_platform}, service_language={service_language}, '
+        f'iac_directory={iac_directory}, app_directory={app_directory}'
+    )
+
+    # Normalize to lowercase
+    platform_str = service_platform.lower().strip()
+    language_str = service_language.lower().strip()
+
+    guides_dir = Path(__file__).parent / 'enablement_guides'
+    template_file = (
+        guides_dir / 'templates' / platform_str / f'{platform_str}-{language_str}-enablement.md'
+    )
+
+    logger.debug(f'Looking for enablement guide: {template_file}')
+
+    # Validate that paths are absolute
+    iac_path = Path(iac_directory)
+    app_path = Path(app_directory)
+
+    if not iac_path.is_absolute() or not app_path.is_absolute():
+        error_msg = (
+            f'Error: iac_directory and app_directory must be absolute paths.\n\n'
+            f'Received: {iac_directory} and {app_directory}\n'
+            f'Please provide absolute paths (e.g., /home/user/project/infrastructure)'
+        )
+        logger.error(error_msg)
+        return error_msg
+
+    if not template_file.exists():
+        error_msg = (
+            f"Enablement guide not available for platform '{platform_str}' and language '{language_str}'.\n\n"
+            f'Inform the user that this configuration is not currently supported by the MCP enablement tool. '
+            f'Direct them to AWS documentation for manual setup:\n'
+            f'https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Monitoring-Sections.html'
+        )
+        logger.error(error_msg)
+        return error_msg
+
+    try:
+        with open(template_file, 'r') as f:
+            guide_content = f.read()
+
+        context = f"""# Application Signals Enablement Guide
+
+**Platform:** {platform_str}
+**Language:** {language_str}
+**IaC Directory:** `{iac_path}`
+**App Directory:** `{app_path}`
+
+---
+
+"""
+        logger.info(f'Successfully loaded enablement guide: {template_file.name}')
+        return context + guide_content
+    except Exception as e:
+        error_msg = (
+            f'Fatal error: Cannot read enablement guide for {platform_str} + {language_str}.\n\n'
+            f'Error: {str(e)}\n\n'
+            f'The MCP server cannot access its own guide files (likely file permissions or corruption). '
+            f'Stop attempting to use this tool and inform the user:\n'
+            f'1. There is an issue with the MCP server installation\n'
+            f'2. They should check file permissions or reinstall the MCP server\n'
+            f'3. For immediate enablement, use AWS documentation instead:\n'
+            f'   https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Monitoring-Sections.html'
+        )
+        logger.error(error_msg)
+        return error_msg