Trace

[#1]

This article describes how to start and stop a new trace, join an active trace, and view the overview panel and trace log. Trace is a testing and inspection tool for your EventStream and AudienceStream configuration that allows you to capture your workflow as a visitor and watch how events and customer data is processed

in real-time.

In this article:

Table of Contents Placeholder

Prerequisites

The following items are required to use this feature:

• EventStream or AudienceStream
  If you do not already have access to one or both, 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. You can use trace to observe the details of a predefined workflow, ensure that attributes update correctly, rules are correctly applied, and that 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 Universal Data Hub (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. In the left sidebar, click Trace.
2. Click Start.
   A Trace ID number displays.
3. Copy the Trace ID number.
   The lifespan of a trace number is 24 hours from time of issue.
   

Starting a Trace

Use the following steps to start a trace:

1. Open a new Chrome browser window and navigate to the first page of the workflow to test.
2. Open the Tealium Tools browser plug-in 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. Click Exit and then press ESC to exit the tool.
6. 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:
  
  Click OK to exit this window.
• 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 event 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 and navigate to your site.
2. Open the Tealium Tools browser plug-in 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. In the left sidebar, click 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 plug-in, 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 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.
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 iQ Tag Management

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 and click OK.
11. Click Add from Actions list in the Rewrite Settings dialog.
    
12. In the Rewrite Settings dialog, configure the settings to match the following example:
    

    

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

    "data":{

16. Click to select the Match whole value checkbox.
17. 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.

18. Click to select the Replace first checkbox.
19. The steps are now complete.
    You can now browse your application and view the requests in the AudienceStream trace session.
20. 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 want 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.

Use the following examples for some of the 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 optionally 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 iQ Tag Management

This method requires the Tealium Collect tag in your iQ Tag Management (TiQ) 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.

Use the following steps to start a trace using TiQ:

1. In the sidebar, click EventStream > Live Events.
2. From the Data Sources drop-down list, 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 window.
9. In the sidebar, go to and navigate to iQ Tag Management > Data Layer.
10. Cick + Add Variable to add a new variable.
11. In the Source field, enter trace_id.
12. In the Type drop-down list, select First Party Cookie.
    
13. Go back to the sidebar and navigate toiQ Tag Management  > Extensions.
14. Aadd 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>
15. Save and publish to the environment where you are testing.
16. Open your app and navigate through desired screens and events and then navigate back to your Trace tab to see your trace in action.