# 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.

!!! info "Availability"
    Tracing is not enabled for all tenants by default. [Contact us](../../support/contact.md) if you want this feature enabled for your tenant.

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 "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

!!! info "Workflow configuration"
    See [Product > Workflow Actions](../../product/workflows/actions.md#start-tracing) for how to configure **Start Tracing** and related workflow settings.

## 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.