# Tracing

<img alt="Capture SDK Support" src="https://img.shields.io/badge/Android-0.22.14-006C9C">
<img alt="Capture SDK Support" src="https://img.shields.io/badge/iOS-0.22.14-006C9C">

!!! example "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.

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

!!! info "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.

!!! note "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](../quickstart.md).

## Network integration

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

=== "Android"

    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:

    - [Networking integrations](../integrations.md#networking)
    - [OkHttp (Android)](../integrations.md#okhttp-android)
    - [Auto-instrumentation via Gradle plugin](../integrations.md#auto-instrumentation-via-gradle-plugin)

    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:

    - [Automatic Instrumentation](./automatic-instrumentation.md)
    - [Integrations](../integrations.md#auto-instrumentation-via-gradle-plugin)

=== "iOS"

    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)](../integrations.md#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.

!!! note "Related docs"
    See [Integrations](../integrations.md#networking) for network integration setup and [Product > Workflows Actions](../../product/workflows/actions.md) for workflow action details.