Skip to main content

Network span parents

Network span parents​

Embrace's SDK records a span for each network request your app makes. By default, each network span is the root of its own trace, so nothing connects a request to the operation in your app that made it.

You can choose a parent for network spans. A checkout span can then contain the POST /orders request it made.

Choosing a parent doesn't change the requests your app sends. Embrace only changes a request's traceparent header when traceparent injection is enabled for the request's host.

Minimum requirements

Network span parents require Android SDK 9.5.0 or later and apply to requests your app makes with OkHttp. Embrace doesn't parent requests made with HttpURLConnection or requests you record manually with recordNetworkRequest.

You can choose a parent in three ways:

  • Add a traceparent header to the request.
  • Set one parent for all network requests with setNetworkSpanParent.
  • Choose a parent for each request with a NetworkSpanParentProvider.

Start the SDK before you call setNetworkSpanParent or register a provider. Calls made before the SDK starts have no effect.

Use a traceparent header​

If a request carries a W3C traceparent header, such as one your own tracing adds, Embrace makes the network span a child of the span the header names. Add the header when you build the request:

val checkout = Embrace.startSpan("checkout")

val request = Request.Builder()
.url("https://api.example.com/orders")
.apply {
// The network span for this request becomes a child of "checkout"
checkout?.let { header("traceparent", "00-${it.traceId}-${it.spanId}-01") }
}
.build()

A valid header takes precedence over the parent you set with setNetworkSpanParent, and your provider can override it. Embrace ignores a header that isn't valid.

Embrace sends your header unchanged unless traceparent injection is enabled for the request's host. When it is, Embrace replaces your header with the network span's IDs, so the trace reads app span → network span → server span. See Propagate the trace to your backend.

Set a parent for all network requests​

Pass a span to setNetworkSpanParent. Network spans that start from then on become its children:

val checkout = Embrace.startSpan("checkout")

// Network requests that start from now on are children of "checkout"
val token = checkout?.let { Embrace.setNetworkSpanParent(it) }

submitOrder()

// Stop parenting network requests to "checkout"
token?.let { Embrace.clearNetworkSpanParent(it) }
checkout?.stop()

The parent applies to requests made on any thread. Embrace chooses a request's parent when the request starts, so setting or clearing the parent doesn't affect requests already in flight.

Only one network span parent is active at a time, and calling setNetworkSpanParent again replaces it. If the span you pass hasn't started or has already stopped, the call has no effect.

Embrace clears the parent for you when the parent span stops or the user session ends. The parent stays set when your app goes to the background.

Clear the parent​

Each call to setNetworkSpanParent returns a NetworkSpanParentToken that identifies that call. You can clear the parent in two ways:

  • clearNetworkSpanParent(token) clears the parent and returns true if token is from the most recent setNetworkSpanParent call. Otherwise, it does nothing and returns false.
  • clearNetworkSpanParent() clears the parent unconditionally.

Prefer clearing with the token. If another part of your app has set a newer parent since your call, your token leaves that parent in place.

Use a span context​

If your parent isn't an EmbraceSpan, such as a span you created with OpenTelemetry or a span context from outside your app, pass its SpanContext instead:

// spanContext is an io.opentelemetry.kotlin.tracing.SpanContext
val token = Embrace.setNetworkSpanParent(spanContext)

If Embrace doesn't track the span behind the span context, it can't tell when that span stops. Clear the parent yourself when the operation ends.

Choose a parent for each request​

A single parent works when one operation makes requests at a time. When operations overlap, or when you want to treat some requests differently, register a NetworkSpanParentProvider. Embrace consults your provider for each request before its network span starts:

import io.embrace.android.embracesdk.network.NetworkSpanParent

Embrace.setNetworkSpanParentProvider { info ->
if (info.request.url.contains("/analytics/")) {
// Keep analytics requests out of your app's traces
NetworkSpanParent.NO_PARENT
} else {
// Choose a parent as if no provider were set
NetworkSpanParent.USE_DEFAULT
}
}

Register your provider after you start the SDK, ideally right after starting it in your Application.onCreate(). Your provider applies to requests captured after setNetworkSpanParentProvider returns. Registering another provider replaces it.

Parent a request to the span that made it​

info.request.nativeRequest is the HTTP client's own request object, which for OkHttp is the okhttp3.Request. This lets you carry the parent on the request itself. Tag each request with the span it belongs to, then return that span from your provider:

import io.embrace.android.embracesdk.network.NetworkSpanParent
import io.embrace.android.embracesdk.spans.EmbraceSpan
import okhttp3.Request

// When you build a request, tag it with the span it belongs to
val request = Request.Builder()
.url("https://api.example.com/orders")
.tag(EmbraceSpan::class.java, checkout)
.build()

// Parent each request to the span in its tag
Embrace.setNetworkSpanParentProvider { info ->
val okHttpRequest = info.request.nativeRequest as? Request
val span = okHttpRequest?.tag(EmbraceSpan::class.java)

if (span != null) {
NetworkSpanParent.parent(span)
} else {
NetworkSpanParent.USE_DEFAULT
}
}

What a provider can see​

Your provider receives a NetworkSpanStartInfo:

PropertyDescription
requestThe request the network span is for, as an HttpRequestInfo with url, httpMethod, and nativeRequest.
currentParentThe parent currently set with setNetworkSpanParent, which you can return as the decision, or null if none is set.
currentParentSpanThe span of the current parent, or null if none is set or Embrace doesn't track it.
currentParentSpanContextThe span context of the current parent, or null if none is set.

What a provider can return​

ValueEffect
NetworkSpanParent.parent(span)Parents the network span to span.
NetworkSpanParent.parent(spanContext)Parents the network span to spanContext.
NetworkSpanParent.parent(traceId, spanId)Parents the network span to the span with traceId and spanId.
NetworkSpanParent.NO_PARENTMakes the network span a root span, overriding the network span parent and any traceparent header.
NetworkSpanParent.USE_DEFAULTApplies the default rules, as if no provider were set.

Return one of these values rather than implementing NetworkSpanParent in your own classes, as Embrace may add new properties to the interface in the future.

How Embrace chooses a parent​

For each request, Embrace uses the first of these that applies:

  1. Your provider's decision, unless it returns USE_DEFAULT.
  2. The span in a valid traceparent header already on the request.
  3. The parent you set with setNetworkSpanParent.

If none applies, the network span is a root span.

Propagate the trace to your backend​

By default, Embrace doesn't change the headers of the requests your app sends, however the parent was chosen. When traceparent injection is enabled for a host, Embrace sets the traceparent header of requests to that host to the network span's IDs, so your backend's spans become children of the network span.

Use traceparent_only_allow_domains to choose which hosts this applies to, and see network spans forwarding to send network spans to your own observability platform.

Guidance​

Keep your provider fast and side effect free. Embrace calls it before every captured request starts, so any work it does is work your app's network path pays for.

If your provider throws an exception or returns an invalid parent, Embrace applies the default rules for that request, as if your provider returned USE_DEFAULT.

While a parent is set with setNetworkSpanParent, every captured request becomes its child, including requests from other parts of your app and from third-party libraries. Set the parent just before the requests that belong to it, and clear it as soon as they've started. If operations overlap, use a provider instead of switching the parent back and forth.