Trace

[#1]

Trace is a testing and inspection tool for your EventStream and AudienceStream configuration. It allows you to capture your workflow as a visitor and watch how events and customer data is processed in real-time. The guide shows you how to start and stop a new trace, join an active trace, and view the overview panel and trace log.

This article covers the following topics:

Table of Contents Placeholder

Prerequisites

The following items are required to use trace:

• EventStream or AudienceStream
  Contact your account manager to activate.
• Tealium Tools Browser Extension
  Tealium Tools is needed to start and end a trace session in your browser.

How It Works

Trace provides an inside view into the inner workings of EventStream and AudienceStream. The trace tool is critical for testing your configuration. With trace you can observe the details of a predefined workflow, ensure attributes update correctly, rules are applied, and actions trigger as expected.

From the Trace interface, you can:

• View predefined workflows and event log details in real time
• Start or stop a trace
• Join an active trace
• Establish rules and view results
• Get replay code to replay, pause, or resume an event
• View a scrolling summary of actions, events, and audiences
• View the details of an event or processing step
• View snapshots of visitor profiles

Getting a Trace ID

Once you have saved your UDH configuration and are ready to begin testing your enrichments, audiences, and actions, you need to get a Trace ID to use in the Trace tool.

Use the following steps to get a Trace ID:

1. Navigate to Tools > Trace.
2. Click Start Trace.
3. Copy the Trace ID number.
   The lifespan of a trace number is 24 hours from time of issue.
   

   

4. Click Continue.

Starting a Trace

Once you have a Trace ID, you can open another browser window and start the trace.

Use the following steps to start a trace:

1. Open a new Chrome browser window or tab and navigate to the first page of the workflow to test.
2. Open the Tealium Tools browser plugin and click AudienceStream Trace.
   
3. Paste or enter the Trace ID number.
   Uncheck Trace me as a new visitor if you are tracing a session across multiple domains.
   
4. Click Start Trace.
5. Return to UDH, where you got the Trace ID, and click Continue.
   As you navigate through your workflow in one browser window, trace sends information back to UDH and displays a timeline of visitor activity.

Start or Join a Trace Using the Slide-Out Window

You can optionally use the collapsible trace feature to to start or join a trace from a slide-out window in the user interface without having to leave your current location in the product. When a trace is in progress, a shortcut button that "glows" displays on the menu bar.

Replaying Trace Events from the Overview Panel

From the overview panel, you can replay, pause, or resume an event, as shown in the following table. You can also save time repeating tasks by getting code to replay events and reusing the configuration settings for a different Trace ID.

• Replaying the trace at Normal or 2x Speed
  The default setting used to replay an event is normal speed. To speed up the replay, select the double arrows to replay the event at two times the speed.
• Pausing the Trace
  The pause button allows you to pause the replay of an ongoing trace. When paused, trace continues to process new events behind the scenes but does not display new log entries until you click pause again to restart.
  
• Exiting the Current Trace
  Clicking the X will exit the current trace. If the trace is still active on the web page, the user can rejoin the trace using the Trace ID.
• Viewing the Latest Visitor Profile
  Clicking the icon to view the latest visitor profile displays the a snapshot of the profile for the latest visitor in JSON format, as shown in the following example:
  
• Get Code to Replay Events
  Clicking the Get Code to Replay Events button </> generates a curl command for each event. Using this command, you can repeat or replay an even in trace without having to recreate the configuration steps on the web page.
  • To replay a single event, copy and paste the matching curl command in the terminal application and press Enter to run the command.
  • To replay multiple events, click Download Bash Script to download the .sh file. Use the terminal application to run the .sh script.

Viewing Event Details

The following image illustrates the parts of the trace interface. The Trace Log is a real-time scrolling summary of actions, events, and audiences. The top section is called the Overview Panel and displays a snapshot of the detailed activity. Filters can be used to filter and sort attributes.

The left side of the screen is used to filter attributes and values. No event attributes are displayed in the left filter, this filter only displays visitor and visitor-scoped attributes. Use the Filter by: drop-down list to choose how you want to view the attributes and their values. Filtering allows you to examine if the attributes and the configurations tied to them are functioning properly. Attributes and their values can be filtered by one of the following:

• All
  Shows all attribute types and values set up in your AudienceStream profile.
• Existing
  Shows only the attributes that acquired a value after AudienceStream processing.
• Modified
  Shows only the modified, or enriched, attributes.

In the trace log, clickable text displays in white font, other text displays in gray. The timestamp adjacent to the log entry displays the time of the log entry. To view the details of an event, simply click an icon next to an event to slide out a detailed view of the event.

You can minimize the trace window to continue the process while moving on to other functions, such as clicking on an attribute or rule in the left sliding panel.

Stopping a Trace

Use the following steps to end an active trace and associated visitor session.

1. Open a new Chrome browser window or tab and navigate to your site.
2. Open the Tealium Tools browser plugin and click AudienceStream Trace.
   
3. Verify the Current Domain and Current Trace ID of the trace you want to stop.
4. Click Stop Trace.

Joining an Active Trace

Use the following steps to join a trace that is currently in progress:

You must exit any active traces before you can join a trace. 

1. Navigate to Tools > Trace.
2. Enter the known Trace ID for an active trace.
3. Under Join Trace, click Join.
   This step redirects you to the corresponding trace in progress.
   

   

Starting a Trace from the Browser Console

If you do not use Chrome or cannot use the Tealium Tools plugin, you can manually start a trace using your  browser developer tools. The trace tool uses a manually-created cookie called trace_id.

Traces started manually will always follow the "Trace me as a new visitor" feature.

 Use the following steps to start a trace manually:

1. Open a new Chrome browser window or tab and navigate to the first page of the workflow to test.
2. Open your developer tools or the web console for your browser.
3. Enter the following line of code to enable the traced_id cookie.
   Replace the variable 12345 with the Trace ID number from UDH.
   

   document.cookie="trace_id=12345;path=/";

4. Reload the page to begin the trace.

Ending the Trace from the Browser Console

Use the following steps to end a trace manually:

1. Open a new Chrome browser window or tab.
2. Open your developer tools or the web console for your browser.
3. Enter the following line of code to trigger the event and delete the trace_id cookie:
   

   console.log("Attempting to kill visitor session for Trace."),window.utag&&utag.track?utag.track("kill_visitor_session",{event:"kill_visitor_session","cp.trace_id":utag.data["cp.trace_id"]}):console.log("Unable to kill visitor session using utag.track.");

Starting a Trace from an App

There are several ways to start a trace within an app. This section will show the following methods:

• Using Charles Proxy
• Using Native Code
• Using Tealium iQ

Starting from an App Using Charles Proxy

This procedure uses the Charles Web Debugging Proxy (Charles Proxy) to start a trace from an application using the Mobile SDK and the collect tag.

Use the following steps to start the trace using the Charles proxy:

1. Set up your mobile device to proxy traffic on your computer to Charles on your computer.
   In this step, follow the iOS or Android instructions
2. Run your application using Charles as the Proxy and filter the network traffic in Charles for "teal".
   A request similar to the following displays:
   

   

3. Right-click the request and select Copy URL.
4. From the Charles menu, click Tools > Rewrite.
5. Click Enable Rewrite.
6. In the Name field, type Add Trace ID.
7. Click Add to add a location.
   

   

8. In the Host field, type or paste the URL for the collect tag.
9. Click outside of the Edit Location dialog box.
   Charles automatically determines the additional components of the URL, resulting in a screen similar to the following:
   

   

10. Ensure that the query parameters are empty and remove any existing text in the Query field.
11. Click OK.
12. Click Add from Actions list in the Rewrite Settings dialog.
    

    

13. In the Rewrite Settings dialog, configure the settings to match the following example:
    

    

14. In the Type field, select Body from the drop-down list.
15. Under Where, click to select the Request checkbox.
16. In the Value field, under Match, enter the following:
    

    "data":{

17. Click to select the Match whole value checkbox.
18. In the Value field under Replace, enter the following:
    

    "data":{"cp.trace_id":"12345",

    In this step, use your actual trace ID instead of 12345.

19. Click to select the Replace first checkbox.
20. The steps are now complete.
    You can now browse your application and view the requests in the AudienceStream trace session.
21. Charles retains the settings from your last setup, you do not have to do these steps each time you want to trace. To run another trace, simply start Charles, edit the existing rewrite rule to change the 12345 value of the trace id.

Starting from an App Using Native Code

If you do not wish to use Charles Proxy or are still in development mode and using a simulator, a quicker way to run a trace is to simply add the trace ID to the Volatile Data within your native code. Below are some examples for some of our most popular device libraries.

Swift Library

tealium?.volatileData()?.add(data: ["tealium_trace_id": "09755"])

iOS Library (5.X)

Swift:

tealium.addVolatileDataSources(["tealium_trace_id" : "02837"]) 

Objective-C

NSDictionary *tealiumTrace = @{@"tealium_trace_id":@"XXXXX"};

[[Tealium instanceForKey:TEALIUM_INSTANCE_ID] addVolatileDataSources: tealiumTrace];

Android Library (5.X)

instance.getDataSources().getVolatileDataSources().put("tealium_trace_id", “XXXXX");

Ending a Trace Using Native Code

You can also end your trace manually and simulate any "end of visit" enrichments by adding a track call with the following key value pairs to the optional data anywhere in the app:

"event":"kill_visitor_session", "cp.trace_id":"XXXXX"

iOS

tealium?.trackViewWithTitle("screenName", dataSources: ["event":"kill_visitor_session", "cp.trace_id":"XXXXX"])

Android

Map<String, Object> data = new HashMap<>(1);
data.put("event", "kill_visitor_session");
data.put("cp.trace_id", "XXXXX");

Tealium.getInstance("INSTANCE").trackView("screenName", data);

Starting from an App Using Tealium iQ

This method requires the Tealium Collect tag in your iQ configuration. You will first use Live Events in UDH to determine the Universally Unique Identifier (UUID) of your device, then use that value in a Set Data Values extension in iQ to set a trace ID for tracking that comes from your testing device. This is a powerful method while in later stages of development because it does not require editing the native code.

To start a trace using Tealium iQ: 

1. Go to EventStream > Live Events.
2. From the Data Sources drop-down menu, select the mobile data source you are testing.
3. Open the application on your device to trigger tracking activity.
4. Return to the Live Events screen to observe activity in the chart.
5. Click on one of the events to open the details.
6. Locate the  app_uuid parameter (or  uuid, depending on which version of the Tealium SDK you are using) and copy the value.
   Ensure that this event is coming from the device you are testing.
7. Follow the previous instructions to get a new trace ID and start a new trace.
8. Once you have a new trace ID, open a new browser tab and go to the Tealium iQ profile for your mobile app.
9. From the Data Layer tab, add a new variable named trace_id.
10. In the Type drop-down list, select First Party Cookie.
    

    

11. From the Extensions tab, add a Set Data Values extension with the following settings:
    • Scope: Tealium Collect
    • Set:  trace_id (cp) To: (Text) < your_trace_ID>
    • Condition:  app_uuid equals <value of uuid>
      

      

12. Save and publish to the environment where you are testing.
13. Open your app and navigate through desired screens and events, then navigate back to your Trace tab to see your trace in action.