Skip to content
View as Markdown

Tracing

Capture SDK Support Capture SDK Support

Experimental

Client-driven tracing is currently an experimental feature.

Tracing allows bitdrift workflows to turn backend trace propagation on for a session.

When tracing is enabled for a session:

  • Capture marks the session as traced.
  • Android and iOS network integrations add trace propagation headers to supported requests.
  • Trace IDs are recorded on logs so Timeline can deep link to your tracing system.

Availability

Tracing is not enabled for all tenants by default. Contact bitdrift Support if you want this feature enabled for your tenant.

Configuration Requirements

To use tracing today, you must:

  1. Upgrade to a supported SDK version.
  2. Ask bitdrift Support to enable tracing for your tenant.
  3. Configure trace deep linking for your tenant.

If tracing has not been enabled for your tenant, the Start Tracing workflow action will not appear in the workflow builder.

Start the SDK normally

Tracing does not use a separate SDK startup path. Start Capture normally, then enable the supported network integration for your platform.

Start the SDK normally as described in the SDK Quickstart.

Network integration

To automatically propagate tracing headers, you must use bitdrift's network integrations.

For OkHttp, use either:

  • the Capture Gradle plugin auto-instrumentation, or
  • the Capture OkHttp integration directly

If you use automatic Android instrumentation, tracing only requires enabling the existing Gradle plugin OkHttp instrumentation flag. You do not need to manually add the tracing interceptor yourself.

See the existing Android network setup docs:

A manual OkHttp setup should include both the tracing interceptor and the Capture event listener factory.

Kotlin
import io.bitdrift.capture.network.okhttp.CaptureOkHttpEventListenerFactory
import io.bitdrift.capture.network.okhttp.CaptureOkHttpTracingInterceptor
import okhttp3.OkHttpClient

val client = OkHttpClient.Builder()
    .addInterceptor(CaptureOkHttpTracingInterceptor())
    .eventListenerFactory(CaptureOkHttpEventListenerFactory())
    .build()

See:

Tracing on iOS uses the existing URLSession integration.

The default URLSession integration path uses swizzling. If your app already uses the non-swizzling integration path, tracing follows that setup as well.

See URLSession (iOS) for setup details.

Trace propagation

Trace propagation is controlled remotely. Capture currently supports these propagation formats:

  • w3c
  • b3-single
  • b3-multi

Workflow setup

Once tracing is enabled for your tenant, the workflow builder exposes a Start Tracing action.

Use it on a match step that identifies the sessions you want traced.

Examples include:

  • app version or build-specific sessions
  • feature-flag-specific sessions
  • sessions that hit a specific screen or flow
  • sessions that later hit a known problem condition

Timeline

When tenant tracing is enabled and deep-link configuration is present:

  • Timeline log rows can show View Trace links.
  • Span views can deep link to the backend trace.

These links are built from the trace ID captured by the SDK and your tenant-specific trace URL template.

Related docs

See Integrations for network integration setup and Product > Workflows Actions for workflow action details.