Skip to content

Commit 9865c17

Browse files
trasktrask
authored
Rename ktor tracing to ktor telemetry (#12855)
1 parent b08d272 commit 9865c17

File tree

64 files changed

+1297
-99
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

64 files changed

+1297
-99
lines changed

‎instrumentation/ktor/ktor-1.0/library/README.md

+5-4
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
# Library Instrumentation for Ktor version 1.x
22

3-
This package contains libraries to help instrument Ktor. Currently, only server instrumentation is supported.
3+
This package contains libraries to help instrument Ktor.
4+
Currently, only server instrumentation is supported.
45

56
## Quickstart
67

@@ -29,14 +30,14 @@ implementation("io.opentelemetry.instrumentation:opentelemetry-ktor-1.0:OPENTELE
2930

3031
## Usage
3132

32-
Initialize instrumentation by installing the `KtorServerTracing` feature. You must set the `OpenTelemetry` to use with
33-
the feature.
33+
Initialize instrumentation by installing the `KtorServerTelemetry` feature.
34+
You must set the `OpenTelemetry` to use with the feature.
3435

3536
```kotlin
3637
OpenTelemetry openTelemetry = ...
3738

3839
embeddedServer(Netty, 8080) {
39-
install(KtorServerTracing) {
40+
install(KtorServerTelemetry) {
4041
setOpenTelemetry(openTelemetry)
4142
}
4243
}

‎instrumentation/ktor/ktor-1.0/library/src/main/kotlin/io/opentelemetry/instrumentation/ktor/v1_0/KtorServerTelemetry.kt

+169
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
/*
2+
* Copyright The OpenTelemetry Authors
3+
* SPDX-License-Identifier: Apache-2.0
4+
*/
5+
6+
package io.opentelemetry.instrumentation.ktor.v1_0
7+
8+
import io.ktor.application.*
9+
import io.ktor.request.*
10+
import io.ktor.response.*
11+
import io.ktor.routing.*
12+
import io.ktor.util.*
13+
import io.ktor.util.pipeline.*
14+
import io.opentelemetry.api.OpenTelemetry
15+
import io.opentelemetry.context.Context
16+
import io.opentelemetry.extension.kotlin.asContextElement
17+
import io.opentelemetry.instrumentation.api.incubator.builder.internal.DefaultHttpServerInstrumenterBuilder
18+
import io.opentelemetry.instrumentation.api.instrumenter.AttributesExtractor
19+
import io.opentelemetry.instrumentation.api.instrumenter.Instrumenter
20+
import io.opentelemetry.instrumentation.api.instrumenter.SpanKindExtractor
21+
import io.opentelemetry.instrumentation.api.instrumenter.SpanStatusBuilder
22+
import io.opentelemetry.instrumentation.api.instrumenter.SpanStatusExtractor
23+
import io.opentelemetry.instrumentation.api.internal.InstrumenterUtil
24+
import io.opentelemetry.instrumentation.api.semconv.http.HttpServerRoute
25+
import io.opentelemetry.instrumentation.api.semconv.http.HttpServerRouteSource
26+
import kotlinx.coroutines.withContext
27+
28+
class KtorServerTelemetry private constructor(
29+
private val instrumenter: Instrumenter<ApplicationRequest, ApplicationResponse>,
30+
) {
31+
32+
class Configuration {
33+
internal lateinit var builder: DefaultHttpServerInstrumenterBuilder<ApplicationRequest, ApplicationResponse>
34+
35+
internal var spanKindExtractor:
36+
(SpanKindExtractor<ApplicationRequest>) -> SpanKindExtractor<ApplicationRequest> = { a -> a }
37+
38+
fun setOpenTelemetry(openTelemetry: OpenTelemetry) {
39+
this.builder =
40+
DefaultHttpServerInstrumenterBuilder.create(
41+
INSTRUMENTATION_NAME,
42+
openTelemetry,
43+
KtorHttpServerAttributesGetter.INSTANCE
44+
)
45+
}
46+
47+
fun setStatusExtractor(
48+
extractor: (SpanStatusExtractor<in ApplicationRequest, in ApplicationResponse>) -> SpanStatusExtractor<in ApplicationRequest, in ApplicationResponse>
49+
) {
50+
builder.setStatusExtractor { prevExtractor ->
51+
SpanStatusExtractor { spanStatusBuilder: SpanStatusBuilder,
52+
request: ApplicationRequest,
53+
response: ApplicationResponse?,
54+
throwable: Throwable? ->
55+
extractor(prevExtractor).extract(spanStatusBuilder, request, response, throwable)
56+
}
57+
}
58+
}
59+
60+
fun setSpanKindExtractor(extractor: (SpanKindExtractor<ApplicationRequest>) -> SpanKindExtractor<ApplicationRequest>) {
61+
this.spanKindExtractor = extractor
62+
}
63+
64+
fun addAttributesExtractor(extractor: AttributesExtractor<in ApplicationRequest, in ApplicationResponse>) {
65+
builder.addAttributesExtractor(extractor)
66+
}
67+
68+
fun setCapturedRequestHeaders(requestHeaders: List<String>) {
69+
builder.setCapturedRequestHeaders(requestHeaders)
70+
}
71+
72+
fun setCapturedResponseHeaders(responseHeaders: List<String>) {
73+
builder.setCapturedResponseHeaders(responseHeaders)
74+
}
75+
76+
fun setKnownMethods(knownMethods: Set<String>) {
77+
builder.setKnownMethods(knownMethods)
78+
}
79+
80+
internal fun isOpenTelemetryInitialized(): Boolean = this::builder.isInitialized
81+
}
82+
83+
private fun start(call: ApplicationCall): Context? {
84+
val parentContext = Context.current()
85+
if (!instrumenter.shouldStart(parentContext, call.request)) {
86+
return null
87+
}
88+
89+
return instrumenter.start(parentContext, call.request)
90+
}
91+
92+
private fun end(context: Context, call: ApplicationCall, error: Throwable?) {
93+
instrumenter.end(context, call.request, call.response, error)
94+
}
95+
96+
companion object Feature : ApplicationFeature<Application, Configuration, KtorServerTelemetry> {
97+
private const val INSTRUMENTATION_NAME = "io.opentelemetry.ktor-1.0"
98+
99+
private val contextKey = AttributeKey<Context>("OpenTelemetry")
100+
private val errorKey = AttributeKey<Throwable>("OpenTelemetryException")
101+
102+
override val key: AttributeKey<KtorServerTelemetry> = AttributeKey("OpenTelemetry")
103+
104+
override fun install(pipeline: Application, configure: Configuration.() -> Unit): KtorServerTelemetry {
105+
val configuration = Configuration().apply(configure)
106+
107+
if (!configuration.isOpenTelemetryInitialized()) {
108+
throw IllegalArgumentException("OpenTelemetry must be set")
109+
}
110+
111+
val instrumenter = InstrumenterUtil.buildUpstreamInstrumenter(
112+
configuration.builder.instrumenterBuilder(),
113+
ApplicationRequestGetter,
114+
configuration.spanKindExtractor(SpanKindExtractor.alwaysServer())
115+
)
116+
117+
val feature = KtorServerTelemetry(instrumenter)
118+
119+
val startPhase = PipelinePhase("OpenTelemetry")
120+
pipeline.insertPhaseBefore(ApplicationCallPipeline.Monitoring, startPhase)
121+
pipeline.intercept(startPhase) {
122+
val context = feature.start(call)
123+
124+
if (context != null) {
125+
call.attributes.put(contextKey, context)
126+
withContext(context.asContextElement()) {
127+
try {
128+
proceed()
129+
} catch (err: Throwable) {
130+
// Stash error for reporting later since need ktor to finish setting up the response
131+
call.attributes.put(errorKey, err)
132+
throw err
133+
}
134+
}
135+
} else {
136+
proceed()
137+
}
138+
}
139+
140+
val postSendPhase = PipelinePhase("OpenTelemetryPostSend")
141+
pipeline.sendPipeline.insertPhaseAfter(ApplicationSendPipeline.After, postSendPhase)
142+
pipeline.sendPipeline.intercept(postSendPhase) {
143+
val context = call.attributes.getOrNull(contextKey)
144+
if (context != null) {
145+
var error: Throwable? = call.attributes.getOrNull(errorKey)
146+
try {
147+
proceed()
148+
} catch (t: Throwable) {
149+
error = t
150+
throw t
151+
} finally {
152+
feature.end(context, call, error)
153+
}
154+
} else {
155+
proceed()
156+
}
157+
}
158+
159+
pipeline.environment.monitor.subscribe(Routing.RoutingCallStarted) { call ->
160+
val context = call.attributes.getOrNull(contextKey)
161+
if (context != null) {
162+
HttpServerRoute.update(context, HttpServerRouteSource.SERVER, { _, arg -> arg.route.parent.toString() }, call)
163+
}
164+
}
165+
166+
return feature
167+
}
168+
}
169+
}

‎instrumentation/ktor/ktor-1.0/library/src/main/kotlin/io/opentelemetry/instrumentation/ktor/v1_0/KtorServerTracing.kt

+1
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@ import io.opentelemetry.instrumentation.api.semconv.http.HttpServerRoute
2525
import io.opentelemetry.instrumentation.api.semconv.http.HttpServerRouteSource
2626
import kotlinx.coroutines.withContext
2727

28+
@Deprecated("Use KtorServerTelemetry instead", ReplaceWith("KtorServerTelemetry"))
2829
class KtorServerTracing private constructor(
2930
private val instrumenter: Instrumenter<ApplicationRequest, ApplicationResponse>,
3031
) {

‎instrumentation/ktor/ktor-1.0/library/src/test/kotlin/io/opentelemetry/instrumentation/ktor/v1_0/KtorHttpServerOldTest.kt

+143
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
/*
2+
* Copyright The OpenTelemetry Authors
3+
* SPDX-License-Identifier: Apache-2.0
4+
*/
5+
6+
package io.opentelemetry.instrumentation.ktor.v1_0
7+
8+
import io.ktor.application.*
9+
import io.ktor.http.*
10+
import io.ktor.request.*
11+
import io.ktor.response.*
12+
import io.ktor.routing.*
13+
import io.ktor.server.engine.*
14+
import io.ktor.server.netty.*
15+
import io.opentelemetry.api.trace.Span
16+
import io.opentelemetry.api.trace.SpanKind
17+
import io.opentelemetry.api.trace.StatusCode
18+
import io.opentelemetry.context.Context
19+
import io.opentelemetry.extension.kotlin.asContextElement
20+
import io.opentelemetry.instrumentation.testing.junit.http.AbstractHttpServerTest
21+
import io.opentelemetry.instrumentation.testing.junit.http.HttpServerInstrumentationExtension
22+
import io.opentelemetry.instrumentation.testing.junit.http.HttpServerTestOptions
23+
import io.opentelemetry.instrumentation.testing.junit.http.ServerEndpoint
24+
import io.opentelemetry.semconv.ServerAttributes
25+
import kotlinx.coroutines.withContext
26+
import org.junit.jupiter.api.extension.RegisterExtension
27+
import java.util.concurrent.ExecutionException
28+
import java.util.concurrent.TimeUnit
29+
30+
class KtorHttpServerOldTest : AbstractHttpServerTest<ApplicationEngine>() {
31+
32+
companion object {
33+
@JvmStatic
34+
@RegisterExtension
35+
val testing = HttpServerInstrumentationExtension.forLibrary()
36+
}
37+
38+
override fun setupServer(): ApplicationEngine {
39+
return embeddedServer(Netty, port = port) {
40+
KtorOldTestUtil.installOpenTelemetry(this, testing.openTelemetry)
41+
42+
routing {
43+
get(ServerEndpoint.SUCCESS.path) {
44+
controller(ServerEndpoint.SUCCESS) {
45+
call.respondText(ServerEndpoint.SUCCESS.body, status = HttpStatusCode.fromValue(ServerEndpoint.SUCCESS.status))
46+
}
47+
}
48+
49+
get(ServerEndpoint.REDIRECT.path) {
50+
controller(ServerEndpoint.REDIRECT) {
51+
call.respondRedirect(ServerEndpoint.REDIRECT.body)
52+
}
53+
}
54+
55+
get(ServerEndpoint.ERROR.path) {
56+
controller(ServerEndpoint.ERROR) {
57+
call.respondText(ServerEndpoint.ERROR.body, status = HttpStatusCode.fromValue(ServerEndpoint.ERROR.status))
58+
}
59+
}
60+
61+
get(ServerEndpoint.EXCEPTION.path) {
62+
controller(ServerEndpoint.EXCEPTION) {
63+
throw IllegalStateException(ServerEndpoint.EXCEPTION.body)
64+
}
65+
}
66+
67+
get("/query") {
68+
controller(ServerEndpoint.QUERY_PARAM) {
69+
call.respondText("some=${call.request.queryParameters["some"]}", status = HttpStatusCode.fromValue(ServerEndpoint.QUERY_PARAM.status))
70+
}
71+
}
72+
73+
get("/path/{id}/param") {
74+
controller(ServerEndpoint.PATH_PARAM) {
75+
call.respondText(
76+
call.parameters["id"]
77+
?: "",
78+
status = HttpStatusCode.fromValue(ServerEndpoint.PATH_PARAM.status),
79+
)
80+
}
81+
}
82+
83+
get("/child") {
84+
controller(ServerEndpoint.INDEXED_CHILD) {
85+
ServerEndpoint.INDEXED_CHILD.collectSpanAttributes { call.request.queryParameters[it] }
86+
call.respondText(ServerEndpoint.INDEXED_CHILD.body, status = HttpStatusCode.fromValue(ServerEndpoint.INDEXED_CHILD.status))
87+
}
88+
}
89+
90+
get("/captureHeaders") {
91+
controller(ServerEndpoint.CAPTURE_HEADERS) {
92+
call.response.header("X-Test-Response", call.request.header("X-Test-Request") ?: "")
93+
call.respondText(ServerEndpoint.CAPTURE_HEADERS.body, status = HttpStatusCode.fromValue(ServerEndpoint.CAPTURE_HEADERS.status))
94+
}
95+
}
96+
}
97+
}.start()
98+
}
99+
100+
override fun stopServer(server: ApplicationEngine) {
101+
server.stop(0, 10, TimeUnit.SECONDS)
102+
}
103+
104+
// Copy in HttpServerTest.controller but make it a suspending function
105+
private suspend fun controller(endpoint: ServerEndpoint, wrapped: suspend () -> Unit) {
106+
assert(Span.current().spanContext.isValid, { "Controller should have a parent span. " })
107+
if (endpoint == ServerEndpoint.NOT_FOUND) {
108+
wrapped()
109+
}
110+
val span = testing.openTelemetry.getTracer("test").spanBuilder("controller").setSpanKind(SpanKind.INTERNAL).startSpan()
111+
try {
112+
withContext(Context.current().with(span).asContextElement()) {
113+
wrapped()
114+
}
115+
span.end()
116+
} catch (e: Exception) {
117+
span.setStatus(StatusCode.ERROR)
118+
span.recordException(if (e is ExecutionException) e.cause ?: e else e)
119+
span.end()
120+
throw e
121+
}
122+
}
123+
124+
override fun configure(options: HttpServerTestOptions) {
125+
options.setTestPathParam(true)
126+
127+
options.setHttpAttributes {
128+
HttpServerTestOptions.DEFAULT_HTTP_ATTRIBUTES - ServerAttributes.SERVER_PORT
129+
}
130+
131+
options.setExpectedHttpRoute { endpoint, method ->
132+
when (endpoint) {
133+
ServerEndpoint.PATH_PARAM -> "/path/{id}/param"
134+
else -> expectedHttpRoute(endpoint, method)
135+
}
136+
}
137+
// ktor does not have a controller lifecycle so the server span ends immediately when the
138+
// response is sent, which is before the controller span finishes.
139+
options.setVerifyServerSpanEndTime(false)
140+
141+
options.setResponseCodeOnNonStandardHttpMethod(404)
142+
}
143+
}

‎instrumentation/ktor/ktor-1.0/library/src/test/kotlin/io/opentelemetry/instrumentation/ktor/v1_0/KtorOldTestUtil.kt

+22
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
/*
2+
* Copyright The OpenTelemetry Authors
3+
* SPDX-License-Identifier: Apache-2.0
4+
*/
5+
6+
package io.opentelemetry.instrumentation.ktor.v1_0
7+
8+
import io.ktor.application.*
9+
import io.opentelemetry.api.OpenTelemetry
10+
import io.opentelemetry.instrumentation.testing.junit.http.AbstractHttpServerTest
11+
12+
class KtorOldTestUtil {
13+
companion object {
14+
fun installOpenTelemetry(application: Application, openTelemetry: OpenTelemetry) {
15+
application.install(KtorServerTracing) {
16+
setOpenTelemetry(openTelemetry)
17+
setCapturedRequestHeaders(listOf(AbstractHttpServerTest.TEST_REQUEST_HEADER))
18+
setCapturedResponseHeaders(listOf(AbstractHttpServerTest.TEST_RESPONSE_HEADER))
19+
}
20+
}
21+
}
22+
}

‎instrumentation/ktor/ktor-1.0/library/src/test/kotlin/io/opentelemetry/instrumentation/ktor/v1_0/KtorServerSpanKindExtractorTest.kt

+1-1
Original file line numberDiff line numberDiff line change
@@ -58,7 +58,7 @@ class KtorServerSpanKindExtractorTest : AbstractHttpServerUsingTest<ApplicationE
5858

5959
override fun setupServer(): ApplicationEngine {
6060
return embeddedServer(Netty, port = port) {
61-
install(KtorServerTracing) {
61+
install(KtorServerTelemetry) {
6262
setOpenTelemetry(testing.openTelemetry)
6363
setSpanKindExtractor {
6464
SpanKindExtractor { req ->

‎instrumentation/ktor/ktor-1.0/library/src/test/kotlin/io/opentelemetry/instrumentation/ktor/v1_0/KtorTestUtil.kt

+1-1
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ import io.opentelemetry.instrumentation.testing.junit.http.AbstractHttpServerTes
1212
class KtorTestUtil {
1313
companion object {
1414
fun installOpenTelemetry(application: Application, openTelemetry: OpenTelemetry) {
15-
application.install(KtorServerTracing) {
15+
application.install(KtorServerTelemetry) {
1616
setOpenTelemetry(openTelemetry)
1717
setCapturedRequestHeaders(listOf(AbstractHttpServerTest.TEST_REQUEST_HEADER))
1818
setCapturedResponseHeaders(listOf(AbstractHttpServerTest.TEST_RESPONSE_HEADER))

0 commit comments

Comments
 (0)