{"id":15137371,"url":"https://github.com/trace4cats/trace4cats","last_synced_at":"2025-05-15T23:05:12.743Z","repository":{"id":39648966,"uuid":"276227193","full_name":"trace4cats/trace4cats","owner":"trace4cats","description":"Distributed app tracing implementation in pure scala using cats-effect ","archived":false,"fork":false,"pushed_at":"2025-01-20T03:29:53.000Z","size":2858,"stargazers_count":188,"open_issues_count":31,"forks_count":33,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-04-08T10:20:03.098Z","etag":null,"topics":["cats","cats-effect","graalvm","jaeger","native-image","opencensus","opentelemetry","opentracing","scala","tracing"],"latest_commit_sha":null,"homepage":"","language":"Scala","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/trace4cats.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-06-30T23:05:16.000Z","updated_at":"2024-11-27T21:12:41.000Z","dependencies_parsed_at":"2023-11-18T04:27:24.230Z","dependency_job_id":"581f3515-ca28-4801-95df-804ed93cbfac","html_url":"https://github.com/trace4cats/trace4cats","commit_stats":{"total_commits":1165,"total_committers":22,"mean_commits":52.95454545454545,"dds":0.5751072961373391,"last_synced_commit":"c2ab51e7c71bee3a9a3ddf4b04f50c269d18c487"},"previous_names":["janstenpickle/trace4cats"],"tags_count":28,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trace4cats%2Ftrace4cats","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trace4cats%2Ftrace4cats/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trace4cats%2Ftrace4cats/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trace4cats%2Ftrace4cats/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/trace4cats","download_url":"https://codeload.github.com/trace4cats/trace4cats/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254436944,"owners_count":22070946,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cats","cats-effect","graalvm","jaeger","native-image","opencensus","opentelemetry","opentracing","scala","tracing"],"created_at":"2024-09-26T07:00:39.100Z","updated_at":"2025-05-15T23:05:12.692Z","avatar_url":"https://github.com/trace4cats.png","language":"Scala","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Trace4Cats\n\n[![GitHub Workflow Status](https://img.shields.io/github/workflow/status/trace4cats/trace4cats/Continuous%20Integration)](https://github.com/trace4cats/trace4cats/actions?query=workflow%3A%22Continuous%20Integration%22)\n[![GitHub stable release](https://img.shields.io/github/v/release/trace4cats/trace4cats?label=stable\u0026sort=semver)](https://github.com/trace4cats/trace4cats/releases)\n[![GitHub latest release](https://img.shields.io/github/v/release/trace4cats/trace4cats?label=latest\u0026include_prereleases\u0026sort=semver)](https://github.com/trace4cats/trace4cats/releases)\n[![Maven Central early release](https://img.shields.io/maven-central/v/io.janstenpickle/trace4cats-model_2.13?label=early)](https://maven-badges.herokuapp.com/maven-central/io.janstenpickle/trace4cats-model_2.13)\n[![Join the chat at https://gitter.im/trace4cats/community](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/trace4cats/community?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=badge)\n[![Scala Steward badge](https://img.shields.io/badge/Scala_Steward-helping-blue.svg?style=flat\u0026logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAA4AAAAQCAMAAAARSr4IAAAAVFBMVEUAAACHjojlOy5NWlrKzcYRKjGFjIbp293YycuLa3pYY2LSqql4f3pCUFTgSjNodYRmcXUsPD/NTTbjRS+2jomhgnzNc223cGvZS0HaSD0XLjbaSjElhIr+AAAAAXRSTlMAQObYZgAAAHlJREFUCNdNyosOwyAIhWHAQS1Vt7a77/3fcxxdmv0xwmckutAR1nkm4ggbyEcg/wWmlGLDAA3oL50xi6fk5ffZ3E2E3QfZDCcCN2YtbEWZt+Drc6u6rlqv7Uk0LdKqqr5rk2UCRXOk0vmQKGfc94nOJyQjouF9H/wCc9gECEYfONoAAAAASUVORK5CYII=)](https://scala-steward.org)\n\n\u003e ## ⚠️ If you are upgrading to `0.14.0` please read the [migration guide].\n\nYet another distributed tracing system, this time just for Scala. Heavily relies upon\n[Cats] and [Cats Effect].\n\nCompatible with [OpenTelemetry] and [Jaeger], based on, and interoperates with [Natchez].\n\n[Obligatory XKCD](https://xkcd.com/927/)\n\n#### For release information and changes see [the releases page](https://github.com/trace4cats/trace4cats/releases).\n\n  * [Motivation](#motivation)\n  * [Highlights](#highlights)\n  * [Quickstart](#quickstart)\n  * [Migrating to `0.14.0`](#migrating-to-0140)\n  * [Repositories](#repositories)\n  * [Components](#components)\n  * [Documentation](#documentation)\n  * [SBT Dependencies](#sbt-dependencies)\n  * [native-image Compatibility](#native-image-compatibility)\n  * [Contributing](#contributing)\n\n## Motivation\n\nIt increasingly seems that Java tracing libraries are dependent on [gRPC], which usually\nbrings along lots of other dependencies. You may find *Trace4Cats* useful if you want to...\n\n- Reduce the number of dependencies in your application\n- Resolve a dependency conflict caused by a tracing implementation\n- Create a [`native-image`] using [GraalVM]\n\n## Highlights\n\nTrace4Cats supports publishing spans to the following systems:\n\n- [Jaeger] via Thrift over UDP and Protobuf over gRPC\n- [OpenTelemetry] via Protobuf over gRPC and JSON over HTTP\n- Log using [Log4Cats]\n- Trace4Cats Avro over UDP, TCP and Kafka\n- [Google Cloud Trace] over HTTP and gRPC\n- [Datadog] over HTTP\n- [New Relic] over HTTP\n- [Zipkin] over HTTP\n\nInstrumentation for trace propagation and continuation is available for the following libraries:\n\n- [Http4s] client and server\n- [Sttp] client v3\n- [Tapir]\n- [FS2 Kafka] consumer and producer\n- [FS2]\n\n**Unlike other tracing libraries, trace attributes are lazily evaluated. If a span is not\n[sampled](https://github.com/trace4cats/trace4cats-docs/blob/master/docs/sampling.md), no computation associated with\ncalculating attribute values will be performed.**\n\nMore information on how to use these can be found in the\n[examples documentation](https://github.com/trace4cats/trace4cats-docs/blob/master/docs/examples.md).\n\n## Quickstart\n\n**For more see the [documentation](#documentation) and more advanced\n[examples](https://github.com/trace4cats/trace4cats-docs/blob/master/docs/examples.md).**\n\nAdd the following dependencies to your `build.sbt`:\n\n```scala\n\"io.janstenpickle\" %% \"trace4cats-core\" % \"0.14.0\"\n\"io.janstenpickle\" %% \"trace4cats-avro-exporter\" % \"0.14.0\"\n```\n\nThen run the [collector](https://github.com/trace4cats/trace4cats-docs/blob/master/docs/components.md#collectors) in\nspan logging mode:\n\n```bash\necho \"log-spans: true\" \u003e /tmp/collector.yaml\ndocker run -p7777:7777 -p7777:7777/udp -it \\\n  -v /tmp/collector.yaml:/tmp/collector.yaml \\\n  janstenpickle/trace4cats-collector-lite:0.14.0 \\\n  --config-file=/tmp/collector.yaml\n```\n\nFinally, run the following code to export some spans to the collector:\n\n```scala\nimport cats.Monad\nimport cats.data.Kleisli\nimport cats.effect._\nimport cats.effect.std.Console\nimport cats.implicits._\nimport trace4cats._\nimport trace4cats.avro.AvroSpanCompleter\n\nimport scala.concurrent.duration._\n\nobject Trace4CatsQuickStart extends IOApp.Simple {\n  def entryPoint[F[_]: Async](process: TraceProcess): Resource[F, EntryPoint[F]] =\n    AvroSpanCompleter.udp[F](process, config = CompleterConfig(batchTimeout = 50.millis)).map { completer =\u003e\n      EntryPoint[F](SpanSampler.always[F], completer)\n    }\n\n  def runF[F[_]: Monad: Console: Trace]: F[Unit] =\n    for {\n      _ \u003c- Trace[F].span(\"span1\")(Console[F].println(\"trace this operation\"))\n      _ \u003c- Trace[F].span(\"span2\", SpanKind.Client)(Console[F].println(\"send some request\"))\n      _ \u003c- Trace[F].span(\"span3\", SpanKind.Client)(\n        Trace[F].putAll(\"attribute1\" -\u003e \"test\", \"attribute2\" -\u003e 200) \u003e\u003e\n          Trace[F].setStatus(SpanStatus.Cancelled)\n      )\n    } yield ()\n\n  def run: IO[Unit] =\n    entryPoint[IO](TraceProcess(\"trace4cats\")).use { ep =\u003e\n      ep.root(\"this is the root span\").use { span =\u003e\n        runF[Kleisli[IO, Span[IO], *]].run(span)\n      }\n    }\n}\n```\n\n## Migrating to `0.14.0`\n\nVersion `0.14.0` introduced a reworked module and package structure that reduced the number of dependencies and imports\nrequired to get started quickly. Effectively `import trace4cats._` is all you should need to import throughout most of\nyour codebase.\n\nSee the [migration guide] for information\non how to migrate.\n\n## Repositories\n\nTrace4Cats is separated into a few repositories:\n\n- [`trace4cats-avro`](https://github.com/trace4cats/trace4cats-avro) [Avro] codecs, TCP/UDP server and exporter\n- [`trace4cats-avro-kafka`](https://github.com/trace4cats/trace4cats-avro-kafka) [Avro] [Kafka] exporter and consumer\n- [`trace4cats-cloudtrace`](https://github.com/trace4cats/trace4cats-cloudtrace) [Google Cloud Trace] exporters\n- [`trace4cats-components`](https://github.com/trace4cats/trace4cats-components) standalone Trace4Cats\n  [components](#components)\n- [`trace4cats-datadog`](https://github.com/trace4cats/trace4cats-datadog) [Datadog] exporters\n- [`trace4cats-docs`](https://github.com/trace4cats/trace4cats-docs) documentation and examples\n- [`trace4cats-dynamic-extras`](https://github.com/trace4cats/trace4cats-dynamic-extras) extra utilities for dynamically\n  configuring Trace4Cats\n- [`trace4cats-exporter-http`](https://github.com/trace4cats/trace4cats-exporter-http) HTTP span exporter\n- [`trace4cats-http4s`](https://github.com/trace4cats/trace4cats-http4s) [Http4s] client and server integrations\n- [`trace4cats-jaeger`](https://github.com/trace4cats/trace4cats-jaeger) [Jaeger] exporters\n- [`trace4cats-jaeger-integration-test`](https://github.com/trace4cats/trace4cats-jaeger-integration-test) Integration\n  test for exporters to [Jaeger]\n- [`trace4cats-kafka`](https://github.com/trace4cats/trace4cats-kafka) [FS2 Kafka] integrations\n- [`trace4cats-natchez`](https://github.com/trace4cats/trace4cats-natchez) [Natchez] integrations\n- [`trace4cats-newrelic`](https://github.com/trace4cats/trace4cats-newrelic) [New Relic] exporters\n- [`trace4cats-opentelemetry`](https://github.com/trace4cats/trace4cats-opentelemetry) [OpenTelemetry] exporters\n- [`trace4cats-sttp`](https://github.com/trace4cats/trace4cats-sttp) [Sttp] client and [Tapir] integrations\n- [`trace4cats-tail-sampling-extras`](https://github.com/trace4cats/trace4cats-tail-sampling-extras) extra utilities for\n  tail sampling\n- [`trace4cats-zipkin`](https://github.com/trace4cats/trace4cats-zipkin) [Zipkin] exporters\n- [`trace4cats-zio`](https://github.com/trace4cats/trace4cats-zio) [ZIO] implementations of Trace4Cats typeclasses\n\n## Components\n\nTrace4Cats is made up as both a set of libraries for integration in applications and standalone processes. For\ninformation on the libraries and interfaces see the [design documentation](https://github.com/trace4cats/trace4cats-docs/blob/master/docs/design.md).\n\nThe standalone components are the agent and the collector. To see how they work together, see the\n[topologies documentation](https://github.com/trace4cats/trace4cats-docs/blob/master/docs/topologies.md), for information on configuring and running the agent and collector see\nthe [components documentation](https://github.com/trace4cats/trace4cats-docs/blob/master/docs/components.md).\n\nThe source code for these components is located in the\n[`trace4cats-components`](https://github.com/trace4cats/trace4cats-components) repository.\n\n## Documentation\n\n- [Design](https://github.com/trace4cats/trace4cats-docs/blob/master/docs/design.md) - Trace4Cats design\n- [Components](https://github.com/trace4cats/trace4cats-docs/blob/master/docs/components.md) - running and configuring\n  Trace4Cats components\n- [Topologies](https://github.com/trace4cats/trace4cats-docs/blob/master/docs/topologies.md) - information on potential\n  Trace4Cats deployment topologies\n- [Sampling](https://github.com/trace4cats/trace4cats-docs/blob/master/docs/sampling.md) - trace sampling\n- [Filtering](https://github.com/trace4cats/trace4cats-docs/blob/master/docs/filtering.md) - span attribute filtering\n- [Examples](https://github.com/trace4cats/trace4cats-docs/blob/master/docs/examples.md) - code usage examples\n\n## SBT Dependencies\n\nTo use Trace4Cats within your application add the dependencies listed below as needed:\n\n```scala\n\"io.janstenpickle\" %% \"trace4cats-core\" % \"0.14.0\"\n\"io.janstenpickle\" %% \"trace4cats-rate-sampling\" % \"0.14.0\"\n\"io.janstenpickle\" %% \"trace4cats-fs2\" % \"0.14.0\"\n\"io.janstenpickle\" %% \"trace4cats-http4s-client\" % \"0.14.0\"\n\"io.janstenpickle\" %% \"trace4cats-http4s-server\" % \"0.14.0\"\n\"io.janstenpickle\" %% \"trace4cats-sttp-client3\" % \"0.14.0\"\n\"io.janstenpickle\" %% \"trace4cats-sttp-tapir\" % \"0.14.0\"\n\"io.janstenpickle\" %% \"trace4cats-natchez\" % \"0.14.0\"\n\"io.janstenpickle\" %% \"trace4cats-avro-exporter\" % \"0.14.0\"\n\"io.janstenpickle\" %% \"trace4cats-avro-kafka-exporter\" % \"0.14.0\"\n\"io.janstenpickle\" %% \"trace4cats-avro-kafka-consumer\" % \"0.14.0\"\n\"io.janstenpickle\" %% \"trace4cats-jaeger-thrift-exporter\" % \"0.14.0\"\n\"io.janstenpickle\" %% \"trace4cats-opentelemetry-otlp-grpc-exporter\" % \"0.14.0\"\n\"io.janstenpickle\" %% \"trace4cats-opentelemetry-otlp-http-exporter\" % \"0.14.0\"\n\"io.janstenpickle\" %% \"trace4cats-opentelemetry-jaeger-exporter\" % \"0.14.0\"\n\"io.janstenpickle\" %% \"trace4cats-stackdriver-grpc-exporter\" % \"0.14.0\"\n\"io.janstenpickle\" %% \"trace4cats-stackdriver-http-exporter\" % \"0.14.0\"\n\"io.janstenpickle\" %% \"trace4cats-datadog-http-exporter\" % \"0.14.0\"\n\"io.janstenpickle\" %% \"trace4cats-newrelic-http-exporter\" % \"0.14.0\"\n\"io.janstenpickle\" %% \"trace4cats-zipkin-http-exporter\" % \"0.14.0\"\n```\n\n## [`native-image`] Compatibility\n\nThe following span completers have been found to be compatible with [`native-image`]:\n\n- Trace4Cats Avro\n- [Jaeger] Thrift over UDP\n- [OpenTelemetry] JSON over HTTP\n- Log\n- [Google Cloud Trace] over HTTP\n- [Datadog] over HTTP\n- [New Relic] over HTTP\n- [Zipkin] over HTTP\n\n## Contributing\n\nThis project supports the [Scala Code of Conduct](https://typelevel.org/code-of-conduct.html) and aims that its channels\n(mailing list, Gitter, github, etc.) to be welcoming environments for everyone.\n\n[migration guide]: https://github.com/trace4cats/trace4cats-docs/blob/master/docs/migrating.md\n\n[Avro]: https://avro.apache.org\n[Kafka]: https://kafka.apache.org\n[FS2]: https://fs2.io/\n[Http4s]: https://http4s.org/\n[Jaeger]: https://www.jaegertracing.io/\n[Log4Cats]: https://github.com/typelevel/log4cats\n[Natchez]: https://github.com/tpolecat/natchez\n[`native-image`]: https://www.graalvm.org/docs/reference-manual/native-image/\n[OpenTelemetry]: http://opentelemetry.io\n[Google Cloud Trace]: https://cloud.google.com/trace/docs/reference\n[Datadog]: https://docs.datadoghq.com/api/v1/tracing/\n[New Relic]: https://docs.newrelic.com/docs/understand-dependencies/distributed-tracing/trace-api/report-new-relic-format-traces-trace-api#new-relic-guidelines\n[ZIO]: https://zio.dev\n[Sttp]: https://sttp.softwaremill.com\n[Tapir]: https://tapir.softwaremill.com\n[FS2 Kafka]: https://fd4s.github.io/fs2-kafka/\n[Zipkin]: https://zipkin.io\n[GraalVM]: https://www.graalvm.org\n[gRPC]: https://grpc.io\n[Cats]: https://typelevel.org/cats\n[Cats Effect]: https://typelevel.org/cats-effect\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrace4cats%2Ftrace4cats","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftrace4cats%2Ftrace4cats","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrace4cats%2Ftrace4cats/lists"}