Monitor Amazon Q in Connect by using CloudWatch Logs

To gain visibility into the real-time recommendations that Amazon Q in Connect provides to your agents, and the customer intents it detects through natural language understanding, you can query CloudWatch Logs. CloudWatch Logs give you visibility into the entire contact journey: the conversation, triggers, intents, recommendations. You can also use this information for debugging, or provide it to Support when you contact them for help.

This topic explains how to enable logging for Amazon Q in Connect.

Required IAM permissions

Before you enable logging for an Amazon Q in Connect assistant, check that you have the following AWS Identity and Access Management permissions. They are required for the user account that is signed into the Amazon Connect console:

• wisdom:AllowVendedLogDeliveryForResource: Required to allow logs to be delivered for the assistant resource.

To view an example IAM role with all the required permissions for your specific logging destination, see Logging that requires additional permissions [V2]. That topic contains examples for different logging destinations, such as logs sent to CloudWatch Logs and logs sent to Amazon S3 The examples show how to allow updates to your specific logging destination resource.

Enable logging for Amazon Q in Connect

To enable logging for Amazon Q in Connect, you use the CloudWatch API. Complete the following steps.

1. Get the ARN of your Amazon Q in Connect assistant (also known as its domain). After you create an assistant, you can obtain it's ARN from the Amazon Connect console or by calling the GetAssistant API. The ARN follows this format:

   arn:aws:wisdom:your-region:your-account-id:assistant/assistant-id

2. Call PutDeliverySource: Use this CloudWatch API to create a delivery source for the assistant. Pass the ARN of the assistant as the resourceArn. For logType, specify EVENT_LOGS to collect logs from your assistant.

   {
       "logType": "EVENT_LOGS",
       "name": "your-assistant-delivery-source",
       "resourceArn": "arn:aws:wisdom:your-region:your-account-id:assistant/assistant_id
   }

3. Call PutDeliveryDestination: Use this CloudWatch API to configure where the logs are to be stored. You can choose CloudWatch Logs, Amazon S3, or Amazon Data Firehose as the destination for storing logs. You must specify the ARN of one of the destination options for where your logs are to be stored. You can choose the outputFormat of the logs to be one of the following: json, plain, w3c, raw, parquet.

   The following example shows how to configure logs to be stored in an Amazon CloudWatch Logs Group and in JSON format.

   {
       "deliveryDestinationConfiguration": {
           "destinationResourceArn": "arn:aws:logs:your-region:your-account-id:log-group:your-log-group-name:*"
       },
       "name": "string",
       "outputFormat": "json",
       "tags": {
           "key": "value"
       }
   }

4. Call CreateDelivery: Use this CloudWatch API to link the delivery source to the delivery destination that you created in the previous steps. This API operation associates the delivery source with the end destination.

   {
       "deliveryDestinationArn": "string",
       "deliverySourceName": "string",
       "tags": {
           "string": "string"
       }
   }

Supported log types

Amazon Q in Connect supports the following log type:

• EVENT_LOGS: Logs that track event of an Amazon Q in Connect assistant during calls and chats.

Check for CloudWatch Logs quotas

We recommend checking Amazon CloudWatch Logs endpoints and quotas to see whether there are any quotas for making CloudWatch Logs delivery-related API calls. Quotas set a maximum number of times you can call an API or create a resource. Exceeding the limit results in a ServiceQuotaExceededException error.

Examples of assistant logs

Following is an example of an event log. There may be more fields visible depending on the event type.

{
    "assistant_id": "AssistantId",
    "event_timestamp": 1729530173612,
    "event_type": "TRANSCRIPT_CREATE_SESSION" | "TRANSCRIPT_INTENT_TRIGGERING_REFERENCE" | "TRANSCRIPT_RECOMMENDATION" | "TRANSCRIPT_UTTERANCE" | "TRANSCRIPT_TRIGGER_DETECTION_MODEL_INVOCATION" | "TRANSCRIPT_LARGE_LANGUAGE_MODEL_INVOCATION",
    "session_id": "SessionId",
    "session_name": "SessionName",
    "recommendation": "Recommendation",
    "intent": "Intent",
    "prompt": "Prompt",
    "utterance": "Utterance"
}

There may be more fields visible depending on the event type. For example, a chat or voice event has information relating to the utterance. An event that generated a recommendation has information on the intent, trigger, or the recommendation itself.

Examples of common queries to debug assistant logs

You can interact with logs by using queries. For example, you can query for all events within a session by using SESSION_NAME.

Following are two common queries to return all the logs generated for a specific session.

• filter session_name = "SessionName"

• filter session_id = "SessionId"