site: add Tracing instrumentation page

docs/instrumentation/directory.conf

@@ -0,0 +1,5 @@
+laika.title = Instrumentation
+
+laika.navigationOrder = [
+  tracing
+]

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))
+
+}
+```