typelevel/natchez

Natchez is a distributed tracing library for Scala that provides a unified API for creating and managing spans across various backend providers. It supports integration with major observability platforms including Datadog, Jaeger, Honeycomb, New Relic, AWS X-Ray, and OpenTelemetry, while also offering local logging and testing utilities. The system is built on cats-effect and supports multiple Scala versions, enabling consistent trace context propagation and span management in functional applications.

7 changes.

The project was rebranded from Skunk to Natchez and restructured into a multi-module distributed tracing library for Scala. This period focused on establishing the core abstractions and implementing initial backend integrations for Jaeger, Honeycomb, and OpenCensus, alongside migrating the build system to sbt-typelevel.

9 changes.

The project significantly expanded its distributed tracing capabilities by introducing dedicated integration modules for Odin, Datadog, New Relic, and OpenTelemetry. Concurrently, the core API was restructured with new EntryPoint and Trace abstractions to better manage span contexts and support various effect types like Kleisli and MTL.

4 changes.

This period focused on implementing AWS X-Ray distributed tracing support, including span propagation and context handling. It also expanded the test suite to cover tracing behavior and added ScalaCheck instances to the testkit for property-based testing of core types.

Introduces a new X-Ray module that enables distributed tracing via the AWS X-Ray daemon. The implementation sends span data over UDP to a configurable daemon address (defaulting to 127.0.0.1:2000) and supports automatic context propagation by reading trace headers from environment variables (e.g., \\_X\_AMZN\_TRACE\_ID\) and system properties. It includes robust environment fallback logic and handles exception serialization for detailed error reporting in traces.

modules/xray · high confidence

This change introduces a new Datadog integration for Natchez, providing \DDTracer\ and \DDEntryPoint\ implementations that wrap the native Datadog OpenTracing library. The implementation supports span kinds (client, server, producer, consumer) via tags and allows linking spans from incoming kernels. Crucially, the \continue()\ method now explicitly ignores the active span (\ignoreActiveSpan\) to prevent trace ID collisions in fiber-based runtimes where thread-local state can cause unrelated concurrent requests to share trace IDs; this is verified by new concurrency tests ensuring unique trace IDs are generated for each request.

modules/datadog · high confidence

A new \GlobalTracer\ object has been added to the \modules/opentracing\ module, providing utilities to interact with the OpenTracing \GlobalTracer\ singleton. This allows users to check if a tracer is registered, fetch the currently registered tracer, or register a new tracer if one is not already present, facilitating easier integration with global tracing contexts.

modules/opentracing · high confidence

Introduces a new Honeycomb backend for the Natchez tracing library, allowing users to send trace data to Honeycomb. The implementation provides an \entryPoint\ method to initialize the connection and supports creating trace spans via \root\, \continue\, and a new \continueOrElseRoot\ operation. It includes a default response observer to log warnings for rejected or unknown server responses.

modules/honeycomb · high confidence

Users can now export traces to Jaeger using the OpenTracing-compatible \natchez-jaeger\ module. This change introduces \Jaeger.entryPoint\ for creating a new tracer instance (with optional URI prefix for trace links) and \Jaeger.globalTracerEntryPoint\ for wrapping an existing global tracer. The implementation supports root spans, continuing spans from kernel headers, and fallback logic for incomplete headers, while mapping Natchez span kinds (Client, Server, Consumer, Producer) to Jaeger tags.

modules/jaeger, modules/lightstep · high confidence

Introduces a new \Log.scala\ file in the \modules/log-odin\ module that provides an \EntryPoint\ implementation for distributed tracing using the \io.odin\ logging library. This allows users to initialize log spans and continue or create root spans within the Odin logging ecosystem, effectively bringing back the Odin module support for structured logging.

modules/log-odin · high confidence

Users can now export distributed traces to OpenCensus-compatible backends (such as Jaeger or Zipkin via the OpenCensus Agent) by using the new \OpenCensus\ module. This integration provides an \EntryPoint\ implementation that registers the \OcAgentTraceExporter\, allowing applications to create root spans, continue existing spans from kernel data, or combine both strategies while respecting configured sampling rates.

modules/opencensus/src · high confidence

A new \opentelemetry\ module has been added to the project, providing integration with the OpenTelemetry SDK. This includes an \OpenTelemetry\ object with methods to create entry points from existing SDK instances or to build and register new SDK resources (including global registration support), and a \Shutdownable\ type class to ensure proper cleanup of OpenTelemetry components like span exporters and processors.

modules/opentelemetry · high confidence

The testkit module now includes ScalaCheck Arbitrary and Cogen instances for core Natchez types, including Kernel, TraceValue, SpanCreationPolicy, SpanKind, and Span.Options. This enables users to easily generate random test data for these types when writing property-based tests.

modules/testkit · high confidence

This change introduces a new \LocalTrace\ implementation in the \mtl\ module that leverages \cats.mtl.Local\ to manage span context, enabling users to create traces where the current span is implicitly available via the \Local\ effect. It also adds an implicit \Local\ instance for \Kleisli\[F, Span\[F\], \*\]\, allowing span operations to be composed within Kleisli arrows while maintaining proper context scoping and error handling through \attachError\.

modules/mtl/shared/src/main · high confidence

This change introduces the Natchez distributed tracing library, providing a unified API for creating and managing spans across various backend providers. The core module defines the \Span\, \Kernel\, and \TraceValue\ abstractions, while specific modules implement support for Datadog, Honeycomb, Jaeger, Lightstep, New Relic, OpenCensus, OpenTelemetry, X-Ray, and logging backends (Odin, log4cats). It also includes a mock implementation for testing and a no-op entry point for environments where tracing is disabled.

repository · high confidence

Users can now integrate New Relic for distributed tracing by using the new \NewRelic.entryPoint\ method, which creates a Natchez \EntryPoint\ backed by a \SpanBatchSender\. This allows existing applications to export trace spans to New Relic's telemetry system.

modules/newrelic · high confidence

A new Log module has been added to the shared codebase, providing a structured logging implementation that integrates with the existing tracing system. This module introduces an EntryPoint that creates spans enriched with span kind and links, allowing users to generate structured log entries that maintain context across distributed services. The implementation leverages cats-effect for resource management and includes a deprecated entry point method for backward compatibility with versions prior to 0.3.8.

modules/log/shared/src/main · high confidence

Added new example files demonstrating tracing integration with OpenTelemetry, Log4cats, and global tracer setups, alongside a shared Sort utility for demonstrating span branching. The examples now explicitly support configuring entry points for various backends including Honeycomb, Lightstep, DataDog, Jaeger, and Odin, with specific implementations for OpenTelemetry and Log4cats active in the codebase.

modules/examples · high confidence

The core module introduces a new \EntryPoint\ trait to manage root spans and trace continuation via kernels, including a \noop\ implementation for non-tracing contexts. The \Trace\ effect is redefined to manage the current span context, adding methods like \spanK\ for natural transformation support, \imapK\ for effect-type transformation, and \spanId\ retrieval. Standard OpenTelemetry-compatible tagging helpers are now provided in \Tags\ (covering HTTP, DB, peer, and span kinds), and a \Fields\ mixin allows exceptions to carry trace data.

modules/core · high confidence

The project has been renamed from Skunk to Natchez, a distributed tracing library for Scala. This change is reflected in the README, which updates the project title, description, and links (including the Gitter badge and microsite URL), and in the LICENSE file, which updates the copyright year to 2019.

(repo-wide) · high confidence

Added test suite for tracing behavior and implicit resolution; Added tests for Local instance on Kleisli-wrapped spans; Added tests for the log module's JSON formatting and trace handling.

The build system has been migrated to sbt-typelevel, introducing a new multi-module structure (core, jaeger, honeycomb, opentelemetry, etc.) and enabling cross-compilation for Scala 2.12, 2.13, and 3.3.7. Core library dependencies have been updated to cats 2.13.0, cats-effect 3.7.1, and fs2 3.14.0, while test dependencies now use munit 1.3.6 and related typelevel testing libraries.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• First survey — no prior run to compare against. CAI 55.

• Code Health 97
• Architecture 100
• Maturity 43
• Readiness 50
• Security 70

• 300 commits — 298 feature/other, 2 fixes

• (repo) — 145 commits
• (root) — 105 commits
• project/plugins.sbt — 22 commits
• project/build.properties — 20 commits
• .github/workflows — 3 commits
• modules/datadog — 2 commits
• modules/core — 1 commit
• modules/examples — 1 commit
• modules/xray — 1 commit

• fix: Fix trace ID collision in DDEntryPoint.continue() (#1270)
• fix: fix NullPointerException when XRay tries to serialize an exception with a null message
• change: Add 'Reformat with scalafmt 3.9.10' to .git-blame-ignore-revs
• change: Add method to run code with activated span for interop with Java libraries (#1189)
• change: Do not activate span since thread-local propagation does not work correctly when using cats-effect. (#1191)
• change: Merge pull request #1194 from typelevel/update/cats-effect-3.6.2
• change: Merge pull request #1195 from typelevel/update/sbt-mdoc-2.7.2
• change: Merge pull request #1196 from typelevel/update/dd-trace-api-1.51.0
• change: Merge pull request #1197 from typelevel/update/opentelemetry-exporter-otlp-1.52.0
• change: Merge pull request #1199 from typelevel/update/dd-trace-api-1.51.1
• change: Merge pull request #1200 from typelevel/update/dd-trace-api-1.51.2
• change: Merge pull request #1201 from typelevel/update/cats-effect-3.6.3
• change: Merge pull request #1202 from typelevel/update/grpc-netty-1.74.0
• change: Merge pull request #1204 from typelevel/update/sbt-1.11.4
• change: Merge pull request #1205 from typelevel/update/dd-trace-api-1.52.0
• change: Merge pull request #1207 from typelevel/update/opentelemetry-exporter-otlp-1.53.0
• change: Merge pull request #1208 from typelevel/update/dd-trace-api-1.52.1
• change: Merge pull request #1209 from typelevel/update/ciris-3.10.0
• change: Merge pull request #1210 from typelevel/update/grpc-netty-1.75.0
• change: Merge pull request #1211 from typelevel/update/sbt-1.11.5
• …and 280 more

• 0 containers · 1 bounded contexts · 0 dependency edges (baseline)

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

typelevel/natchez was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.