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

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

@@ -0,0 +1,236 @@
+# Task: Enable AWS Application Signals for Python on ECS
+
+## Overview
+This guide provides complete steps to enable AWS Application Signals for ECS Fargate services, distributed tracing, performance monitoring, and service mapping.
+
+## Prerequisites
+- Services running on ECS both the ec2 and Fargate launch types.
+- Applications using Python language
+
+## Implementation Steps
+
+**Constraints:**
+You must strictly follow the steps in the order below, do not skip or combine steps.
+
+### Step 1: Setup CloudWatch Agent Task
+When running in ECS, the CloudWatch Agent is deployed as a sidecar container next to the application container.
+Proper permissions, a CWAgentConfig configuration file, and the target log group must be set up to enable logging and metrics collection.
+
+#### 1.1 Add CloudWatch Agent Permissions to ECS Task Role
+
+Update ECS task role to add CloudWatchAgentServerPolicy:
+
+```typescript
+// Update existing taskRole or create new one
+const taskRole = new iam.Role(this, 'EcsTaskRole', {
+  assumedBy: new iam.ServicePrincipal('ecs-tasks.amazonaws.com'),
+  managedPolicies: [
+    iam.ManagedPolicy.fromAwsManagedPolicyName('AWSXRayDaemonWriteAccess'),
+    iam.ManagedPolicy.fromAwsManagedPolicyName('CloudWatchAgentServerPolicy'),
+  ],
+  inlinePolicies: {
+    // Your existing inline policies...
+  },
+});
+```
+
+#### 1.2 Create CloudWatch Agent Log Group
+```typescript
+const cwAgentLogGroup = new logs.LogGroup(this, 'CwAgentLogGroup', {
+  logGroupName: '/ecs/ecs-cwagent',
+  removalPolicy: cdk.RemovalPolicy.DESTROY,
+  retention: logs.RetentionDays.ONE_WEEK,
+});
+```
+
+#### 1.3 Add CloudWatch Agent Container to Each Task Definition
+```typescript
+// Add CloudWatch Agent sidecar to each task definition
+const cwAgentContainer = taskDefinition.addContainer('ecs-cwagent-{SERVICE_NAME}', {
+  image: ecs.ContainerImage.fromRegistry('public.ecr.aws/cloudwatch-agent/cloudwatch-agent:latest'),
+  essential: false,
+  memoryReservationMiB: 128,
+  cpu: 64,
+  environment: {
+    CW_CONFIG_CONTENT: JSON.stringify({
+      "traces": {
+        "traces_collected": {
+          "application_signals": {}
+        }
+      },
+      "logs": {
+        "metrics_collected": {
+          "application_signals": {}
+        }
+      }
+    }),
+  },
+  logging: ecs.LogDrivers.awsLogs({
+    streamPrefix: 'ecs',
+    logGroup: cwAgentLogGroup,
+  }),
+});
+```
+
+### Step 2: Add AWS Distro of OpenTelemetry Zero-Code Instrumentation to Main Service
+
+#### 2.1 Add Bind Mount Volumes to Task Definition
+```typescript
+const taskDefinition = new ecs.FargateTaskDefinition(this, '{SERVICE_NAME}TaskDefinition', {
+  // Existing configuration...
+  volumes: [
+    {
+      name: "opentelemetry-auto-instrumentation-python"
+    }
+  ],
+});
+```
+
+#### 2.2 Add ADOT Auto-instrumentation Init Container
+```typescript
+const initContainer = taskDefinition.addContainer('init', {
+  image: ecs.ContainerImage.fromRegistry('public.ecr.aws/aws-observability/adot-autoinstrumentation-python:v0.12.0'),
+  essential: false,
+  memoryReservationMiB: 64,
+  cpu: 32,
+  command: ['cp', '-a', '/autoinstrumentation/.', '/otel-auto-instrumentation-python'],
+  logging: ecs.LogDrivers.awsLogs({
+    streamPrefix: 'init-{SERVICE_NAME}',
+    logGroup: serviceLogGroup,
+  }),
+});
+
+// Add mount point to init container
+initContainer.addMountPoints({
+  sourceVolume: 'opentelemetry-auto-instrumentation-python',
+  containerPath: '/otel-auto-instrumentation-python',
+  readOnly: false,
+});
+```
+
+#### 2.3 Configure Main Application Container OpenTelemetry Environment Variables
+
+##### Python Application Configuration:
+```typescript
+const mainContainer = taskDefinition.addContainer('{SERVICE_NAME}-container', {
+  // Existing configuration...
+  environment: {
+    // Existing environment variables...
+
+    // ADOT Configuration for Application Signals
+    OTEL_RESOURCE_ATTRIBUTES: 'service.name=${SERVICE_NAME}', // SERVICE_NAME is defined by user
+    OTEL_METRICS_EXPORTER: 'none',
+    OTEL_LOGS_EXPORTER: 'none',
+    PYTHONPATH: '/otel-auto-instrumentation-python/opentelemetry/instrumentation/auto_instrumentation:$APP_PATH:/otel-auto-instrumentation-python',
+    OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED: 'true',
+    OTEL_TRACES_EXPORTER: 'otlp',
+    OTEL_EXPORTER_OTLP_PROTOCOL: 'http/protobuf',
+    OTEL_PYTHON_DISTRO: 'aws_distro',
+    OTEL_PYTHON_CONFIGURATOR: 'aws_configurator',
+    OTEL_EXPORTER_OTLP_TRACES_ENDPOINT: 'http://localhost:4316/v1/traces',
+    OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT: 'http://localhost:4316/v1/metrics',
+    OTEL_AWS_APPLICATION_SIGNALS_ENABLED: 'true',
+  },
+});
+```
+If there is PYTHONPATH in container definition, APP_PATH is the existing PYTHONPATH value,
+else no need APP_PATH, PYTHONPATH: '/otel-auto-instrumentation-python/opentelemetry/instrumentation/auto_instrumentation:/otel-auto-instrumentation-python'
+
+#### 2.4 Add Mount Point to Main Container
+```typescript
+// Add mount point to main application container
+mainContainer.addMountPoints({
+  sourceVolume: 'opentelemetry-auto-instrumentation-python',
+  containerPath: '/otel-auto-instrumentation-python',
+  readOnly: false,
+});
+```
+
+#### 2.5 Configure Container Dependencies
+```typescript
+// Ensure containers start in correct order
+mainContainer.addContainerDependencies({
+  container: initContainer,
+  condition: ecs.ContainerDependencyCondition.SUCCESS,
+});
+
+mainContainer.addContainerDependencies({
+  container: cwAgentContainer,
+  condition: ecs.ContainerDependencyCondition.START,
+});
+```
+
+### Step 3: Apply Python Framework–Specific Changes
+Depending on the Python web framework your application uses, additional configuration may be required to ensure OpenTelemetry zero-code instrumentation initializes correctly.
+
+#### 3.a: Django-Specific Configuration
+Django applications may require additional settings to work seamlessly with OpenTelemetry zero-code instrumentation. These adjustments ensure that Django initializes with the correct configuration。
+
+#### 3.a.1: set DJANGO_SETTINGS_MODULE
+If your ECS application is built with Django, explicitly set the DJANGO_SETTINGS_MODULE environment variable in the container definition to ensure correct initialization during OpenTelemetry zero-code instrumentation.
+```typescript
+const mainContainer = taskDefinition.addContainer('{SERVICE_NAME}-container', {
+  // Existing configuration...
+  environment: {
+    // Existing environment variables...
+
+    // Ensure Django settings module is explicitly defined
+    DJANGO_SETTINGS_MODULE: {{your django settings}}
+  },
+});
+```
+
+#### 3.a.2: Add --noreload When Using Django’s Development Server
+If you are using Django’s development server, override the Docker CMD in your ECS container definition by adding the --noreload flag. This prevents startup failures caused by conflicts between Django’s auto-reloader and OpenTelemetry instrumentation.
+Skip this step if you run Django in production with a WSGI or ASGI server (e.g., Gunicorn, Uvicorn, Daphne).
+
+**Before (Dockerfile):**
+```dockerfile
+CMD ["python", "manage.py", "runserver", "0.0.0.0:8000"]
+```
+
+**After (ECS IaC override):**
+```typescript
+Const appContainer = taskDefinition.addContainer('Application', {
+      // Override Dockerfile CMD to include "--noreload"
+      command: ["python", "manage.py", "runserver", "0.0.0.0:8000", "--noreload"],
+
+```
+
+
+## Completion
+
+**Tell the user:**
+
+"I've completed the Application Signals enablement for your application. Here's what I modified:
+
+**Files Changed:**
+- IAM role: Added CloudWatchAgentServerPolicy
+- ECS container: Installed and configured CloudWatch Agent as sidecar
+- ADOT SDK container: Mounted ADOT SDK dependencies into Application container
+- Applicaiton container: Enabled zero-code instrumentation for Application
+
+**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).
+This is a one-time setup; if already enabled, you can skip this step.
+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, wait 5-10 minutes for telemetry data to start flowing
+
+**Verification:**
+Once deployed, you can verify Application Signals is working by:
+- Opening the AWS CloudWatch Console
+- Navigating to Application Signals → Services
+- Looking for your service (named: {{SERVICE_NAME}})
+- Checking that traces and metrics are being collected
+
+**Monitor Application Health:**
+After enablement, you can monitor your application'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_guides/templates/eks/eks-dotnet-enablement.md

@@ -0,0 +1,166 @@
+# Task: Enable AWS Application Signals for .NET Applications on Amazon EKS
+
+This guide shows how to modify the existing CDK and Terraform infrastructure code to enable AWS Application Signals for .NET applications running on Amazon EKS.
+
+## Prerequisites
+
+- Application Signals enabled in your AWS account (see [Enable Application Signals in your account](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Signals-Enable.html))
+- Existing EKS cluster deployed using the provided CDK or Terraform code
+- .NET application containerized and pushed to ECR
+- AWS CLI configured with appropriate permissions
+
+## Critical Requirements
+
+**Error Handling:**
+- If you cannot determine required values from the IaC, STOP and ask the user
+- For multiple EC2 instances, ask which one(s) to modify
+- Preserve all existing UserData commands; add new ones in sequence
+
+**Do NOT:**
+- Run deployment commands automatically (`cdk deploy`, `terraform apply`, etc.)
+- Remove existing application startup logic
+- Skip the user approval step before deployment
+
+## CDK Implementation
+
+### 1. Install CloudWatch Observability Add-on
+
+Create an IAM role and install the CloudWatch Observability add-on:
+
+```typescript
+import * as eks from 'aws-cdk-lib/aws-eks';
+import * as iam from 'aws-cdk-lib/aws-iam';
+
+// Create IAM role for CloudWatch agent
+const cloudwatchRole = new iam.Role(this, 'CloudWatchAgentAddOnRole', {
+  assumedBy: new iam.OpenIdConnectPrincipal(cluster.openIdConnectProvider),
+  managedPolicies: [
+    iam.ManagedPolicy.fromAwsManagedPolicyName('CloudWatchAgentServerPolicy')
+  ],
+});
+
+// Install the CloudWatch Observability add-on
+new eks.CfnAddon(this, 'CloudWatchAddon', {
+  addonName: 'amazon-cloudwatch-observability',
+  clusterName: cluster.clusterName,
+  serviceAccountRoleArn: cloudwatchRole.roleArn
+});
+```
+
+### 2. Add .NET Instrumentation Annotation
+
+Update your deployment template metadata to include the .NET instrumentation annotation:
+
+```typescript
+template: {
+  metadata: {
+    labels: { app: config.appName },
+    annotations: {
+      'instrumentation.opentelemetry.io/inject-dotnet': 'true'
+    }
+  },
+  // ... rest of your template configuration
+}
+```
+
+## Terraform Implementation
+
+### 1. Add CloudWatch Agent IAM Permissions
+
+Add the CloudWatch policy to the node role:
+
+```hcl
+# Additional IAM policies for Application Signals
+resource "aws_iam_role_policy_attachment" "cloudwatch_agent_policy" {
+  policy_arn = "arn:aws:iam::aws:policy/CloudWatchAgentServerPolicy"
+  role       = aws_iam_role.node_role.name
+}
+```
+
+**Important:** Add this policy attachment to your node group's `depends_on` block:
+
+```hcl
+resource "aws_eks_node_group" "app_nodes" {
+  # ... existing configuration ...
+
+  depends_on = [
+    aws_iam_role_policy_attachment.node_policy,
+    aws_iam_role_policy_attachment.cloudwatch_agent_policy
+  ]
+}
+```
+
+### 2. Install CloudWatch Observability Add-on
+
+Add the CloudWatch Observability EKS add-on:
+
+```hcl
+# CloudWatch Observability Add-on
+resource "aws_eks_addon" "cloudwatch_observability" {
+  cluster_name = aws_eks_cluster.app_cluster.name
+  addon_name   = "amazon-cloudwatch-observability"
+
+  depends_on = [
+    aws_eks_node_group.app_nodes
+  ]
+}
+```
+
+### 3. Add .NET Instrumentation Annotation
+
+Update your Kubernetes deployment template to include the .NET instrumentation annotation:
+
+```hcl
+template {
+  metadata {
+    labels = {
+      app = var.app_name
+    }
+    annotations = {
+      "instrumentation.opentelemetry.io/inject-dotnet" = "true"
+    }
+  }
+  # ... rest of your template configuration
+}
+```
+
+## Important Notes
+
+- The .NET instrumentation annotation will cause pods to restart automatically
+- .NET applications require .NET 6.0 or later for Application Signals support
+- It may take a few minutes for data to appear in the Application Signals console after deployment
+
+## Completion
+
+**Tell the user:**
+
+"I've completed the Application Signals enablement for your .NET application. Here's what I modified:
+
+**Files Changed:**
+- IAM role: Added CloudWatchAgentServerPolicy
+- CloudWatch Observability EKS add-on: Added to the EKS Cluster
+- Kubernetes Deployment: Instrumentation annotation added with inject-dotnet set to true
+
+**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, wait 5-10 minutes for telemetry data to start flowing
+
+**Verification:**
+Once deployed, you can verify Application Signals is working by:
+- Opening the AWS CloudWatch Console
+- Navigating to Application Signals → Services
+- Looking for your service (named: {{SERVICE_NAME}})
+- Checking that traces and metrics are being collected
+
+**Monitor Application Health:**
+After enablement, you can monitor your application'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_guides/templates/eks/eks-java-enablement.md

@@ -0,0 +1,166 @@
+# Task: Enable AWS Application Signals for Java Applications on Amazon EKS
+
+This guide shows how to modify the existing CDK and Terraform infrastructure code to enable AWS Application Signals for Java applications running on Amazon EKS.
+
+## Prerequisites
+
+- Application Signals enabled in your AWS account (see [Enable Application Signals in your account](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Signals-Enable.html))
+- Existing EKS cluster deployed using the provided CDK or Terraform code
+- Java application containerized and pushed to ECR
+- AWS CLI configured with appropriate permissions
+
+## Critical Requirements
+
+**Error Handling:**
+- If you cannot determine required values from the IaC, STOP and ask the user
+- For multiple EC2 instances, ask which one(s) to modify
+- Preserve all existing UserData commands; add new ones in sequence
+
+**Do NOT:**
+- Run deployment commands automatically (`cdk deploy`, `terraform apply`, etc.)
+- Remove existing application startup logic
+- Skip the user approval step before deployment
+
+## CDK Implementation
+
+### 1. Install CloudWatch Observability Add-on
+
+Create an IAM role and install the CloudWatch Observability add-on:
+
+```typescript
+import * as eks from 'aws-cdk-lib/aws-eks';
+import * as iam from 'aws-cdk-lib/aws-iam';
+
+// Create IAM role for CloudWatch agent
+const cloudwatchRole = new iam.Role(this, 'CloudWatchAgentAddOnRole', {
+  assumedBy: new iam.OpenIdConnectPrincipal(cluster.openIdConnectProvider),
+  managedPolicies: [
+    iam.ManagedPolicy.fromAwsManagedPolicyName('CloudWatchAgentServerPolicy')
+  ],
+});
+
+// Install the CloudWatch Observability add-on
+new eks.CfnAddon(this, 'CloudWatchAddon', {
+  addonName: 'amazon-cloudwatch-observability',
+  clusterName: cluster.clusterName,
+  serviceAccountRoleArn: cloudwatchRole.roleArn
+});
+```
+
+### 2. Add Java Instrumentation Annotation
+
+Update your deployment template metadata to include the Java instrumentation annotation:
+
+```typescript
+template: {
+  metadata: {
+    labels: { app: config.appName },
+    annotations: {
+      'instrumentation.opentelemetry.io/inject-java': 'true'
+    }
+  },
+  // ... rest of your template configuration
+}
+```
+
+## Terraform Implementation
+
+### 1. Add CloudWatch Agent IAM Permissions
+
+Add the CloudWatch policy to the node role:
+
+```hcl
+# Additional IAM policies for Application Signals
+resource "aws_iam_role_policy_attachment" "cloudwatch_agent_policy" {
+  policy_arn = "arn:aws:iam::aws:policy/CloudWatchAgentServerPolicy"
+  role       = aws_iam_role.node_role.name
+}
+```
+
+**Important:** Add this policy attachment to your node group's `depends_on` block:
+
+```hcl
+resource "aws_eks_node_group" "app_nodes" {
+  # ... existing configuration ...
+
+  depends_on = [
+    aws_iam_role_policy_attachment.node_policy,
+    aws_iam_role_policy_attachment.cloudwatch_agent_policy
+  ]
+}
+```
+
+### 2. Install CloudWatch Observability Add-on
+
+Add the CloudWatch Observability EKS add-on:
+
+```hcl
+# CloudWatch Observability Add-on
+resource "aws_eks_addon" "cloudwatch_observability" {
+  cluster_name = aws_eks_cluster.app_cluster.name
+  addon_name   = "amazon-cloudwatch-observability"
+
+  depends_on = [
+    aws_eks_node_group.app_nodes
+  ]
+}
+```
+
+### 3. Add Java Instrumentation Annotation
+
+Update your Kubernetes deployment template to include the Java instrumentation annotation:
+
+```hcl
+template {
+  metadata {
+    labels = {
+      app = var.app_name
+    }
+    annotations = {
+      "instrumentation.opentelemetry.io/inject-java" = "true"
+    }
+  }
+  # ... rest of your template configuration
+}
+```
+
+## Important Notes
+
+- The Java instrumentation annotation will cause pods to restart automatically
+- Java applications typically have faster startup times with Application Signals compared to other languages
+- It may take a few minutes for data to appear in the Application Signals console after deployment
+
+## Completion
+
+**Tell the user:**
+
+"I've completed the Application Signals enablement for your Java application. Here's what I modified:
+
+**Files Changed:**
+- IAM role: Added CloudWatchAgentServerPolicy
+- CloudWatch Observability EKS add-on: Added to the EKS Cluster
+- Kubernetes Deployment: Instrumentation annotation added with inject-java set to true
+
+**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, wait 5-10 minutes for telemetry data to start flowing
+
+**Verification:**
+Once deployed, you can verify Application Signals is working by:
+- Opening the AWS CloudWatch Console
+- Navigating to Application Signals → Services
+- Looking for your service (named: {{SERVICE_NAME}})
+- Checking that traces and metrics are being collected
+
+**Monitor Application Health:**
+After enablement, you can monitor your application'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!"