ECS Container Insights for MCP Servers

Enabling Container Insights

Container Insights is a cluster-level setting. Enable it at creation or update an existing cluster:

# Enable at cluster creation
aws ecs create-cluster \
  --cluster-name my-cluster \
  --configuration '{"executeCommandConfiguration": {}, "containerInsights": "enabled"}'

# Enable on an existing cluster
aws ecs update-cluster-settings \
  --cluster my-cluster \
  --settings name=containerInsights,value=enabled

In CDK:

const cluster = new ecs.Cluster(this, 'Cluster', {
  vpc,
  containerInsights: true,
});

Container Insights has two tiers:

Metrics available per task

Container Insights emits metrics under the ECS/ContainerInsights namespace with dimensions ClusterName, ServiceName, TaskDefinitionFamily:

Container-level metrics (with ContainerName dimension) give you a breakdown per container inside a task definition. Useful for multi-container tasks where an app container and a sidecar (e.g., FireLens log router) share the same task CPU.

Custom application metrics via EMF

Container Insights collects infrastructure metrics automatically. For application-level metrics (MCP tool call count, per-tool latency, error rate by tool name), use Embedded Metric Format (EMF) — write structured JSON to stdout and CloudWatch Logs agent converts it to CloudWatch Metrics automatically, with no API calls or SDK dependencies:

function emitToolMetric(toolName: string, durationMs: number, success: boolean): void {
  const emfPayload = {
    _aws: {
      Timestamp: Date.now(),
      CloudWatchMetrics: [{
        Namespace: "MCPServer/Tools",
        Dimensions: [["ToolName"], ["ToolName", "ServiceName"]],
        Metrics: [
          { Name: "ToolCallDuration", Unit: "Milliseconds" },
          { Name: "ToolCallCount", Unit: "Count" },
          { Name: "ToolCallErrors", Unit: "Count" },
        ],
      }],
    },
    // Dimension values
    ToolName: toolName,
    ServiceName: process.env.ECS_SERVICE_NAME ?? "mcp-server",
    // Metric values
    ToolCallDuration: durationMs,
    ToolCallCount: 1,
    ToolCallErrors: success ? 0 : 1,
  };
  // Write to stdout — CloudWatch Logs agent picks it up
  process.stdout.write(JSON.stringify(emfPayload) + "\n");
}

// Usage in your MCP tool handler
async function handleToolCall(name: string, args: unknown): Promise<unknown> {
  const start = Date.now();
  let success = false;
  try {
    const result = await executeToolLogic(name, args);
    success = true;
    return result;
  } finally {
    emitToolMetric(name, Date.now() - start, success);
  }
}

This produces metrics in a custom MCPServer/Tools namespace, dimensioned by ToolName and ServiceName. You can alarm on ToolCallErrors / ToolCallCount > 0.05 (5% error rate per tool) without any third-party APM.

Log groups and retention

Fargate tasks write to CloudWatch Logs via the awslogs log driver. Each service gets its own log group. Without explicit retention, logs accumulate indefinitely at $0.50/GB/month ingestion + $0.03/GB/month storage:

# Set 30-day retention on an existing log group
aws logs put-retention-policy \
  --log-group-name /ecs/mcp-server \
  --retention-in-days 30

# Automate for all /ecs/ log groups
aws logs describe-log-groups \
  --log-group-name-prefix /ecs/ \
  --query 'logGroups[?!retentionInDays].logGroupName' \
  --output text | tr '\t' '\n' | while read lg; do
    aws logs put-retention-policy --log-group-name "$lg" --retention-in-days 30
    echo "Set 30d retention on $lg"
  done

In the task definition, configure the log driver explicitly with a group name and stream prefix:

{
  "logConfiguration": {
    "logDriver": "awslogs",
    "options": {
      "awslogs-group": "/ecs/mcp-server",
      "awslogs-region": "us-east-1",
      "awslogs-stream-prefix": "mcp-server",
      "awslogs-create-group": "true"
    }
  }
}

Use awslogs-create-group: "true" only in development — in production, create log groups explicitly with a retention policy before the service starts, to prevent the Fargate task from creating a group with infinite retention.

Correlating Container Insights with application metrics

Container Insights task ARNs and application-level EMF metrics share no common dimension by default. Add the task ARN as a dimension to EMF metrics to correlate a spike in ToolCallErrors with a specific task's CPU saturation:

const TASK_METADATA_URI = process.env.ECS_CONTAINER_METADATA_URI_V4;
let taskArn: string | undefined;

async function getTaskArn(): Promise<string> {
  if (!taskArn) {
    const metadata = await fetch(`${TASK_METADATA_URI}/task`).then(r => r.json());
    taskArn = metadata.TaskARN;
  }
  return taskArn!;
}

// Include TaskARN in EMF dimensions
async function emitEnrichedToolMetric(toolName: string, durationMs: number, success: boolean): Promise<void> {
  const arn = await getTaskArn();
  const emfPayload = {
    _aws: {
      Timestamp: Date.now(),
      CloudWatchMetrics: [{
        Namespace: "MCPServer/Tools",
        Dimensions: [["ToolName"], ["ToolName", "TaskArn"]],
        Metrics: [
          { Name: "ToolCallDuration", Unit: "Milliseconds" },
          { Name: "ToolCallErrors", Unit: "Count" },
        ],
      }],
    },
    ToolName: toolName,
    TaskArn: arn,
    ToolCallDuration: durationMs,
    ToolCallErrors: success ? 0 : 1,
  };
  process.stdout.write(JSON.stringify(emfPayload) + "\n");
}

High cardinality dimensions (TaskArn changes with every deployment) produce many CloudWatch metric streams — $0.30/stream/month × unique TaskArns. Use the task ARN dimension only for debug dashboards, not production alarms.

Common failures