Natchez

https://typelevel.org/natchez/
Admin
Natchez is a minimal distributed tracing library for Cats that provides interfaces to abstract over...
Tokens:5,563
Snippets:68
Trust Score:9.6
Update:6 months ago
Show doc for...
Tokens:
Raw
### Construct Honeycomb EntryPoint

Source: https://typelevel.org/natchez/backends/honeycomb.html

Example of creating a Natchez EntryPoint for Honeycomb. Requires Cats Effect's Sync and provides a service name, API key, and dataset.

```scala
import cats.effect.{ Resource, Sync }
import natchez.EntryPoint
import natchez.honeycomb.Honeycomb

def entryPoint[F[_]: Sync]: Resource[F, EntryPoint[F]] = 
  Honeycomb.entryPoint[F]("my-service") { ob =>
    Sync[F].delay {
      ob.setWriteKey("<my API key>")
        .setDataset("<my dataset>")
        .build
    }
  }
```

--------------------------------

### Imports for Natchez Http4s Examples

Source: https://typelevel.org/natchez/reference/kernels.html

Required imports for working with Natchez spans and Http4s client requests.

```scala
import cats.effect.IO
import natchez.{ Span }
import org.http4s.{ EntityDecoder, Uri, Header }
import org.http4s.Method.GET
import org.http4s.client.Client
import org.http4s.client.dsl.io._
import org.typelevel.ci.CIString
```

--------------------------------

### Example Trace JSON Output

Source: https://typelevel.org/natchez/backends/log.html

A sample JSON structure representing a root span with two child spans as produced by the log handler.

```json
{
  "name" : "root span",
  "service" : "example-service",
  "timestamp" : "2021-05-26T16:41:09.221325Z",
  "duration_ms" : 108,
  "trace.span_id" : "dd817430-c00a-423e-9db4-0a24897b9cb9",
  "trace.parent_id" : null,
  "trace.trace_id" : "ef7758f0-7b33-4358-81f5-4f2070f7196d",
  "exit.case" : "succeeded",
  "person.name" : "bob",
  "person.age" : 42,
  "children" : [
    {
      "name" : "thing one",
      "service" : "example-service",
      "timestamp" : "2021-05-26T16:41:09.301796Z",
      "duration_ms" : 3,
      "trace.span_id" : "93f6aab7-b89d-4c11-b21a-2272ae6f5697",
      "trace.parent_id" : "ef7758f0-7b33-4358-81f5-4f2070f7196d",
      "trace.trace_id" : "ef7758f0-7b33-4358-81f5-4f2070f7196d",
      "exit.case" : "succeeded",
      "children" : [
      ]
    },
    {
      "name" : "thing two",
      "service" : "example-service",
      "timestamp" : "2021-05-26T16:41:09.328357Z",
      "duration_ms" : 1,
      "trace.span_id" : "f94c8eed-8c1a-4c02-b40e-36266e40b4d5",
      "trace.parent_id" : "ef7758f0-7b33-4358-81f5-4f2070f7196d",
      "trace.trace_id" : "ef7758f0-7b33-4358-81f5-4f2070f7196d",
      "exit.case" : "succeeded",
      "children" : [
      ]
    }
  ]
}
```

--------------------------------

### Using Trace[F] Implicitly

Source: https://typelevel.org/natchez/backends/noop.html

Once the no-op instance is in scope, Trace[F] will be available implicitly for any applicative functor F. This example shows how Trace[Option] is satisfied.

```scala
import natchez.Trace

def foo[F[_]: Trace]: F[Unit] = ???

// Trace[Option] is satisfied, for example.
def go = foo[Option]
```

--------------------------------

### Log EntryPoint Construction

Source: https://typelevel.org/natchez/backends/log.html

How to construct a log EntryPoint using an implicit Logger.

```APIDOC
## Log EntryPoint Construction

### Description
Constructs a log EntryPoint given an implicit Logger[F].

### Request Example
```scala
import cats.effect.IO
import natchez.EntryPoint
import natchez.log.Log
import org.typelevel.log4cats.Logger
import org.typelevel.log4cats.slf4j.Slf4jLogger

implicit val log: Logger[IO] = Slf4jLogger.getLoggerFromName("example-logger")

val ep: EntryPoint[IO] = Log.entryPoint[IO]("example-service")
```
```

--------------------------------

### Constructing a Log EntryPoint

Source: https://typelevel.org/natchez/backends/log.html

Initialization of a log EntryPoint using an implicit log4cats Logger.

```scala
import cats.effect.IO
import natchez.EntryPoint
import natchez.log.Log
import org.typelevel.log4cats.Logger
import org.typelevel.log4cats.slf4j.Slf4jLogger

implicit val log: Logger[IO] =
  Slf4jLogger.getLoggerFromName("example-logger")

val ep: EntryPoint[IO] =
  Log.entryPoint[IO]("example-service")
```

--------------------------------

### Add natchez-log dependency

Source: https://typelevel.org/natchez/backends/log.html

Configuration snippets for including the natchez-log library in various build systems.

```sbt
libraryDependencies += "org.tpolecat" %% "natchez-log" % "0.1.5"
```

```maven
<dependencies>
  <dependency>
    <groupId>org.tpolecat</groupId>
    <artifactId>natchez-log_2.13</artifactId>
    <version>0.1.5</version>
  </dependency>
</dependencies>
```

```gradle
dependencies {
  implementation "org.tpolecat:natchez-log_2.13:0.1.5"
}
```

--------------------------------

### Constructing Trace Values

Source: https://typelevel.org/natchez/reference/tracevalues.html

Demonstrates explicit construction of TraceValue types and their implicit conversion equivalents.

```scala
Tracevalue.StringValue("foo")
```

```scala
"foo"
```

```scala
TraceValue.BooleanValue(true)
```

```scala
true
```

```scala
TraceValue.NumberValue(1.23)
```

```scala
1.23
```

--------------------------------

### No-Op Trace Instance for Development and Testing

Source: https://typelevel.org/natchez/reference/trace.html

Provides a no-operation Trace instance for any effect F with an Applicative constraint. Useful for development and testing when tracing is not required. Imports `natchez.Trace.Implicits.noop`.

```scala
object NoTraceForYou {

  // In this scope we will ignore tracing
  import natchez.Trace.Implicits.noop

  // So this compiles fine
  def go[F[_]: Monad]: F[Unit] = 
    wibble("bob", 42)

}
```

--------------------------------

### Add Honeycomb Dependency for SBT

Source: https://typelevel.org/natchez/backends/honeycomb.html

Add this dependency to your build.sbt file to include the Honeycomb back end.

```scala
libraryDependencies += "org.tpolecat" %% "natchez-honeycomb" % "0.1.5"
```

--------------------------------

### Import No-Op Trace Instance

Source: https://typelevel.org/natchez/backends/noop.html

Import the no-op trace instance to enable implicit Trace[F] availability for any applicative functor F.

```scala
import natchez.Trace.Implicits.noop
```

--------------------------------

### Add Honeycomb Dependency for Gradle

Source: https://typelevel.org/natchez/backends/honeycomb.html

Add this dependency to your Gradle project's build.gradle file for Honeycomb integration.

```gradle
dependencies {
  implementation "org.tpolecat:natchez-honeycomb_2.13:0.1.5"
}
```

--------------------------------

### Ambient Span Usage with Trace Constraint

Source: https://typelevel.org/natchez/reference/spans.html

Illustrates using the Trace constraint for ambient span management. This is preferred for tagless style programming or when using concrete types with reader capabilities.

```scala
def wibble[F[_]: Trace: Monad](name: String, age: Int, parent: Span[F]): F[Unit] = 
  Trace[F].span("wibble") {
    for {
      _ <- Trace[F].put("name" -> name, "age" -> age)
      // ... actual method logic in F
    } yield ()
  }
```

--------------------------------

### Cats-MTL Local Trace Instance

Source: https://typelevel.org/natchez/reference/trace.html

Provides a Trace[F] instance given MonadCancel[F, Throwable] and Local[F, Span[F]]. This is more general than the Kleisli instance and requires the natchez-mtl module.

```scala
def goLocal[F[_]](
  implicit ev0: MonadCancel[F, Throwable],
           ev1: Local[F, Span[F]]
): F[Unit] = 
  wibble("bob", 42)
```

--------------------------------

### Add Natchez Core Dependency (sbt)

Source: https://typelevel.org/natchez/index.html

Use this dependency if you are writing library code that needs to support any tracing back-end. Ensure you have Scala 2.12, 2.13, or 3.0.

```scala
libraryDependencies += "org.tpolecat" %% "natchez-core" % "0.1.5"
```

--------------------------------

### Propagate Span Kernel via Http4s Client

Source: https://typelevel.org/natchez/reference/kernels.html

Demonstrates how to extract a kernel from a span and inject it into outgoing Http4s request headers.

```scala
def makeRequest[A](span: Span[IO], client: Client[IO], uri: Uri)(
  implicit ev: EntityDecoder[IO, A]
): IO[A] =
  span.kernel.flatMap { k =>
    // turn a Map[String, String] into List[Header]
    val http4sHeaders = k.toHeaders.map { case (k, v) => Header.Raw(CIString(k), v) } .toSeq
    client.expect[A](GET(uri).withHeaders(http4sHeaders))
  }
```

--------------------------------

### Create Http4s Routes with Continue or Root Span

Source: https://typelevel.org/natchez/reference/entrypoints.html

Defines Http4s routes that attempt to continue an existing trace from incoming headers, or create a new root span if the headers are invalid. This is a good default for internal services.

```scala
import cats.effect.IO
import natchez.{ EntryPoint, Kernel }
import org.http4s.HttpRoutes
import org.http4s.dsl.io._

def continuedRoutes(ep: EntryPoint[IO]): HttpRoutes[IO] = 
  HttpRoutes.of[IO] {
    case req@(GET -> Root / "hello" / name) =>

      val k: Kernel = 
        Kernel(req.headers.headers.map { h => h.name.toString -> h.value }.toMap)

      ep.continueOrElseRoot("hello", k).use { span =>
        span.put("the-name" -> name) *> 
        Ok(s"Hello, $name.")
      }

  }
```

--------------------------------

### Add Honeycomb Dependency for Maven

Source: https://typelevel.org/natchez/backends/honeycomb.html

Include this dependency in your Maven project's pom.xml to enable the Honeycomb back end.

```xml
<dependencies>
  <dependency>
    <groupId>org.tpolecat</groupId>
    <artifactId>natchez-honeycomb_2.13</artifactId>
    <version>0.1.5</version>
  </dependency>
</dependencies>
```

--------------------------------

### Add Natchez Core Dependency (Gradle)

Source: https://typelevel.org/natchez/index.html

Add this line to your Gradle build file to include the Natchez core library, supporting Scala 2.13. Modify the dependency string for different Scala versions.

```gradle
dependencies {
  implementation "org.tpolecat:natchez-core_2.13:0.1.5"
}
```

--------------------------------

### Create Http4s Routes with Root Span

Source: https://typelevel.org/natchez/reference/entrypoints.html

Defines Http4s routes that create a new root span for each incoming request. Use this for endpoints on the public surface of a system.

```scala
import cats.effect.IO
import natchez.{ EntryPoint, Kernel }
import org.http4s.HttpRoutes
import org.http4s.dsl.io._

def routes(ep: EntryPoint[IO]): HttpRoutes[IO] = 
  HttpRoutes.of[IO] {
    case GET -> Root / "hello" / name =>
      ep.root("hello").use { span =>
        span.put("the-name" -> name) *> Ok(s"Hello, $name.")
      }
  }
```

--------------------------------

### Log Trace JSON Structure

Source: https://typelevel.org/natchez/backends/log.html

Details the JSON structure of the logged trace data.

```APIDOC
## Log Trace JSON Structure

### Description
The log handler constructs a JSON object for each root span, containing a 'children' collection of child spans.

### Response Example
{
  "name" : "root span",
  "service" : "example-service",
  "timestamp" : "2021-05-26T16:41:09.221325Z",
  "duration_ms" : 108,
  "trace.span_id" : "dd817430-c00a-423e-9db4-0a24897b9cb9",
  "trace.parent_id" : null,
  "trace.trace_id" : "ef7758f0-7b33-4358-81f5-4f2070f7196d",
  "exit.case" : "succeeded",
  "children" : []
}
```

--------------------------------

### Add fields and create child spans with Trace

Source: https://typelevel.org/natchez/reference/trace.html

Use the Trace constraint to add fields to the ambient span, retrieve its kernel, or run computations within a child span. Requires Monad and Trace constraints on the effect type F.

```scala
import cats.{ Applicative, Monad }
import cats.data.Kleisli
import cats.effect.MonadCancel
import cats.mtl.Local
import cats.syntax.all._
import natchez.{ Span, Trace }
import natchez.mtl._

def wibble[F[_]: Monad: Trace](name: String, age: Int): F[Unit] = 
  Trace[F].span("wibble") {
    for {
      _ <- Trace[F].put("name" -> name, "age" -> age)
      // ... actual method logic in F
    } yield ()
  }
```

--------------------------------

### Kleisli Trace Instance with Span

Source: https://typelevel.org/natchez/reference/trace.html

Discharges a Trace constraint for Kleisli[F, Span[F], *] given MonadCancel[F, Throwable] and an initial Span[F]. The outer effect is F, and the traced part is Kleisli. Note: Not always possible for arbitrary F due to additional constraints.

```scala
// Given MonadCancel[F, Throwable] and a Span[F] we can call `wibble`
def go[F[_]](span: Span[F])(
  implicit ev: MonadCancel[F, Throwable]
): F[Unit] = 
  wibble[Kleisli[F, Span[F], *]]("bob", 42).run(span)
```

--------------------------------

### Add Natchez Core Dependency (Maven)

Source: https://typelevel.org/natchez/index.html

Include this dependency in your Maven project to use Natchez core functionality, compatible with Scala 2.13. Adjust the artifactId for other Scala versions.

```xml
<dependencies>
  <dependency>
    <groupId>org.tpolecat</groupId>
    <artifactId>natchez-core_2.13</artifactId>
    <version>0.1.5</version>
  </dependency>
</dependencies>
```

--------------------------------

### Explicit Span Usage

Source: https://typelevel.org/natchez/reference/spans.html

Demonstrates passing a Span explicitly as an argument to a method. Use this when working with concrete effect types like IO without reader capabilities.

```scala
def wibble(name: String, age: Int, parent: Span[IO]): IO[Unit] = 
  parent.span("wibble").use { span =>
    for {
      _ <- span.put("name" -> name, "age" -> age)
      // ... actual method logic in IO
    } yield ()
  }
```
Tokens:
Raw