AWS CloudWatch

Retrieves CloudWatch metric data for a specific metric. This tool retrieves metric data from CloudWatch for a specific metric identified by its namespace, metric name, and dimensions, within a specified time range. It can use either standard GetMetricData API or CloudWatch Metrics Insights for more advanced querying. The function automatically determines whether to use standard GetMetricData or Metrics Insights based on the parameters provided. If any Metrics Insights specific parameters are provided (group_by_dimension, schema_dimension_keys, limit, sort_order, or order_by_statistic), it will use Metrics Insights. When using group_by_dimension, you must include that dimension in schema_dimension_keys. Usage: Use this tool to get actual metric data from CloudWatch for analysis or visualization. Returns: GetMetricDataResponse: An object containing the metric data results Example 1 (Standard GetMetricData): result = await get_metric_data( ctx, namespace="AWS/EC2", metric_name="CPUUtilization", start_time="2023-01-01T00:00:00Z", dimensions=[ Dimension(name="InstanceId", value="i-1234567890abcdef0") ], statistic="Average" # Period will be auto-calculated based on time window and target_datapoints ) Example 2 (Metrics Insights with group by): result = await get_metric_data( ctx, namespace="AWS/EC2", metric_name="CPUUtilization", start_time="2023-01-01T00:00:00Z", end_time="2023-01-02T00:00:00Z", statistic="AVG", schema_dimension_keys=["InstanceType"], group_by_dimension="InstanceType" # This will generate a query like: SELECT AVG("CPUUtilization") FROM SCHEMA("AWS/EC2", "InstanceType") GROUP BY "InstanceType" ) Example 3 (Metrics Insights with schema dimension keys): result = await get_metric_data( ctx, namespace="AWS/EC2", metric_name="CPUUtilization", start_time="2023-01-01T00:00:00Z", end_time="2023-01-02T00:00:00Z", statistic="AVG", schema_dimension_keys=["InstanceId", "InstanceType"], group_by_dimension="InstanceId" # This will generate a query like: SELECT AVG("CPUUtilization") FROM SCHEMA("AWS/EC2", "InstanceId", "InstanceType") GROUP BY "InstanceId" ) Example 4 (Metrics Insights with ORDER BY and LIMIT to find the top 5 EC2 instances with the highest CPU utilization): result = await get_metric_data( ctx, namespace="AWS/EC2", metric_name="CPUUtilization", start_time="2023-01-01T00:00:00Z", end_time="2023-01-02T00:00:00Z", statistic="AVG", schema_dimension_keys=["InstanceId"], group_by_dimension="InstanceId", sort_order="DESC", limit=5, order_by_statistic="MAX" # This will generate a query like: SELECT AVG("CPUUtilization") FROM SCHEMA("AWS/EC2", "InstanceId") GROUP BY "InstanceId" ORDER BY MAX() DESC LIMIT 5 ) Example 5 (Metrics Insights with ORDER BY without sort direction to find the EC2 instances with the highest CPU utilization ordered by default ASC): result = await get_metric_data( ctx, namespace="AWS/EC2", metric_name="CPUUtilization", start_time="2023-01-01T00:00:00Z", end_time="2023-01-02T00:00:00Z", statistic="AVG", schema_dimension_keys=["InstanceId"], group_by_dimension="InstanceId", order_by_statistic="MAX" # This will generate a query like: SELECT AVG("CPUUtilization") FROM SCHEMA("AWS/EC2", "InstanceId") GROUP BY "InstanceId" ORDER BY MAX() ) Example 6 (Metrics Insights without ORDER BY clause to find the EC2 instances with the highest CPU utilization in no specific order): result = await get_metric_data( ctx, namespace="AWS/EC2", metric_name="CPUUtilization", start_time="2023-01-01T00:00:00Z", end_time="2023-01-02T00:00:00Z", statistic="AVG", schema_dimension_keys=["InstanceId"], group_by_dimension="InstanceId" # This will generate a query like: SELECT AVG("CPUUtilization") FROM SCHEMA("AWS/EC2", "InstanceId") GROUP BY "InstanceId" # No ORDER BY clause is added since neither order_by_statistic nor sort_order is specified ) For each result: for metric_result in result.metricDataResults: print(f"Metric: {metric_result.label}") for datapoint in metric_result.datapoints: print(f" {datapoint.timestamp}: {datapoint.value}")

Gets metadata for a CloudWatch metric including description, unit and recommended statistics that can be used for metric data retrieval. This tool retrieves comprehensive metadata about a specific CloudWatch metric identified by its namespace and metric name. Note: This function uses local metadata and does not make AWS API calls. Usage: Use this tool to get detailed information about CloudWatch metrics, including their descriptions, units, and recommended statistics to use. Args: ctx: The MCP context object for error handling and logging. namespace: The metric namespace (e.g., "AWS/EC2", "AWS/Lambda") metric_name: The name of the metric (e.g., "CPUUtilization", "Duration") Returns: Optional[MetricMetadata]: An object containing the metric's description, recommended statistics, and unit if found, None if no metadata is available. Example: result = await get_metric_metadata( ctx, namespace="AWS/EC2", metric_name="CPUUtilization" ) if result: print(f"Description: {result.description}") print(f"Unit: {result.unit}") print(f"Recommended Statistics: {result.recommendedStatistics}")

Analyzes CloudWatch metric data to determine seasonality, trend, data density and statistical properties. This tool provides RAW DATA ONLY about historical metric data and performs analysis including: - Seasonality detection - Trend analysis - Data density and publishing period - Advanced statistical measures (min/max/median, std dev, noise) Usage: Use this tool to get objective metric analysis data. Args: ctx: The MCP context object for error handling and logging. namespace: The metric namespace (e.g., "AWS/EC2", "AWS/Lambda") metric_name: The name of the metric (e.g., "CPUUtilization", "Duration") dimensions: List of dimensions with name and value pairs region: AWS region to query. Defaults to AWS_REGION environment variable or us-east-1 if not set. profile_name: AWS CLI Profile Name to use for AWS access. Falls back to AWS_PROFILE environment variable if not specified, or uses default AWS credential chain. statistic: The statistic to use for metric analysis. For guidance on choosing the correct statistic, refer to the get_recommended_metric_alarms tool. Returns: Dict[str, Any]: Analysis results including: - message: Status message indicating success or reason for empty result - seasonality_seconds: Detected seasonality period in seconds - trend: Trend direction (INCREASING, DECREASING, or NONE) - statistics: Statistical measures (std_deviation, variance, etc.) - data_quality: Data density and publishing period information Example: analysis = await analyze_metric( ctx, namespace="AWS/EC2", metric_name="CPUUtilization", dimensions=[ Dimension(name="InstanceId", value="i-1234567890abcdef0") ] ) print(f"Status: {analysis['message']}") print(f"Seasonality: {analysis['seasonality_seconds']} seconds") print(f"Trend: {analysis['trend']}")

Gets recommended alarms for a CloudWatch metric. This tool retrieves alarm recommendations for a specific CloudWatch metric identified by its namespace, metric name, and dimensions. The recommendations are filtered to match the provided dimensions. Usage: Use this tool to get recommended alarm configurations for CloudWatch metrics, including thresholds, evaluation periods, and other alarm settings. Args: ctx: The MCP context object for error handling and logging. namespace: The metric namespace (e.g., "AWS/EC2", "AWS/Lambda") metric_name: The name of the metric (e.g., "CPUUtilization", "Duration") dimensions: List of dimensions with name and value pairs region: AWS region to query. Defaults to AWS_REGION environment variable or us-east-1 if not set. profile_name: AWS CLI Profile Name to use for AWS access. Falls back to AWS_PROFILE environment variable if not specified, or uses default AWS credential chain. statistic: The statistic to use for alarm recommendations. Must match the metric's data type: - Aggregate count metrics (RequestCount, Errors, Faults, Throttles, CacheHits, Connections, EventsProcessed): Use 'Sum' - Event occurrence metrics (Invocations, CacheMisses): Use 'SampleCount' - Utilization metrics (CPUUtilization, MemoryUtilization, DiskUtilization, NetworkUtilization): Use 'Average' - Latency/Time metrics (Duration, Latency, ResponseTime, ProcessingTime, Delay, ExecutionTime, WaitTime): Use 'Average' - Size metrics (PayloadSize, MessageSize, RequestSize, BodySize): Use 'Average' If uncertain about the correct statistic for a custom metric, ask the user to confirm the metric type before generating recommendations. Using the wrong statistic (e.g., 'Average' on Invocations) will produce ineffective alarm thresholds Returns: AlarmRecommendationResult: A result containing alarm recommendations and optional message. Empty recommendations list if no recommendations are found. Example: recommendations = await get_recommended_metric_alarms( ctx, namespace="AWS/EC2", metric_name="StatusCheckFailed_Instance", dimensions=[ Dimension(name="InstanceId", value="i-1234567890abcdef0") ] ) for alarm in recommendations: print(f"Alarm: {alarm.alarmDescription}") print(f"Threshold: {alarm.threshold.staticValue}")

Gets all CloudWatch Alarms currently in ALARM state. This tool retrieves all CloudWatch Alarms that are currently in the ALARM state, including both metric alarms and composite alarms. Results are optimized for LLM reasoning with summary-level information. Usage: Use this tool to get an overview of all active alarms in your AWS account for troubleshooting, monitoring, and operational awareness. Args: ctx: The MCP context object for error handling and logging. max_items: Maximum number of alarms to return (default: 50). region: AWS region to query. Defaults to AWS_REGION environment variable or us-east-1 if not set. profile_name: AWS CLI Profile Name to use for AWS access. Falls back to AWS_PROFILE environment variable if not specified, or uses default AWS credential chain. Returns: ActiveAlarmsResponse: Response containing active alarms. Example: result = await get_active_alarms(ctx, max_items=25) if isinstance(result, ActiveAlarmsResponse): print(f"Found {len(result.metric_alarms + result.composite_alarms)} active alarms") for alarm in result.metric_alarms: print(f"Metric Alarm: {alarm.alarm_name}") for alarm in result.composite_alarms: print(f"Composite Alarm: {alarm.alarm_name}")

Gets the history for a CloudWatch alarm with time range suggestions for investigation. This tool retrieves the history for a specified CloudWatch alarm, focusing primarily on state transitions to ALARM state. It also provides suggested time ranges for investigation based on the alarm's configuration and history. Usage: Use this tool to understand when an alarm fired and get useful time ranges for investigating the underlying issue using other CloudWatch tools. The tool is particularly useful for identifying patterns like alarm flapping (going in and out of alarm state frequently). Args: ctx: The MCP context object for error handling and logging. region: AWS region to query. Defaults to AWS_REGION environment variable or us-east-1 if not set. alarm_name: Name of the alarm to retrieve history for. start_time: Optional start time for the history query. Defaults to 24 hours ago. end_time: Optional end time for the history query. Defaults to current time. history_item_type: Optional type of history items to retrieve. Defaults to 'StateUpdate'. max_items: Maximum number of history items to return. Defaults to 50. include_component_alarms: For composite alarms, whether to include details about component alarms. profile_name: AWS CLI Profile Name to use for AWS access. Falls back to AWS_PROFILE environment variable if not specified, or uses default AWS credential chain. Returns: Union[AlarmHistoryResponse, CompositeAlarmComponentResponse]: Either a response containing alarm history with time range suggestions, or component alarm details for composite alarms. Example: result = await get_alarm_history( ctx, alarm_name="my-cpu-alarm", start_time="2025-06-18T00:00:00Z", end_time="2025-06-19T00:00:00Z" ) if isinstance(result, AlarmHistoryResponse): print(f"Found {len(result.history_items)} history items") for suggestion in result.time_range_suggestions: print(f"Suggested investigation time range: {suggestion.start_time} to {suggestion.end_time}")

Returns the current onboarding status of the telemetry config feature. Use this tool to check whether telemetry evaluation is enabled for the account. The status indicates if the feature is running, stopped, starting, or has failed. Returns: TelemetryEvaluationStatusResponse: The current telemetry evaluation status.

Begins onboarding the caller's AWS account to the telemetry config feature. This enables CloudWatch to discover and audit telemetry configurations across resources in the account. This is a free feature with no additional charges. See https://docs.aws.amazon.com/cloudwatch/latest/monitoring/telemetry-config.html IMPORTANT: This is a mutating operation. Before calling this tool, confirm with the user that they want to enable telemetry evaluation for their account. For a single account, evaluation typically becomes available almost immediately. After starting, use get_telemetry_evaluation_status to check progress. Use stop_telemetry_evaluation to disable it later if needed. Returns: TelemetryEvaluationStatusResponse: The status after initiating evaluation.

Stops the telemetry config feature for the caller's AWS account. This disables CloudWatch telemetry configuration discovery and auditing. After stopping, use get_telemetry_evaluation_status to confirm the feature has been stopped. IMPORTANT: This is a mutating operation. Before calling this tool, confirm with the user that they want to disable telemetry evaluation for their account. Returns: TelemetryEvaluationStatusResponse: The status after stopping evaluation.

Returns the organization-level onboarding status of the telemetry config feature. Can only be called by the organization's management account or a delegated administrator account. Returns: TelemetryEvaluationStatusResponse: The current organization telemetry evaluation status.

Begins onboarding the organization and all member accounts to the telemetry config feature. Can only be called by the organization's management account or a delegated administrator account. This is a free feature with no additional charges. See https://docs.aws.amazon.com/cloudwatch/latest/monitoring/telemetry-config.html IMPORTANT: This is a mutating operation. Before calling this tool, confirm with the user that they want to enable telemetry evaluation for their organization. Onboarding time depends on organization size: a single account is nearly instant, while large organizations with thousands of accounts may take 20-30 minutes. After starting, use get_telemetry_evaluation_status_for_organization to check progress. Use stop_telemetry_evaluation_for_organization to disable it later if needed. Returns: TelemetryEvaluationStatusResponse: The status after initiating organization evaluation.

Stops the telemetry config feature for the organization and all member accounts. Can only be called by the organization's management account or a delegated administrator account. After stopping, use get_telemetry_evaluation_status_for_organization to confirm the feature has been stopped. IMPORTANT: This is a mutating operation. Before calling this tool, confirm with the user that they want to disable telemetry evaluation for their organization. Returns: TelemetryEvaluationStatusResponse: The status after stopping organization evaluation.

Returns telemetry configurations for AWS resources in the account. Lists the telemetry state (Logs, Metrics, Traces) for resources like EC2 instances, Lambda functions, EKS clusters, etc. Requires telemetry evaluation to be running (use start_telemetry_evaluation first if needed). For a single account, evaluation is typically available almost immediately after starting. Use get_telemetry_evaluation_status to verify the status is RUNNING before querying. Usage: Use this to audit which resources have telemetry enabled or disabled, identify observability gaps, and verify monitoring coverage. Returns: ListResourceTelemetryResponse: List of resource telemetry configurations.

Lists all telemetry rules in the account. Telemetry rules control what telemetry (Logs, Metrics, Traces) is collected for specific resource types. Use this to audit your telemetry collection configuration. Returns: ListTelemetryRulesResponse: List of telemetry rule summaries.

Retrieves the details of a specific telemetry rule in your account. Returns the full configuration of a telemetry rule including resource type, telemetry type, source types, destination configuration, and any resource-type-specific parameters (VPC Flow Logs, CloudTrail, ELB, WAF, etc.). Use list_telemetry_rules first to discover available rule names, then use this tool to get the full configuration details of a specific rule. Returns: GetTelemetryRuleResponse: The full telemetry rule details.

Returns telemetry configurations for AWS resources across the organization. Lists the telemetry state (Logs, Metrics, Traces) for resources across all accounts in the organization. Can only be called by the organization's management account or a delegated administrator account. Requires telemetry evaluation to be running. For large organizations with thousands of accounts, onboarding may take 20-30 minutes. Use get_telemetry_evaluation_status_for_organization to verify the status is RUNNING. Returns: ListResourceTelemetryResponse: List of resource telemetry configurations.

Lists all organization telemetry rules. Can only be called by the organization's management account or a delegated administrator account. Supports filtering by rule name prefix, source account IDs, and organizational unit IDs. Returns: ListTelemetryRulesResponse: List of organization telemetry rule summaries.

Retrieves the details of a specific organization telemetry rule. Can only be called by the organization's management account or a delegated administrator account. Returns the full configuration including resource type, telemetry type, source types, destination configuration, and resource-type-specific parameters. Returns: GetTelemetryRuleResponse: The full organization telemetry rule details.