View all connectors

Amazon Q

By integrating Amazon Q with DX, you can analyze Amazon Q daily usage metrics and AI assistant interactions. Please refer to the API documentation below and our schema explorer to see what data DX imports.

Prerequisites

To connect Amazon Q to DX, you need:

  • An AWS account with Amazon Q access
  • Access to AWS IAM to create a Policy and Role
  • An S3 bucket configured for Amazon Q data storage

Setup instructions

Amazon Q connections use IAM role-based authentication for secure cross-account access.

Step 1 - Get your External ID from DX

  1. In DX, navigate to Settings > Data connectors > Add connector > Amazon Q
  2. Copy the External ID displayed - you’ll need this for the trust policy

Step 2 - Create an IAM policy for S3 access

In your AWS account, create a custom IAM policy with S3 read permissions:

  1. Go to IAM > Policies > Create policy
  2. Select the JSON tab and paste the following (replace YOUR_BUCKET_NAME with your actual bucket name):
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "DXAmazonQReadOnly",
      "Effect": "Allow",
      "Action": ["s3:GetObject", "s3:ListBucket"],
      "Resource": [
        "arn:aws:s3:::YOUR_BUCKET_NAME",
        "arn:aws:s3:::YOUR_BUCKET_NAME/*"
      ]
    }
  ]
}
  1. Name the policy (e.g., DX-AmazonQ-Policy) and create it

Step 3 - Create an IAM role with trust policy

Create an IAM role that DX can assume:

  1. Go to IAM > Roles > Create role
  2. Select Custom trust policy and paste the following (replace YOUR_EXTERNAL_ID_FROM_DX with the External ID from Step 1):
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::703671904508:role/dx-datacloud"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "YOUR_EXTERNAL_ID_FROM_DX"
        }
      }
    }
  ]
}
  1. Click Next and attach the policy you created in Step 2
  2. Name the role (e.g., DX-AmazonQ-Role) and create it
  3. Copy the Role ARN (e.g., arn:aws:iam::123456789012:role/DX-AmazonQ-Role)

Step 4 - Configure the connection in DX

Navigate to the connections page in DX and select “+ Connection” in the top right. Enter the following in the connection form:

  • Role ARN: The ARN of the IAM role you created
  • Region: The AWS region where your S3 bucket is located
  • Bucket Name: The name of your S3 bucket containing Amazon Q data
  • Connection Name: A descriptive name for this connection (e.g., “Amazon Q Production”)
  • User mapping directory path: Path to the directory containing the user mapping files (e.g., if your file is at example/user_mapping.csv, enter example/)
  • Usage metrics directory path: Path to AWSLogs directory (e.g., if your directory is at example/AWSLogs/, enter example/)

Click “Add connection” to establish the connection.

User mapping CSV format

Your user mapping CSV must contain aws_user_uuid and user_email as headers.

How DX ingests usage data

To ensure accurate ingestion, provide the most specific S3 directory paths possible. DX scans recursively under the configured prefixes, so broad paths can unintentionally scan irrelevant files. Do not rename the exported files—DX relies on their original filename patterns to identify the correct reports.

User mapping

DX lists all objects under your configured user-mapping directory prefix (including nested subdirectories) and reads every .csv file it finds. Each file must contain both required columns:

  • aws_user_uuid
  • user_email

Usage metrics

DX lists all objects under your configured usage-metrics directory prefix (including nested subdirectories), then selects CSV files based on filename patterns. For Amazon Q, DX selects files whose name contains _by_user_analytic_ and ends with .csv.

A valid Amazon Q usage report has these columns (in addition to UserId and Date): Chat_AICodeLines, CodeFix_*, CodeReview_*, Dev_*, DocGeneration_*, InlineChat_*, Inline_*, TestGeneration_*, and Transformation_*.

Best practice

Configure narrow, tool-specific folder prefixes so only the intended files are scanned, and keep the original Amazon Q export filenames unchanged.

API reference

The table below lists the specific AWS services and permissions that are used by DX.

Service Documentation
sts:AssumeRole Link
s3:GetObject Link
s3:ListBucket Link

Errors

The table below lists potential error codes when adding a connection in DX.

Error Description
invalid_credentials Your IAM role configuration is not valid.
access_denied DX cannot assume the IAM role. Check the trust policy and external ID.
missing_role_arn IAM role ARN is required for Amazon Q connections.
invalid_role_arn The IAM role ARN format is invalid. Expected format: arn:aws:iam::{account-id}:role/{role-name}
bucket_not_found The specified S3 bucket does not exist or is not accessible.
no_users_found No users found in the user mapping CSV (provide a valid user mapping CSV with aws_user_uuid and user_email columns).
no_metrics_found No usage metrics found in the provided directory.
invalid_permissions Your IAM role does not have the required permissions to access S3.