From 73d89ce2536636882da0a93794bd3aab5c917199 Mon Sep 17 00:00:00 2001 From: Michael Wizner Date: Mon, 16 Dec 2024 17:41:41 +0000 Subject: [PATCH 1/4] Add an example of Trace instance for IO --- modules/docs/src/main/paradox/reference/trace.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/modules/docs/src/main/paradox/reference/trace.md b/modules/docs/src/main/paradox/reference/trace.md index f1b304bd..f20a51a7 100644 --- a/modules/docs/src/main/paradox/reference/trace.md +++ b/modules/docs/src/main/paradox/reference/trace.md @@ -84,4 +84,11 @@ This is more general than the `Kleisli` instance above and allows you to instant Given a `Span[F]` you can construct a `Trace[IO]` for **Cats-Effect 3** (for Cats-Effect 2 you will need to use `Kleisli` or `Local` above). This uses `FiberLocal` to pass the span around. -TODO: Example +```scala mdoc +import cats.effect.IO + +def goIO(span: Span[IO]): IO[Unit] = + Trace.ioTrace(span).flatMap { implicit trace => + wibble[IO]("bob", 42) + } +``` From 93a48fb93ac4fe375550086c3a14e72b554fbea2 Mon Sep 17 00:00:00 2001 From: Michael Wizner Date: Mon, 16 Dec 2024 18:21:06 +0000 Subject: [PATCH 2/4] Add an EntryPoint example --- .../docs/src/main/paradox/reference/trace.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/modules/docs/src/main/paradox/reference/trace.md b/modules/docs/src/main/paradox/reference/trace.md index f20a51a7..5a2ab5c3 100644 --- a/modules/docs/src/main/paradox/reference/trace.md +++ b/modules/docs/src/main/paradox/reference/trace.md @@ -83,6 +83,10 @@ This is more general than the `Kleisli` instance above and allows you to instant ## Cats-Effect 3 IO Instance Given a `Span[F]` you can construct a `Trace[IO]` for **Cats-Effect 3** (for Cats-Effect 2 you will need to use `Kleisli` or `Local` above). This uses `FiberLocal` to pass the span around. +Given a `Span[F]` you can construct a `Trace[IO]` for **Cats-Effect 3** (for +Given a `Span[IO]` you can construct a `Trace[IO]` for **Cats-Effect 3** (for +Cats-Effect 2 you will need to use `Kleisli` or `Local` above). This uses +`IOLocal` to pass the span around. ```scala mdoc import cats.effect.IO @@ -92,3 +96,17 @@ def goIO(span: Span[IO]): IO[Unit] = wibble[IO]("bob", 42) } ``` + +Alternatively, a `Trace[IO]` can be constructed from an `EntryPoint`, which +Alternatively, a `Trace[IO]` can be constructed from an `EntryPoint[IO]`, which +takes care of creation of child spans. + +```scala mdoc +import cats.effect.IO +import natchez.EntryPoint + +def goIO(ep: EntryPoint[IO]): IO[Unit] = + Trace.ioTraceForEntryPoint(ep).flatMap { implicit trace => + wibble[IO]("bob", 42) + } +``` From 0790449f0e93b1ceffec0bc9ef1d3367faecc4e7 Mon Sep 17 00:00:00 2001 From: Michael Wizner Date: Mon, 16 Dec 2024 18:21:57 +0000 Subject: [PATCH 3/4] Add an EntryPoint example --- modules/docs/src/main/paradox/reference/trace.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/modules/docs/src/main/paradox/reference/trace.md b/modules/docs/src/main/paradox/reference/trace.md index 5a2ab5c3..5b3f9752 100644 --- a/modules/docs/src/main/paradox/reference/trace.md +++ b/modules/docs/src/main/paradox/reference/trace.md @@ -82,8 +82,6 @@ This is more general than the `Kleisli` instance above and allows you to instant ## Cats-Effect 3 IO Instance -Given a `Span[F]` you can construct a `Trace[IO]` for **Cats-Effect 3** (for Cats-Effect 2 you will need to use `Kleisli` or `Local` above). This uses `FiberLocal` to pass the span around. -Given a `Span[F]` you can construct a `Trace[IO]` for **Cats-Effect 3** (for Given a `Span[IO]` you can construct a `Trace[IO]` for **Cats-Effect 3** (for Cats-Effect 2 you will need to use `Kleisli` or `Local` above). This uses `IOLocal` to pass the span around. @@ -97,7 +95,6 @@ def goIO(span: Span[IO]): IO[Unit] = } ``` -Alternatively, a `Trace[IO]` can be constructed from an `EntryPoint`, which Alternatively, a `Trace[IO]` can be constructed from an `EntryPoint[IO]`, which takes care of creation of child spans. From 112a103e774c57a3d8fade96bc2d9e016d2dc2eb Mon Sep 17 00:00:00 2001 From: Michael Wizner Date: Tue, 17 Dec 2024 10:58:15 +0000 Subject: [PATCH 4/4] Prefer constructing Trace from EntryPoint --- .../docs/src/main/paradox/reference/trace.md | 21 ++++++++++--------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/modules/docs/src/main/paradox/reference/trace.md b/modules/docs/src/main/paradox/reference/trace.md index 5b3f9752..4ff8b81a 100644 --- a/modules/docs/src/main/paradox/reference/trace.md +++ b/modules/docs/src/main/paradox/reference/trace.md @@ -82,28 +82,29 @@ This is more general than the `Kleisli` instance above and allows you to instant ## Cats-Effect 3 IO Instance -Given a `Span[IO]` you can construct a `Trace[IO]` for **Cats-Effect 3** (for -Cats-Effect 2 you will need to use `Kleisli` or `Local` above). This uses -`IOLocal` to pass the span around. +Given an `EntryPoint[IO]` you can construct a `Trace[IO]` for **Cats-Effect 3**. +This will create a root span for each requested child span. ```scala mdoc import cats.effect.IO +import natchez.EntryPoint -def goIO(span: Span[IO]): IO[Unit] = - Trace.ioTrace(span).flatMap { implicit trace => +def goIO(ep: EntryPoint[IO]): IO[Unit] = + Trace.ioTraceForEntryPoint(ep).flatMap { implicit trace => wibble[IO]("bob", 42) } ``` -Alternatively, a `Trace[IO]` can be constructed from an `EntryPoint[IO]`, which -takes care of creation of child spans. +Alternatively, a `Trace[IO]` can be constructed from a `Span[IO]` directly. ```scala mdoc import cats.effect.IO -import natchez.EntryPoint -def goIO(ep: EntryPoint[IO]): IO[Unit] = - Trace.ioTraceForEntryPoint(ep).flatMap { implicit trace => +def goIO(span: Span[IO]): IO[Unit] = + Trace.ioTrace(span).flatMap { implicit trace => wibble[IO]("bob", 42) } ``` + +Both methods use `IOLocal` to pass the span around. For Cats-Effect 2 you will +need to use `Kleisli` or `Local` as described above.