Executable host observability example
This entire Kotlin file is compiled and run by :observability:test. It configures a
local Ktor application, records a verification phase, asserts the response, and checks
that only an authenticated scrape exposes metrics. The default tracer is a no-op; see
the host runbook for application-owned OpenTelemetry export and TLS.
Run ./gradlew :observability:test --tests '*HostDocumentationExampleTest' from the SDK
root with JDK 21. The synthetic token below is for this isolated test only.
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
package org.trustweave.observability
import io.ktor.client.request.get
import io.ktor.client.request.header
import io.ktor.client.statement.bodyAsText
import io.ktor.http.HttpStatusCode
import io.ktor.server.application.call
import io.ktor.server.response.respondText
import io.ktor.server.routing.get
import io.ktor.server.routing.routing
import io.ktor.server.testing.testApplication
import org.junit.jupiter.api.Test
import kotlin.test.assertEquals
import kotlin.test.assertNotNull
import kotlin.test.assertTrue
class HostDocumentationExampleTest {
@Test
fun `documented host setup serves requests and protects metrics`() {
// Synthetic test secret only. A deployed host supplies its own secret and TLS.
val token = "documentation-fixture-token-32-characters"
val telemetry = HostTelemetry(maxConcurrentRequests = 8, maxQueuedRequests = 4, queueTimeoutMillis = 500)
testApplication {
application {
HostObservability(telemetry, metricsBearerToken = token).install(this, HostKind.VC_API)
routing {
get("/verify") {
val result = telemetry.phase(HostPhase.VERIFY) { "verified" }
call.respondText(result)
}
}
}
val response = client.get("/verify")
assertEquals(HttpStatusCode.OK, response.status)
assertEquals("verified", response.bodyAsText())
assertNotNull(response.headers["X-Request-ID"])
assertEquals(HttpStatusCode.Unauthorized, client.get("/internal/metrics").status)
val metrics = client.get("/internal/metrics") { header("Authorization", "Bearer $token") }
assertEquals(HttpStatusCode.OK, metrics.status)
assertEquals("no-store", metrics.headers["Cache-Control"])
assertTrue(metrics.bodyAsText().contains("host=\"vc_api\",outcome=\"success\"} 1"))
}
}
}
The source marker is checked by python scripts/check-documentation.py. CI also
requires this named test in JUnit XML; source synchronization alone is not execution.