Add PropagationContextElement Kotlin operator

Prior to this commit, the Micrometer context-propagation project would
help propagating information from `ThreadLocal`, Reactor `Context` and
other context objects. This is already well supported for Micrometer
Observations.

In the case of Kotlin suspending functions, the processing of tasks
would not necessarily update the `ThreadLocal` when the function is
scheduled on a different thread.

This commit introduces the `PropagationContextElement` operator that
connects the `ThreadLocal`, Reactor `Context` and Coroutine `Context`
for all libraries using the "context-propagation" project.

Applications must manually use this operator in suspending functions
like so:

```
suspend fun suspendingFunction() {
  return withContext(PropagationContextElement(currentCoroutineContext())) {
    logger.info("Suspending function with traceId")
  }
}
```

Closes gh-35185

framework-docs/framework-docs.gradle

@@ -65,6 +65,7 @@ dependencies {
 	implementation("com.github.ben-manes.caffeine:caffeine")
 	implementation("com.mchange:c3p0:0.9.5.5")
 	implementation("com.oracle.database.jdbc:ojdbc11")
+    implementation("io.micrometer:context-propagation")
 	implementation("io.projectreactor.netty:reactor-netty-http")
 	implementation("jakarta.jms:jakarta.jms-api")
 	implementation("jakarta.servlet:jakarta.servlet-api")
@@ -78,6 +79,8 @@ dependencies {
 	implementation("org.assertj:assertj-core")
 	implementation("org.eclipse.jetty.websocket:jetty-websocket-jetty-api")
 	implementation("org.jetbrains.kotlin:kotlin-stdlib")
+    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core")
+    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-reactor")
 	implementation("org.junit.jupiter:junit-jupiter-api")
 	implementation("tools.jackson.core:jackson-databind")
 	implementation("tools.jackson.dataformat:jackson-dataformat-xml")

framework-docs/modules/ROOT/pages/languages/kotlin/coroutines.adoc

@@ -250,3 +250,36 @@ For Kotlin `Flow`, a  `Flow<T>.transactional` extension is provided.
 		}
 	}
 ----
+
+[[coroutines.propagation]]
+== Context Propagation
+
+Spring applications are xref:integration/observability.adoc[instrumented with Micrometer for Observability support].
+For tracing support, the current observation is propagated through a `ThreadLocal` for blocking code,
+or the Reactor `Context` for reactive pipelines. But the current observation also needs to be made available
+in the execution context of a suspended function. Without that, the current "traceId" will not be automatically prepended
+to logged statements from coroutines.
+
+The `org.springframework.core.PropagationContextElement` operator generally ensures that the
+{micrometer-context-propagation-docs}/[Micrometer Context Propagation library] works with Kotlin Coroutines.
+
+The `PropagationContextElement` requires the following dependencies:
+
+`build.gradle.kts`
+[source,kotlin,indent=0]
+----
+dependencies {
+    implementation("io.micrometer:context-propagation:${contextPropagationVersion}")
+	implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:${coroutinesVersion}")
+	implementation("org.jetbrains.kotlinx:kotlinx-coroutines-reactor:${coroutinesVersion}")
+}
+----
+
+Applications can then use the `PropagationContextElement` operator to connect the `currentCoroutineContext()`
+with the context propagation mechanism:
+
+include-code::./ContextPropagationSample[tag=context,indent=0]
+
+Here, assuming that Micrometer Tracing is configured, the resulting logging statement
+will show the current "traceId" and unlock better observability for your application.
+

framework-docs/src/main/kotlin/org/springframework/docs/languages/kotlin/coroutines/propagation/ContextPropagationSample.kt

@@ -0,0 +1,40 @@
+/*
+ * Copyright 2002-present the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.docs.languages.kotlin.coroutines.propagation
+
+import kotlinx.coroutines.currentCoroutineContext
+import kotlinx.coroutines.withContext
+import org.apache.commons.logging.Log
+import org.apache.commons.logging.LogFactory
+import org.springframework.core.PropagationContextElement
+
+class ContextPropagationSample {
+
+	companion object {
+		private val logger: Log = LogFactory.getLog(
+			ContextPropagationSample::class.java
+		)
+	}
+
+	// tag::context[]
+	suspend fun suspendingFunction() {
+		return withContext(PropagationContextElement(currentCoroutineContext())) {
+            logger.info("Suspending function with traceId")
+        }
+	}
+	// end::context[]
+}