From 38f6e5f297a73d01967403f8981904e6e8185df9 Mon Sep 17 00:00:00 2001
From: Maksym Ochenashko <maxochenashko@gmail.com>
Date: Mon, 30 Oct 2023 21:21:32 +0200
Subject: [PATCH] site: add `Tracing instrumentation` page

---
 docs/instrumentation/directory.conf |  5 ++
 docs/instrumentation/tracing.md     | 79 +++++++++++++++++++++++++++++
 2 files changed, 84 insertions(+)
 create mode 100644 docs/instrumentation/directory.conf
 create mode 100644 docs/instrumentation/tracing.md

diff --git a/docs/instrumentation/directory.conf b/docs/instrumentation/directory.conf
new file mode 100644
index 000000000..4503b4d76
--- /dev/null
+++ b/docs/instrumentation/directory.conf
@@ -0,0 +1,5 @@
+laika.title = Instrumentation
+
+laika.navigationOrder = [
+  tracing
+]
diff --git a/docs/instrumentation/tracing.md b/docs/instrumentation/tracing.md
new file mode 100644
index 000000000..8b935c941
--- /dev/null
+++ b/docs/instrumentation/tracing.md
@@ -0,0 +1,79 @@
+# Tracing
+
+`Tracer` is an entry point to the tracing capabilities.
+
+The Tracer trait is a key component in your library for enabling tracing and instrumentation in your application. It provides various functionalities for creating and managing spans, extracting context from carriers, and more. This documentation outlines the methods and their usage in your library.
+
+These examples demonstrate how to create spans, root spans, and how to disable tracing using noopScope in your library, enhancing your ability to control and monitor your application's behavior.
+
+
+### How to get the tracer
+
+```scala
+
+```
+
+
+### Creating a span
+
+You can use the `span` or `spanBuilder` method to create a new span. 
+
+The tracer automatically determines whether to create a child span or a root span based on the presence of a valid parent in the tracing context. 
+If a valid parent is available, the new span becomes a child of it; otherwise, it becomes a root span. 
+
+Here's how you can do it:
+
+```scala mdoc:silent:reset
+import cats.Monad
+import cats.effect.Ref
+import cats.syntax.flatMap._
+import cats.syntax.functor._
+import org.typelevel.otel4s.Attribute
+import org.typelevel.otel4s.trace.Tracer
+
+case class User(email: String)
+
+class UserRepository[F[_]: Monad: Tracer](storage: Ref[F, Map[Long, User]]) {
+  
+  def findUser(userId: Long): F[Option[User]] =
+    Tracer[F].span("find-user", Attribute("user_id", userId)).use { span =>
+      for {
+        current <- storage.get
+        user    <- Monad[F].pure(current.get(userId))
+        _       <- span.addAttribute(Attribute("user_exists", user.isDefined))
+      } yield user
+    }
+  
+}
+```
+
+### Starting a root span
+
+A root span is a span that is not a child of any other span. 
+You can use `Tracer[F].rootScope` to wrap an existing effect or `Tracer[F].rootSpan` to explicitly start a new root span:
+
+```scala mdoc:silent
+class UserRequestHandler[F[_]: Tracer](repo: UserRepository[F]) {
+  
+  def handleUser(userId: Long): F[Option[User]] =
+    Tracer[F].rootScope(repo.findUser(userId))
+    
+  def handleUserInternal(userId: Long): F[Option[User]] =
+    Tracer[F].rootSpan("handle-for-user").surround(repo.findUser(userId))
+    
+}
+```
+
+### Running effect without tracing
+
+If you want to disable tracing for a specific section of the effect, you can use the `Tracer[F].noopScope` method. 
+This creates a no-op scope where tracing operations have no effect:
+
+```scala mdoc:silent
+class InternalUserService[F[_]: Tracer](repo: UserRepository[F]) {
+  
+  def findUserInternal(userId: Long): F[Option[User]] =
+    Tracer[F].noopScope(repo.findUser(userId))
+  
+}
+```