-
-
Notifications
You must be signed in to change notification settings - Fork 468
ref(kafka): [Queue Instrumentation 14] Extract sentry-kafka module #5288
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
adinauer
merged 2 commits into
feat/queue-instrumentation
from
feat/queue-instrumentation-kafka-module
Apr 29, 2026
Merged
Changes from all commits
Commits
Show all changes
2 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,5 @@ | ||
| # sentry-kafka | ||
|
|
||
| This module provides Kafka-native queue instrumentation for applications using `kafka-clients` directly. | ||
|
|
||
| Spring users should use `sentry-spring-boot-jakarta` / `sentry-spring-jakarta`, which provide higher-fidelity consumer instrumentation via Spring Kafka hooks. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,25 @@ | ||
| public final class io/sentry/kafka/BuildConfig { | ||
| public static final field SENTRY_KAFKA_SDK_NAME Ljava/lang/String; | ||
| public static final field VERSION_NAME Ljava/lang/String; | ||
| } | ||
|
|
||
| public final class io/sentry/kafka/SentryKafkaConsumerInterceptor : org/apache/kafka/clients/consumer/ConsumerInterceptor { | ||
| public static final field TRACE_ORIGIN Ljava/lang/String; | ||
| public fun <init> (Lio/sentry/IScopes;)V | ||
| public fun close ()V | ||
| public fun configure (Ljava/util/Map;)V | ||
| public fun onCommit (Ljava/util/Map;)V | ||
| public fun onConsume (Lorg/apache/kafka/clients/consumer/ConsumerRecords;)Lorg/apache/kafka/clients/consumer/ConsumerRecords; | ||
| } | ||
|
|
||
| public final class io/sentry/kafka/SentryKafkaProducerInterceptor : org/apache/kafka/clients/producer/ProducerInterceptor { | ||
| public static final field SENTRY_ENQUEUED_TIME_HEADER Ljava/lang/String; | ||
| public static final field TRACE_ORIGIN Ljava/lang/String; | ||
| public fun <init> (Lio/sentry/IScopes;)V | ||
| public fun <init> (Lio/sentry/IScopes;Ljava/lang/String;)V | ||
| public fun close ()V | ||
| public fun configure (Ljava/util/Map;)V | ||
| public fun onAcknowledgement (Lorg/apache/kafka/clients/producer/RecordMetadata;Ljava/lang/Exception;)V | ||
| public fun onSend (Lorg/apache/kafka/clients/producer/ProducerRecord;)Lorg/apache/kafka/clients/producer/ProducerRecord; | ||
| } | ||
|
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,83 @@ | ||
| import net.ltgt.gradle.errorprone.errorprone | ||
| import org.jetbrains.kotlin.gradle.tasks.KotlinCompile | ||
|
|
||
| plugins { | ||
| `java-library` | ||
| id("io.sentry.javadoc") | ||
| alias(libs.plugins.kotlin.jvm) | ||
| jacoco | ||
| alias(libs.plugins.errorprone) | ||
| alias(libs.plugins.gradle.versions) | ||
| alias(libs.plugins.buildconfig) | ||
| } | ||
|
|
||
| tasks.withType<KotlinCompile>().configureEach { | ||
| compilerOptions.jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_1_8 | ||
| } | ||
|
|
||
| dependencies { | ||
| api(projects.sentry) | ||
| compileOnly(libs.kafka.clients) | ||
| compileOnly(libs.jetbrains.annotations) | ||
| compileOnly(libs.nopen.annotations) | ||
|
|
||
| errorprone(libs.errorprone.core) | ||
| errorprone(libs.nopen.checker) | ||
| errorprone(libs.nullaway) | ||
|
|
||
| // tests | ||
| testImplementation(projects.sentryTestSupport) | ||
| testImplementation(kotlin(Config.kotlinStdLib)) | ||
| testImplementation(libs.kotlin.test.junit) | ||
| testImplementation(libs.mockito.kotlin) | ||
| testImplementation(libs.mockito.inline) | ||
| testImplementation(libs.kafka.clients) | ||
| } | ||
|
|
||
| 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) | ||
| } | ||
| } | ||
|
|
||
| tasks.withType<JavaCompile>().configureEach { | ||
| options.errorprone { | ||
| check("NullAway", net.ltgt.gradle.errorprone.CheckSeverity.ERROR) | ||
| option("NullAway:AnnotatedPackages", "io.sentry") | ||
| } | ||
| } | ||
|
|
||
| buildConfig { | ||
| useJavaOutput() | ||
| packageName("io.sentry.kafka") | ||
| buildConfigField("String", "SENTRY_KAFKA_SDK_NAME", "\"${Config.Sentry.SENTRY_KAFKA_SDK_NAME}\"") | ||
| buildConfigField("String", "VERSION_NAME", "\"${project.version}\"") | ||
| } | ||
|
|
||
| tasks.jar { | ||
| manifest { | ||
| attributes( | ||
| "Sentry-Version-Name" to project.version, | ||
| "Sentry-SDK-Name" to Config.Sentry.SENTRY_KAFKA_SDK_NAME, | ||
| "Sentry-SDK-Package-Name" to "maven:io.sentry:sentry-kafka", | ||
| "Implementation-Vendor" to "Sentry", | ||
| "Implementation-Title" to project.name, | ||
| "Implementation-Version" to project.version, | ||
| ) | ||
| } | ||
| } |
95 changes: 95 additions & 0 deletions
95
sentry-kafka/src/main/java/io/sentry/kafka/SentryKafkaConsumerInterceptor.java
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,95 @@ | ||
| package io.sentry.kafka; | ||
|
|
||
| import io.sentry.BaggageHeader; | ||
| import io.sentry.IScopes; | ||
| import io.sentry.ITransaction; | ||
| import io.sentry.SentryTraceHeader; | ||
| import io.sentry.SpanDataConvention; | ||
| import io.sentry.SpanStatus; | ||
| import io.sentry.TransactionContext; | ||
| import io.sentry.TransactionOptions; | ||
| import java.nio.charset.StandardCharsets; | ||
| import java.util.Collections; | ||
| import java.util.List; | ||
| import java.util.Map; | ||
| import org.apache.kafka.clients.consumer.ConsumerInterceptor; | ||
| import org.apache.kafka.clients.consumer.ConsumerRecord; | ||
| import org.apache.kafka.clients.consumer.ConsumerRecords; | ||
| import org.apache.kafka.clients.consumer.OffsetAndMetadata; | ||
| import org.apache.kafka.common.TopicPartition; | ||
| import org.apache.kafka.common.header.Header; | ||
| import org.jetbrains.annotations.ApiStatus; | ||
| import org.jetbrains.annotations.NotNull; | ||
| import org.jetbrains.annotations.Nullable; | ||
|
|
||
| @ApiStatus.Internal | ||
| public final class SentryKafkaConsumerInterceptor<K, V> implements ConsumerInterceptor<K, V> { | ||
|
|
||
| public static final @NotNull String TRACE_ORIGIN = "auto.queue.kafka.consumer"; | ||
|
|
||
| private final @NotNull IScopes scopes; | ||
|
|
||
| public SentryKafkaConsumerInterceptor(final @NotNull IScopes scopes) { | ||
| this.scopes = scopes; | ||
| } | ||
|
|
||
| @Override | ||
| public @NotNull ConsumerRecords<K, V> onConsume(final @NotNull ConsumerRecords<K, V> records) { | ||
| if (!scopes.getOptions().isEnableQueueTracing() || records.isEmpty()) { | ||
| return records; | ||
| } | ||
|
|
||
| final @NotNull ConsumerRecord<K, V> firstRecord = records.iterator().next(); | ||
|
|
||
| try { | ||
| final @Nullable TransactionContext continued = continueTrace(firstRecord); | ||
| final @NotNull TransactionContext txContext = | ||
| continued != null ? continued : new TransactionContext("queue.receive", "queue.receive"); | ||
| txContext.setName("queue.receive"); | ||
| txContext.setOperation("queue.receive"); | ||
|
|
||
| final @NotNull TransactionOptions txOptions = new TransactionOptions(); | ||
| txOptions.setOrigin(TRACE_ORIGIN); | ||
| txOptions.setBindToScope(false); | ||
|
|
||
| final @NotNull ITransaction transaction = scopes.startTransaction(txContext, txOptions); | ||
| if (!transaction.isNoOp()) { | ||
| transaction.setData(SpanDataConvention.MESSAGING_SYSTEM, "kafka"); | ||
| transaction.setData(SpanDataConvention.MESSAGING_DESTINATION_NAME, firstRecord.topic()); | ||
| transaction.setData("messaging.batch.message.count", records.count()); | ||
| transaction.setStatus(SpanStatus.OK); | ||
| transaction.finish(); | ||
|
adinauer marked this conversation as resolved.
|
||
| } | ||
| } catch (Throwable ignored) { | ||
| // Instrumentation must never break the customer's Kafka poll loop. | ||
| } | ||
|
|
||
| return records; | ||
| } | ||
|
|
||
| @Override | ||
| public void onCommit(final @NotNull Map<TopicPartition, OffsetAndMetadata> offsets) {} | ||
|
|
||
| @Override | ||
| public void close() {} | ||
|
|
||
| @Override | ||
| public void configure(final @Nullable Map<String, ?> configs) {} | ||
|
|
||
| private @Nullable TransactionContext continueTrace(final @NotNull ConsumerRecord<K, V> record) { | ||
| final @Nullable String sentryTrace = headerValue(record, SentryTraceHeader.SENTRY_TRACE_HEADER); | ||
| final @Nullable String baggage = headerValue(record, BaggageHeader.BAGGAGE_HEADER); | ||
| final @Nullable List<String> baggageHeaders = | ||
| baggage != null ? Collections.singletonList(baggage) : null; | ||
| return scopes.continueTrace(sentryTrace, baggageHeaders); | ||
| } | ||
|
|
||
| private @Nullable String headerValue( | ||
| final @NotNull ConsumerRecord<K, V> record, final @NotNull String headerName) { | ||
| final @Nullable Header header = record.headers().lastHeader(headerName); | ||
| if (header == null || header.value() == null) { | ||
| return null; | ||
| } | ||
| return new String(header.value(), StandardCharsets.UTF_8); | ||
| } | ||
| } | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
72 changes: 72 additions & 0 deletions
72
sentry-kafka/src/test/kotlin/io/sentry/kafka/SentryKafkaConsumerInterceptorTest.kt
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,72 @@ | ||
| package io.sentry.kafka | ||
|
|
||
| import io.sentry.IScopes | ||
| import io.sentry.ITransaction | ||
| import io.sentry.SentryOptions | ||
| import io.sentry.TransactionContext | ||
| import io.sentry.TransactionOptions | ||
| import kotlin.test.Test | ||
| import kotlin.test.assertSame | ||
| import org.apache.kafka.clients.consumer.ConsumerRecord | ||
| import org.apache.kafka.clients.consumer.ConsumerRecords | ||
| import org.apache.kafka.clients.consumer.OffsetAndMetadata | ||
| import org.apache.kafka.common.TopicPartition | ||
| import org.mockito.kotlin.any | ||
| import org.mockito.kotlin.mock | ||
| import org.mockito.kotlin.never | ||
| import org.mockito.kotlin.verify | ||
| import org.mockito.kotlin.whenever | ||
|
|
||
| class SentryKafkaConsumerInterceptorTest { | ||
|
|
||
| @Test | ||
| fun `does nothing when queue tracing is disabled`() { | ||
| val scopes = mock<IScopes>() | ||
| val options = SentryOptions().apply { isEnableQueueTracing = false } | ||
| whenever(scopes.options).thenReturn(options) | ||
|
|
||
| val interceptor = SentryKafkaConsumerInterceptor<String, String>(scopes) | ||
| val records = singleRecordBatch() | ||
|
|
||
| val result = interceptor.onConsume(records) | ||
|
|
||
| assertSame(records, result) | ||
| verify(scopes, never()).startTransaction(any<TransactionContext>(), any<TransactionOptions>()) | ||
| } | ||
|
|
||
| @Test | ||
| fun `starts and finishes queue receive transaction for consumed batch`() { | ||
| val scopes = mock<IScopes>() | ||
| val options = SentryOptions().apply { isEnableQueueTracing = true } | ||
| val transaction = mock<ITransaction>() | ||
|
|
||
| whenever(scopes.options).thenReturn(options) | ||
| whenever(scopes.continueTrace(any(), any())).thenReturn(null) | ||
| whenever(scopes.startTransaction(any<TransactionContext>(), any<TransactionOptions>())) | ||
| .thenReturn(transaction) | ||
| whenever(transaction.isNoOp).thenReturn(false) | ||
|
|
||
| val interceptor = SentryKafkaConsumerInterceptor<String, String>(scopes) | ||
|
|
||
| interceptor.onConsume(singleRecordBatch()) | ||
|
|
||
| verify(scopes).startTransaction(any<TransactionContext>(), any<TransactionOptions>()) | ||
| verify(transaction).setData("messaging.system", "kafka") | ||
| verify(transaction).setData("messaging.destination.name", "my-topic") | ||
| verify(transaction).setData("messaging.batch.message.count", 1) | ||
| verify(transaction).finish() | ||
| } | ||
|
|
||
| @Test | ||
| fun `commit callback is no-op`() { | ||
| val interceptor = SentryKafkaConsumerInterceptor<String, String>(mock()) | ||
|
|
||
| interceptor.onCommit(mapOf(TopicPartition("my-topic", 0) to OffsetAndMetadata(1))) | ||
| } | ||
|
|
||
| private fun singleRecordBatch(): ConsumerRecords<String, String> { | ||
| val partition = TopicPartition("my-topic", 0) | ||
| val record = ConsumerRecord("my-topic", 0, 0L, "key", "value") | ||
| return ConsumerRecords(mapOf(partition to listOf(record))) | ||
| } | ||
| } |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.