feat: add PersistedTelemetryRecord

Author: fractalwrench

exporters-persistence/README.md

@@ -0,0 +1,4 @@
+# exporters-core
+
+This module contains exporters that persist telemetry before attempting to send it, thus avoiding
+data loss in a process termination scenario.

exporters-persistence/api/android/exporters-persistence.api

@@ -0,0 +1,33 @@
+plugins {
+    kotlin("multiplatform")
+    id("com.android.kotlin.multiplatform.library")
+    id("io.opentelemetry.kotlin.build-logic")
+    id("signing")
+    id("com.vanniktech.maven.publish")
+    id("org.jetbrains.kotlinx.kover")
+}
+
+kotlin {
+    sourceSets {
+        val commonMain by getting {
+            dependencies {
+                implementation(project(":api"))
+                implementation(project(":exporters-otlp"))
+                implementation(libs.kotlinx.coroutines)
+            }
+        }
+        val commonTest by getting {
+            dependencies {
+                implementation(project(":test-fakes"))
+                implementation(project(":integration-test"))
+                implementation(libs.kotlin.test)
+                implementation(libs.kotlinx.coroutines.test)
+            }
+        }
+        val jvmTest by getting {
+            dependencies {
+                implementation(libs.kotlin.test)
+            }
+        }
+    }
+}

exporters-persistence/api/jvm/exporters-persistence.api

@@ -0,0 +1,16 @@
+package io.opentelemetry.kotlin.export
+
+internal class PersistedTelemetryConfig(
+
+    /**
+     * Maximum number of batches that should be stored for each telemetry signal. 100 by default.
+     * For example, 100 batches of X logs may be stored before old telemetry is deleted.
+     */
+    val maxBatchedItemsPerSignal: Int = 100,
+
+    /**
+     * Maximum age of telemetry before it should be deleted. Old telemetry is not considered useful
+     * so it can be deleted after 30 days by default.
+     */
+    val maxTelemetryAgeInDays: Long = 30,
+)

exporters-persistence/build.gradle.kts

@@ -0,0 +1,53 @@
+package io.opentelemetry.kotlin.export
+
+/**
+ * Creates a filename that can be used to persist a telemetry record.
+ */
+internal data class PersistedTelemetryRecord(
+    val timestamp: Long,
+    val type: PersistedTelemetryType,
+    val uid: String,
+) {
+
+    /**
+     * String filename that encodes information about the telemetry record.
+     */
+    val filename: String = "${type}_${timestamp}_$uid.gz"
+
+    companion object {
+
+        private const val EXTENSION = ".gz"
+        private const val DELIMITER = "_"
+
+        /**
+         * Comparator that orders records by timestamp (oldest first), then type, then uid.
+         */
+        val comparator: Comparator<PersistedTelemetryRecord> = compareBy(
+            { it.timestamp },
+            { it.type },
+            { it.uid }
+        )
+
+        /**
+         * Decodes a filename to gain information about the telemetry recorded within.
+         *
+         * Returns null if the filename does not match the expected format.
+         */
+        fun fromFilename(filename: String): PersistedTelemetryRecord? {
+            if (!filename.endsWith(EXTENSION)) {
+                return null
+            }
+            val parts = filename.removeSuffix(EXTENSION).split(DELIMITER, limit = 3)
+            if (parts.size != 3) {
+                return null
+            }
+            val type = try {
+                PersistedTelemetryType.valueOf(parts[0])
+            } catch (e: IllegalArgumentException) {
+                return null
+            }
+            val timestamp = parts[1].toLongOrNull() ?: return null
+            return PersistedTelemetryRecord(timestamp, type, parts[2])
+        }
+    }
+}

exporters-persistence/src/commonMain/kotlin/io/opentelemetry/kotlin/export/PersistedTelemetryConfig.kt

@@ -0,0 +1,8 @@
+package io.opentelemetry.kotlin.export
+
+/**
+ * The type of telemetry that is persisted.
+ */
+internal enum class PersistedTelemetryType {
+    LOGS, SPANS,
+}

exporters-persistence/src/commonMain/kotlin/io/opentelemetry/kotlin/export/PersistedTelemetryRecord.kt

@@ -0,0 +1,14 @@
+package io.opentelemetry.kotlin.export
+
+import kotlin.test.Test
+import kotlin.test.assertEquals
+
+internal class PersistedTelemetryConfigTest {
+
+    @Test
+    fun testDefaults() {
+        val cfg = PersistedTelemetryConfig()
+        assertEquals(30, cfg.maxTelemetryAgeInDays)
+        assertEquals(100, cfg.maxBatchedItemsPerSignal)
+    }
+}

exporters-persistence/src/commonMain/kotlin/io/opentelemetry/kotlin/export/PersistedTelemetryType.kt

@@ -0,0 +1,84 @@
+package io.opentelemetry.kotlin.export
+
+import io.opentelemetry.kotlin.export.PersistedTelemetryRecord.Companion.comparator
+import io.opentelemetry.kotlin.export.PersistedTelemetryRecord.Companion.fromFilename
+import io.opentelemetry.kotlin.export.PersistedTelemetryType.LOGS
+import io.opentelemetry.kotlin.export.PersistedTelemetryType.SPANS
+import kotlin.test.Test
+import kotlin.test.assertEquals
+import kotlin.test.assertNull
+
+internal class PersistedTelemetryRecordTest {
+
+    @Test
+    fun testFilenameEncodesLogType() {
+        val record = PersistedTelemetryRecord(
+            timestamp = 1234567890L,
+            type = LOGS,
+            uid = "abc-123"
+        )
+        assertEquals("LOGS_1234567890_abc-123.gz", record.filename)
+        val decoded = fromFilename(record.filename)
+        assertEquals(record, decoded)
+    }
+
+    @Test
+    fun testFilenameEncodesSpansType() {
+        val record = PersistedTelemetryRecord(
+            timestamp = 9876543210L,
+            type = SPANS,
+            uid = "xyz-789"
+        )
+        assertEquals("SPANS_9876543210_xyz-789.gz", record.filename)
+        val decoded = fromFilename(record.filename)
+        assertEquals(record, decoded)
+    }
+
+    @Test
+    fun testFromFilenameReturnsNullForInvalid() {
+        val invalid = listOf(
+            "LOGS_1234567890_abc-123",
+            "INVALID_1234567890_abc-123.gz",
+            "LOGS_notanumber_abc-123.gz",
+            "LOGS_1234567890.gz",
+            "",
+        )
+        invalid.forEach {
+            val record = fromFilename(it)
+            assertNull(record)
+        }
+    }
+
+    @Test
+    fun testFromFilenamePreservesuidWithUnderscores() {
+        val record = fromFilename("LOGS_1234567890_uid_with_underscores.gz")
+        assertEquals("uid_with_underscores", record?.uid)
+    }
+
+    @Test
+    fun testComparatorSorting() {
+        val a = PersistedTelemetryRecord(200L, SPANS, "a")
+        val b = PersistedTelemetryRecord(100L, LOGS, "b")
+        val c = PersistedTelemetryRecord(100L, LOGS, "a")
+        val d = PersistedTelemetryRecord(100L, SPANS, "a")
+        val e = PersistedTelemetryRecord(200L, LOGS, "a")
+
+        val records = listOf(a, b, c, d, e)
+        val sorted = records.sortedWith(comparator)
+        // Sorted by timestamp (oldest first), then type, then uid
+        assertEquals(listOf(c, b, d, e, a), sorted)
+    }
+
+    @Test
+    fun testSortEmptyList() {
+        val sorted = emptyList<PersistedTelemetryRecord>().sortedWith(comparator)
+        assertEquals(emptyList(), sorted)
+    }
+
+    @Test
+    fun testSortSingleElement() {
+        val record = PersistedTelemetryRecord(100L, LOGS, "a")
+        val sorted = listOf(record).sortedWith(comparator)
+        assertEquals(listOf(record), sorted)
+    }
+}

exporters-persistence/src/commonTest/kotlin/io/opentelemetry/kotlin/export/PersistedTelemetryConfigTest.kt

@@ -34,6 +34,7 @@ include(
     ":exporters-core",
     ":exporters-in-memory",
     ":exporters-otlp",
+    ":exporters-persistence",
     ":exporters-protobuf",
     ":java-typealiases",
     "examples:jvm-app",