Blog

Contact Flow Log Analysis with CloudWatch Insights

So, you have your Amazon Connect Contact Center setup and live.  With the Real-Time and Historical Reports available in the Connect Console, you’re able to see all the calls coming and going, which queues are full or empty, and which agents are busy or available.  Here we can understand your caller’s experience once they have left your IVR and are either waiting or dealing with an Agent.  But what about their experience within the IVR itself?  How often are they following a particular menu option?  How often are they experiencing system errors caused by Lambda functions?  What about their interactions with Lex Bots?  Or entering information with their keypad?

Your Amazon Connect instance can provide you with this data in the form of Contact Flow Logs.  You can use Contact Flow Logs (CFLs) to analyze your caller’s experience in your IVR since each block in your Contact Flow is being processed and logged, both with input parameters and process results.  These logs can then be viewed in the CloudWatch Console by selecting Logs, then Log Group for your Connect Instance.

The more volume your Contact Center handles, however, the more difficult it will be too look through the standard CloudWatch Log Streams.  The CloudWatch console organizes log entries by timestamp, which means that concurrent calls will be all mixed together.  While there is some filtering you can do with the log streams, there is a great tool available to us where we can better search and analyze CFLs using a “purpose-built query language.”

From the CloudWatch Console, you can access the CloudWatch Insights service which provides an interface where you can select one or more Log Groups to search through.  Queries can be added to a CloudWatch Dashboard and Query results can be exported to CSV files.  With this, we can easily search through CFLs regardless of call volume and within any time periods, we desire.

We should note that Contact Flow Logs are not enabled by default.  You must first navigate to your instance in the AWS console, click “Contact Flows” on the left-hand side. 

At the bottom, you will see a checkbox to “Enable Contact flow logs.”

Check this box, click “Apply” and note the destination Log Group for your logs. 

Also, Contact Flows do not log data by default.  For each Contact Flow, you must add the “Set Logging Behavior” block and ensure the value is enabled. 

There are some situations in which you may not want logging enabled, such as a caller entering personal information, so you must be careful when enabling and disabling logging.  This data will be accessible to anyone with CloudWatch dashboard access unless certain IAM permissions are set.[CA1]   Check out [CA2] https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/iam-identity-based-access-control-cw.html to learn more about CloudWatch Console access.

CloudWatch Insights is not a free service, it costs $0.005 per GB of data scanned.  For more information, check out https://aws.amazon.com/cloudwatch/pricing/.

A Quick Look at CloudWatch Insights

Here is the CloudWatch Insights page, which can be found under Logs on the left-hand side menu on the CloudWatch Console home page.

The top drop-down is where you will select the log group(s) you want to query.  For Contact Flow Logs, you’ll choose your Connect Instance, which will have the following format: “/aws/connect/{instance-name}.”  To the right of the log group selection, you will want to specify the date range in which you want to query.  Like with most AWS services, you can select a variety of periods from 5 minutes to 4 weeks or any custom time frame.  Help is also available on the far right of the console.

Below the Log Group, you will see the Query Editor.

This is where you will be able to enter your query to begin analyzing your CFLs.  The editor provides some helpful code completion.  When your query is ready, just hit the “Run query” button and wait.  Depending on the time frame you specified, it may take a few moments to run, the more data that needs to be scanned, the longer the time it takes.  If there is any problem with your query, the editor will let you know before it starts to execute the query.  The results will be populated in the box below the timeline.  The timeline can give you a quick visual indication of how many log messages your query returned in your selected timeframe.  You can also see exactly how many records were returned along with how much data was scanned and the scanning speed below the timeline.

Once you have your results, you can freely expand the logs as needed to get further details and look at the results directly. 

You may also click the “Actions” button to reveal several export options if you want to pull this data into a different program.  You can also add your query to a CloudWatch Dashboard in order to keep everything together in the same place. 

The CloudWatch Insights console is easy to use and understand and makes looking through logs much easier than the standard Log Stream output.  Now let’s learn more about the logs themselves and how we can query them specifically for Amazon Connect.

Contact Flow Log Type

Let’s first look at the structure of CFL.  The following is a real example but with a few details redacted.

There are five standard attributes for all CFLs which I have listed below.  The timestamps are in UNIX format and CloudWatch Insights has helper functions to translate to friendlier formats if needed.

  • @ingestionTime is the timestamp the log was actually received and consumed into CloudWatch.
  • @log is the name of the Log Group.
  • @logStream contains the Log Stream name for that specific period of time.
  • @message contains the unparsed JSON log data.
  • @timestamp contains the event timestamp for when the log was added to CloudWatch. 

Below these standard attributes, you can see that the JSON data contained in the @message is broken out into easily read and searchable fields.

Basic Contact Flow Log Queries

The queries below help address common scenarios in CFL analysis.  Once you get the hang of the commands and syntax, you’ll be writing your own queries with no effort!

Default Query

This query is the default, which appears when you first load the Log Group.  It shows the logs in descending order and limited to the last 20 log messages.  We’ll use this as a starting point for the following queries but remove the limit keyword.  Note that all the syntax commands start with the “|” (UNIX-style pipe character) at the beginning of the line; this is required.  You may also write comments by using “#” at the beginning of the line, which will be ignored by your query.

Get All CFL’s for specific Contact Id

This query will retrieve all CFL’s for the specified Contact Id displayed in order by timestamp.  This is the entire journey of the caller through your Contact Flows up until they are connected to an Agent.

Count Unique Calls

This query will return the number of any call which generated some type of logging.  This will not necessarily return the number of calls to your Connect Instance, only those where logging is enabled.

Find Lambda Errors

This query will return all logs where a Lambda Function Module returned an error.  This will help you identify why a Lambda failed by returning the list of parameters sent.  You can see if it was an isolated incident or a general trend under certain conditions.  The full error message is “The Lambda Function Returned An Error.”

Find all Specific Lambda Invocations

This query will return all logs for a specific Lambda Function.  You can see the Parameters sent to the Lambda Function and the Returned Results for each invocation logged.

Find all Lambda Invocations with Specific Parameter Value

This query will return all logs for the specified Lambda Function where the Parameter is equal to a certain value.  In this example, the Parameter key is “Group” and the value is “Sales.” 

Count Unique Calls hitting Certain Call Flow

This query will return the total number of unique calls that journeyed through the specified Contact Flow.  This is useful if you want to determine the percentage of callers that go to a certain Contact Flow based on Menu Options, for example.

Count how many times a user pressed an option in a Get User Input Block

This query will return the number of times a specific option was selected on a Get User Input Block.  In this example, we want to know how many callers selected option 2.  Get the total number for all other options to compare which option is most popular.  Also, you can swap out “GetUserInput” with “StoreUserInput” since those blocks work in similar way.

Count how many times an attribute was set

This query will return the number of times a specific Contact Attribute was set.  In this example, we want to know how many times callers wanted to check their current account balance in a self-service Contact Flow rather than be directed to an agent.

Contact Flow Module Types

Here is a handy reference for Contact Flow Module Types with their respective Connect Blocks.  Most are obvious but there are a few differences between some of them.  Note that, for example, the SetContactFlow and Transfer module types are used by several different Connect Blocks and actual type is passed a Parameter to the module, available in the CFL details.  When searching for a specific Connect block in your CFLs, use the specified ContactFlowModuleType.

Conclusion

I hope with this information you can start using CloudWatch Insights to quickly analyze your Contact Center experience.  By learning a few commands, you will be able to get valuable information about how your IVR’s are being used by callers and pinpoint any errors or issues that they might be encountering.  This service is a must for Contact Flow development and troubleshooting.

For more information regarding CloudWatch Insights, check out the great documentation at https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/AnalyzingLogData.html.  There you can learn more about the commands used throughout this post and additional operators and helper functions available.

Please reach out to us and thanks for reading!

Joseph


X