Add extension functions and example for OpenTelemetry

README.md

@@ -25,6 +25,7 @@ note on [Docs and Samples Migration](https://blog.jetbrains.com/ktor/2020/09/16/
 * [postgres](postgres/README.md) - An application for creating, editing and deleting articles that uses Postgres database running on Docker image as a storage.
 * [mongodb](mongodb/README.md) - An application for creating, editing and deleting articles that uses Mongodb running on Docker image as a storage.
 * [mvc-web](mvc-web/README.md) - An application for adding and removing wishes to wishlist that uses [FreeMarker](https://ktor.io/docs/freemarker.html) templates and Exposed.
+* [opentelemetry](opentelemetry/README.md) - An application that uses Kotlin DSL to work with OpenTelemetry Ktor plugins.
 
 ## Server
 

opentelemetry/README.md

@@ -0,0 +1,63 @@
+# OpenTelemetry-Ktor Demo
+
+## Running
+To run a sample, first, execute the following command in an `opentelemetry` directory:
+```bash
+./gradlew :runWithDocker
+```
+It will start a `Jaeger` in the docker container (`Jaeger UI` available on http://localhost:16686/search) and
+then it will start a `server` on http://localhost:8080/
+
+Then, to run the client, which will send requests to a server, you can execute the following command in an `opentelemetry` directory:
+```bash
+./gradlew :client:run
+```
+
+[OpenTelemetry](https://opentelemetry.io/) has support for `Ktor`, you can find source code [here](https://github.com/open-telemetry/opentelemetry-java-instrumentation/tree/main/instrumentation/ktor).
+It contains plugins for client and server: `KtorClientTracing` and `KtorServerTracing`.
+
+## Motivation
+This project contains extension functions for plugins that allow you to write code in the Ktor DSL style. \
+For example, you can rewrite the next code:
+```kotlin
+install(KtorServerTracing) {
+    ...
+    addAttributeExtractor(
+        object : AttributesExtractor<ApplicationRequest, ApplicationResponse> {
+            override fun onEnd(
+                attributes: AttributesBuilder,
+                context: Context,
+                request: ApplicationRequest,
+                response: ApplicationResponse?,
+                error: Throwable?
+            ) {
+                attributes.put("end-time", Instant.now().toEpochMilli())
+            }
+        }
+    )
+    ...
+}
+```
+To a more readable for `Ktor` style:
+```kotlin
+install(KtorServerTracing) {
+    ...
+    attributeExtractor {
+        onEnd {
+            attributes.put("end-time", Instant.now().toEpochMilli())
+        }
+    }    
+    ...
+}
+```
+You can find all extensions for the client plugin `KtorClientTracing` in the [extractions](./client/src/main/kotlin/opentelemetry/ktor/example/plugins/opentelemetry/extractions/) folder. \
+And you can find all extensions for the server plugin `KtorServerTracing` in the [extractions](./server/src/main/kotlin/opentelemetry/ktor/example/plugins/opentelemetry/extractions/) folder.
+
+## Examples
+Let's see what we will see in the `Jaeger UI` after running the server (with Docker) and client:
+1. We can see two services that send opentelemetry data: `opentelemetry-ktor-sample-server` and `opentelemetry-ktor-sample-client`:
+   ![img.png](images/1.png)
+2. If we choose `opentelemetry-ktor-sample-server` service, we will see the next traces:
+   ![img.png](images/2.png)
+3. And if we choose one of the traces:
+   ![img.png](images/3.png)

opentelemetry/build.gradle.kts

@@ -0,0 +1,32 @@
+description = "OpenTelemetry-Ktor example"
+
+plugins {
+    id("com.avast.gradle.docker-compose") version "0.14.0"
+}
+
+subprojects {
+    group = "opentelemetry.ktor.example"
+    version = "0.0.1"
+
+    repositories {
+        mavenCentral()
+    }
+}
+
+dockerCompose {
+    useComposeFiles.add("docker/docker-compose.yml")
+}
+
+tasks.register("runWithDocker") {
+    dependsOn("composeUp", ":server:run")
+}
+
+project(":server").setEnvironmentVariablesForOpenTelemetry()
+project(":client").setEnvironmentVariablesForOpenTelemetry()
+
+fun Project.setEnvironmentVariablesForOpenTelemetry() {
+    tasks.withType<JavaExec> {
+        environment("OTEL_METRICS_EXPORTER", "none")
+        environment("OTEL_EXPORTER_OTLP_ENDPOINT", "http://localhost:4317/")
+    }
+}

opentelemetry/client/build.gradle.kts

@@ -0,0 +1,28 @@
+val ktor_version: String by project
+val logback_version: String by project
+val kotlin_version: String by project
+val opentelemetry_version: String by project
+
+plugins {
+    kotlin("jvm") version "1.9.21"
+    id("io.ktor.plugin") version "2.3.6"
+    id("application")
+}
+
+application {
+    mainClass.set("opentelemetry.ktor.example.ClientKt")
+
+    val isDevelopment: Boolean = project.ext.has("development")
+    applicationDefaultJvmArgs = listOf("-Dio.ktor.development=$isDevelopment")
+}
+
+dependencies {
+    implementation(project(":shared"))
+
+    implementation("io.ktor:ktor-client-core-jvm")
+    implementation("io.ktor:ktor-client-cio-jvm")
+    implementation("io.ktor:ktor-client-websockets:$ktor_version")
+    implementation("ch.qos.logback:logback-classic:$logback_version")
+
+    implementation("io.opentelemetry.instrumentation:opentelemetry-ktor-2.0:$opentelemetry_version-alpha")
+}

opentelemetry/client/src/main/kotlin/opentelemetry/ktor/example/Client.kt

@@ -0,0 +1,23 @@
+package opentelemetry.ktor.example
+
+import io.ktor.client.*
+import io.ktor.client.engine.cio.*
+import io.ktor.client.plugins.*
+import io.ktor.client.plugins.websocket.*
+import opentelemetry.ktor.example.plugins.opentelemetry.installOpenTelemetryOnClient
+
+suspend fun main() {
+    val openTelemetry = getOpenTelemetry(serviceName = "opentelemetry-ktor-sample-client")
+
+    val client = HttpClient(CIO) {
+        install(WebSockets)
+
+        defaultRequest {
+            url("http://$SERVER_HOST:$SERVER_PORT")
+        }
+
+        installOpenTelemetryOnClient(openTelemetry)
+    }
+
+    doRequests(client)
+}

opentelemetry/client/src/main/kotlin/opentelemetry/ktor/example/Requests.kt

@@ -0,0 +1,34 @@
+package opentelemetry.ktor.example
+
+import io.ktor.client.*
+import io.ktor.client.plugins.websocket.*
+import io.ktor.client.request.*
+import io.ktor.websocket.*
+
+
+suspend fun doRequests(client: HttpClient) {
+    client.request("/known-methods") {
+        method = CUSTOM_METHOD
+    }
+
+    client.request("/known-methods") {
+        method = CUSTOM_METHOD_NOT_KNOWN
+    }
+
+    client.get("/captured-headers")
+
+    client.get("/span-status-extractor")
+
+    client.post("/span-kind-extractor")
+
+    client.get("/attribute-extractor")
+
+    client.get("/opentelemetry/tracer")
+
+    client.ws("/opentelemetry/websocket") {
+        send(Frame.Text("Hello, world!"))
+        repeat(10) {
+            send(incoming.receive())
+        }
+    }
+}

opentelemetry/client/src/main/kotlin/opentelemetry/ktor/example/plugins/opentelemetry/configureOpenTelemetryClient.kt

@@ -0,0 +1,36 @@
+package opentelemetry.ktor.example.plugins.opentelemetry
+
+import opentelemetry.ktor.example.CUSTOM_HEADER
+import opentelemetry.ktor.example.CUSTOM_METHOD
+import io.ktor.client.*
+import io.ktor.client.engine.cio.*
+import io.ktor.http.*
+import io.opentelemetry.api.OpenTelemetry
+import io.opentelemetry.instrumentation.ktor.v2_0.client.KtorClientTracing
+import opentelemetry.ktor.example.plugins.opentelemetry.extractions.*
+
+
+/**
+ * Install OpenTelemetry on the client.
+ * You can see usages of new extension functions for [KtorClientTracing].
+ */
+fun HttpClientConfig<CIOEngineConfig>.installOpenTelemetryOnClient(openTelemetry: OpenTelemetry) {
+    install(KtorClientTracing) {
+        setOpenTelemetry(openTelemetry)
+
+        emitExperimentalHttpClientMetrics()
+
+        knownMethods(HttpMethod.DefaultMethods + CUSTOM_METHOD)
+        capturedRequestHeaders(HttpHeaders.UserAgent)
+        capturedResponseHeaders(HttpHeaders.ContentType, CUSTOM_HEADER)
+
+        attributeExtractor {
+            onStart {
+                attributes.put("start-time", System.currentTimeMillis())
+            }
+            onEnd {
+                attributes.put("end-time", System.currentTimeMillis())
+            }
+        }
+    }
+}

opentelemetry/client/src/main/kotlin/opentelemetry/ktor/example/plugins/opentelemetry/extractions/attributeExtractor.kt

@@ -0,0 +1,69 @@
+package opentelemetry.ktor.example.plugins.opentelemetry.extractions
+
+import io.ktor.client.request.*
+import io.ktor.client.statement.*
+import io.opentelemetry.api.common.AttributesBuilder
+import io.opentelemetry.context.Context
+import io.opentelemetry.instrumentation.api.instrumenter.AttributesExtractor
+import io.opentelemetry.instrumentation.ktor.v2_0.client.KtorClientTracingBuilder
+
+// addAttributeExtractor
+fun KtorClientTracingBuilder.attributeExtractor(
+    extractorBuilder: ExtractorBuilder.() -> Unit = {}
+) {
+    val builder = ExtractorBuilder().apply(extractorBuilder).build()
+    addAttributesExtractors(
+        object : AttributesExtractor<HttpRequestData, HttpResponse> {
+            override fun onStart(
+                attributes: AttributesBuilder,
+                parentContext: Context,
+                request: HttpRequestData
+            ) {
+                builder.onStart(OnStartData(attributes, parentContext, request))
+            }
+
+            override fun onEnd(
+                attributes: AttributesBuilder,
+                context: Context,
+                request: HttpRequestData,
+                response: HttpResponse?,
+                error: Throwable?
+            ) {
+                builder.onEnd(OnEndData(attributes, context, request, response, error))
+            }
+        }
+    )
+}
+
+class ExtractorBuilder {
+    private var onStart: OnStartData.() -> Unit = {}
+    private var onEnd: OnEndData.() -> Unit = {}
+
+    fun onStart(block: OnStartData.() -> Unit) {
+        onStart = block
+    }
+
+    fun onEnd(block: OnEndData.() -> Unit) {
+        onEnd = block
+    }
+
+    internal fun build(): Extractor {
+        return Extractor(onStart, onEnd)
+    }
+}
+
+internal class Extractor(val onStart: OnStartData.() -> Unit, val onEnd: OnEndData.() -> Unit)
+
+data class OnStartData(
+    val attributes: AttributesBuilder,
+    val parentContext: Context,
+    val request: HttpRequestData
+)
+
+data class OnEndData(
+    val attributes: AttributesBuilder,
+    val parentContext: Context,
+    val request: HttpRequestData,
+    val response: HttpResponse?,
+    val error: Throwable?
+)

opentelemetry/client/src/main/kotlin/opentelemetry/ktor/example/plugins/opentelemetry/extractions/capturedHeaders.kt

@@ -0,0 +1,21 @@
+package opentelemetry.ktor.example.plugins.opentelemetry.extractions
+
+import io.opentelemetry.instrumentation.ktor.v2_0.client.KtorClientTracingBuilder
+
+// setCapturedRequestHeaders
+fun KtorClientTracingBuilder.capturedRequestHeaders(vararg headers: String) {
+    capturedRequestHeaders(headers.asIterable())
+}
+
+fun KtorClientTracingBuilder.capturedRequestHeaders(headers: Iterable<String>) {
+    setCapturedRequestHeaders(headers.toList())
+}
+
+// setCapturedResponseHeaders
+fun KtorClientTracingBuilder.capturedResponseHeaders(vararg headers: String) {
+    capturedResponseHeaders(headers.asIterable())
+}
+
+fun KtorClientTracingBuilder.capturedResponseHeaders(headers: Iterable<String>) {
+    setCapturedResponseHeaders(headers.toList())
+}

opentelemetry/client/src/main/kotlin/opentelemetry/ktor/example/plugins/opentelemetry/extractions/emitExperimentalHttpClientMetrics.kt

@@ -0,0 +1,8 @@
+package opentelemetry.ktor.example.plugins.opentelemetry.extractions
+
+import io.opentelemetry.instrumentation.ktor.v2_0.client.KtorClientTracingBuilder
+
+// setEmitExperimentalHttpClientMetrics
+fun KtorClientTracingBuilder.emitExperimentalHttpClientMetrics() {
+    setEmitExperimentalHttpClientMetrics(true)
+}

opentelemetry/client/src/main/kotlin/opentelemetry/ktor/example/plugins/opentelemetry/extractions/knownMethods.kt

@@ -0,0 +1,13 @@
+package opentelemetry.ktor.example.plugins.opentelemetry.extractions
+
+import io.ktor.http.*
+import io.opentelemetry.instrumentation.ktor.v2_0.client.KtorClientTracingBuilder
+
+// setKnownMethods
+fun KtorClientTracingBuilder.knownMethods(vararg methods: HttpMethod) {
+    knownMethods(methods.asIterable())
+}
+
+fun KtorClientTracingBuilder.knownMethods(methods: Iterable<HttpMethod>) {
+    setKnownMethods(methods.map { it.value }.toSet())
+}

opentelemetry/docker/docker-compose.yml

@@ -0,0 +1,8 @@
+# This file is used to start the Jaeger all-in-one container
+version: '3.7'
+services:
+  jaeger:
+    image: jaegertracing/all-in-one:latest
+    ports:
+      - "4317:4317"   # OTLP gRPC receiver
+      - "16686:16686" # Jaeger UI

opentelemetry/gradle.properties

@@ -0,0 +1,7 @@
+ktor_version=2.3.6
+kotlin_version=1.9.21
+logback_version=1.4.11
+kotlin.code.style=official
+
+opentelemetry_version=1.32.0
+opentelemetry_semconv_version=1.21.0-alpha

opentelemetry/gradle/wrapper/gradle-wrapper.properties

@@ -0,0 +1,5 @@
+distributionBase=GRADLE_USER_HOME
+distributionPath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.4-bin.zip
+zipStoreBase=GRADLE_USER_HOME
+zipStorePath=wrapper/dists