ovotech / natchez-extras

Integrations between Natchez, Doobie, HTTP4s, Log4cats and Datadog. Formerly called effect-utils.

Version Matrix

Natchez Extras

This repository consists of a number of additional integrations for Natchez, primarily to assist with integrating Natchez & Datadog. Separate to the Natchez integrations but included here for simplicity is a module to send metrics to Datadog over UDP with FS2.

Cats Effect versions

If you're using Cats Effect 2.x you should use versions 4.x.x of this library, for Cats Effect 3 use versions 5.0.0 and up.

Migration from effect-utils

For historical reasons prior to 4.0.0 this repository was called effect-utils. If you're upgrading your dependencies the renamings are as follows:

"com.ovoenergy.effect" % "datadog-metrics"  => "com.ovoenergy" % "natchez-extras-dogstatsd"
"com.ovoenergy.effect" % "natchez-datadog"  => "com.ovoenergy" % "natchez-extras-datadog"
"com.ovoenergy.effect" % "natchez-doobie"   => "com.ovoenergy" % "natchez-extras-doobie"
"com.ovoenergy.effect" % "natchez-slf4j"    => "com.ovoenergy" % "natchez-extras-slf4j"
"com.ovoenergy.effect" % "natchez-combine"  => "com.ovoenergy" % "natchez-extras-combine"
"com.ovoenergy.effect" % "natchez-fs2"      => "com.ovoenergy" % "natchez-extras-fs2"
"com.ovoenergy.effect" % "natchez-testkit"  => "com.ovoenergy" % "natchez-extras-testkit"
"com.ovoenergy.effect" % "natchez-http4s"   => "com.ovoenergy" % "natchez-extras-http4s"

Other significant changes are the Datadog metrics object being renamed to Dogstatsd and the modules having their code moved into a subpackage under com.ovoenergy.natchez.extras, for example:

import com.ovoenergy.effect.Combine // effect-utils
import com.ovoenergy.natchez.extras.combine.Combine // natchez-extras

This is to ensure that each module has an isolated package and so can define, for example, a syntax object without affecting anything else.

Current modules

Dogstatsd

latest version

This module allows you to send Metrics and Events to the Datadog agent over UDP with FS2.

Datadog

latest version

This module integrates Natchez with Datadog. It uses HTTP4s and does not depend on the Java Datadog library.

Doobie

latest version

This module integrates Natchez with Doobie so you can trace which DB queries are being run and for how long.

HTTP4S

latest version

This module integrates Natchez with the HTTP4S client and provides middleware to trace both inbound and outbound HTTP requests. It aims to be as configurable as possible so can be configured for use with tracing platforms other than Datadog.

Sl4fj

latest version

This module provides an Slf4j integration with Natchez that logs whenever spans get started or completed. This is mainly useful when running applications locally or integrating with existing logging platforms.

Combine

latest version

This module allows two Natchez EntryPoints to be combined so that they'll both be used. For example if you want to log spans with the above Slf4j integration as well as submitting them to Datadog.

FS2

latest version

This module provides an AllocatedSpan that can be manually submitted, for use in FS2 streams where the Resource based model of Natchez isn't a good fit if you want to have one trace per stream item.

Testkit

latest version

This module provides a TestEntrypoint backed by a Ref which can be useful in unit tests.

Log4cats

latest version

This module provides a TracedLogger for log4cats that will automatically add trace & span IDs to your log lines so that they're linked in the Datadog UI.

Notes for maintainers

To create a release, push a tag to master of the format x.y.z. See the semantic versioning guide for details of how to choose a version number.