Trace

The Trace module provides debugging and testing capabilities for the Tealium Prism SDK. Use trace sessions for real-time event monitoring to verify that events are tracked and dispatched correctly. When a trace is active, the trace ID is automatically added to all tracking events for server-side filtering and analysis.

For more information about the trace tool, see Debug with trace.

Collected data points

When a trace session is active, the Trace module collects the following data:

Data point	Key	Description
Trace ID	`cp.trace_id`	The unique identifier for the active trace session (legacy compatibility)
Trace ID	`tealium_trace_id`	The unique identifier for the active trace session

Installation

The Trace module can be configured using programmatic, remote JSON, or local JSON settings.

To limit the events that include the trace ID, add the Trace module to your mobile profile and assign a rule to it. For more information, see Rules.

In React Native, the Trace module is enabled via your Tealium settings JSON. No programmatic setup is required.

Add the Trace module to your Tealium configuration:

val config = TealiumConfig.Builder(
    application = application,
    accountName = "tealiummobile",
    profileName = "your-profile",
    environment = "dev",
    modules = listOf(Modules.trace())
).build()

To configure with enforced settings:

val config = TealiumConfig.Builder(
    application = application,
    accountName = "tealiummobile",
    profileName = "your-profile",
    environment = "dev",
    modules = listOf(Modules.trace {
        it.setEnabled(true)
            .setTrackErrors(true)
    })
).build()

Add the Trace module to your Tealium configuration:

let config = TealiumConfig(account: "tealiummobile",
                          profile: "your-profile",
                          environment: "dev",
                          modules: [
                              Modules.trace(),
                              // other modules...
                          ])

To configure with enforced settings:

let config = TealiumConfig(account: "tealiummobile",
                          profile: "your-profile",
                          environment: "dev",
                          modules: [
                              Modules.trace(forcingSettings: { builder in
                                  builder.setEnabled(true)
                                         .setTrackErrors(true)
                              }),
                              // other modules...
                          ])

JSON configuration

Configure the Trace module in your local or remote settings JSON file:

{
    "modules": {
        "Trace": {
            "module_type": "Trace",
            "enabled": true,
            "configuration": {
                "track_errors": true
            }
        }
    }
}

Join a trace session

To start a trace session, call trace.join() with a trace ID. The trace ID is added to all future events until you call leave() or the session expires.

tealium.trace.join("your-trace-id")
    .subscribe { result ->
        // Optionally handle result here
    }

tealium.trace.join(id: "your-trace-id").subscribe { result in
    // Optionally handle result here
}

await tealium.trace.join("your-trace-id");

Leave a trace session

To stop a trace session, call trace.leave(). This removes the trace ID from future events.

tealium.trace.leave()
    .subscribe { result ->
        // Optionally handle result here
    }

tealium.trace.leave().subscribe { result in
    // Optionally handle result here
}

await tealium.trace.leave();

Force end of visit

To test “End of Visit” actions in Customer Data Platform (CDP), force the session to end immediately instead of waiting for the session to expire:

tealium.trace.forceEndOfVisit()
    .subscribe { result ->
        // Handle the track result
    }

tealium.trace.forceEndOfVisit().subscribe { result in
    // Handle the track result
}

await tealium.trace.forceEndOfVisit();

The trace remains active until leave() is called. The forceEndOfVisit() method dispatches a track call that signals the session to end, following standard dequeueing flows.

Error tracking

When error tracking is enabled (track_errors: true), the Trace module automatically tracks SDK errors that occur during an active trace session. To prevent duplicate error reports, the module deduplicates errors by category:

Only the first error from each category is tracked per trace session
Subsequent errors from the same category are ignored until a new trace session begins
Joining a new trace session or leaving the current session resets the deduplication cache

QR trace

You can also start a trace directly from a deep link. If the opened URL contains the right query parameter, the trace starts automatically. This is typically done with the QR trace tool on the Tealium platform. For more information, see Debug with trace.

API reference

For detailed class and method signatures, see the API reference documentation: