Skip to content

Commit 6913800

Browse files
lcianlcian
committed
feat(android): document Ktor Client integration
1 parent 4f124dc commit 6913800

File tree

1 file changed

+180
-0
lines changed
  • docs/platforms/android/integrations/ktor-client

1 file changed

+180
-0
lines changed

‎docs/platforms/android/integrations/ktor-client/index.mdx‎

Lines changed: 180 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,180 @@
1+
---
2+
title: Ktor Client
3+
caseStyle: camelCase
4+
supportLevel: production
5+
sdk: sentry.java.ktor-client
6+
description: "Learn more about the Sentry Ktor Client integration for the Android SDK."
7+
categories:
8+
- mobile
9+
---
10+
11+
The `sentry-ktor-client` library provides [Ktor Client](https://ktor.io/) support for Sentry via the Sentry Ktor Client Plugin.
12+
13+
On this page, we get you up and running with Sentry's Ktor Client Integration.
14+
The integration supports:
15+
- Adding breadcrumbs for each HTTP request
16+
- Capturing spans for each HTTP Request, with support for distributed tracing. The span will be created as a child of the current span bound to the scope (if any)
17+
- Capturing certain request failures as errors in Sentry.
18+
19+
The Sentry Ktor Client integration supports Ktor Client version `3.x`.
20+
21+
<Alert level="warning">
22+
If you're using Ktor Client with OKHttp as the engine, and you're already using the [Sentry OkHttp integration](/platforms/android/integrations/okhttp/),
23+
either with manual or automatic installation (via the Sentry Android Gradle Plugin), you shouldn't use this integration, otherwise the SDK will produce duplicate data, instrumenting each HTTP request twice.
24+
</Alert>
25+
26+
## Install
27+
28+
Add a dependency to the Sentry SDK and to the Sentry Ktor Client Plugin:
29+
30+
```groovy
31+
implementation 'io.sentry:sentry-android:{{@inject packages.version('sentry.java.android', '8.18.0') }}'
32+
implementation 'io.sentry:sentry-ktor-client:{{@inject packages.version('sentry.java.ktor-client', '8.18.0') }}'
33+
```
34+
35+
## Configure
36+
37+
Create the Ktor HTTP Client with your preferred engine, and install the Sentry Ktor Client Plugin:
38+
39+
40+
```kotlin
41+
import io.ktor.client.*
42+
import io.ktor.client.engine.android.*
43+
import io.sentry.ktorClient.SentryKtorClientPlugin
44+
45+
val ktorClient = HttpClient(Android) {
46+
install(SentryKtorClientPlugin)
47+
}
48+
```
49+
50+
## Verify
51+
52+
This snippet includes a HTTP Request and captures an intentional message, so you can test that everything is working as soon as you set it up:
53+
54+
```kotlin
55+
import io.ktor.client.*
56+
import io.ktor.client.engine.android.*
57+
import io.ktor.client.request.*
58+
import io.ktor.client.statement.*
59+
import io.sentry.ktorClient.SentryKtorClientPlugin
60+
import io.sentry.Sentry
61+
62+
suspend fun run(url: String): String? {
63+
val ktorClient = HttpClient(Android) {
64+
install(SentryKtorClientPlugin)
65+
}
66+
67+
val response = ktorClient.get(url)
68+
val bodyStr = response.bodyAsText()
69+
70+
Sentry.captureMessage("The Message $bodyStr")
71+
72+
return bodyStr
73+
}
74+
```
75+
76+
<Alert>
77+
78+
Learn more about manually capturing an error or message, in our <PlatformLink to="/usage/">Usage documentation</PlatformLink>.
79+
80+
</Alert>
81+
82+
To view and resolve the recorded message, log into [sentry.io](https://sentry.io) and open your project. Clicking on the error's title will open a page where you can see detailed information and mark it as resolved.
83+
84+
## Customize the Recorded Span
85+
86+
The captured span can be customized or dropped with a `BeforeSpanCallback`:
87+
88+
```kotlin
89+
import io.ktor.client.*
90+
import io.ktor.client.engine.android.*
91+
import io.ktor.client.request.*
92+
import io.ktor.http.*
93+
import io.sentry.ISpan
94+
import io.sentry.ktorClient.SentryKtorClientPlugin
95+
96+
val ktorClient = HttpClient(Android) {
97+
install(SentryKtorClientPlugin) {
98+
beforeSpan = { span, request ->
99+
// Drop spans for admin requests
100+
if (request.url.toString().contains("/admin")) {
101+
null
102+
} else {
103+
span
104+
}
105+
}
106+
}
107+
}
108+
```
109+
110+
## HTTP Client Errors
111+
112+
This feature automatically captures HTTP client errors (like bad response codes) as error events and reports them to Sentry. The error event will contain the `request` and `response` data, including the `url`, `status_code`, and so on.
113+
114+
HTTP client error capturing is enabled by default. The SDK captures HTTP client errors with a response code between `500` and `599`, but you can change this behavior by configuring the plugin:
115+
116+
```kotlin
117+
import io.ktor.client.*
118+
import io.ktor.client.engine.android.*
119+
import io.sentry.HttpStatusCodeRange
120+
import io.sentry.ktorClient.SentryKtorClientPlugin
121+
122+
val ktorClient = HttpClient(Android) {
123+
install(SentryKtorClientPlugin) {
124+
captureFailedRequests = true
125+
failedRequestStatusCodes = listOf(HttpStatusCodeRange(400, 599))
126+
}
127+
}
128+
```
129+
130+
HTTP client errors from every target (`.*` regular expression) are automatically captured, but you can change this behavior by setting the `failedRequestTargets` option with either a regular expression or a plain `String`. A plain string must contain at least one of the items from the list. Plain strings don't have to be full matches, meaning the URL of a request is matched when it contains a string provided through the option.
131+
132+
```kotlin
133+
import io.ktor.client.*
134+
import io.ktor.client.engine.android.*
135+
import io.sentry.ktorClient.SentryKtorClientPlugin
136+
137+
val ktorClient = HttpClient(Android) {
138+
install(SentryKtorClientPlugin) {
139+
captureFailedRequests = true
140+
failedRequestTargets = listOf("myapi.com")
141+
}
142+
}
143+
```
144+
145+
By default, error events won't contain any PII data, such as `Headers` and `Cookies`, but you can change this behavior by setting the `sendDefaultPii` option to `true`:
146+
147+
```xml {filename:AndroidManifest.xml}
148+
<application>
149+
<meta-data android:name="io.sentry.send-default-pii" android:value="true" />
150+
</application>
151+
```
152+
153+
Those events are searchable and you can set alerts on them if you use the `http.url` and `http.status_code` properties. Learn more in our full [Searchable Properties](/concepts/search/searchable-properties/) documentation.
154+
155+
### Customize or Drop the Error Event
156+
157+
To customize or drop the error event, you need to do a [manual initialization](/platforms/android/configuration/manual-init/#manual-initialization) of the Sentry Android SDK.
158+
159+
The captured error event can be customized or dropped with a `BeforeSendCallback`:
160+
161+
```kotlin
162+
import io.sentry.android.core.SentryAndroid
163+
import io.sentry.SentryOptions.BeforeSendCallback
164+
import io.sentry.TypeCheckHint.KTOR_REQUEST
165+
import io.sentry.TypeCheckHint.KTOR_RESPONSE
166+
import io.ktor.client.request.*
167+
import io.ktor.client.statement.*
168+
169+
SentryAndroid.init(this) { options ->
170+
// Add a callback that will be used before the event is sent to Sentry.
171+
// With this callback, you can modify the event or, when returning null, also discard the event.
172+
options.beforeSend = BeforeSendCallback { event, hint ->
173+
val request = hint.getAs(KTOR_REQUEST, HttpRequest::class.java)
174+
val response = hint.getAs(KTOR_RESPONSE, HttpResponse::class.java)
175+
176+
// customize or drop the event
177+
event
178+
}
179+
}
180+
```

0 commit comments

Comments
 (0)