Merge pull request #789 from iRevive/sdk-contrib-aws/aws-xray-docs

sdk-contrib-aws: add docs for AwsXRayIdGenerator
typelevel · Sep 24, 2024 · 4437cd1 · 4437cd1
2 parents 28b19c6 + 9220089
commit 4437cd1
Show file tree

Hide file tree

Showing 5 changed files with 178 additions and 3 deletions.
diff --git a/build.sbt b/build.sbt
@@ -106,8 +106,8 @@ lazy val root = tlCrossRootProject
     `sdk-exporter-metrics`,
     `sdk-exporter-trace`,
     `sdk-exporter`,
-    `sdk-contrib-aws-xray`,
     `sdk-contrib-aws-resource`,
+    `sdk-contrib-aws-xray`,
     `sdk-contrib-aws-xray-propagator`,
     `oteljava-common`,
     `oteljava-common-testkit`,
@@ -752,6 +752,7 @@ lazy val docs = project
     sdk.jvm,
     `sdk-exporter`.jvm,
     `sdk-contrib-aws-resource`.jvm,
+    `sdk-contrib-aws-xray`.jvm,
     `sdk-contrib-aws-xray-propagator`.jvm
   )
   .settings(
@@ -827,6 +828,7 @@ lazy val unidocs = project
       `sdk-exporter-trace`.jvm,
       `sdk-exporter`.jvm,
       `sdk-contrib-aws-resource`.jvm,
+      `sdk-contrib-aws-xray`.jvm,
       `sdk-contrib-aws-xray-propagator`.jvm,
       `oteljava-common`,
       `oteljava-common-testkit`,

diff --git a/docs/sdk/aws-xray.md b/docs/sdk/aws-xray.md
@@ -0,0 +1,142 @@
+# AWS | X-Ray ID Generator
+
+The AWS X-Ray ID generator generates trace IDs that are compatible with AWS X-Ray tracing [spec][xray-traceid].
+An example of the AWS X-Ray trace and span IDs:
+```scala mdoc:passthrough
+import cats.effect.IO
+import cats.effect.std.Random
+import cats.effect.unsafe.implicits.global
+import org.typelevel.otel4s.sdk.trace.contrib.aws.xray._
+
+val (traceId, spanId) = Random.scalaUtilRandom[IO].flatMap { implicit random =>
+  val generator = AwsXRayIdGenerator[IO]
+  for {
+    traceId <- generator.generateTraceId
+    spanId <- generator.generateSpanId
+  } yield (traceId.toHex, spanId.toHex)
+}.unsafeRunSync()
+
+println("```yaml")
+println("trace_id: " + traceId)
+println("span_id: " + spanId)
+println("```")
+```
+
+## Getting Started
+
+@:select(build-tool)
+
+@:choice(sbt)
+
+Add settings to the `build.sbt`:
+
+```scala
+libraryDependencies ++= Seq(
+  "org.typelevel" %%% "otel4s-sdk" % "@VERSION@", // <1>
+  "org.typelevel" %%% "otel4s-sdk-exporter" % "@VERSION@", // <2>
+  "org.typelevel" %%% "otel4s-sdk-contrib-aws-xray" % "@VERSION@" // <3>
+)
+```
+
+@:choice(scala-cli)
+
+Add directives to the `*.scala` file:
+
+```scala
+//> using lib "org.typelevel::otel4s-sdk::@VERSION@" // <1>
+//> using lib "org.typelevel::otel4s-sdk-exporter::@VERSION@" // <2>
+//> using lib "org.typelevel::otel4s-sdk-contrib-aws-xray::@VERSION@" // <3>
+```
+
+@:@
+
+1. Add the `otel4s-sdk` library
+2. Add the `otel4s-sdk-exporter` library. Without the exporter, the application will crash
+3. Add the `otel4s-sdk-contrib-aws-xray` library
+
+_______
+
+Then autoconfigure the SDK:
+
+@:select(sdk-entry-point)
+
+@:choice(sdk)
+
+`OpenTelemetrySdk.autoConfigured` configures both `MeterProvider` and `TracerProvider`:
+
+```scala mdoc:reset:silent
+import cats.effect.{IO, IOApp}
+import cats.effect.std.Random
+import org.typelevel.otel4s.metrics.MeterProvider
+import org.typelevel.otel4s.sdk.OpenTelemetrySdk
+import org.typelevel.otel4s.sdk.exporter.otlp.autoconfigure.OtlpExportersAutoConfigure
+import org.typelevel.otel4s.sdk.trace.contrib.aws.xray._
+import org.typelevel.otel4s.trace.TracerProvider
+
+object TelemetryApp extends IOApp.Simple {
+
+  def run: IO[Unit] = 
+    Random.scalaUtilRandom[IO].flatMap { implicit random =>
+      OpenTelemetrySdk
+        .autoConfigured[IO](
+          // register OTLP exporters configurer
+          _.addExportersConfigurer(OtlpExportersAutoConfigure[IO])
+            // add AWS X-Ray ID generator
+            .addTracerProviderCustomizer((b, _) =>
+              b.withIdGenerator(AwsXRayIdGenerator[IO])
+            )
+        )
+        .use { autoConfigured =>
+          val sdk = autoConfigured.sdk
+          program(sdk.meterProvider, sdk.tracerProvider)
+        } 
+    }
+
+  def program(
+      meterProvider: MeterProvider[IO], 
+      tracerProvider: TracerProvider[IO]
+  ): IO[Unit] =
+    ???
+}
+```
+
+@:choice(traces)
+
+`SdkTraces` configures only `TracerProvider`:
+
+```scala mdoc:reset:silent
+import cats.effect.{IO, IOApp}
+import cats.effect.std.Random
+import org.typelevel.otel4s.sdk.exporter.otlp.trace.autoconfigure.OtlpSpanExporterAutoConfigure
+import org.typelevel.otel4s.sdk.trace.SdkTraces
+import org.typelevel.otel4s.sdk.trace.contrib.aws.xray._
+import org.typelevel.otel4s.trace.TracerProvider
+
+object TelemetryApp extends IOApp.Simple {
+
+  def run: IO[Unit] =
+    Random.scalaUtilRandom[IO].flatMap { implicit random =>
+      SdkTraces
+        .autoConfigured[IO](
+          // register OTLP exporters configurer
+          _.addExporterConfigurer(OtlpSpanExporterAutoConfigure[IO])
+            // add AWS X-Ray ID generator
+            .addTracerProviderCustomizer((b, _) =>
+              b.withIdGenerator(AwsXRayIdGenerator[IO])
+            )
+        )
+        .use { autoConfigured =>
+          program(autoConfigured.tracerProvider)
+        }
+    }
+
+  def program(
+      tracerProvider: TracerProvider[IO]
+  ): IO[Unit] =
+    ???
+}
+```
+
+@:@
+
+[xray-traceid]: https://docs.aws.amazon.com/xray/latest/devguide/xray-api-sendingdata.html#xray-api-traceids
diff --git a/docs/sdk/directory.conf b/docs/sdk/directory.conf
@@ -4,5 +4,6 @@ laika.navigationOrder = [
   overview.md
   configuration.md
   aws-resource-detectors.md
+  aws-xray.md
   aws-xray-propagator.md
 ]
diff --git a/...race/contrib/aws/AwsXRayIdGenerator.scala → ...contrib/aws/xray/AwsXRayIdGenerator.scala b/...race/contrib/aws/AwsXRayIdGenerator.scala → ...contrib/aws/xray/AwsXRayIdGenerator.scala
@@ -19,7 +19,7 @@
  * which was originally based on https://github.com/open-telemetry/opentelemetry-java-contrib/blob/eece7e8ef04170fb463ddf692f61d4527b50febf/aws-xray/src/main/java/io/opentelemetry/contrib/awsxray/AwsXrayIdGenerator.java
  * SPDX-License-Identifier: Apache-2.0
  */
-package org.typelevel.otel4s.sdk.trace.contrib.aws
+package org.typelevel.otel4s.sdk.trace.contrib.aws.xray
 
 import cats._
 import cats.effect._
@@ -30,9 +30,39 @@ import org.typelevel.otel4s.trace.SpanContext._
 import scodec.bits.ByteVector
 
 object AwsXRayIdGenerator {
+
+  /** Generates trace IDs that are compatible with AWS X-Ray tracing spec.
+    *
+    * @example
+    *   {{{
+    * Random.scalaUtilRandom[IO].flatMap { implicit random =>
+    *   OpenTelemetrySdk
+    *     .autoConfigured[IO](
+    *       // register OTLP exporters configurer
+    *       _.addExportersConfigurer(OtlpExportersAutoConfigure[IO])
+    *       // set AWS X-Ray ID generator
+    *        .addTracerProviderCustomizer((b, _) => b.withIdGenerator(AwsXRayIdGenerator[IO]))
+    *     )
+    *     .use { autoConfigured =>
+    *       val sdk = autoConfigured.sdk
+    *       ???
+    *     }
+    * }
+    *   }}}
+    *
+    * @see
+    *   [[https://docs.aws.amazon.com/xray/latest/devguide/xray-api-sendingdata.html#xray-api-traceids]]
+    */
   def apply[F[_]: Monad: Clock: Random]: AwsXRayIdGenerator[F] = new AwsXRayIdGenerator
 }
 
+/** Generates trace IDs that are compatible with AWS X-Ray tracing spec.
+  *
+  * According to the X-Ray spec, the first 32 bits of the trace ID represent the Unix epoch time in seconds.
+  *
+  * @see
+  *   [[https://docs.aws.amazon.com/xray/latest/devguide/xray-api-sendingdata.html#xray-api-traceids]]
+  */
 class AwsXRayIdGenerator[F[_]: Monad: Clock: Random] extends IdGenerator[F] {
   override def generateSpanId: F[ByteVector] =
     Random[F].nextLong

diff --git a/...contrib/aws/AwsXRayIdGeneratorSuite.scala → ...ib/aws/xray/AwsXRayIdGeneratorSuite.scala b/...contrib/aws/AwsXRayIdGeneratorSuite.scala → ...ib/aws/xray/AwsXRayIdGeneratorSuite.scala
@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-package org.typelevel.otel4s.sdk.trace.contrib.aws
+package org.typelevel.otel4s.sdk.trace.contrib.aws.xray
 
 import cats.MonadThrow
 import cats.effect._