Skip to content

Commit ecdd0ed

Browse files
lciancoolguyzone
lcian
and
coolguyzone
authored
feat(android/java): document Ktor Client integration (#14457)
Co-authored-by: Alex Krawiec <[email protected]>
1 parent 6726d1c commit ecdd0ed

File tree

2 files changed

+359
-0
lines changed

2 files changed

+359
-0
lines changed

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

Lines changed: 181 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,181 @@
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 should avoid using this integration, otherwise the SDK will produce duplicate data, instrumenting each HTTP request twice.
24+
Use the [Sentry OkHttp integration](/platforms/android/integrations/okhttp/) instead, as it provides more detailed information about HTTP request.
25+
</Alert>
26+
27+
## Install
28+
29+
Add a dependency to the Sentry SDK and to the Sentry Ktor Client Plugin:
30+
31+
```groovy
32+
implementation 'io.sentry:sentry-android:{{@inject packages.version('sentry.java.android', '8.18.0') }}'
33+
implementation 'io.sentry:sentry-ktor-client:{{@inject packages.version('sentry.java.ktor-client', '8.18.0') }}'
34+
```
35+
36+
## Configure
37+
38+
Create the Ktor HTTP Client with your preferred engine, and install the Sentry Ktor Client Plugin:
39+
40+
41+
```kotlin
42+
import io.ktor.client.*
43+
import io.ktor.client.engine.android.*
44+
import io.sentry.ktorClient.SentryKtorClientPlugin
45+
46+
val ktorClient = HttpClient(Android) {
47+
install(SentryKtorClientPlugin)
48+
}
49+
```
50+
51+
## Verify
52+
53+
This snippet includes an HTTP Request and captures an intentional message, so you can verify that everything is working as soon as you set it up:
54+
55+
```kotlin
56+
import io.ktor.client.*
57+
import io.ktor.client.engine.android.*
58+
import io.ktor.client.request.*
59+
import io.ktor.client.statement.*
60+
import io.sentry.ktorClient.SentryKtorClientPlugin
61+
import io.sentry.Sentry
62+
63+
suspend fun run(url: String): String? {
64+
val ktorClient = HttpClient(Android) {
65+
install(SentryKtorClientPlugin)
66+
}
67+
68+
val response = ktorClient.get(url)
69+
val bodyStr = response.bodyAsText()
70+
71+
Sentry.captureMessage("The Message $bodyStr")
72+
73+
return bodyStr
74+
}
75+
```
76+
77+
<Alert>
78+
79+
Learn more about manually capturing an error or message in our <PlatformLink to="/usage/">Usage documentation</PlatformLink>.
80+
81+
</Alert>
82+
83+
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.
84+
85+
## Customize the Recorded Span
86+
87+
The captured span can be customized or dropped with a `BeforeSpanCallback`:
88+
89+
```kotlin
90+
import io.ktor.client.*
91+
import io.ktor.client.engine.android.*
92+
import io.ktor.client.request.*
93+
import io.ktor.http.*
94+
import io.sentry.ISpan
95+
import io.sentry.ktorClient.SentryKtorClientPlugin
96+
97+
val ktorClient = HttpClient(Android) {
98+
install(SentryKtorClientPlugin) {
99+
beforeSpan = { span, request ->
100+
// Drop spans for admin requests
101+
if (request.url.toString().contains("/admin")) {
102+
null
103+
} else {
104+
span
105+
}
106+
}
107+
}
108+
}
109+
```
110+
111+
## HTTP Client Errors
112+
113+
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.
114+
115+
HTTP client error capturing is enabled by default. The SDK captures HTTP client errors with a response code between `500` and `599` by default, but you can change this behavior by configuring the plugin:
116+
117+
```kotlin
118+
import io.ktor.client.*
119+
import io.ktor.client.engine.android.*
120+
import io.sentry.HttpStatusCodeRange
121+
import io.sentry.ktorClient.SentryKtorClientPlugin
122+
123+
val ktorClient = HttpClient(Android) {
124+
install(SentryKtorClientPlugin) {
125+
captureFailedRequests = true
126+
failedRequestStatusCodes = listOf(HttpStatusCodeRange(400, 599))
127+
}
128+
}
129+
```
130+
131+
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 need to match the entire URL — a match occurs as long as the URL contains the string provided in the option.
132+
133+
```kotlin
134+
import io.ktor.client.*
135+
import io.ktor.client.engine.android.*
136+
import io.sentry.ktorClient.SentryKtorClientPlugin
137+
138+
val ktorClient = HttpClient(Android) {
139+
install(SentryKtorClientPlugin) {
140+
captureFailedRequests = true
141+
failedRequestTargets = listOf("myapi.com")
142+
}
143+
}
144+
```
145+
146+
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`:
147+
148+
```xml {filename:AndroidManifest.xml}
149+
<application>
150+
<meta-data android:name="io.sentry.send-default-pii" android:value="true" />
151+
</application>
152+
```
153+
154+
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.
155+
156+
### Customize or Drop the Error Event
157+
158+
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.
159+
160+
The captured error event can be customized or dropped with a `BeforeSendCallback`:
161+
162+
```kotlin
163+
import io.sentry.android.core.SentryAndroid
164+
import io.sentry.SentryOptions.BeforeSendCallback
165+
import io.sentry.TypeCheckHint.KTOR_CLIENT_REQUEST
166+
import io.sentry.TypeCheckHint.KTOR_CLIENT_RESPONSE
167+
import io.ktor.client.request.*
168+
import io.ktor.client.statement.*
169+
170+
SentryAndroid.init(this) { options ->
171+
// Add a callback that will be used before the event is sent to Sentry.
172+
// With this callback, you can modify the event or, when returning null, also discard the event.
173+
options.beforeSend = BeforeSendCallback { event, hint ->
174+
val request = hint.getAs(KTOR_CLIENT_REQUEST, HttpRequest::class.java)
175+
val response = hint.getAs(KTOR_CLIENT_RESPONSE, HttpResponse::class.java)
176+
177+
// customize or drop the event
178+
event
179+
}
180+
}
181+
```

‎docs/platforms/java/common/tracing/instrumentation/ktor-client.mdx

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
---
2+
title: Ktor Client Integration
3+
sidebar_order: 45
4+
sdk: sentry.java.ktor-client
5+
description: "Learn how to capture tracing information when using Ktor Client."
6+
notSupported:
7+
- java.logback
8+
- java.log4j2
9+
- java.jul
10+
---
11+
12+
<Alert>
13+
14+
To be able to capture transactions, you'll need to first <PlatformLink to="/tracing/">set up tracing</PlatformLink>.
15+
16+
</Alert>
17+
18+
The `sentry-ktor-client` library provides [Ktor Client](https://ktor.io/) support for Sentry via the Sentry Ktor Client Plugin.
19+
20+
On this page, we get you up and running with Sentry's Ktor Client Integration.
21+
The integration supports:
22+
- Adding breadcrumbs for each HTTP request.
23+
- 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).
24+
- Capturing certain request failures as errors in Sentry.
25+
26+
The Sentry Ktor Client integration supports Ktor Client version `3.x`.
27+
28+
<Alert level="warning">
29+
If you're using Ktor Client with OKHttp as the engine, and you're already using the [Sentry OkHttp integration](/platforms/java/tracing/instrumentation/okhttp/),
30+
you should avoid using this integration, otherwise the SDK will produce duplicate data, instrumenting each HTTP request twice.
31+
Use the [Sentry OkHttp integration](/platforms/java/tracing/instrumentation/okhttp/) instead, as it provides more detailed information about HTTP request.
32+
</Alert>
33+
34+
## Install
35+
36+
To install the integration:
37+
38+
```groovy {tabTitle:Gradle}
39+
implementation 'io.sentry:sentry-ktor-client:{{@inject packages.version('sentry.java.ktor-client', '8.18.0') }}'
40+
```
41+
42+
## Configure
43+
44+
Create the Ktor HTTP Client with your preferred engine, and install the Sentry Ktor Client Plugin:
45+
46+
```kotlin
47+
import io.ktor.client.*
48+
import io.ktor.client.engine.java.*
49+
import io.sentry.ktorClient.SentryKtorClientPlugin
50+
51+
val ktorClient = HttpClient(Java) {
52+
install(SentryKtorClientPlugin)
53+
}
54+
```
55+
56+
## Verify
57+
58+
This snippet includes an HTTP Request and captures an intentional message, so you can verify that everything is working as soon as you set it up:
59+
60+
```kotlin
61+
import io.ktor.client.*
62+
import io.ktor.client.engine.java.*
63+
import io.ktor.client.request.*
64+
import io.ktor.client.statement.*
65+
import io.sentry.ktorClient.SentryKtorClientPlugin
66+
import io.sentry.Sentry
67+
68+
suspend fun run(url: String): String? {
69+
val ktorClient = HttpClient(Java) {
70+
install(SentryKtorClientPlugin)
71+
}
72+
73+
val response = ktorClient.get(url)
74+
val bodyStr = response.bodyAsText()
75+
76+
Sentry.captureMessage("The Message $bodyStr")
77+
78+
return bodyStr
79+
}
80+
```
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.java.*
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(Java) {
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.java.*
119+
import io.sentry.HttpStatusCodeRange
120+
import io.sentry.ktorClient.SentryKtorClientPlugin
121+
122+
val ktorClient = HttpClient(Java) {
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.java.*
135+
import io.sentry.ktorClient.SentryKtorClientPlugin
136+
137+
val ktorClient = HttpClient(Java) {
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+
```kotlin
148+
Sentry.init { options ->
149+
options.isSendDefaultPii = true
150+
}
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+
The captured error event can be customized or dropped with a `BeforeSendCallback`:
158+
159+
```kotlin
160+
import io.sentry.Sentry
161+
import io.sentry.SentryOptions.BeforeSendCallback
162+
import io.sentry.TypeCheckHint.KTOR_CLIENT_REQUEST
163+
import io.sentry.TypeCheckHint.KTOR_CLIENT_RESPONSE
164+
import io.ktor.client.request.*
165+
import io.ktor.client.statement.*
166+
167+
Sentry.init { options ->
168+
// Add a callback that will be used before the event is sent to Sentry.
169+
// With this callback, you can modify the event or, when returning null, also discard the event.
170+
options.beforeSend = BeforeSendCallback { event, hint ->
171+
val request = hint.getAs(KTOR_CLIENT_REQUEST, HttpRequest::class.java)
172+
val response = hint.getAs(KTOR_CLIENT_RESPONSE, HttpResponse::class.java)
173+
174+
// customize or drop the event
175+
event
176+
}
177+
}
178+
```

0 commit comments

Comments
 (0)