Apollo 5 Integration for Spring
Learn how to capture tracing information and failed GraphQL requests from Apollo Kotlin 5.
To capture transactions, first set up tracing.
Sentry's Apollo 5 integration provides SentryApollo5Interceptor and SentryApollo5HttpInterceptor. Together, they create spans and breadcrumbs for outgoing HTTP requests made with an Apollo Kotlin 5 GraphQL client. The integration can also report failed GraphQL requests as error events.
Install the Apollo 5 integration:
<dependency>
<groupId>io.sentry</groupId>
<artifactId>sentry-apollo-5</artifactId>
<version>8.58.0</version>
</dependency>
<dependency>
<groupId>io.sentry</groupId>
<artifactId>sentry-apollo-5</artifactId>
<version>8.58.0</version>
</dependency>
implementation 'io.sentry:sentry-apollo-5:8.58.0'
libraryDependencies += "io.sentry" % "sentry-apollo-5" % "8.58.0"
For other dependency managers, see the central Maven repository.
Use the sentryTracing extension to add both Sentry interceptors to ApolloClient.Builder:
import com.apollographql.apollo.ApolloClient;
import io.sentry.apollo5.SentryApolloBuilderExtensionsKt;
ApolloClient apollo = SentryApolloBuilderExtensionsKt
.sentryTracing(new ApolloClient.Builder())
.serverUrl("https://your-api-host/graphql")
.build();
import com.apollographql.apollo.ApolloClient;
import io.sentry.apollo5.SentryApolloBuilderExtensionsKt;
ApolloClient apollo = SentryApolloBuilderExtensionsKt
.sentryTracing(new ApolloClient.Builder())
.serverUrl("https://your-api-host/graphql")
.build();
import com.apollographql.apollo.ApolloClient
import io.sentry.apollo5.sentryTracing
val apollo = ApolloClient.Builder()
.serverUrl("https://your-api-host/graphql")
.sentryTracing()
.build()
The extension adds the Apollo interceptor before the cache and adds the HTTP interceptor to Apollo's default network transport. A response served from the normalized cache doesn't create an HTTP span.
Because HttpInterceptors need to be added to the NetworkTransport, the Sentry interceptors need to be added manually if you're using a custom NetworkTransport. Apollo rejects builder-level HTTP interceptors in that case, so calling sentryTracing() fails:
import com.apollographql.apollo.ApolloClient;
import com.apollographql.apollo.interceptor.ApolloInterceptor;
import com.apollographql.apollo.network.http.HttpNetworkTransport;
import io.sentry.apollo5.SentryApollo5HttpInterceptor;
import io.sentry.apollo5.SentryApollo5Interceptor;
ApolloClient apollo = new ApolloClient.Builder()
.networkTransport(
new HttpNetworkTransport.Builder()
.serverUrl("https://your-api-host/graphql")
.addInterceptor(new SentryApollo5HttpInterceptor())
.build())
.addInterceptor(
new SentryApollo5Interceptor(),
ApolloInterceptor.InsertionPoint.BeforeCache)
.build();
import com.apollographql.apollo.ApolloClient;
import com.apollographql.apollo.interceptor.ApolloInterceptor;
import com.apollographql.apollo.network.http.HttpNetworkTransport;
import io.sentry.apollo5.SentryApollo5HttpInterceptor;
import io.sentry.apollo5.SentryApollo5Interceptor;
ApolloClient apollo = new ApolloClient.Builder()
.networkTransport(
new HttpNetworkTransport.Builder()
.serverUrl("https://your-api-host/graphql")
.addInterceptor(new SentryApollo5HttpInterceptor())
.build())
.addInterceptor(
new SentryApollo5Interceptor(),
ApolloInterceptor.InsertionPoint.BeforeCache)
.build();
import com.apollographql.apollo.ApolloClient
import com.apollographql.apollo.interceptor.ApolloInterceptor
import com.apollographql.apollo.network.http.HttpNetworkTransport
import io.sentry.apollo5.SentryApollo5HttpInterceptor
import io.sentry.apollo5.SentryApollo5Interceptor
val transport = HttpNetworkTransport.Builder()
.serverUrl("https://your-api-host/graphql")
.addInterceptor(SentryApollo5HttpInterceptor())
.build()
val apollo = ApolloClient.Builder()
.networkTransport(transport)
.addInterceptor(
SentryApollo5Interceptor(),
ApolloInterceptor.InsertionPoint.BeforeCache,
)
.build()
The default Apollo HTTP request composer copies operation metadata through Apollo's execution context. If your transport uses a custom HttpRequestComposer, call addExecutionContext(apolloRequest.executionContext) when building the HttpRequest. Without this context, Sentry still creates an HTTP span, but it won't contain the GraphQL operation name, type, ID, or variables.
Important
Apollo Kotlin uses Kotlin coroutines. Make sure each coroutine has access to the correct Sentry context by using Sentry's coroutine support.
Pass a SentryContext when launching a coroutine so that Apollo spans attach to the current Sentry context:
import io.sentry.kotlin.SentryContext
import kotlinx.coroutines.launch
launch(SentryContext()) {
val response = apollo.query(LaunchDetailsQuery(launchId)).execute()
}
import io.sentry.kotlin.SentryContext
import kotlinx.coroutines.launch
launch(SentryContext()) {
val response = apollo.query(LaunchDetailsQuery(launchId)).execute()
}
Use SentryApollo5HttpInterceptor.BeforeSpanCallback to modify or drop request spans. Return the span to keep it, or return null to drop it:
import com.apollographql.apollo.ApolloClient;
import io.sentry.apollo5.SentryApolloBuilderExtensionsKt;
import java.util.Collections;
ApolloClient apollo = SentryApolloBuilderExtensionsKt.sentryTracing(
new ApolloClient.Builder(),
true,
Collections.singletonList(".*"),
(span, request, response) -> {
if ("query LaunchDetails".equals(span.getDescription())) {
span.setTag("tag-name", "tag-value");
}
return span;
})
.serverUrl("https://your-api-host/graphql")
.build();
import com.apollographql.apollo.ApolloClient;
import io.sentry.apollo5.SentryApolloBuilderExtensionsKt;
import java.util.Collections;
ApolloClient apollo = SentryApolloBuilderExtensionsKt.sentryTracing(
new ApolloClient.Builder(),
true,
Collections.singletonList(".*"),
(span, request, response) -> {
if ("query LaunchDetails".equals(span.getDescription())) {
span.setTag("tag-name", "tag-value");
}
return span;
})
.serverUrl("https://your-api-host/graphql")
.build();
import com.apollographql.apollo.ApolloClient
import io.sentry.apollo5.sentryTracing
val apollo = ApolloClient.Builder()
.serverUrl("https://your-api-host/graphql")
.sentryTracing { span, request, response ->
if (span.description == "query LaunchDetails") {
span.setTag("tag-name", "tag-value")
}
span
}
.build()
The integration reports a failed GraphQL response when its JSON body contains an errors array. This also covers GraphQL errors returned with an HTTP 200 status. The event contains request and response context such as the URL, status code, and body data.
Sentry groups these events by operation name, operation type, and status code. Failed request capture is enabled by default. Disable it with captureFailedRequests:
import com.apollographql.apollo.ApolloClient
import io.sentry.apollo5.sentryTracing
val apollo = ApolloClient.Builder()
.serverUrl("https://your-api-host/graphql")
.sentryTracing(captureFailedRequests = false)
.build()
import com.apollographql.apollo.ApolloClient
import io.sentry.apollo5.sentryTracing
val apollo = ApolloClient.Builder()
.serverUrl("https://your-api-host/graphql")
.sentryTracing(captureFailedRequests = false)
.build()
By default, the integration captures failed responses from every target. Restrict capture with failedRequestTargets, using regular expressions or plain strings. A plain string matches when the request URL contains it:
import com.apollographql.apollo.ApolloClient
import io.sentry.apollo5.sentryTracing
val apollo = ApolloClient.Builder()
.serverUrl("https://your-api-host/graphql")
.sentryTracing(
captureFailedRequests = true,
failedRequestTargets = listOf("myapi.com"),
)
.build()
import com.apollographql.apollo.ApolloClient
import io.sentry.apollo5.sentryTracing
val apollo = ApolloClient.Builder()
.serverUrl("https://your-api-host/graphql")
.sentryTracing(
captureFailedRequests = true,
failedRequestTargets = listOf("myapi.com"),
)
.build()
Use Data Collection to control headers, cookies, URL query parameters, request and response bodies, GraphQL documents, and GraphQL variables. For example, disable GraphQL variables and all HTTP body collection:
import io.sentry.Sentry
Sentry.init { options ->
options.dataCollection.graphql.variables = false
options.dataCollection.httpBodies = emptySet()
}
import io.sentry.Sentry
Sentry.init { options ->
options.dataCollection.graphql.variables = false
options.dataCollection.httpBodies = emptySet()
}
Configuring either field activates the Data Collection defaults for omitted fields. GraphQL request and response bodies may contain sensitive data, so review both graphql and httpBodies before enabling them. You can also customize the event and scrub application-specific data yourself.
Use the request and response stored in the event hint to customize failed GraphQL events:
import com.apollographql.apollo.api.http.HttpRequest
import com.apollographql.apollo.api.http.HttpResponse
import io.sentry.Sentry
import io.sentry.SentryOptions.BeforeSendCallback
import io.sentry.TypeCheckHint.APOLLO_REQUEST
import io.sentry.TypeCheckHint.APOLLO_RESPONSE
Sentry.init { options ->
options.beforeSend = BeforeSendCallback { event, hint ->
val request = hint.getAs(APOLLO_REQUEST, HttpRequest::class.java)
val response = hint.getAs(APOLLO_RESPONSE, HttpResponse::class.java)
// Customize the event, or return null to drop it.
event
}
}
import com.apollographql.apollo.api.http.HttpRequest
import com.apollographql.apollo.api.http.HttpResponse
import io.sentry.Sentry
import io.sentry.SentryOptions.BeforeSendCallback
import io.sentry.TypeCheckHint.APOLLO_REQUEST
import io.sentry.TypeCheckHint.APOLLO_RESPONSE
Sentry.init { options ->
options.beforeSend = BeforeSendCallback { event, hint ->
val request = hint.getAs(APOLLO_REQUEST, HttpRequest::class.java)
val response = hint.getAs(APOLLO_RESPONSE, HttpResponse::class.java)
// Customize the event, or return null to drop it.
event
}
}
- Failed GraphQL request detection checks the raw JSON response body for an
errorsfield. - Failed request detection is skipped for streaming responses such as
multipart/mixedandtext/event-stream. The integration still records spans and breadcrumbs for these responses. - WebSocket subscriptions aren't instrumented.
- Batching behavior depends on HTTP interceptor ordering.
- Responses served from Apollo's normalized cache don't create HTTP spans.
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").