new_module

Module Addition Rules for sentry-java

Overview

This document outlines the complete process for adding a new module to the sentry-java repository. Follow these steps in order to ensure proper integration and release management.

Step-by-Step Process

1. Create the Module Structure

1. Create the new module, conforming to the existing naming conventions and build scripts. Copy the build.gradle.kts of the closest existing integration rather than writing one from scratch — sentry-kafka is a good JVM template, sentry-android-timber a good Android one.

2. Add the module to the include list in settings.gradle.kts

If adding a sentry-samples module, also add it to the ignoredProjects list in the root build.gradle.kts:

ignoredProjects.addAll(
    listOf(
        // ... existing projects ...
        "sentry-samples-{module-name}"
    )
)

1. Add a SENTRY_{MODULE}_SDK_NAME constant to the Config.Sentry block in buildSrc/src/main/java/Config.kt:

val SENTRY_FOO_SDK_NAME = "$SENTRY_JAVA_SDK_NAME.foo"

The module's build.gradle.kts consumes it in both buildConfig and the jar manifest (Sentry-SDK-Name / Sentry-SDK-Package-Name) — see sentry-kafka/build.gradle.kts.

1. Add the instrumented library to gradle/libs.versions.toml and depend on it with compileOnly(libs.<lib>), so the integration does not force the dependency on users.

2. Register the integration with the SDK so it is reported in the sdk payload. Every integration does this — see sentry-openfeature/.../SentryOpenFeatureHook.java:

static {
  SentryIntegrationPackageStorage.getInstance()
      .addPackage("maven:io.sentry:sentry-{module-name}", BuildConfig.VERSION_NAME);
}
// then, from the constructor:
addIntegrationToSdkVersion("{IntegrationName}");

1. If adding a JVM sample, add E2E (system) tests, following the structure we have in the existing JVM examples. The test should then be added to test/system-test-runner.py and .github/workflows/system-tests-backend.yml.