android apollo3 integration (#5289)

Co-authored-by: Isabel <[email protected]>

src/platforms/android/configuration/integrations/apollo3.mdx

@@ -0,0 +1,119 @@
+---
+title: Apollo3
+caseStyle: camelCase
+supportLevel: production
+sdk: sentry.java.apollo-3
+description: "Learn more about the Sentry Apollo3 integration for the Android SDK."
+categories:
+  - mobile
+---
+
+<Note>
+
+Capturing transactions requires that you first <PlatformLink to="/performance/">set up performance monitoring</PlatformLink> if you haven't already.
+
+</Note>
+
+Sentry Apollo3 integration provides the `SentryApollo3Interceptor` and the `SentryApollo3HttpInterceptor`, which create a span for each outgoing HTTP request executed with an [Apollo Kotlin](https://github.com/apollographql/apollo-kotlin) GraphQL client. For easier usage, the integration also provides extension functions on the `ApolloClient.Builder`.
+
+## Install
+
+```groovy {tabTitle:Gradle}
+implementation 'io.sentry:sentry-apollo-3:{{ packages.version('sentry.java.apollo-3', '6.1.4') }}'
+```
+
+For other dependency managers, see the [central Maven repository](https://search.maven.org/artifact/io.sentry/sentry-apollo-3).
+
+## Configure With Extension
+
+Add `Interceptors` to `ApolloClient.Builder` using `ApolloBuilderExtensions`:
+
+```java
+import com.apollographql.apollo3.ApolloClient;
+import io.sentry.apollo3.SentryApolloBuilderExtensionsKt;
+
+ApolloClient apollo = SentryApolloBuilderExtensionsKt.sentryTracing(new ApolloClient.Builder())
+    .serverUrl("https://your-api-host/")
+    .build();
+```
+
+```kotlin
+import com.apollographql.apollo3.ApolloClient
+import io.sentry.apollo3.sentryTracing
+
+val apollo = ApolloClient.builder()
+    .serverUrl("https://your-api-host/")
+    .sentryTracing()
+    .build()
+```
+
+## Manual Configuration
+When using a custom `NetworkTransport`, the `SentryInterceptors` need to be added manually, because `HttpInterceptors` need to be added to the `NetworkTransport`:
+
+```java
+import com.apollographql.apollo3.ApolloClient;
+import com.apollographql.apollo3.network.http.HttpNetworkTransport;
+import io.sentry.apollo3.SentryApollo3HttpInterceptor;
+import io.sentry.apollo3.SentryApollo3Interceptor;
+
+ApolloClient apollo = new ApolloClient.Builder()
+        .networkTransport(
+            new HttpNetworkTransport.Builder()
+                .serverUrl("https://your-api-host/")
+                .addInterceptor(new SentryApollo3HttpInterceptor())
+                .build())
+        .addInterceptor(new SentryApollo3Interceptor())
+        .build();
+```
+
+```kotlin
+import com.apollographql.apollo3.ApolloClient
+import io.sentry.apollo3.SentryApollo3HttpInterceptor
+import io.sentry.apollo3.SentryApollo3Interceptor
+import com.apollographql.apollo3.network.http.HttpNetworkTransport
+
+val apollo = ApolloClient.builder()
+    .networkTransport(
+        HttpNetworkTransport.Builder()
+            .serverUrl("https://apollo-fullstack-tutorial.herokuapp.com/graphql")
+            .addInterceptor(SentryApollo3HttpInterceptor())
+            .build()
+    )
+    .addInterceptor(SentryApollo3Interceptor())
+    .build()
+```
+
+## Modify or Drop Spans
+
+Spans created around requests can be modified or dropped using `SentryApollo3HttpInterceptor.BeforeSpanCallback` passed to `SentryApollo3HttpInterceptor` or the `sentryTracing` extension function:
+
+```java
+import com.apollographql.apollo3.ApolloClient;
+import io.sentry.apollo3.SentryApolloBuilderExtensionsKt;
+
+ApolloClient apollo = SentryApolloBuilderExtensionsKt.sentryTracing(
+            new ApolloClient.Builder(),
+            (span, request, response) -> {
+              if ("LaunchDetails".equals(span.getOperation())) {
+                span.setTag("tag-name", "tag-value");
+              }
+              return span;
+            })
+        .serverUrl("https://your-api-host/")
+        .build();
+```
+
+```kotlin
+import com.apollographql.apollo3.ApolloClient
+import io.sentry.apollo3.sentryTracing
+
+val apollo = ApolloClient.builder()
+    .serverUrl("https://apollo-fullstack-tutorial.herokuapp.com/graphql")
+    .sentryTracing { span, request, response ->
+        if ("LaunchDetails" == span.operation) {
+            span.setTag("tag-name", "tag-value")
+        }
+        span
+    }
+    .build()
+```

src/platforms/java/common/performance/instrumentation/apollo.mdx

@@ -75,7 +75,9 @@ Sentry.init(options -> {
 ```
 
 <Note>
+
 In Global Hub Mode, all threads use the same Hub.
+
 </Note>
 
 ## Using With Kotlin Coroutines

src/platforms/java/common/performance/instrumentation/apollo3.mdx

@@ -0,0 +1,175 @@
+---
+title: Apollo3 Integration
+sidebar_order: 31
+description: "Learn how to capture the performance of Apollo GraphQL client."
+notSupported:
+  - java.logback
+  - java.log4j2
+  - java.jul
+---
+
+<Note>
+
+Capturing transactions requires that you first <PlatformLink to="/performance/">set up performance monitoring</PlatformLink> if you haven't already.
+
+</Note>
+
+Sentry Apollo3 integration provides the `SentryApollo3Interceptor` and the `SentryApollo3HttpInterceptor`, which create a span for each outgoing HTTP request executed with an [Apollo Kotlin](https://github.com/apollographql/apollo-kotlin) GraphQL client. For easier usage, the integration also provides extension functions on the `ApolloClient.Builder`.
+
+## Install
+
+```xml {tabTitle:Maven}
+<dependency>
+    <groupId>io.sentry</groupId>
+    <artifactId>sentry-apollo-3</artifactId>
+    <version>{{ packages.version('sentry.java.apollo3', '5.2.0') }}</version>
+</dependency>
+```
+
+```groovy {tabTitle:Gradle}
+implementation 'io.sentry:sentry-apollo-3:{{ packages.version('sentry.java.apollo3', '5.2.0') }}'
+```
+
+```scala {tabTitle: SBT}
+libraryDependencies += "io.sentry" % "sentry-apollo-3" % "{{ packages.version('sentry.java.apollo3', '5.2.0') }}"
+```
+
+For other dependency managers, see the [central Maven repository](https://search.maven.org/artifact/io.sentry/sentry-apollo-3).
+
+## Configure With Extension
+
+Add `Interceptors` to `ApolloClient.Builder` using `SentryApolloBuilderExtensions`:
+
+```java
+import com.apollographql.apollo3.ApolloClient;
+import io.sentry.apollo3.SentryApolloBuilderExtensionsKt;
+
+ApolloClient apollo = SentryApolloBuilderExtensionsKt.sentryTracing(new ApolloClient.Builder())
+    .serverUrl("https://your-api-host/")
+    .build();
+```
+
+```kotlin
+import com.apollographql.apollo3.ApolloClient
+import io.sentry.apollo3.sentryTracing
+
+val apollo = ApolloClient.builder()
+    .serverUrl("https://your-api-host/")
+    .sentryTracing()
+    .build()
+```
+
+## Manual Configuration
+When using a custom `NetworkTransport`, the `SentryInterceptors` need to be added manually, because `HttpInterceptors` need to be added to the `NetworkTransport`:
+
+```java
+import com.apollographql.apollo3.ApolloClient;
+import com.apollographql.apollo3.network.http.HttpNetworkTransport;
+import io.sentry.apollo3.SentryApollo3HttpInterceptor;
+import io.sentry.apollo3.SentryApollo3Interceptor;
+
+ApolloClient apollo = new ApolloClient.Builder()
+        .networkTransport(
+            new HttpNetworkTransport.Builder()
+                .serverUrl("https://your-api-host/")
+                .addInterceptor(new SentryApollo3HttpInterceptor())
+                .build())
+        .addInterceptor(new SentryApollo3Interceptor())
+        .build();
+```
+
+```kotlin
+import com.apollographql.apollo3.ApolloClient
+import io.sentry.apollo3.SentryApollo3HttpInterceptor
+import io.sentry.apollo3.SentryApollo3Interceptor
+import com.apollographql.apollo3.network.http.HttpNetworkTransport
+
+val apollo = ApolloClient.builder()
+    .networkTransport(
+        HttpNetworkTransport.Builder()
+            .serverUrl("https://apollo-fullstack-tutorial.herokuapp.com/graphql")
+            .addInterceptor(SentryApollo3HttpInterceptor())
+            .build()
+    )
+    .addInterceptor(SentryApollo3Interceptor())
+    .build()
+```
+
+<Alert level="info" title="Important">
+
+Apollo Kotlin is built with Kotlin coroutines. This means that `SentryApolloInterceptor` can be used with Java using only Global Hub Mode (single Hub used by all threads), with Kotlin using single Hub mode, or with <PlatformLink to="/enriching-events/scopes/#kotlin-coroutines">Sentry's coroutines support</PlatformLink>.
+
+</Alert>
+
+## Using With Java
+
+Configure Global Hub Mode:
+
+```java
+import io.sentry.Sentry;
+
+Sentry.init(options -> {
+  ..
+}, true)
+```
+
+<Note>
+
+In Global Hub Mode, all threads use the same Hub.
+
+</Note>
+
+## Using With Kotlin Coroutines
+
+To make sure that a coroutine has access to the correct Sentry context, provide an instance of `SentryContext` when launching a coroutine:
+
+```kotlin
+import com.apollographql.apollo3.ApolloClient
+import com.apollographql.apollo3.exception.ApolloException
+import io.sentry.kotlin.SentryContext
+import kotlinx.coroutines.launch
+
+launch(SentryContext()) {
+  val response = try {
+    apollo.query(..).toDeferred().await()
+  } catch (e: ApolloException) {
+    // handle protocol errors
+    return@launch
+  }
+}
+```
+
+## Modify or Drop Spans
+
+Spans created around requests can be modified or dropped using `SentryApollo3HttpInterceptor.BeforeSpanCallback` passed to `SentryApollo3HttpInterceptor` or the `sentryTracing` extension function:
+
+```java
+import com.apollographql.apollo3.ApolloClient;
+import io.sentry.apollo3.SentryApolloBuilderExtensionsKt;
+
+ApolloClient apollo = SentryApolloBuilderExtensionsKt.sentryTracing(
+            new ApolloClient.Builder(),
+            (span, request, response) -> {
+              if ("LaunchDetails".equals(span.getOperation())) {
+                span.setTag("tag-name", "tag-value");
+              }
+              return span;
+            })
+        .serverUrl("https://your-api-host/")
+        .build();
+```
+
+```kotlin
+import com.apollographql.apollo3.ApolloClient
+import io.sentry.apollo3.sentryTracing
+
+val apollo = ApolloClient.builder()
+    .serverUrl("https://apollo-fullstack-tutorial.herokuapp.com/graphql")
+    .sentryTracing { span, request, response ->
+        if ("LaunchDetails" == span.operation) {
+            span.setTag("tag-name", "tag-value")
+        }
+        span
+    }
+    .build()
+```