CloudWatch Logs를 사용하여 Amazon Q in Connect 모니터링 - Amazon Connect
필수 IAM 권한 로깅 활성화지원되는 로그 유형CloudWatch Logs 할당량 확인대화형 핸들러를 사용하여 CloudWatch 이벤트 문서화어시스턴트 로그를 디버깅하기 위한 일반적인 쿼리의 예

기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

CloudWatch Logs를 사용하여 Amazon Q in Connect 모니터링

Amazon Q in Connect가 에이전트에게 제공하는 실시간 권장 사항과 자연어 이해를 통해 감지하는 고객 의도를 파악하기 위해 CloudWatch Logs를 쿼리할 수 있습니다. CloudWatch Logs는 대화, 트리거, 의도, 권장 사항 등 전체 연락 여정에 대한 가시성을 제공합니다. 이 정보를 디버깅에 사용하거나 도움을 요청할 지원 때에 제공할 수도 있습니다.

이 주제에서는 Amazon Q in Connect에 대한 로깅을 활성화하는 방법을 설명합니다.

필수 IAM 권한

Amazon Q in Connect 어시스턴트에 대한 로깅을 활성화하기 전에 다음 AWS Identity and Access Management 권한이 있는지 확인합니다. Amazon Connect 콘솔에 로그인한 사용자 계정에 필요합니다.

  • wisdom:AllowVendedLogDeliveryForResource: 어시스턴트 리소스에 대한 로그 전달을 허용하는 데 필요합니다.

특정 로깅 대상에 필요한 모든 권한이 있는 예시 IAM 역할을 보려면 Logging that requires additional permissions [V2]를 참조하세요. 이 주제에는 CloudWatch Logs로 전송된 로그 및 Amazon S3로 전송된 로그와 같은 다양한 로깅 대상에 대한 예제가 포함되어 있습니다. 예제에서는 특정 로깅 대상 리소스에 대한 업데이트를 허용하는 방법을 보여줍니다.

Amazon Q in Connect 로깅 활성화

Amazon Q in Connect 로깅을 활성화하려면 CloudWatch API 작업을 사용합니다. 다음 단계를 완료합니다.

  1. Amazon Q in Connect 어시스턴트(도메인이라고도 함)의 ARN을 가져옵니다. 어시스턴트를 생성한 후 Amazon Connect 콘솔에서 또는 GetAssistant API를 직접적으로 호출하여 ARN을 가져올 수 있습니다. ARN은 다음 형식을 따릅니다.

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

  2. PutDeliverySource: 이 CloudWatch API를 사용하여 어시스턴트의 전송 소스를 생성합니다. 어시스턴트의 ARN을 resourceArn으로 전달합니다. logType의 경우 EVENT_LOGS를 지정하여 어시스턴트에서 로그를 수집합니다.

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

  3. PutDeliveryDestination 직접 호출: 이 CloudWatch API를 사용하여 로그를 저장할 위치를 구성합니다. 로그 저장 대상으로 CloudWatch Logs, Amazon S3 또는 Amazon Data Firehose를 선택할 수 있습니다. 로그를 저장할 대상 옵션 중 하나의 ARN을 지정해야 합니다. 로그의 outputFormat을 json, plain, w3c, raw, parquet 중 하나로 선택할 수 있습니다.

    다음 예제에서는 Amazon CloudWatch Logs 그룹 및 JSON 형식으로 저장할 로그를 구성하는 방법을 보여줍니다.

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

  4. CreateDelivery 직접 호출: 이 CloudWatch API를 사용하여 이전 단계에서 생성한 전송 대상에 전송 소스를 연결합니다. 이 API 작업은 전송 소스를 최종 대상과 연결합니다.

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

지원되는 로그 유형

Amazon Q in Connect는 다음 로그 유형을 지원합니다.

  • EVENT_LOGS: 통화, 채팅 및 이메일 중에 Amazon Q in Connect 어시스턴트의 이벤트를 추적하는 로그입니다.

CloudWatch Logs 할당량 확인

Amazon CloudWatch Logs 엔드포인트 및 할당량을 확인하여 CloudWatch Logs 전송 관련 API 직접 호출을 수행할 할당량이 있는지 확인하는 것이 좋습니다. 할당량은 API를 직접적으로 호출하거나 리소스를 생성할 수 있는 최대 횟수를 설정합니다. 제한을 초과할 경우 ServiceQuotaExceededException 오류가 발생합니다.

대화형 핸들러를 사용하여 CloudWatch 이벤트 문서화

이벤트 유형 정의

다음 표에서는 각 이벤트 유형을 설명합니다. 다른 이벤트 유형에는 다른 필드가 포함되어 있습니다. 각 필드에 대한 자세한 내용은 필드 정의 섹션을 참조하세요.

EventType 정의
TRANSCRIPT_CREATE_SESSION 새 Amazon Q in Connect 세션이 생성될 때 로깅됩니다. 이는 대화의 시작을 나타냅니다.
TRANSCRIPT_INTENT_TRIGGERING_REFERENCE 대화에서 특정 고객 의도가 감지되면 로깅되어 자동 응답 또는 워크플로가 트리거될 수 있습니다.
TRANSCRIPT_LARGE_LANGUAGE_MODEL_INVOCATION 대규모 언어 모델(LLM)이 호출되어 응답을 생성하거나 대화 콘텐츠를 처리할 때 로깅됩니다. LLM에 대한 입력과 LLM의 출력을 기록합니다.
TRANSCRIPT_QUERY_ASSISTANT Amazon Q in Connect에 수동 검색 또는 직접 쿼리를 수행할 때 로깅됨
TRANSCRIPT_RECOMMENDATION 시스템이 지식 문서, 생성된 응답 또는 제안된 작업을 포함할 수 있는 권장 사항을 에이전트 또는 고객에게 제공할 때 로깅됩니다.
TRANSCRIPT_RESULT_FEEDBACK 검색 또는 쿼리 결과의 유용성 또는 관련성에 대한 피드백이 제공되면 로깅됩니다.
TRANSCRIPT_SELF_SERVICE_MESSAGE 고객이 Amazon Q in Connect의 셀프 서비스 구성 요소와 상호 작용할 때 로깅됨
TRANSCRIPT_SESSION_POLLED 시스템이 에이전트가 세션에 연결되어 있음을 감지하면 로깅됩니다(GetRecommendations API 호출이 수행되면 세션이 폴링됨).
TRANSCRIPT_TRIGGER_DETECTION_MODEL_INVOCATION 대화에 의도가 있는지 확인하기 위해 트리거 감지 모델을 호출할 때 로깅됩니다.
TRANSCRIPT_UTTERANCE 대화의 참가자가 메시지를 전송하여 실제 대화 콘텐츠를 기록할 때 로깅됩니다.

필드 정의

다음 표에서는 각 필드를 설명합니다.

필드 정의
ai_agent_id Amazon Q in Connect AI 에이전트 리소스의 고유 식별자입니다.
assistant_id Amazon Q in Connect 어시스턴트 리소스의 고유 식별자입니다.
completion LLM에서 반환하거나 메시지에 대해 생성된 원시 완료 텍스트입니다.
connect_user_arn 세션에 액세스하는 Connect 사용자의 Amazon 리소스 이름(ARN)입니다.
event_timestamp 이벤트가 발생한 시점의 Unix 타임스탬프(밀리초)입니다.
event_type 시스템에서 발생한 작업 또는 프로세스를 나타내는 이벤트 유형입니다.
generation_id 특정 AI 생성 응답의 고유 식별자입니다.
의도 의도 텍스트 또는 설명입니다.
intent_clicked 추천이 클릭 의도에 의해 트리거되었는지 여부를 나타내는 부울입니다.
intent_id 감지된 의도의 고유 식별자입니다.
issue_probability 대화에서 문제가 감지된 숫자 확률(0.0~1.0)(0.5보다 큰 확률은 의도 생성을 호출함)
is_recommendation_유용 사용자가 결과를 유용하게 찾았는지 여부를 나타내는 부울입니다.
is_valid_trigger 감지 모델 분석에서 유효한 트리거가 발생했는지 여부를 나타내는 부울입니다.
model_id LLM을 호출하는 데 사용되는 AI 모델의 식별자입니다.
구문 분석된_응답 종종 구조화된 형식의 언어 모델 응답의 처리/파싱된 버전입니다.
프롬프트 LLM을 호출하는 데 사용되는 입력 프롬프트입니다.
prompt_type 메시지 또는 쿼리를 처리하는 데 사용되는 Amazon Q in Connect 프롬프트의 유형입니다.
권장 사항 사용자에게 제공된 실제 권장 사항 텍스트 콘텐츠
recommendation_id 권장 사항의 고유 식별자입니다.
응답 처리 후 사용자에 대해 생성된 최종 응답 텍스트입니다.
session_event_id 세션 내 특정 이벤트의 고유 식별자입니다.
session_event_ids 세션 이벤트 식별자 목록입니다.
session_id Amazon Q in Connect 세션의 고유 식별자입니다.
session_message_id 세션 내 셀프 서비스 메시지의 고유 식별자입니다.
session_name 세션의 이름입니다.
발화 대화에서 교환된 실제 메시지 텍스트입니다.

어시스턴트 로그의 예

다음은 각 이벤트 유형에 대한 다양한 이벤트 로그의 예입니다. 각 이벤트 유형에 대한 자세한 설명은 이벤트 유형 정의 섹션을 참조하세요.

CreateSession


{
    "assistant_id": "a1c2d3e4-5b67-4a89-9abc-def012345678",
    "event_timestamp": 1729530173612,
    "event_type": "TRANSCRIPT_CREATE_SESSION",
    "session_id": "s9f8e7d6-1234-4cde-9abc-ffeeddccbbaa",
    "session_name": "nabbccdd-9999-4b23-aaee-112233445566"
}

IntentTriggeringReference


{
    "assistant_id": "a1c2d3e4-5b67-4a89-9abc-def012345678",
    "event_timestamp": 1729530173623,
    "event_type": "TRANSCRIPT_INTENT_TRIGGERING_REFERENCE",
    "intent": "To learn about how to autoscale DynamoDB.",
    "intent_id": "i78bc90-1234-4dce-8012-f0e1d2c3b4a5",
    "session_id": "s9f8e7d6-1234-4cde-9abc-ffeeddccbbaa"
}

LargeLanguageModelInvocation

쿼리 재구성


{
    "ai_agent_id": "ai112233-7a85-4b3c-8def-0123456789ab",
    "assistant_id": "a1c2d3e4-5b67-4a89-9abc-def012345678",
    "completion": "<query>The customer is asking for information on how to autoscale DynamoDB.</query>",
    "event_timestamp": 1729530173645,
    "event_type": "TRANSCRIPT_LARGE_LANGUAGE_MODEL_INVOCATION",
    "generation_id": "gabc1234-9def-47ff-bb88-abcdefabcdef",
    "intent_id": "i78bc90-1234-4dce-8012-f0e1d2c3b4a5"
    "model_id": "us.amazon.nova-lite-v1:0",
    "parsed_response": "The customer is asking for information on how to autoscale DynamoDB.",
    "prompt": "{\"anthropic_version\":\"bedrock-2023-05-31\",\"max_tokens\":1024,\"system\":\"You are a...\"}",
    "prompt_type": "BEDROCK_KB_QUERY_REFORMULATION",
    "session_event_id": "seaa9988-2233-4f44-8899-abcabcabcabc",
    "session_id": "s9f8e7d6-1234-4cde-9abc-ffeeddccbbaa"
}

의도 감지


{
    "ai_agent_id": "ai112233-7a85-4b3c-8def-0123456789ab",
    "assistant_id": "a1c2d3e4-5b67-4a89-9abc-def012345678",
    "completion": "no</malice>\n  - Step 2. <specific>yes</specific>\n  - Step 3. <intent>To learn how to autoscale DynamoDB.</intent>",
    "event_timestamp": 1729530173645,
    "event_type": "TRANSCRIPT_LARGE_LANGUAGE_MODEL_INVOCATION",
    "generation_id": "gabc1234-9def-47ff-bb88-abcdefabcdef",
    "intent_id": "i78bc90-1234-4dce-8012-f0e1d2c3b4a5"
    "model_id": "us.amazon.nova-lite-v1:0",
    "parsed_response": "To learn how to autoscale DynamoDB.",
    "prompt": "{\"anthropic_version\":\"bedrock-2023-05-31\",\"max_tokens\":1024,\"system\":\"You are a...\"}",
    "prompt_type": "GENERATIVE_INTENT_DETECTION",
    "session_event_id": "seaa9988-2233-4f44-8899-abcabcabcabc",
    "session_id": "s9f8e7d6-1234-4cde-9abc-ffeeddccbbaa"
}

의도 응답 생성


{
    "ai_agent_id": "ai112233-7a85-4b3c-8def-0123456789ab",
    "assistant_id": "a1c2d3e4-5b67-4a89-9abc-def012345678",
    "completion": "{\"citations\":[{\"citation\":{\"generatedResponsePart\":{\"textResponsePart\":{\"span\":{\"end\":1065,\"start\":0},\"text\":\"\\nDynamoDB auto s\"}}}}]}",
    "event_timestamp": 1729530173645,
    "event_type": "TRANSCRIPT_LARGE_LANGUAGE_MODEL_INVOCATION",
    "generation_id": "gabc1234-9def-47ff-bb88-abcdefabcdef",
    "intent_id": "i78bc90-1234-4dce-8012-f0e1d2c3b4a5",
    "model_id": "us.anthropic.claude-3-7-sonnet-20250219-v1:0",
    "parsed_response": "DynamoDB auto scaling works by creating CloudWatch alarms that monitor your table's activity. When the...",
    "prompt": "{\"input\":{\"text\":\"The customer is seeking information on how to autoscale DynamoDB. Key utterance: \\\"How can \"}}",
    "prompt_type": "BEDROCK_KB_GENERATIVE_ANSWER",
    "session_event_id": "seaa9988-2233-4f44-8899-abcabcabcabc",
    "session_id": "s9f8e7d6-1234-4cde-9abc-ffeeddccbbaa"
}

수동 검색 생성


{
    "ai_agent_id": "ai112233-7a85-4b3c-8def-0123456789ab",
    "assistant_id": "a1c2d3e4-5b67-4a89-9abc-def012345678",
    "completion": "no</malice>\n  - Step 2. <specific>yes</specific>\n  - Step 3. <intent>To learn how to autoscale DynamoDB.</intent>",
    "event_timestamp": 1729530173645,
    "event_type": "TRANSCRIPT_LARGE_LANGUAGE_MODEL_INVOCATION",
    "generation_id": "gabc1234-9def-47ff-bb88-abcdefabcdef",
    "intent_id": "i78bc90-1234-4dce-8012-f0e1d2c3b4a5",
    "model_id": "us.anthropic.claude-3-7-sonnet-20250219-v1:0",
    "parsed_response": "DynamoDB auto scaling works by creating CloudWatch alarms that monitor...",
    "prompt": "{\"anthropic_version\":\"bedrock-2023-05-31\",\"max_tokens\":1024,\"system\":\"You are a...\"}",
    "prompt_type": "BEDROCK_KB_GENERATIVE_ANSWER",
    "session_id": "******************-*****************"
}

QueryAssistant


{
    "assistant_id": "a1c2d3e4-5b67-4a89-9abc-def012345678",
    "event_timestamp": 1729530173667,
    "event_type": "TRANSCRIPT_QUERY_ASSISTANT",
    "recommendation_id": "r0001112-3f4e-4fa5-9111-aabbccddeeff",
    "session_id": "s9f8e7d6-1234-4cde-9abc-ffeeddccbbaa"
}

권장 사항


{
    "assistant_id": "a1c2d3e4-5b67-4a89-9abc-def012345678",
    "event_timestamp": 1729530173656,
    "event_type": "TRANSCRIPT_RECOMMENDATION",
    "intent_clicked": 1,
    "intent_id": "i78bc90-1234-4dce-8012-f0e1d2c3b4a5",
    "recommendation_id": "r0001112-3f4e-4fa5-9111-aabbccddeeff",
    "session_id": "s9f8e7d6-1234-4cde-9abc-ffeeddccbbaa"
}

ResultFeedback


{
    "assistant_id": "a1c2d3e4-5b67-4a89-9abc-def012345678",
    "event_timestamp": 1729530173667,
    "event_type": "TRANSCRIPT_RESULT_FEEDBACK",
    "generation_id": "gabc1234-9def-47ff-bb88-abcdefabcdef",
    "is_recommendation_useful": 1,
    "recommendation_id": "r0001112-3f4e-4fa5-9111-aabbccddeeff"
}

SelfServiceMessage


{
    "assistant_id": "a1c2d3e4-5b67-4a89-9abc-def012345678",
    "completion": "{\"citations\":[{\"generatedResponsePart\":{\"textResponsePart\":{\"span\":{\"end\":276,\"start\":0},\"text\":\"To autoscale Amazon DynamoDB...\"}}]}",
    "event_timestamp": 1729530173678,
    "event_type": "TRANSCRIPT_SELF_SERVICE_MESSAGE",
    "model_id": "us.amazon.nova-pro-v1:0",
    "parsed_response": "To autoscale Amazon DynamoDB, follow these steps:...",
    "prompt": "{\"input\":{\"text\":\"how to autoscale dynamodb\"},\"retrieveAndGenerateConfiguration\":...}",
    "prompt_type": "SELF_SERVICE_ANSWER_GENERATION",
    "session_id": "s9f8e7d6-1234-4cde-9abc-ffeeddccbbaa",
    "session_message_id": "mdee1234-5678-4eab-9333-ffeebb998877",
    "utterance": "[Customer] How can I autoscale DyanmoDB?"
}

TranscriptSessionPolled


{
    "assistant_id": "a1c2d3e4-5b67-4a89-9abc-def012345678",
    "connect_user_arn": "arn:aws:connect:us-east-1:204585150770:instance/seaa9988-2233-4f44-8899-abcabcabcabc/agent/agbbccdd-9999-4b23-aaee-112233445566",
    "event_timestamp": 1729530173623,
    "event_type": "TRANSCRIPT_SESSION_POLLED",
    "session_id": "s9f8e7d6-1234-4cde-9abc-ffeeddccbbaa",
    "session_name": "nabbccdd-9999-4b23-aaee-112233445566"
}

TriggerDetectionModelInvocation


{
    "assistant_id": "a1c2d3e4-5b67-4a89-9abc-def012345678",
    "event_timestamp": 1729530173634,
    "event_type": "TRANSCRIPT_TRIGGER_DETECTION_MODEL_INVOCATION",
    "is_valid_trigger": 1,
    "issue_probability": "0.87",
    "session_event_id": "seaa9988-2233-4f44-8899-abcabcabcabc",
    "session_event_ids": ["seaa9988-2233-4f44-8899-abcabcabcabc"],
    "session_id": "s9f8e7d6-1234-4cde-9abc-ffeeddccbbaa"
}

발화


{
    "assistant_id": "a1c2d3e4-5b67-4a89-9abc-def012345678",
    "event_timestamp": 1729530173623,
    "event_type": "TRANSCRIPT_UTTERANCE",
    "session_event_id": "seaa9988-2233-4f44-8899-abcabcabcabc",
    "session_id": "s9f8e7d6-1234-4cde-9abc-ffeeddccbbaa",
    "utterance": "[Customer] My laptop won't connect to WiFi after the recent update"
}

어시스턴트 로그를 디버깅하기 위한 일반적인 쿼리의 예

쿼리를 사용하여 로그와 상호 작용할 수 있습니다. 예를 들어 SESSION_NAME을 사용하여 세션 내의 모든 이벤트를 쿼리할 수 있습니다.

다음은 특정 세션에 대해 생성된 모든 로그를 반환하는 두 가지 일반적인 쿼리입니다.

  • filter session_name = "SessionName"

  • filter session_id = "SessionId"