feat(logback): add posthog-server-logback appender module

New pure-JVM module publishing com.posthog:posthog-server-logback — a Logback
appender that mirrors qualifying log events into PostHog error tracking.

- PostHogAppender (AppenderBase<ILoggingEvent>): captures events at
  minimumCaptureLevel (default ERROR) that carry a real Throwable; maps log
  level to $exception_level; attaches logger name and the log message when it
  differs from the throwable message; never throws from append.
- Client wiring via static PostHogAppender.setPostHog(...); events before
  registration are dropped by design. Runs on the logging thread, so
  PostHogRequestContext scopes resolve the distinct id automatically.
- Recursion guard: com.posthog.* loggers are never captured.
- Dedup: consults the core PostHogCapturedThrowables identity marker so the
  appender and the uncaught handler don't double-report the same Throwable.
- logback-classic is compileOnly (1.3.x line, Java 8); animalsniffer and
  apiCheck pass. release.yml publish matrix / version-sync intentionally not
  updated (workflow edits out of scope) — human follow-up before release.

# Conflicts:
#	gradle.properties

Author: cat-ph

.changeset/server-logback-appender.md

@@ -0,0 +1,10 @@
+---
+'posthog-server-logback': minor
+---
+
+Initial `0.x` release of `com.posthog:posthog-server-logback` — a Logback appender that reports logged errors to PostHog Error Tracking through the server SDK. This module is pre-1.0; its public API may change between minor versions.
+
+- `PostHogAppender` (`ch.qos.logback.core.AppenderBase<ILoggingEvent>`, package `com.posthog.server.logback`) captures events at or above `minimumCaptureLevel` (default `ERROR`) that carry a `Throwable`, sending them through the server SDK's `captureException` so request-context distinct-id resolution and in-app frame config apply automatically.
+- Register a configured server client once at startup with `PostHogAppender.setPostHog(client)`; events logged before registration are dropped. Alternatively self-configure from `logback.xml` via `<apiKey>`/`<host>` (each self-configuring appender owns its client and closes it on `stop()`, so a Logback config reload keeps capturing). An application-registered client always wins.
+- Events from `com.posthog…` loggers are always skipped (recursion guard), events without a throwable are skipped (no message-only synthesis in v1), and captured events carry `$exception_level` (`error`, or `warning` when the threshold is lowered), `logger_name`, and the log message under `log_message` when it differs from the throwable message.
+- Depends on `com.posthog:posthog-server` (transitive `api`); Logback is `compileOnly` — provide `logback-classic` yourself (1.3.x line for Java 8 compatibility).

Makefile

@@ -35,6 +35,9 @@ dryReleaseSurveysCompose:
 dryReleaseServer:
 	./gradlew :posthog-server:publishToMavenLocal
 
+dryReleaseServerLogback:
+	./gradlew :posthog-server-logback:publishToMavenLocal
+
 dryReleaseAndroidPlugin:
 	./gradlew :posthog-android-gradle-plugin:publishToMavenLocal
 
@@ -53,6 +56,9 @@ releaseSurveysCompose:
 releaseServer:
 	./gradlew :posthog-server:publishToSonatype closeAndReleaseSonatypeStagingRepository
 
+releaseServerLogback:
+	./gradlew :posthog-server-logback:publishToSonatype closeAndReleaseSonatypeStagingRepository
+
 releaseAndroidPlugin:
 	./gradlew :posthog-android-gradle-plugin:publishToSonatype :posthog-android-gradle-plugin:closeAndReleaseSonatypeStagingRepository
 

buildSrc/src/main/java/PosthogBuildConfig.kt

@@ -65,6 +65,9 @@ object PosthogBuildConfig {
         val GSON = "2.10.1"
 
         val OKHTTP = "4.12.0"
+
+        // Logback appender: 1.3.x is the last line targeting Java 8 (1.4.x+ requires Java 11).
+        val LOGBACK = "1.3.14"
         val CURTAINS = "1.2.5"
         val ANDROIDX_CORE = "1.5.0"
         val ANDROIDX_COMPOSE = "1.0.0"

gradle.properties

@@ -26,6 +26,7 @@ coreVersion=6.29.0
 androidVersion=3.58.0
 surveysComposeVersion=0.1.0
 serverVersion=2.9.0
+serverLogbackVersion=0.1.0
 
 # Shared build versions (single source of truth for buildSrc, PosthogBuildConfig, and gradle plugin)
 kotlinVersion=2.1.10

pnpm-lock.yaml

@@ -3,6 +3,7 @@ packages:
     - "posthog-android"
     - "posthog-android-surveys-compose"
     - "posthog-server"
+    - "posthog-server-logback"
     - "posthog-android-gradle-plugin"
 
 minimumReleaseAge: 10080

pnpm-workspace.yaml

@@ -0,0 +1,3 @@
+# posthog-server-logback
+
+## Next

posthog-server-logback/CHANGELOG.md

@@ -0,0 +1,21 @@
+public final class com/posthog/server/logback/PostHogAppender : ch/qos/logback/core/AppenderBase {
+	public static final field Companion Lcom/posthog/server/logback/PostHogAppender$Companion;
+	public fun <init> ()V
+	public synthetic fun append (Ljava/lang/Object;)V
+	public static final fun clearPostHog ()V
+	public final fun getApiKey ()Ljava/lang/String;
+	public final fun getHost ()Ljava/lang/String;
+	public final fun getMinimumCaptureLevel ()Lch/qos/logback/classic/Level;
+	public final fun setApiKey (Ljava/lang/String;)V
+	public final fun setHost (Ljava/lang/String;)V
+	public final fun setMinimumCaptureLevel (Lch/qos/logback/classic/Level;)V
+	public static final fun setPostHog (Lcom/posthog/server/PostHogInterface;)V
+	public fun start ()V
+	public fun stop ()V
+}
+
+public final class com/posthog/server/logback/PostHogAppender$Companion {
+	public final fun clearPostHog ()V
+	public final fun setPostHog (Lcom/posthog/server/PostHogInterface;)V
+}
+

posthog-server-logback/api/posthog-server-logback.api

@@ -0,0 +1,109 @@
+@file:Suppress("ktlint:standard:max-line-length")
+
+import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
+
+version = properties["serverLogbackVersion"].toString()
+
+plugins {
+    `java-library`
+    kotlin("jvm")
+    id("com.android.lint")
+
+    // publish
+    `maven-publish`
+    signing
+    id("org.jetbrains.dokka")
+
+    // plugins
+    id("com.github.gmazzo.buildconfig")
+
+    // tests
+    id("org.jetbrains.kotlinx.kover")
+
+    // compatibility
+    id("ru.vyarus.animalsniffer")
+}
+
+buildConfig {
+    useKotlinOutput()
+    packageName("com.posthog.server.logback")
+    buildConfigField("String", "SDK_NAME", "\"posthog-server-logback\"")
+    buildConfigField("String", "VERSION_NAME", "\"${project.version}\"")
+}
+
+java {
+    withSourcesJar()
+    sourceCompatibility = PosthogBuildConfig.Build.JAVA_VERSION
+    targetCompatibility = PosthogBuildConfig.Build.JAVA_VERSION
+}
+
+val dokkaJavadocJar by tasks.register<Jar>("dokkaJavadocJar") {
+    dependsOn(tasks.dokkaJavadoc)
+    from(tasks.dokkaJavadoc.flatMap { it.outputDirectory })
+    archiveClassifier.set("javadoc")
+}
+
+val dokkaHtmlJar by tasks.register<Jar>("dokkaHtmlJar") {
+    dependsOn(tasks.dokkaHtml)
+    from(tasks.dokkaHtml.flatMap { it.outputDirectory })
+    archiveClassifier.set("html-doc")
+}
+
+publishing {
+    publications {
+        create<MavenPublication>("maven") {
+            from(components["java"])
+            artifact(dokkaJavadocJar)
+            artifact(dokkaHtmlJar)
+
+            postHogConfig(project.name, project.version.toString())
+            pom.postHogConfig(
+                project.name,
+                moduleDescription = "Logback appender that reports errors to PostHog via the server SDK",
+            )
+        }
+    }
+    signing.postHogConfig("maven", this)
+}
+
+tasks.withType<KotlinCompile>().configureEach {
+    compilerOptions.postHogConfig()
+}
+
+kotlin {
+    explicitApi()
+}
+
+configure<SourceSetContainer> {
+    test {
+        java.srcDir("src/test/java")
+    }
+}
+
+dependencies {
+    // Expose the server SDK transitively: consumers configure and use a PostHog server client
+    // alongside the appender, so it belongs on the compile classpath of anything depending on this.
+    api(project(":posthog-server"))
+
+    implementation(kotlin("stdlib-jdk8", PosthogBuildConfig.Kotlin.KOTLIN))
+
+    // Logback is provided by the host application; keep it off our runtime classpath and pin a
+    // conservative Java 8-compatible floor (the 1.3.x line; 1.4.x+ requires Java 11).
+    compileOnly("ch.qos.logback:logback-classic:${PosthogBuildConfig.Dependencies.LOGBACK}")
+    compileOnly("org.codehaus.mojo:animal-sniffer-annotations:${PosthogBuildConfig.Plugins.ANIMAL_SNIFFER_SDK_ANNOTATION}")
+
+    // compatibility
+    signature("org.codehaus.mojo.signature:java18:${PosthogBuildConfig.Plugins.SIGNATURE_JAVA18}@signature")
+
+    // tests
+    testImplementation("ch.qos.logback:logback-classic:${PosthogBuildConfig.Dependencies.LOGBACK}")
+    testImplementation("org.jetbrains.kotlin:kotlin-test-junit:${PosthogBuildConfig.Kotlin.KOTLIN}")
+    testImplementation("com.squareup.okhttp3:mockwebserver:${PosthogBuildConfig.Dependencies.OKHTTP}")
+    testImplementation("com.google.code.gson:gson:${PosthogBuildConfig.Dependencies.GSON}")
+}
+
+tasks.javadoc {
+    if (JavaVersion.current().isJava9Compatible) {
+        (options as StandardJavadocDocletOptions).addBooleanOption("html5", true)
+    }
+}