Add Ktor client integration

CHANGELOG.md

@@ -7,6 +7,19 @@
 - Add `SentryUserFeedbackButton` Composable ([#4559](https://github.com/getsentry/sentry-java/pull/4559))
   - Also added `Sentry.showUserFeedbackDialog` static method
 - Add deadlineTimeout option ([#4555](https://github.com/getsentry/sentry-java/pull/4555))
+- Add Ktor client integration ([#4527](https://github.com/getsentry/sentry-java/pull/4527))
+  - To use the integration, add a dependency on `io.sentry:sentry-ktor-client`, then install the `SentryKtorClientPlugin` on your `HttpClient`,
+    e.g.:
+    ```kotlin
+    val client =
+      HttpClient(Java) {
+        install(io.sentry.ktorClient.SentryKtorClientPlugin) {
+          captureFailedRequests = true
+          failedRequestTargets = listOf(".*")
+          failedRequestStatusCodes = listOf(HttpStatusCodeRange(500, 599))
+        }
+      }
+    ```
 
 ### Fixes
 

build.gradle.kts

@@ -69,6 +69,7 @@ apiValidation {
             "sentry-samples-spring-boot-jakarta-opentelemetry-noagent",
             "sentry-samples-spring-boot-webflux",
             "sentry-samples-spring-boot-webflux-jakarta",
+            "sentry-samples-ktor-client",
             "sentry-uitest-android",
             "sentry-uitest-android-benchmark",
             "sentry-uitest-android-critical",

buildSrc/src/main/java/Config.kt

@@ -78,6 +78,7 @@ object Config {
         val SENTRY_OKHTTP_SDK_NAME = "$SENTRY_JAVA_SDK_NAME.okhttp"
         val SENTRY_REACTOR_SDK_NAME = "$SENTRY_JAVA_SDK_NAME.reactor"
         val SENTRY_KOTLIN_EXTENSIONS_SDK_NAME = "$SENTRY_JAVA_SDK_NAME.kotlin-extensions"
+        val SENTRY_KTOR_CLIENT_SDK_NAME = "$SENTRY_JAVA_SDK_NAME.ktor-client"
         val group = "io.sentry"
         val description = "SDK for sentry.io"
         val versionNameProp = "versionName"

gradle/libs.versions.toml

@@ -13,6 +13,7 @@ jackson = "2.18.3"
 jetbrainsCompose = "1.6.11"
 kotlin = "1.9.24"
 kotlin-compatible-version = "1.6"
+ktorClient = "3.0.0"
 logback = "1.2.9"
 log4j2 = "2.20.0"
 nopen = "1.0.1"
@@ -95,6 +96,8 @@ jetbrains-annotations = { module = "org.jetbrains:annotations", version = "23.0.
 kotlin-test-junit = { module = "org.jetbrains.kotlin:kotlin-test-junit", version.ref = "kotlin" }
 kotlinx-coroutines = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-core", version.ref = "coroutines" }
 kotlinx-coroutines-android = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-android", version.ref = "coroutines" }
+ktor-client-core = { module = "io.ktor:ktor-client-core", version.ref = "ktorClient" }
+ktor-client-java = { module = "io.ktor:ktor-client-java", version.ref = "ktorClient" }
 log4j-api = { module = "org.apache.logging.log4j:log4j-api", version.ref = "log4j2" }
 log4j-core = { module = "org.apache.logging.log4j:log4j-core", version.ref = "log4j2" }
 leakcanary = { module = "com.squareup.leakcanary:leakcanary-android", version = "2.14" }

sentry-ktor-client/api/sentry-ktor-client.api

@@ -0,0 +1,34 @@
+public final class io/sentry/ktorClient/BuildConfig {
+	public static final field SENTRY_KTOR_CLIENT_SDK_NAME Ljava/lang/String;
+	public static final field VERSION_NAME Ljava/lang/String;
+}
+
+public final class io/sentry/ktorClient/SentryKtorClientPluginConfig {
+	public fun <init> ()V
+	public final fun getBeforeSpan ()Lio/sentry/ktorClient/SentryKtorClientPluginConfig$BeforeSpanCallback;
+	public final fun getCaptureFailedRequests ()Z
+	public final fun getFailedRequestStatusCodes ()Ljava/util/List;
+	public final fun getFailedRequestTargets ()Ljava/util/List;
+	public final fun getScopes ()Lio/sentry/IScopes;
+	public final fun setBeforeSpan (Lio/sentry/ktorClient/SentryKtorClientPluginConfig$BeforeSpanCallback;)V
+	public final fun setCaptureFailedRequests (Z)V
+	public final fun setFailedRequestStatusCodes (Ljava/util/List;)V
+	public final fun setFailedRequestTargets (Ljava/util/List;)V
+	public final fun setScopes (Lio/sentry/IScopes;)V
+}
+
+public abstract interface class io/sentry/ktorClient/SentryKtorClientPluginConfig$BeforeSpanCallback {
+	public abstract fun execute (Lio/sentry/ISpan;Lio/ktor/client/request/HttpRequest;)Lio/sentry/ISpan;
+}
+
+public class io/sentry/ktorClient/SentryKtorClientPluginContextHook : io/ktor/client/plugins/api/ClientHook {
+	public fun <init> (Lio/sentry/IScopes;)V
+	protected final fun getScopes ()Lio/sentry/IScopes;
+	public synthetic fun install (Lio/ktor/client/HttpClient;Ljava/lang/Object;)V
+	public fun install (Lio/ktor/client/HttpClient;Lkotlin/jvm/functions/Function2;)V
+}
+
+public final class io/sentry/ktorClient/SentryKtorClientPluginKt {
+	public static final fun getSentryKtorClientPlugin ()Lio/ktor/client/plugins/api/ClientPlugin;
+}
+

sentry-ktor-client/build.gradle.kts

@@ -0,0 +1,94 @@
+import net.ltgt.gradle.errorprone.errorprone
+import org.jetbrains.kotlin.config.KotlinCompilerVersion
+import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
+
+plugins {
+  `java-library`
+  kotlin("jvm")
+  jacoco
+  id("io.sentry.javadoc")
+  alias(libs.plugins.errorprone)
+  alias(libs.plugins.gradle.versions)
+  alias(libs.plugins.buildconfig)
+}
+
+tasks.withType<KotlinCompile>().configureEach {
+  kotlinOptions.jvmTarget = JavaVersion.VERSION_1_8.toString()
+}
+
+kotlin { explicitApi() }
+
+dependencies {
+  api(projects.sentry)
+
+  implementation(kotlin(Config.kotlinStdLib, KotlinCompilerVersion.VERSION))
+  api(projects.sentryKotlinExtensions)
+
+  compileOnly(libs.jetbrains.annotations)
+  compileOnly(libs.nopen.annotations)
+  compileOnly(libs.ktor.client.core)
+  errorprone(libs.errorprone.core)
+  errorprone(libs.nopen.checker)
+  errorprone(libs.nullaway)
+
+  testImplementation(projects.sentryTestSupport)
+  testImplementation(libs.kotlin.test.junit)
+  testImplementation(libs.mockito.kotlin)
+  testImplementation(libs.mockito.inline)
+  testImplementation(libs.ktor.client.core)
+  testImplementation(libs.ktor.client.java)
+  testImplementation(libs.okhttp.mockwebserver)
+}
+
+configure<SourceSetContainer> { test { java.srcDir("src/test/java") } }
+
+jacoco { toolVersion = libs.versions.jacoco.get() }
+
+tasks.jacocoTestReport {
+  reports {
+    xml.required.set(true)
+    html.required.set(false)
+  }
+}
+
+tasks {
+  jacocoTestCoverageVerification {
+    violationRules { rule { limit { minimum = Config.QualityPlugins.Jacoco.minimumCoverage } } }
+  }
+  check {
+    dependsOn(jacocoTestCoverageVerification)
+    dependsOn(jacocoTestReport)
+  }
+}
+
+buildConfig {
+  useJavaOutput()
+  packageName("io.sentry.ktorClient")
+  buildConfigField(
+    "String",
+    "SENTRY_KTOR_CLIENT_SDK_NAME",
+    "\"${Config.Sentry.SENTRY_KTOR_CLIENT_SDK_NAME}\"",
+  )
+  buildConfigField("String", "VERSION_NAME", "\"${project.version}\"")
+}
+
+tasks.withType<JavaCompile>().configureEach {
+  dependsOn(tasks.generateBuildConfig)
+  options.errorprone {
+    check("NullAway", net.ltgt.gradle.errorprone.CheckSeverity.ERROR)
+    option("NullAway:AnnotatedPackages", "io.sentry")
+  }
+}
+
+tasks.jar {
+  manifest {
+    attributes(
+      "Sentry-Version-Name" to project.version,
+      "Sentry-SDK-Name" to Config.Sentry.SENTRY_KTOR_CLIENT_SDK_NAME,
+      "Sentry-SDK-Package-Name" to "maven:io.sentry:sentry-ktor-client",
+      "Implementation-Vendor" to "Sentry",
+      "Implementation-Title" to project.name,
+      "Implementation-Version" to project.version,
+    )
+  }
+}

sentry-ktor-client/src/main/java/io/sentry/ktorClient/SentryKtorClientPlugin.kt

@@ -0,0 +1,210 @@
+package io.sentry.ktorClient
+
+import io.ktor.client.HttpClient
+import io.ktor.client.plugins.api.*
+import io.ktor.client.plugins.api.ClientPlugin
+import io.ktor.client.request.*
+import io.ktor.client.statement.*
+import io.ktor.util.*
+import io.ktor.util.pipeline.*
+import io.sentry.BaggageHeader
+import io.sentry.BuildConfig
+import io.sentry.HttpStatusCodeRange
+import io.sentry.IScopes
+import io.sentry.ISpan
+import io.sentry.ScopesAdapter
+import io.sentry.Sentry
+import io.sentry.SentryDate
+import io.sentry.SentryIntegrationPackageStorage
+import io.sentry.SentryOptions
+import io.sentry.SpanStatus
+import io.sentry.kotlin.SentryContext
+import io.sentry.util.IntegrationUtils.addIntegrationToSdkVersion
+import io.sentry.util.Platform
+import io.sentry.util.PropagationTargetsUtils
+import io.sentry.util.SpanUtils
+import io.sentry.util.TracingUtils
+import kotlinx.coroutines.withContext
+
+/** Configuration for the Sentry Ktor client plugin. */
+public class SentryKtorClientPluginConfig {
+  /** The [IScopes] instance to use. Defaults to [ScopesAdapter.getInstance]. */
+  public var scopes: IScopes = ScopesAdapter.getInstance()
+
+  /** Callback to customize or drop spans before they are created. Return null to drop the span. */
+  public var beforeSpan: BeforeSpanCallback? = null
+
+  /** Whether to capture HTTP client errors as Sentry events. Defaults to true. */
+  public var captureFailedRequests: Boolean = true
+
+  /**
+   * The HTTP status code ranges that should be considered as failed requests. Defaults to 500-599
+   * (server errors).
+   */
+  public var failedRequestStatusCodes: List<HttpStatusCodeRange> =
+    listOf(HttpStatusCodeRange(HttpStatusCodeRange.DEFAULT_MIN, HttpStatusCodeRange.DEFAULT_MAX))
+
+  /**
+   * The list of targets (URLs) for which failed requests should be captured. Supports regex
+   * patterns. Defaults to capture all requests.
+   */
+  public var failedRequestTargets: List<String> = listOf(SentryOptions.DEFAULT_PROPAGATION_TARGETS)
+
+  /** Callback interface for customizing spans before they are created. */
+  public fun interface BeforeSpanCallback {
+    /**
+     * Customize or drop a span before it's created.
+     *
+     * @param span The span to customize
+     * @param request The HTTP request being executed
+     * @return The customized span, or null to drop the span
+     */
+    public fun execute(span: ISpan, request: HttpRequest): ISpan?
+  }
+
+  /**
+   * Forcefully use the passed in scope instead of relying on the one injected by [SentryContext].
+   * Used for testing.
+   */
+  internal var forceScopes: Boolean = false
+}
+
+internal const val SENTRY_KTOR_CLIENT_PLUGIN_KEY = "SentryKtorClientPlugin"
+internal const val TRACE_ORIGIN = "auto.http.ktor-client"
+
+/**
+ * Sentry plugin for Ktor HTTP client that provides automatic instrumentation for HTTP requests,
+ * including error capturing, request/response breadcrumbs, and distributed tracing.
+ */
+public val SentryKtorClientPlugin: ClientPlugin<SentryKtorClientPluginConfig> =
+  createClientPlugin(SENTRY_KTOR_CLIENT_PLUGIN_KEY, ::SentryKtorClientPluginConfig) {
+    // Init
+    SentryIntegrationPackageStorage.getInstance()
+      .addPackage("maven:io.sentry:sentry-ktor-client", BuildConfig.VERSION_NAME)
+    addIntegrationToSdkVersion("KtorClient")
+
+    // Options
+    val scopes = pluginConfig.scopes
+    val beforeSpan = pluginConfig.beforeSpan
+    val captureFailedRequests = pluginConfig.captureFailedRequests
+    val failedRequestStatusCodes = pluginConfig.failedRequestStatusCodes
+    val failedRequestTargets = pluginConfig.failedRequestTargets
+    val forceScopes = pluginConfig.forceScopes
+
+    // Attributes
+    // Request start time for breadcrumbs
+    val requestStartTimestampKey = AttributeKey<SentryDate>("SentryRequestStartTimestamp")
+    // Span associated with the request
+    val requestSpanKey = AttributeKey<ISpan>("SentryRequestSpan")
+
+    onRequest { request, _ ->
+      request.attributes.put(
+        requestStartTimestampKey,
+        (if (forceScopes) scopes else Sentry.getCurrentScopes()).options.dateProvider.now(),
+      )
+
+      val parentSpan: ISpan? =
+        if (forceScopes) scopes.getSpan()
+        else {
+          if (Platform.isAndroid()) scopes.transaction else scopes.span
+        }
+
+      val spanOp = "http.client"
+      val spanDescription = "${request.method.value.toString()} ${request.url.buildString()}"
+      val span: ISpan? = parentSpan?.startChild(spanOp, spanDescription)
+      if (span != null) {
+        span.spanContext.origin = TRACE_ORIGIN
+        request.attributes.put(requestSpanKey, span)
+      }
+
+      if (
+        !SpanUtils.isIgnored(
+          (if (forceScopes) scopes else Sentry.getCurrentScopes()).options.getIgnoredSpanOrigins(),
+          TRACE_ORIGIN,
+        )
+      ) {
+        TracingUtils.traceIfAllowed(
+            if (forceScopes) scopes else Sentry.getCurrentScopes(),
+            request.url.buildString(),
+            request.headers.getAll(BaggageHeader.BAGGAGE_HEADER),
+            span,
+          )
+          ?.let { tracingHeaders ->
+            request.headers[tracingHeaders.sentryTraceHeader.name] =
+              tracingHeaders.sentryTraceHeader.value
+            tracingHeaders.baggageHeader?.let {
+              request.headers.remove(BaggageHeader.BAGGAGE_HEADER)
+              request.headers[it.name] = it.value
+            }
+          }
+      }
+    }
+
+    client.requestPipeline.intercept(HttpRequestPipeline.Before) {
+      try {
+        proceed()
+      } catch (t: Throwable) {
+        context.attributes.getOrNull(requestSpanKey)?.apply {
+          throwable = t
+          status = SpanStatus.INTERNAL_ERROR
+          finish()
+        }
+        throw t
+      }
+    }
+
+    onResponse { response ->
+      val request = response.request
+      val startTimestamp = response.call.attributes.getOrNull(requestStartTimestampKey)
+      val endTimestamp =
+        (if (forceScopes) scopes else Sentry.getCurrentScopes()).options.dateProvider.now()
+
+      if (
+        captureFailedRequests &&
+          failedRequestStatusCodes.any { it.isInRange(response.status.value) } &&
+          PropagationTargetsUtils.contain(failedRequestTargets, request.url.toString())
+      ) {
+        SentryKtorClientUtils.captureClientError(scopes, request, response)
+      }
+
+      SentryKtorClientUtils.addBreadcrumb(scopes, request, response, startTimestamp, endTimestamp)
+
+      response.call.attributes.getOrNull(requestSpanKey)?.let { span ->
+        var result: ISpan? = span
+
+        if (beforeSpan != null) {
+          result = beforeSpan.execute(span, request)
+        }
+
+        if (result == null) {
+          // span is dropped
+          span.spanContext.sampled = false
+        }
+
+        val spanStatus = SpanStatus.fromHttpStatusCode(response.status.value)
+        span.finish(spanStatus, endTimestamp)
+      }
+    }
+
+    on(SentryKtorClientPluginContextHook(scopes)) { block -> block() }
+  }
+
+/**
+ * Context hook to manage scopes during request handling. Forks the current scope and uses
+ * [SentryContext] to ensure that the whole pipeline runs within the correct scopes.
+ */
+public open class SentryKtorClientPluginContextHook(protected val scopes: IScopes) :
+  ClientHook<suspend (suspend () -> Unit) -> Unit> {
+  private val phase = PipelinePhase("SentryKtorClientPluginContext")
+
+  override fun install(client: HttpClient, handler: suspend (suspend () -> Unit) -> Unit) {
+    client.requestPipeline.insertPhaseBefore(HttpRequestPipeline.Before, phase)
+    client.requestPipeline.intercept(phase) {
+      val scopes =
+        [email protected](
+          SENTRY_KTOR_CLIENT_PLUGIN_KEY
+        )
+      withContext(SentryContext(scopes)) { proceed() }
+    }
+  }
+}