Sentry Error Tracking Integration

This guide covers the step-by-step process to integrate Sentry into an Arda Kotlin service, including account setup, code changes, logging configuration, and CI/CD integration.

1. Account Setup

1. Log into Sentry.io.
2. Create a new project. Choose Kotlin (or Java) as the platform. Name the project (e.g., arda-operations) and select the appropriate team.
3. Go to Project Settings → Client Keys (DSN) and copy the DSN URL. This becomes the SENTRY_DSN environment variable.
4. Go to User Settings → API Tokens, create a new token with project:releases scope, and save it as SENTRY_AUTH_TOKEN in GitHub Actions secrets.

2. Dependencies

Update gradle/libs.versions.toml

[versions]
sentry-version = "7.14.0"  # Check for latest version

[libraries]
sentry = { module = "io.sentry:sentry", version.ref = "sentry-version" }
sentry-logback = { module = "io.sentry:sentry-logback", version.ref = "sentry-version" }

Update build.gradle.kts

dependencies {
    implementation(libs.sentry)
    implementation(libs.sentry.logback)
}

3. Code Modifications

Shared Configuration Helper (common-module)

Create common-module/lib/src/main/kotlin/cards/arda/common/lib/util/monitoring/SentryConfig.kt:

package cards.arda.common.lib.util.monitoring

import io.sentry.Sentry

object SentryMonitor {
    fun init(dsn: String?, env: String?, release: String?) {
        if (dsn.isNullOrBlank()) {
            println("Sentry DSN not provided, skipping initialization.")
            return
        }
        Sentry.init { options ->
            options.dsn = dsn
            options.environment = env ?: "local"
            options.release = release
            options.tracesSampleRate = 1.0
            options.isDebug = env == "local" || env == "dev"
        }
    }
}

Initialize at Application Startup (operations)

In operations/src/main/kotlin/cards/arda/operations/runtime/Main.kt, add Sentry initialization in applicationConfigurer or main:

import cards.arda.common.lib.util.monitoring.SentryMonitor

fun applicationConfigurer(cfgProvider: ConfigurationProvider): Application.() -> Unit = {
    val dsn = System.getenv("SENTRY_DSN")
    val env = System.getenv("SENTRY_ENVIRONMENT") ?: "local"
    val release = System.getenv("SENTRY_RELEASE")

    SentryMonitor.init(dsn, env, release)
    // ... rest of configuration
}

4. Logging Configuration

Update operations/src/main/resources/logback.xml to forward WARN+ level logs to Sentry:

<configuration>
    <!-- Existing console appender... -->

    <appender name="SENTRY" class="io.sentry.logback.SentryAppender">
        <options>
            <dsn>${SENTRY_DSN}</dsn>
        </options>
        <minimumEventLevel>WARN</minimumEventLevel>
    </appender>

    <root level="info">
        <appender-ref ref="PERF_STDOUT"/>
        <appender-ref ref="SENTRY"/>
    </root>
</configuration>

5. Deployment and CI/CD

Helm Chart

In operations/src/main/helm/templates/deployment.yaml:

env:
  - name: SENTRY_DSN
    valueFrom:
      secretKeyRef:
        name: {{ .Values.secrets.ardaParamsSecretName }}
        key: sentry-dsn
  - name: SENTRY_ENVIRONMENT
    value: {{ .Values.global.purpose | default "dev" }}
  - name: SENTRY_RELEASE
    value: {{ .Values.projectVersion }}

GitHub Actions

Add a step after the build/publish phase in .github/workflows/deploy.yaml:

- name: Create Sentry release
  uses: getsentry/action-release@v1
  env:
    SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
    SENTRY_ORG: "arda-systems"
    SENTRY_PROJECT: "arda-operations"
  with:
    environment: ${{ env.DEPLOY_ENV }}
    version: ${{ env.RELEASE_VERSION }}
    set_commits: "auto"

6. Verification

Local run:

1. Set SENTRY_DSN in your local .env or run configuration.
2. Start the app and trigger an error (or log one manually for testing).
3. Check the Sentry dashboard for the issue.

Deployment:

1. Deploy to a test environment.
2. Verify the Environment tag in Sentry issues matches the deployed env.
3. Verify the Release tag matches the git tag or version.