Natchez

The Natchez Trace, also known as the “Old Natchez Trace”, is a historic forest trail within the United States which extends roughly 440 miles (710 km) from Nashville, Tennessee, to Natchez, Mississippi, linking the Cumberland, Tennessee, and Mississippi rivers.

Credits: Wikipedia and the National Park Service.

Welcome!

Natchez is a minimal distributed tracing library for Cats, inspired by earlier work done on puretracing. Natchez is published for Scala 2.12/2.13/3.0, with limited support for Scala-JS.

Below are the available version series (see releases for exact version numbers). You are strongly encouraged to use the Active series. Older series will receive bug fixes when necessary but are not actively maintained.

Quick Start

1. Choose your dependency:

   • If you wish to write application code then you should use the dependency specific to your tracing back end.

   • If you wish to write library code that supports any tracing back-end, then you should use the core dependency below (also available for Scala-JS).

   sbt

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

   Maven

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

   Gradle

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

2. Read the Overview and explore from there.

   Natchez is written for cats and cats-effect. This documentation assumes you are familiar with pure-functional programming with effects, including use of Resource and tagless-final coding style. If you run into trouble be sure to check out:

   • The Natchez channel on Typelevel Discord.
   • The API Documentation.

3. Let us know how it goes!

How to Contribute

This is a community-supported project and contributions are welcome!

• If you see a typo in the doc, click the link at the bottom and fix it!
• If you find a bug please open an issue (or fix it and open a PR) at our GitHub Repository.
• If you want to make a larger contribution, please open an issue first so we can discuss.

Contibutions should target the newest active branch (see above). Maintainers will back-port to older branches when appropriate.