Update the Android OkHttp instrumentation docs and fix some Otel docs #29392

mariusc83 · 2025-05-16T08:30:43Z

What does this PR do? What is the motivation?

This pull request updates documentation for Android setup and custom instrumentation, focusing on improving clarity and providing additional examples. The most important changes include adding instructions for using DatadogInterceptor with OkHttpClient and updating code snippets to correct terminology for accessing tracers.

Additions to Android setup documentation:

Added instructions for using DatadogInterceptor as a network interceptor with OkHttpClient to automatically create RUM resources and Spans for network requests. Included Kotlin and Java code examples.
Clarified that TracingInterceptor can be used instead of DatadogInterceptor if only Spans are needed, without RUM resources.

Updates to custom instrumentation documentation:

Updated Kotlin and Java code snippets to replace tracerProvider with tracer for accessing tracers via GlobalOpenTelemetry.get(), aligning with correct terminology

Merge instructions

Merge readiness:

Ready for merge

For Datadog employees:
Merge queue is enabled in this repo. Your branch name MUST follow the <name>/<description> convention and include the forward slash (/). Without this format, your pull request will not pass in CI, the GitLab pipeline will not run, and you won't get a branch preview. Getting a branch preview makes it easier for us to check any issues with your PR, such as broken links.

If your branch doesn't follow this format, rename it or create a new branch and PR.

To have your PR automatically merged after it receives the required reviews, add the following PR comment:

/merge

Additional notes

github-actions · 2025-05-16T08:34:14Z

Preview links (active after the `build_preview` check completes)

Modified Files

content/en/real_user_monitoring/mobile_and_tv_monitoring/android/setup.md

0xnm · 2025-05-16T08:47:02Z

content/en/real_user_monitoring/mobile_and_tv_monitoring/android/setup.md

 This records each request processed by the `OkHttpClient` as a resource, with all the relevant information (URL, method, status code, and error) automatically filled in. Only the network requests that started when a view is active are tracked. To track requests when your application is in the background, [create a view manually][13].

+In case you want to monitor the network redirects or retries, you can use the `DatadogInterceptor` as a network interceptor.


maybe it is worth to link OkHttp documentation on the difference between interceptor and networkInterceptor?

not sure, I am waiting for suggestions here from doc reviewers.

We link to the OkHttp docs early in step 3, right before the tabs that you can see the closing tags for at the very top of this PR. I think that's close enough to this note to be useful, but I'm not against adding the link again if you're concerned about users getting the two confused.

Yes, linking to the OkHttp docs is a good idea. I would put the link on the phrase "network interceptor."

content/en/tracing/trace_collection/custom_instrumentation/android/otel.md

urseberry · 2025-05-16T21:44:41Z

content/en/real_user_monitoring/mobile_and_tv_monitoring/android/setup.md

@@ -417,8 +417,31 @@ OkHttpClient okHttpClient = new OkHttpClient.Builder()
 {{% /tab %}}
 {{< /tabs >}}

+If you want RUM resources and Spans to be automatically created for your OkHttp requests, you can use the `DatadogInterceptor` as an interceptor.


Suggested change

If you want RUM resources and Spans to be automatically created for your OkHttp requests, you can use the `DatadogInterceptor` as an interceptor.

To automatically create RUM resources and spans for your OkHttp requests, use the `DatadogInterceptor` as an interceptor.

urseberry · 2025-05-16T21:46:40Z

content/en/real_user_monitoring/mobile_and_tv_monitoring/android/setup.md

 This records each request processed by the `OkHttpClient` as a resource, with all the relevant information (URL, method, status code, and error) automatically filled in. Only the network requests that started when a view is active are tracked. To track requests when your application is in the background, [create a view manually][13].

+In case you want to monitor the network redirects or retries, you can use the `DatadogInterceptor` as a network interceptor.


Suggested change

In case you want to monitor the network redirects or retries, you can use the `DatadogInterceptor` as a network interceptor.

To monitor the network redirects or retries, you can use the `DatadogInterceptor` as a network interceptor.

urseberry · 2025-05-16T21:47:08Z

content/en/real_user_monitoring/mobile_and_tv_monitoring/android/setup.md

 This records each request processed by the `OkHttpClient` as a resource, with all the relevant information (URL, method, status code, and error) automatically filled in. Only the network requests that started when a view is active are tracked. To track requests when your application is in the background, [create a view manually][13].

+In case you want to monitor the network redirects or retries, you can use the `DatadogInterceptor` as a network interceptor.


Yes, linking to the OkHttp docs is a good idea. I would put the link on the phrase "network interceptor."

urseberry · 2025-05-16T21:49:42Z

content/en/real_user_monitoring/mobile_and_tv_monitoring/android/setup.md

+{{% /tab %}}
+{{< /tabs >}}
+
+**Note**: In case you only want to have Spans without RUM resources, you can use the `TracingInterceptor` instead of `DatadogInterceptor` the same way we explained above.


Suggested change

**Note**: In case you only want to have Spans without RUM resources, you can use the `TracingInterceptor` instead of `DatadogInterceptor` the same way we explained above.

**Note**: To use spans but not RUM resources, you can use the `TracingInterceptor` instead of `DatadogInterceptor` as described above.

janine-c

Looks great! I have some suggestions to try and make the structure more readable, but they're subject to what info you think would be most helpful - let me know what you think and how you think we can improve them 🙂

janine-c · 2025-05-16T21:04:45Z

content/en/real_user_monitoring/mobile_and_tv_monitoring/android/setup.md

 This records each request processed by the `OkHttpClient` as a resource, with all the relevant information (URL, method, status code, and error) automatically filled in. Only the network requests that started when a view is active are tracked. To track requests when your application is in the background, [create a view manually][13].

+In case you want to monitor the network redirects or retries, you can use the `DatadogInterceptor` as a network interceptor.


We link to the OkHttp docs early in step 3, right before the tabs that you can see the closing tags for at the very top of this PR. I think that's close enough to this note to be useful, but I'm not against adding the link again if you're concerned about users getting the two confused.

janine-c · 2025-05-16T21:45:59Z

content/en/real_user_monitoring/mobile_and_tv_monitoring/android/setup.md

+If you want RUM resources and Spans to be automatically created for your OkHttp requests, you can use the `DatadogInterceptor` as an interceptor.
+
 This records each request processed by the `OkHttpClient` as a resource, with all the relevant information (URL, method, status code, and error) automatically filled in. Only the network requests that started when a view is active are tracked. To track requests when your application is in the background, [create a view manually][13].

+In case you want to monitor the network redirects or retries, you can use the `DatadogInterceptor` as a network interceptor.
+
+{{< tabs >}}
+{{% tab "Kotlin" %}}
+```kotlin
+val okHttpClient = OkHttpClient.Builder()
+    .addNetworkInterceptor(DatadogInterceptor.Builder(tracedHostsWithHeaderType).build())
+    .build()
+```
+{{% /tab %}}
+{{% tab "Java" %}}
+```java
+OkHttpClient okHttpClient = new OkHttpClient.Builder()
+    .addNetworkInterceptor(new DatadogInterceptor.Builder(tracedHostsWithHeaderType).build())
+    .build();
+```
+{{% /tab %}}
+{{< /tabs >}}


The two notes about using DatadogInterceptor seem similar to each other; I'm wondering if someone reading quickly might skip "network" and get confused.

I'm not sure I totally understand the intended placement of the paragraphs as they are now; I suspect that more should be embedded under step 3 than currently is, and that we can use some further embedding to make the relationships between these pieces more clear. I was wondering if this would make sense to you:

Suggested change

If you want RUM resources and Spans to be automatically created for your OkHttp requests, you can use the `DatadogInterceptor` as an interceptor.

This records each request processed by the `OkHttpClient` as a resource, with all the relevant information (URL, method, status code, and error) automatically filled in. Only the network requests that started when a view is active are tracked. To track requests when your application is in the background, [create a view manually][13].

In case you want to monitor the network redirects or retries, you can use the `DatadogInterceptor` as a network interceptor.

{{< tabs >}}

{{% tab "Kotlin" %}}

```kotlin

val okHttpClient = OkHttpClient.Builder()

.addNetworkInterceptor(DatadogInterceptor.Builder(tracedHostsWithHeaderType).build())

.build()

```

{{% /tab %}}

{{% tab "Java" %}}

```java

OkHttpClient okHttpClient = new OkHttpClient.Builder()

.addNetworkInterceptor(new DatadogInterceptor.Builder(tracedHostsWithHeaderType).build())

.build();

```

{{% /tab %}}

{{< /tabs >}}

- If you want RUM resources and Spans to be automatically created for your OkHttp requests, you can use the `DatadogInterceptor` as an interceptor.

- This records each request processed by the `OkHttpClient` as a resource, with all the relevant information (URL, method, status code, and error) automatically filled in. Only the network requests that started when a view is active are tracked. To track requests when your application is in the background, [create a view manually][13].

- In case you want to monitor the network redirects or retries, you can use the `DatadogInterceptor` as a network interceptor:

{{< tabs >}}

{{% tab "Kotlin" %}}

\```kotlin

val okHttpClient = OkHttpClient.Builder()

.addNetworkInterceptor(DatadogInterceptor.Builder(tracedHostsWithHeaderType).build())

.build()

\```

{{% /tab %}}

{{% tab "Java" %}}

\```java

OkHttpClient okHttpClient = new OkHttpClient.Builder()

.addNetworkInterceptor(new DatadogInterceptor.Builder(tracedHostsWithHeaderType).build())

.build();

\```

{{% /tab %}}

{{< /tabs >}}

Note that in order to make that suggestion render properly in GitHub, I had to escape the code samples, so if you accept that change, you have to un-escape them. I don't know how to make that less buggy 😬

This is what that would look like:

janine-c · 2025-05-16T21:49:06Z

content/en/real_user_monitoring/mobile_and_tv_monitoring/android/setup.md

+**Note**: In case you only want to have Spans without RUM resources, you can use the `TracingInterceptor` instead of `DatadogInterceptor` the same way we explained above.
+
 **Note**: If you also use multiple Interceptors, add `DatadogInterceptor` first.


Suggested change

**Note**: In case you only want to have Spans without RUM resources, you can use the `TracingInterceptor` instead of `DatadogInterceptor` the same way we explained above.

**Note**: If you also use multiple Interceptors, add `DatadogInterceptor` first.

**Notes**:

- If you only want to have Spans without RUM resources, you can use the `TracingInterceptor` in the place of the `DatadogInterceptor`.

- If you also use multiple Interceptors, add `DatadogInterceptor` first.

mariusc83 self-assigned this May 16, 2025

mariusc83 requested a review from a team as a code owner May 16, 2025 08:30

plousada approved these changes May 16, 2025

View reviewed changes

0xnm reviewed May 16, 2025

View reviewed changes

mariusc83 force-pushed the mconstantin/rum-7538/update-fix-tracing-docs branch from 0af7196 to 35a3855 Compare May 16, 2025 09:33

Update the Android OkHttp instrumentation docs and fix some Otel docs

abcabfb

mariusc83 force-pushed the mconstantin/rum-7538/update-fix-tracing-docs branch from 35a3855 to abcabfb Compare May 16, 2025 09:35

urseberry reviewed May 16, 2025

View reviewed changes

janine-c reviewed May 16, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update the Android OkHttp instrumentation docs and fix some Otel docs #29392

Update the Android OkHttp instrumentation docs and fix some Otel docs #29392

mariusc83 commented May 16, 2025

github-actions bot commented May 16, 2025

0xnm May 16, 2025

mariusc83 May 16, 2025

janine-c May 16, 2025

urseberry May 16, 2025

urseberry May 16, 2025

urseberry May 16, 2025

urseberry May 16, 2025

urseberry May 16, 2025

janine-c left a comment

janine-c May 16, 2025

janine-c May 16, 2025

janine-c May 16, 2025

		This records each request processed by the `OkHttpClient` as a resource, with all the relevant information (URL, method, status code, and error) automatically filled in. Only the network requests that started when a view is active are tracked. To track requests when your application is in the background, [create a view manually][13].

		In case you want to monitor the network redirects or retries, you can use the `DatadogInterceptor` as a network interceptor.

	If you want RUM resources and Spans to be automatically created for your OkHttp requests, you can use the `DatadogInterceptor` as an interceptor.
	To automatically create RUM resources and spans for your OkHttp requests, use the `DatadogInterceptor` as an interceptor.

	In case you want to monitor the network redirects or retries, you can use the `DatadogInterceptor` as a network interceptor.
	To monitor the network redirects or retries, you can use the `DatadogInterceptor` as a network interceptor.

	Note: In case you only want to have Spans without RUM resources, you can use the `TracingInterceptor` instead of `DatadogInterceptor` the same way we explained above.
	Note: To use spans but not RUM resources, you can use the `TracingInterceptor` instead of `DatadogInterceptor` as described above.

		Note: In case you only want to have Spans without RUM resources, you can use the `TracingInterceptor` instead of `DatadogInterceptor` the same way we explained above.

		Note: If you also use multiple Interceptors, add `DatadogInterceptor` first.

Update the Android OkHttp instrumentation docs and fix some Otel docs #29392

Are you sure you want to change the base?

Update the Android OkHttp instrumentation docs and fix some Otel docs #29392

Conversation

mariusc83 commented May 16, 2025

What does this PR do? What is the motivation?

Additions to Android setup documentation:

Updates to custom instrumentation documentation:

Merge instructions

Additional notes

github-actions bot commented May 16, 2025

Preview links (active after the build_preview check completes)

Modified Files

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

janine-c left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Preview links (active after the `build_preview` check completes)