Executable library telemetry example
This entire Kotlin file is compiled and run by :observability:test. It installs the bridge,
records a DID resolution under a request id, reports a rejected verification, and asserts that
both reach the trace and the scrape.
Run ./gradlew :observability:test --tests '*LibraryTelemetryDocumentationExampleTest' from the
SDK root with JDK 21. See the library telemetry runbook for what each
metric means and why rejected is not failure.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
package org.trustweave.observability
import io.opentelemetry.sdk.OpenTelemetrySdk
import io.opentelemetry.sdk.testing.exporter.InMemorySpanExporter
import io.opentelemetry.sdk.trace.SdkTracerProvider
import io.opentelemetry.sdk.trace.export.SimpleSpanProcessor
import kotlinx.coroutines.runBlocking
import kotlinx.coroutines.withContext
import org.junit.jupiter.api.Test
import org.trustweave.core.telemetry.Operation
import org.trustweave.core.telemetry.Telemetry
import org.trustweave.core.telemetry.TelemetryContext
import kotlin.test.assertEquals
import kotlin.test.assertTrue
class LibraryTelemetryDocumentationExampleTest {
@Test
fun `a library operation reaches the host trace and scrape under the request that caused it`() {
val spans = InMemorySpanExporter.create()
val openTelemetry =
OpenTelemetrySdk
.builder()
.setTracerProvider(
SdkTracerProvider.builder().addSpanProcessor(SimpleSpanProcessor.create(spans)).build(),
).build()
// One process-wide install, usually at startup. Until this runs the SDK records nothing.
val library = LibraryTelemetry(openTelemetry)
Telemetry.install(library)
try {
// The embedded servers do this for you: HostObservability puts each request's
// X-Request-ID into the coroutine context so library work inherits it.
runBlocking {
withContext(TelemetryContext("request-1")) {
Telemetry.measure(Operation.DID_RESOLVE, mapOf("did.method" to "key")) {
"did:key:z6MkResolved"
}
}
// A credential that fails verification is the library working, not an error:
// it is reported as REJECTED so alerting on failures does not page on it.
Telemetry.rejected(Operation.CREDENTIAL_VERIFY, "SignatureInvalid")
}
val resolution = spans.finishedSpanItems.first { it.name == "did_resolve" }
val attributes = resolution.attributes.asMap().mapKeys { it.key.key }
assertEquals("success", attributes["trustweave.outcome"])
assertEquals("request-1", attributes["trustweave.request_id"])
assertEquals("key", attributes["did.method"])
val scrape = library.prometheus()
assertTrue(
"trustweave_library_operations_total{operation=\"did_resolve\",outcome=\"success\"} 1" in scrape,
scrape,
)
assertTrue(
"trustweave_library_operations_total{operation=\"credential_verify\",outcome=\"rejected\"} 1" in scrape,
scrape,
)
} finally {
Telemetry.uninstall()
openTelemetry.close()
}
}
}