awslabs.cloudwatch-appsignals-mcp-server 0.1.1__py3-none-any.whl → 0.1.2__py3-none-any.whl

awslabs/cloudwatch_appsignals_mcp_server/sli_report_client.py

@@ -0,0 +1,340 @@
+# 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.
+
+"""Retrieve service SLI status based on configured Application Signals SLOs."""
+
+import boto3
+import logging
+from botocore.exceptions import ClientError
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta, timezone
+from typing import Any, Dict, List, Optional
+
+
+# Initialize module logger
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class AWSConfig:
+    """Configuration class for AWS settings and service parameters.
+
+    Attributes:
+        region (str): AWS region identifier (default: us-west-1)
+        period_in_hours (int): Time period for metrics collection (max 24 hours)
+        service_name (str): Name of the AWS service to monitor
+        key_attributes (Dict[str, str]): Key attributes to identify the service
+    """
+
+    region: str
+    period_in_hours: int
+    service_name: str
+    key_attributes: Dict[str, str] = field(default_factory=dict)
+
+    def __init__(
+        self,
+        region: str = 'us-east-1',
+        period_in_hours: int = 24,
+        service_name: str = 'UnknownService',
+        key_attributes: Optional[Dict[str, str]] = None,
+    ):
+        """Initialize AWSConfig with region, period, and service name.
+
+        Args:
+            region: AWS region identifier (default: us-east-1)
+            period_in_hours: Time period for metrics collection, max 24 hours (default: 24)
+            service_name: Name of the AWS service to monitor (default: UnknownService)
+            key_attributes: Optional key attributes to override defaults
+        """
+        self.region = region
+        self.period_in_hours = min(period_in_hours, 24)  # Ensure period doesn't exceed 24 hours
+        self.service_name = service_name
+        if key_attributes is not None:
+            self.key_attributes = key_attributes
+        else:
+            self.key_attributes = {
+                'Name': self.service_name,
+                'Type': 'Service',
+                'Environment': self.region,
+            }
+
+
+@dataclass
+class SLOSummary:
+    """Data class representing a Service Level Objective summary.
+
+    Attributes:
+        name (str): Name of the SLO
+        arn (str): Amazon Resource Name
+        key_attributes (Dict): Service identification attributes
+        operation_name (str): Name of the monitored operation
+        created_time (datetime): When the SLO was created
+    """
+
+    name: str
+    arn: str
+    key_attributes: Dict[str, str]
+    operation_name: str
+    created_time: datetime
+
+
+@dataclass
+class MetricDataResult:
+    """Data class holding CloudWatch metric data results.
+
+    Attributes:
+        timestamps (List[datetime]): Timestamps of metric data points
+        values (List[float]): Corresponding metric values
+    """
+
+    timestamps: List[datetime]
+    values: List[float]
+
+
+class SLIReport:
+    """Class representing an SLI report with various metrics and status information.
+
+    Provides read-only access to report data including start/end times,
+    SLI status, and counts of total, successful, and breached SLOs.
+    """
+
+    def __init__(
+        self,
+        start_time: datetime,
+        end_time: datetime,
+        sli_status: str,
+        total_slo_count: int,
+        ok_slo_count: int,
+        breached_slo_count: int,
+        breached_slo_names: List[str],
+    ):
+        """Initialize SLIReport with metrics and status information.
+
+        Args:
+            start_time: Start time of the reporting period
+            end_time: End time of the reporting period
+            sli_status: Overall SLI status (OK/CRITICAL)
+            total_slo_count: Total number of SLOs monitored
+            ok_slo_count: Number of SLOs meeting their objectives
+            breached_slo_count: Number of SLOs failing to meet their objectives
+            breached_slo_names: Names of SLOs that failed to meet their objectives
+        """
+        self._start_time = start_time
+        self._end_time = end_time
+        self._sli_status = sli_status
+        self._total_slo_count = total_slo_count
+        self._ok_slo_count = ok_slo_count
+        self._breached_slo_count = breached_slo_count
+        self._breached_slo_names = breached_slo_names
+
+    # Property getters for all attributes
+    @property
+    def start_time(self) -> datetime:
+        """Start time of the reporting period."""
+        return self._start_time
+
+    @property
+    def end_time(self) -> datetime:
+        """End time of the reporting period."""
+        return self._end_time
+
+    @property
+    def sli_status(self) -> str:
+        """Overall SLI status (OK/CRITICAL)."""
+        return self._sli_status
+
+    @property
+    def total_slo_count(self) -> int:
+        """Total number of SLOs monitored."""
+        return self._total_slo_count
+
+    @property
+    def ok_slo_count(self) -> int:
+        """Number of SLOs meeting their objectives."""
+        return self._ok_slo_count
+
+    @property
+    def breached_slo_count(self) -> int:
+        """Number of SLOs failing to meet their objectives."""
+        return self._breached_slo_count
+
+    @property
+    def breached_slo_names(self) -> List[str]:
+        """Names of SLOs that failed to meet their objectives."""
+        return self._breached_slo_names.copy()
+
+
+class SLIReportClient:
+    """Client for generating SLI reports using AWS Application Signals and CloudWatch.
+
+    Handles interaction with AWS services to collect and analyze SLO data.
+    """
+
+    def __init__(self, config: AWSConfig):
+        """Initialize SLIReportClient with AWS configuration.
+
+        Args:
+            config: AWSConfig instance containing region, period, and service settings
+
+        Raises:
+            Exception: If AWS clients fail to initialize
+        """
+        self.config = config
+        logger.info(
+            f'Initializing SLIReportClient for service: {config.service_name}, region: {config.region}'
+        )
+
+        try:
+            # Initialize AWS service clients
+            self.signals_client = boto3.client('application-signals', region_name=config.region)
+            self.cloudwatch_client = boto3.client('cloudwatch', region_name=config.region)
+            logger.debug('AWS clients initialized successfully')
+        except Exception as e:
+            logger.error(f'Failed to initialize AWS clients: {str(e)}', exc_info=True)
+            raise
+
+    def get_slo_summaries(self) -> List[SLOSummary]:
+        """Fetches SLO summaries from AWS Application Signals."""
+        logger.debug(f'Fetching SLO summaries for {self.config.service_name}')
+
+        try:
+            response = self.signals_client.list_service_level_objectives(
+                KeyAttributes=self.config.key_attributes,
+                MetricSourceTypes=['ServiceOperation'],
+                IncludeLinkedAccounts=True,
+            )
+            logger.info(f'Retrieved {len(response.get("SloSummaries", []))} SLO summaries')
+        except ClientError as e:
+            error_msg = e.response.get('Error', {}).get('Message', 'Unknown error')
+            error_code = e.response.get('Error', {}).get('Code', 'Unknown')
+            logger.error(f'AWS ClientError getting SLO summaries: {error_code} - {error_msg}')
+            raise
+        except Exception as e:
+            logger.error(f'Unexpected error getting SLO summaries: {str(e)}', exc_info=True)
+            raise
+
+        return [
+            SLOSummary(
+                name=slo['Name'],
+                arn=slo['Arn'],
+                key_attributes=slo.get('KeyAttributes', {}),
+                operation_name=slo.get('OperationName', 'N/A'),
+                created_time=slo.get('CreatedTime', datetime.now(timezone.utc)),
+            )
+            for slo in response['SloSummaries']
+        ]
+
+    def create_metric_queries(self, slo_summaries: List[SLOSummary]) -> List[Dict[str, Any]]:
+        """Creates CloudWatch metric queries for each SLO."""
+        return [
+            {
+                'Id': f'slo{i}',
+                'MetricStat': {
+                    'Metric': {
+                        'Namespace': 'AWS/ApplicationSignals',
+                        'MetricName': 'BreachedCount',
+                        'Dimensions': [{'Name': 'SloName', 'Value': slo.name}],
+                    },
+                    'Period': self.config.period_in_hours * 60 * 60,
+                    'Stat': 'Maximum',
+                },
+                'ReturnData': True,
+            }
+            for i, slo in enumerate(slo_summaries)
+        ]
+
+    def get_metric_data(
+        self, queries: List[Dict[str, Any]], start_time: datetime, end_time: datetime
+    ) -> List[MetricDataResult]:
+        """Retrieves metric data from CloudWatch using the specified queries."""
+        logger.debug(f'Fetching metric data with {len(queries)} queries')
+
+        try:
+            response = self.cloudwatch_client.get_metric_data(
+                MetricDataQueries=queries,  # type: ignore
+                StartTime=start_time,
+                EndTime=end_time,
+            )
+            logger.debug(f'Retrieved {len(response.get("MetricDataResults", []))} metric results')
+        except ClientError as e:
+            error_msg = e.response.get('Error', {}).get('Message', 'Unknown error')
+            error_code = e.response.get('Error', {}).get('Code', 'Unknown')
+            logger.error(f'AWS ClientError getting metric data: {error_code} - {error_msg}')
+            raise
+        except Exception as e:
+            logger.error(f'Unexpected error getting metric data: {str(e)}', exc_info=True)
+            raise
+
+        return [
+            MetricDataResult(
+                timestamps=result.get('Timestamps', []), values=result.get('Values', [])
+            )
+            for result in response['MetricDataResults']
+        ]
+
+    def get_sli_status(self, num_breaching: int) -> str:
+        """Determines overall SLI status based on number of breaching SLOs."""
+        return 'CRITICAL' if num_breaching > 0 else 'OK'
+
+    def generate_sli_report(self) -> SLIReport:
+        """Generates a comprehensive SLI report.
+
+        Collects SLO data, analyzes metrics, and produces a report containing
+        the overall status and details about breaching/healthy SLOs.
+        """
+        logger.info(f'Generating SLI report for {self.config.service_name}')
+        end_time = datetime.now()
+        start_time = end_time - timedelta(hours=self.config.period_in_hours)
+        logger.debug(f'Report time range: {start_time} to {end_time}')
+
+        slo_summaries = self.get_slo_summaries()
+
+        # If no SLOs found, return empty report
+        if not slo_summaries:
+            logger.warning(f'No SLOs found for service {self.config.service_name}')
+            return SLIReport(
+                start_time=start_time,
+                end_time=end_time,
+                sli_status='OK',  # No SLOs means nothing can be breached
+                total_slo_count=0,
+                ok_slo_count=0,
+                breached_slo_count=0,
+                breached_slo_names=[],
+            )
+
+        metric_queries = self.create_metric_queries(slo_summaries)
+        metric_results = self.get_metric_data(metric_queries, start_time, end_time)
+
+        healthy_slos = []
+        breaching_slos = []
+
+        for i, result in enumerate(metric_results):
+            # Check if we have any values and if the SLO is breached
+            if result.values and len(result.values) > 0 and result.values[0] > 0:
+                breaching_slos.append(slo_summaries[i].name)
+            else:
+                healthy_slos.append(slo_summaries[i].name)
+
+        logger.debug(
+            f'SLI report generated - Total SLOs: {len(slo_summaries)}, Breaching: {len(breaching_slos)}, Healthy: {len(healthy_slos)}'
+        )
+        return SLIReport(
+            start_time=start_time,
+            end_time=end_time,
+            sli_status=self.get_sli_status(len(breaching_slos)),
+            total_slo_count=len(slo_summaries),
+            ok_slo_count=len(healthy_slos),
+            breached_slo_count=len(breaching_slos),
+            breached_slo_names=breaching_slos,
+        )

{awslabs_cloudwatch_appsignals_mcp_server-0.1.1.dist-info → awslabs_cloudwatch_appsignals_mcp_server-0.1.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: awslabs.cloudwatch-appsignals-mcp-server
-Version: 0.1.1
+Version: 0.1.2
 Summary: An AWS Labs Model Context Protocol (MCP) server for AWS Application Signals
 Project-URL: Homepage, https://awslabs.github.io/mcp/
 Project-URL: Documentation, https://awslabs.github.io/mcp/servers/cloudwatch-appsignals-mcp-server/
@@ -34,41 +34,88 @@ An MCP (Model Context Protocol) server that provides tools for monitoring and an
 
 This server enables AI assistants like Claude, GitHub Copilot, and Amazon Q to help you monitor service health, analyze performance metrics, track SLO compliance, and investigate issues using distributed tracing.
 
-## Features
+## Key Features
+
+1. Monitor overall service health, diagnose root causes, and recommend actionable fixes with the built-in APM expertise.
+2. Generate business insights from telemetry data through natural language queries.
+
+## Prerequisites
+
+1. [Sign-Up for an AWS account](https://aws.amazon.com/free/?trk=78b916d7-7c94-4cab-98d9-0ce5e648dd5f&sc_channel=ps&ef_id=Cj0KCQjwxJvBBhDuARIsAGUgNfjOZq8r2bH2OfcYfYTht5v5I1Bn0lBKiI2Ii71A8Gk39ZU5cwMLPkcaAo_CEALw_wcB:G:s&s_kwcid=AL!4422!3!432339156162!e!!g!!aws%20sign%20up!9572385111!102212379327&gad_campaignid=9572385111&gbraid=0AAAAADjHtp99c5A9DUyUaUQVhVEoi8of3&gclid=Cj0KCQjwxJvBBhDuARIsAGUgNfjOZq8r2bH2OfcYfYTht5v5I1Bn0lBKiI2Ii71A8Gk39ZU5cwMLPkcaAo_CEALw_wcB)
+2. [Enable Application Signals](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Monitoring-Sections.html) for your applications
+3. Install `uv` from [Astral](https://docs.astral.sh/uv/getting-started/installation/) or the [GitHub README](https://github.com/astral-sh/uv#installation)
+4. Install Python using `uv python install 3.10`
 
 ### Available Tools
 
 1. **`list_monitored_services`** - List all services monitored by AWS Application Signals
    - Get an overview of all monitored services
    - See service names, types, and key attributes
-   - Identify which services are being tracked
+   - Identify the services monitored by Application Signals
 
 2. **`get_service_detail`** - Get detailed information about a specific service
-   - Understand service configuration and deployment
-   - View available CloudWatch metrics
+   - Get Service key properties such as Hosting environment, list of APIs,etc
+   - Get the list of ApplicationSignals metrics available on service
    - Find associated log groups
 
-## Installation
+3. **`list_slis`** - List all SLOs and SLIs status for all services
+   - List the configured SLOs and across all services
+   - Find out all breached SLIs and status
 
-### Installing via Smithery
+4. **`get_slo`** - Gets the details configuration for a specific SLO
+   - Return the relevant metrics info, SLO threshold
 
-To install CloudWatch Application Signals MCP Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/awslabs.cloudwatch-appsignals-mcp-server):
+5. **`search_transaction_spans`** - Queries OTel Spans data via Transaction Search
+   - Query OTel Spans to root cause the potential problems
+   - Generate business performance insights summaries
 
-```bash
-npx @smithery/cli install awslabs.cloudwatch-appsignals-mcp-server --client claude
-```
+6. **`query_sampled_traces`** - Queries AWS X-Ray traces to gain deeper insights
+   - Find the impact from the tracing dependency view
+   - Return the exact error stack for LLM to suggest the actionable fixes
+
+7. **`query_service_metrics`** - Queries Application Signals metrics for root causing service performance issues
+   - Query Application Signals RED metrics to correlate the relevant OTel Spans/Traces for troubleshooting
+
+## Installation
 
 ### Installing via Cursor
 
 To install CloudWatch Application Signals MCP Server for Cursor automatically:
 
-[![Install in Cursor](https://img.shields.io/badge/Install%20in%20Cursor-Install-blue?style=for-the-badge&logo=cursor&logoColor=white)](https://cursor.com/settings/extensions/install?server=awslabs.cloudwatch-appsignals-mcp-server)
+[![Install MCP Server](https://cursor.com/deeplink/mcp-install-light.svg)](https://cursor.com/install-mcp?name=awslabs.cloudwatch-appsignals-mcp-server&config=eyJhdXRvQXBwcm92ZSI6W10sImRpc2FibGVkIjpmYWxzZSwidGltZW91dCI6NjAsImNvbW1hbmQiOiJ1dnggYXdzbGFicy5jbG91ZHdhdGNoLWFwcHNpZ25hbHMtbWNwLXNlcnZlckBsYXRlc3QiLCJlbnYiOnsiQVdTX1BST0ZJTEUiOiJbVGhlIEFXUyBQcm9maWxlIE5hbWUgdG8gdXNlIGZvciBBV1MgYWNjZXNzXSIsIkFXU19SRUdJT04iOiJbVGhlIEFXUyByZWdpb24gdG8gcnVuIGluXSIsIkZBU1RNQ1BfTE9HX0xFVkVMIjoiRVJST1IifSwidHJhbnNwb3J0VHlwZSI6InN0ZGlvIn0%3D)
 
 ### Installing via `uv`
 
 When using [`uv`](https://docs.astral.sh/uv/) no specific installation is needed. We will
 use [`uvx`](https://docs.astral.sh/uv/guides/tools/) to directly run *awslabs.cloudwatch-appsignals-mcp-server*.
 
+### Installing for Amazon Q (Preview)
+
+- Start Amazon Q Developer CLI from [here](https://github.com/aws/amazon-q-developer-cli).
+- Add the following configuration in `~/.aws/amazonq/mcp.json` file.
+```json
+{
+  "mcpServers": {
+    "awslabs.cloudwatch-appsignals-mcp-server": {
+      "autoApprove": [],
+      "disabled": false,
+      "timeout": 60,
+      "command": "uvx",
+      "args": [
+        "awslabs.cloudwatch-appsignals-mcp-server@latest"
+      ],
+      "env": {
+        "AWS_ACCESS_KEY_ID": "[AWS Access Key ID]",
+        "AWS_SECRET_ACCESS_KEY": "[AWS Access Key]",
+        "AWS_REGION": "[AWS Region]",
+        "FASTMCP_LOG_LEVEL": "ERROR"
+      },
+      "transportType": "stdio"
+    }
+  }
+}
+```
+
 ### Installing via Claude Desktop
 
 On MacOS: `~/Library/Application\ Support/Claude/claude_desktop_config.json`
@@ -98,19 +145,38 @@ On Windows: `%APPDATA%/Claude/claude_desktop_config.json`
     "mcpServers": {
       "awslabs.cloudwatch-appsignals-mcp-server": {
         "command": "uvx",
-        "args": ["awslabs.cloudwatch-appsignals-mcp-server"]
+        "args": ["awslabs.cloudwatch-appsignals-mcp-server@latest"]
       }
     }
   }
   ```
 </details>
 
-### Installing for Amazon Q (Preview)
+### Build and install docker image locally on the same host of your LLM client
+
+1. `git clone https://github.com/awslabs/mcp.git`
+2. Go to sub-directory 'src/cloudwatch-appsignals-mcp-server/'
+3. Run 'docker build -t awslabs/cloudwatch-appsignals-mcp-server:latest .'
 
-- Start Q Developer from [here](https://q.aws/chat).
-- Click on "Manage Connectors" and choose MCP Client.
-- Click "Add New Context Connector," enter a name like "CloudWatch AppSignals," and enter the command in the format: `uvx awslabs.cloudwatch-appsignals-mcp-server`.
-- Verify it shows "Connected" in green under the connector.
+### Add or update your LLM client's config with following:
+```json
+{
+  "mcpServers": {
+    "awslabs.cloudwatch-appsignals-mcp-server": {
+      "command": "docker",
+      "args": [
+        "run",
+        "-i",
+        "--rm",
+        "-e", "AWS_ACCESS_KEY_ID=[your data]",
+        "-e", "AWS_SECRET_ACCESS_KEY=[your data]",
+        "-e", "AWS_REGION=[your data]",
+        "awslabs/cloudwatch-appsignals-mcp-server:latest"
+      ]
+    }
+  }
+}
+```
 
 ### Debugging
 

awslabs_cloudwatch_appsignals_mcp_server-0.1.2.dist-info/RECORD

@@ -0,0 +1,10 @@
+awslabs/__init__.py,sha256=WuqxdDgUZylWNmVoPKiK7qGsTB_G4UmuXIrJ-VBwDew,731
+awslabs/cloudwatch_appsignals_mcp_server/__init__.py,sha256=UDBzXsnaAPF0tJrYn7iFk3Kxcnpri-58PAoEZYjrNNE,681
+awslabs/cloudwatch_appsignals_mcp_server/server.py,sha256=yVmgTqYHAIJCzWxopj3o15P8ntrgjmRN5rGzWTKgYF8,58146
+awslabs/cloudwatch_appsignals_mcp_server/sli_report_client.py,sha256=t9ZtbD-yBv-HxGI0Bc_d9b4XtTDNEE59ekCMSh6j_Mo,12641
+awslabs_cloudwatch_appsignals_mcp_server-0.1.2.dist-info/METADATA,sha256=U37D6kDzm7yxIeMrs0ZCzF_q04EYRFYq2TITJ4SibEY,11177
+awslabs_cloudwatch_appsignals_mcp_server-0.1.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+awslabs_cloudwatch_appsignals_mcp_server-0.1.2.dist-info/entry_points.txt,sha256=iGwIMLU6AsBawl2Fhqi9GoeWdMGIVtg86-McaaNQqAQ,114
+awslabs_cloudwatch_appsignals_mcp_server-0.1.2.dist-info/licenses/LICENSE,sha256=zE1N4JILDTkSIDtdmqdnKKxKEQh_VdqeoAV2230eNOI,10141
+awslabs_cloudwatch_appsignals_mcp_server-0.1.2.dist-info/licenses/NOTICE,sha256=Pfbul2Ga0IJU2RMZFHC8QwDvNk72WO2XMn9l3390VYs,108
+awslabs_cloudwatch_appsignals_mcp_server-0.1.2.dist-info/RECORD,,

awslabs_cloudwatch_appsignals_mcp_server-0.1.1.dist-info/RECORD

@@ -1,9 +0,0 @@
-awslabs/__init__.py,sha256=WuqxdDgUZylWNmVoPKiK7qGsTB_G4UmuXIrJ-VBwDew,731
-awslabs/cloudwatch_appsignals_mcp_server/__init__.py,sha256=UDBzXsnaAPF0tJrYn7iFk3Kxcnpri-58PAoEZYjrNNE,681
-awslabs/cloudwatch_appsignals_mcp_server/server.py,sha256=QsNhMYIEnSuP1rW6Czhx6GHwVRc6w-QIoBNHUggpBIc,10383
-awslabs_cloudwatch_appsignals_mcp_server-0.1.1.dist-info/METADATA,sha256=Aom2dgzauVXBfLxlBDhATy8FF3J--i-l1c9saNdew3I,8069
-awslabs_cloudwatch_appsignals_mcp_server-0.1.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-awslabs_cloudwatch_appsignals_mcp_server-0.1.1.dist-info/entry_points.txt,sha256=iGwIMLU6AsBawl2Fhqi9GoeWdMGIVtg86-McaaNQqAQ,114
-awslabs_cloudwatch_appsignals_mcp_server-0.1.1.dist-info/licenses/LICENSE,sha256=zE1N4JILDTkSIDtdmqdnKKxKEQh_VdqeoAV2230eNOI,10141
-awslabs_cloudwatch_appsignals_mcp_server-0.1.1.dist-info/licenses/NOTICE,sha256=Pfbul2Ga0IJU2RMZFHC8QwDvNk72WO2XMn9l3390VYs,108
-awslabs_cloudwatch_appsignals_mcp_server-0.1.1.dist-info/RECORD,,