See a sample investigation Set up operational investigations

Getting started

Note

The Amazon Q Developer operational investigations feature is in preview release and is subject to change. It is currently available only in the US East (N. Virginia) and US West (Oregon) Regions.

To set up Amazon Q Developer operational investigations, you create an investigation group. You can also see a sample investigation to get an overall idea of how they work.

See a sample investigation

Note

The Amazon Q Developer operational investigations feature is in preview release and is subject to change. It is currently available only in the US East (N. Virginia) and US West (Oregon) Regions.

If you'd like to see the Amazon Q Developer operational investigations feature in action before you configure it for your account, you can walk through a sample investigation. The sample investigation doesn't use your data and doesn't make data calls or start API operations in your account.

To view the sample investigation

Open the CloudWatch console at https://console.aws.amazon.com/cloudwatch/.
In the left navigation pane, choose AI Operations, Overview.
Choose Try a sample investigation.

The console displays the sample investigation, with suggestions and findings in the right pane. In each popup, choose Next to advance to the next part of the sample walkthrough.

Set up operational investigations

Note

The Amazon Q Developer operational investigations feature is in preview release and is subject to change. It is currently available only in the US East (N. Virginia) and US West (Oregon) Regions.

To set up Amazon Q Developer operational investigations in your account, you create an investigation group. Creating an investigation group is a one-time setup task. Settings in the investigation group help you centrally manage the common properties of your investigations, such as the following:

Who can access the investigations
Whether investigation data is encrypted with a customer managed AWS Key Management Service key.
How long investigations and their data are retained by default.

Currently, you can have one investigation group per account. Each investigation in your account will be part of this investigation group.

To create an investigation group and set up Amazon Q Developer operational investigations, you must be signed in to an IAM principal that has the either the AIOpsConsoleAdminPolicy or the AdministratorAccess IAM policy attached, or to an account that has similar permissions.

Note

To be able to choose the recommended option of creating a new IAM role for Amazon Q Developer operational investigations, you must be signed in to an IAM principal that has the iam:CreateRole, iam:AttachRolePolicy, and iam:PutRolePolicy permissions.

Important

Amazon Q Developer operational investigations uses cross region inference to distribute traffic across different AWS Regions in the United States. For more information see Cross region inference in Amazon Q Developer in the Amazon Q Developer user guide.

To create an investigation group and enable Amazon Q Developer operational investigations in your account

Open the CloudWatch console at https://console.aws.amazon.com/cloudwatch/.
In the left navigation pane, choose AI Operations, Investigations.
Choose Configure for this account.
Enter a name for the investigation group.
Optionally change the retention period for investigations. For more information about what the retention period governs, see Operational investigation data retention.
(Optional) To encrypt your investigation data with a customer managed AWS KMS key, choose Customize encryption settings and follow the steps to create or specify a key to use. For more information, see Encryption of investigation data.
If you haven't already done so, use the IAM console to provision access for your users to be able to see and manage investigations. We provide IAM roles for administrators, operators, and viewers. For more information, see User permissions.
(Optional) You can have investigations attribute investigation actions such as adding a suggestion to the Feed to individual users. You do this by integrating Amazon Q Developer operational investigations with IAM Identity Center. To do so, validate that you meet the pre-requisites and then choose to allow the creation of a managed IAM Identity Center application for Amazon Q Developer operational investigations. For more information about the pre-requisites, see AWS IAM Identity Center.
For Amazon Q Developer permissions, choose one of the following. For more information about these options, see How to control what data Amazon Q Developer has access to during investigations.

To be able to choose either of the first two options, you must be signed in to an IAM principal that has the iam:CreateRole, iam:AttachRolePolicy, and iam:PutRolePolicy permissions.
- The recommended option is to choose Auto-create a new role with default investigation permissions. If you choose this option, the assistant is granted the AIOpsAssistantPolicy IAM policy. For more information about the contents of this policy, see IAM policy for Amazon Q Developer operational investigations (AIOpsAssistantPolicy).
- Choose Create a new role from AWS policy templates to customize the permissions that Amazon Q Developer will have during investigations. If you choose this option, you must be sure to scope down the policy to only the permissions that you want Amazon Q Developer to have during investigations.
- Choose Assign an existing role if you already have a role with the permissions that you want to use.
  
  If you choose this option, you must make sure the role includes a trust policy that names aiops.amazonaws.com as the service principal. For more information about using service principals in trust policies, see AWS service principals
  
  We also recommend that you include a Condition section with the account number, to prevent a confused deputy situation. The following example trust policy illustrates both the service principal and the Condition section.
```
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Service": "aiops.amazonaws.com"
            },
            "Action": "sts:AssumeRole",
            "Condition": {
                "StringEquals": {
                    "aws:SourceAccount": "123456789012"
                },
                "ArnLike": {
                    "aws:SourceArn": "arn:aws:aiops:us-east-1:123456789012:*"
                }
            }
        }
    ]
}
```
(Optional) For Enhanced integrations, choose to allow Amazon Q Developer access to additional services in your system, to enable it to gather more data and be more useful.
1. In the Tags for application boundary detection section, enter the existing custom tag keys for custom applications in your system. Resource tags help Amazon Q Developer narrow the search space when it is unable to discover definite relationships between resources. For example, to discover that an Amazon ECS service depends on an Amazon RDS database, Amazon Q Developer can discover this relationship using data sources such as X-Ray and CloudWatch Application Signals. However, if you haven't deployed these features, Amazon Q Developer will attempt to identify possible relationships. Tag boundaries can be used to narrow the resources that will be discovered by Amazon Q Developer in these cases.
  
  You don't need to enter tags created by myApplications or AWS CloudFormation, because Amazon Q Developer can automatically detect those tags.
2. CloudTrail records events about changes in your system including deployment events. These events can often be useful to Amazon Q Developer to create hypotheses about root causes of issues in your system. In the CloudTrail for change event detection section, you can do one or both of the following.
  - Give Amazon Q Developer some access to the events logged by AWS CloudTrail by enabling Allow the assistant access to CloudTrail change events through the CloudTrail Event history. For more information, see Working with CloudTrail Event history.
  - Give Amazon Q Developer access to additional CloudTrail data by entering one or more CloudTrail trails, which are records of activities within your AWS account. This is supported only for trails that are sent to log groups in CloudWatch Logs. For more information about trails see Working with CloudTrail trails.
3. The X-Ray for topology mapping and Application Signals for health assessment sections point out other AWS services that can help Amazon Q Developer find information. If you have deployed them and you have granted the AIOpsAssistantPolicy IAM policy to Amazon Q Developer, it will be able to access X-Ray and Application Signals telemetry.
  
  For more information about how these services help Amazon Q Developer, see X-Ray and CloudWatch Application Signals
(Optional) You can integrate Amazon Q Developer operational investigations with a third-party ticketing system. Integrating with a ticketing tool enables Amazon Q Developer to send information about an investigation to that ticketing tool.

Important
When you create an integration with a third-party ticketing system, the system creates a secret in AWS Secrets Manager. This secret contains your basic authentication credentials for the third-party tool and is used to connect your AWS account to that tool. If you delete the integration, the secret that contains your authentication credentials is also deleted.

To integrate Amazon Q Developer operational investigations with a third-party ticketing tool, do the following in the Third-party integrations area:
1. Choose Add integration.
2. In the Add integration dialog box, do the following:
  1. For Name, enter a name to identify this integration in your investigations.
  2. For Instance type, choose from the available third-party tools, such as Jira or ServiceNow.
    
    Note
    Integration with Jira is supported only for Jira Cloud.
  3. Provide the additional information required to integrate with your selected tool:
    Jira
    
    Username – A valid email address with access to the project being onboarded.
    
    Password – Your API token value from Atlassian. For more information, see Manage API tokens for your Atlassian account on the Atlassian website.
    
    Jira site name – The application name for your Jira project. This is typically the first component of the URL for your project in Atlassian. For example, in the URL https://AnyCompany.atlassian.net, the application name is AnyCompany. If you are uncertain, contact your Jira project manager to verify this information.
    
    Project key – The project key for your Jira project.
    
    To retrieve this project key, sign in to your Jira project, choose Administration, Project, View all projects, and then copy the Key value from the appropriate project.
    
    Important
    Ensure that your Jira account and email address both have access to the project. If you are uncertain, contact your Jira project manager to verify this information.
    
    ServiceNow
    
    Username – Your ServiceNow username.
    
    Password – Your ServiceNow instance password.
    
    Instance ID – Your ServiceNow instance ID.
    
    You can view this information by signing in to your ServiceNow account. If you are uncertain, contact your ServiceNow administrator to verify this information.
3. Choose Connect.
Important
After you have completed this configuration procedure, we recommend that you create a test investigation and try out the integration before using it in an active investigation.
(Optional) You can integrate Amazon Q Developer operational investigations with a chat channel using Amazon Q Developer in chat applications. This makes it possible to receive notifications about an investigation through the chat channel. Amazon Q Developer operational investigations and Amazon Q Developer in chat applications support chat channels in the following applications:
- Slack
- Microsoft Teams
If you want to integrate with a chat channel, we recommend that you complete some other steps before performing this step in the create an investigation group process. For more information, see Integration with third-party chat systems.

To then perform the steps here to integrate with a chat channel in Amazon Q Developer in chat applications, do the following:
1. In the Chat client integration section, choose Select SNS topic.
2. Select the SNS topic to use for sending notifications about your investigations.
Choose Complete setup.

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

AWS services where investigations are supported

Investigate operational issues in your environment