From b6b456db9586315f171f03e1362c859880d65505 Mon Sep 17 00:00:00 2001 From: Michael Wizner Date: Fri, 17 Jan 2025 10:43:28 +0000 Subject: [PATCH 1/2] add gitignore --- .gitignore | 49 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) create mode 100644 .gitignore diff --git a/.gitignore b/.gitignore new file mode 100644 index 00000000..9d926716 --- /dev/null +++ b/.gitignore @@ -0,0 +1,49 @@ +*.class +*.log + +# these are moved into the doc project by the build +modules/docs/src/main/tut/changelog.md +modules/docs/src/main/tut/license.md + +# sbt specific +dist/* +target/ +lib_managed/ +src_managed/ +project/boot/ +project/plugins/project/ +project/hydra.sbt + +# Scala-IDE specific +.scala_dependencies +.cache +.classpath +.project +.worksheet/ +bin/ +.settings/ + +# OS X +.DS_Store + +# Ctags +.tags + +# ENSIME +.ensime +.ensime_cache/ + +# IntelliJ +.idea/ + +# Mill +out/ + +# Bloop/Metals +.bloop/ +.metals/ +metals.sbt +.bsp/ + +# VS-Code +.vscode/ \ No newline at end of file From 23f34416e187bd3f74679f50666ccea70cd83a36 Mon Sep 17 00:00:00 2001 From: Michael Wizner Date: Fri, 17 Jan 2025 16:12:11 +0000 Subject: [PATCH 2/2] Regenerate site --- backends/datadog.html | 63 ++++++++- backends/honeycomb.html | 24 ++-- backends/index.html | 25 ++-- backends/jaeger.html | 16 ++- backends/lightstep.html | 16 ++- backends/log.html | 59 ++++---- backends/mock.html | 16 ++- backends/newrelic.html | 16 ++- backends/noop.html | 16 ++- backends/odin.html | 16 ++- backends/opencensus.html | 18 +-- backends/opentelemetry.html | 274 ++++++++++++++++++++++++++++++++++++ examples/http4s.html | 16 ++- examples/index.html | 16 ++- examples/skunk.html | 16 ++- index.html | 26 ++-- overview.html | 16 ++- paradox.json | 2 +- reference/entrypoints.html | 18 +-- reference/index.html | 16 ++- reference/kernels.html | 19 +-- reference/spans.html | 18 +-- reference/trace.html | 36 +++-- reference/tracevalues.html | 16 ++- 24 files changed, 585 insertions(+), 189 deletions(-) create mode 100644 backends/opentelemetry.html diff --git a/backends/datadog.html b/backends/datadog.html index 4feeac1d..9c634b24 100644 --- a/backends/datadog.html +++ b/backends/datadog.html @@ -6,7 +6,7 @@ - + @@ -32,7 +32,7 @@ ⌂Natchez
-0.1.5 +0.3.7
@@ -58,6 +58,7 @@
  • No-Op
  • Odin
  • OpenCensus
    • +
  • OpenTelemetry
  • Examples
      @@ -95,7 +96,7 @@ ⌂Natchez
      -0.1.5 +0.3.7
    • @@ -121,6 +122,7 @@
  • No-Op
  • Odin
  • OpenCensus
    • +
  • OpenTelemetry
  • Examples
      @@ -153,19 +155,66 @@

      Datadog

      +

      To get access to an EntryPoint instance for DataDog, add the following dependency.

      +

      It transitively pulls in "com.datadoghq" % "dd-trace-ot" and "com.datadoghq" % "dd-trace-api".

      sbt
      libraryDependencies += "org.tpolecat" %% "natchez-datadog" % "0.3.7"
      Maven
      <dependencies>
+  <dependency>
+    <groupId>org.tpolecat</groupId>
+    <artifactId>natchez-datadog_2.13</artifactId>
+    <version>0.3.7</version>
+  </dependency>
+</dependencies>
      Gradle
      dependencies {
+  implementation "org.tpolecat:natchez-datadog_2.13:0.3.7"
+}
      +

      Constructing an EntryPoint

      +

      You can use DDTracer.entryPoint to build a DataDog tracer, register it globally, and get it as a Resource[F, EntryPoint[F]]. The method takes a function in which you can customize the underlying DDTracerBuilder instance to specify the service name, sampling rules, etc.

      +

      At the end, the function should return a datadog.opentracing.DDTracer, for example by calling build().

      +

      The builder is mutable, so customizing it is considered an effect - hence the wrapping in Sync[F].delay:

      +
      import cats.effect.{Sync, Resource}
+import natchez.datadog.DDTracer
+import natchez.EntryPoint
+
+def entryPoint[F[_]: Sync]: Resource[F, EntryPoint[F]] =
+  DDTracer.entryPoint[F] {
+    builder => Sync[F].delay {
+      builder
+        .serviceName("my-app")
+        .build()
+    }
+  }
+
      +

      An alternative approach is to use the already registered global tracer (for example, if you’ve already set it up and registered through some other means, like adding the Java Agent):

      +
      import java.net.URI
+
+// Will return `None` if there's no tracer registered already
+def entryPointUseGlobal[F[_]: Sync]: F[Option[EntryPoint[F]]] =
+  DDTracer.globalTracerEntryPoint[F](Some(new URI(s"https://app.datadoghq.com")))
+
      -The source code for this page can be found here. +The source code for this page can be found here.
      - +

      Next: Honeycomb

      +
      @@ -203,7 +252,7 @@

      < @@ -228,7 +277,7 @@

      < - + diff --git a/backends/honeycomb.html b/backends/honeycomb.html index 321de94a..df91e669 100644 --- a/backends/honeycomb.html +++ b/backends/honeycomb.html @@ -6,7 +6,7 @@ - + @@ -32,7 +32,7 @@ ⌂Natchez
      -0.1.5 +0.3.7

    • @@ -58,6 +58,7 @@
  • No-Op
  • Odin
  • OpenCensus
    • +
  • OpenTelemetry
  • Examples
      @@ -95,7 +96,7 @@ ⌂Natchez
      -0.1.5 +0.3.7
    • @@ -121,6 +122,7 @@
  • No-Op
  • Odin
  • OpenCensus
    • +
  • OpenTelemetry
  • Examples
  • Examples
      @@ -95,7 +96,7 @@ ⌂Natchez
      -0.1.5 +0.3.7
    • @@ -121,6 +122,7 @@
  • No-Op
  • Odin
  • OpenCensus
    • +
  • OpenTelemetry
  • Examples
    • @@ -58,6 +58,7 @@
  • No-Op
  • Odin
  • OpenCensus
    • +
  • OpenTelemetry
  • Examples
      @@ -95,7 +96,7 @@ ⌂Natchez
      -0.1.5 +0.3.7
    • @@ -121,6 +122,7 @@
  • No-Op
  • Odin
  • OpenCensus
    • +
  • OpenTelemetry
  • Examples
    • @@ -58,6 +58,7 @@
  • No-Op
  • Odin
  • OpenCensus
    • +
  • OpenTelemetry
  • Examples
      @@ -95,7 +96,7 @@ ⌂Natchez
      -0.1.5 +0.3.7
    • @@ -121,6 +122,7 @@
  • No-Op
  • Odin
  • OpenCensus
    • +
  • OpenTelemetry
  • Examples
    • @@ -58,6 +58,7 @@
  • No-Op
  • Odin
  • OpenCensus
    • +
  • OpenTelemetry
  • Examples
      @@ -95,7 +96,7 @@ ⌂Natchez
      -0.1.5 +0.3.7
    • @@ -121,6 +122,7 @@
  • No-Op
  • Odin
  • OpenCensus
    • +
  • OpenTelemetry
  • Examples
      @@ -153,37 +155,43 @@

      Log

      -

      The natchez-log module provides a back end that logs traces locally (as JSON) to a log4cats Logger, with no distributed functionality. To use it, add the following dependency.

      sbt
      libraryDependencies += "org.tpolecat" %% "natchez-log" % "0.1.5"
      Maven
      <dependencies>
+
      The natchez-log module provides a back end that logs traces locally (as JSON) to a log4cats Logger, with no distributed functionality. To use it, add the following dependency.
      sbt
      libraryDependencies += "org.tpolecat" %% "natchez-log" % "0.3.7"
      Maven
      <dependencies>
   <dependency>
     <groupId>org.tpolecat</groupId>
     <artifactId>natchez-log_2.13</artifactId>
-    <version>0.1.5</version>
+    <version>0.3.7</version>
   </dependency>
 </dependencies>
      Gradle
      dependencies {
-  implementation "org.tpolecat:natchez-log_2.13:0.1.5"
+  implementation "org.tpolecat:natchez-log_2.13:0.3.7"
 }
      
 
      Example Trace
      
 
      The log handler constructs a JSON object for each root span, with a children collection of child spans. On completion of the root span the entire JSON blob is logged as a single message. Here is an example with a root span containing two custom fields and two child spans.
      
 
      {
   "name" : "root span",
   "service" : "example-service",
-  "timestamp" : "2021-05-26T16:41:09.221325Z",
-  "duration_ms" : 108,
-  "trace.span_id" : "dd817430-c00a-423e-9db4-0a24897b9cb9",
+  "timestamp" : "2025-01-17T16:01:57.522113Z",
+  "duration_ms" : 72,
+  "trace.span_id" : "7f8de43a-5aa3-49e5-8dda-158b6a74bab0",
   "trace.parent_id" : null,
-  "trace.trace_id" : "ef7758f0-7b33-4358-81f5-4f2070f7196d",
-  "exit.case" : "succeeded",
+  "trace.trace_id" : "1f6721c6-d67d-41ed-9d26-20e65ec7b79f",
+  "span.kind" : "Internal",
+  "span.links" : [
+  ],
   "person.name" : "bob",
   "person.age" : 42,
+  "exit.case" : "succeeded",
   "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",
+      "timestamp" : "2025-01-17T16:01:57.578712Z",
+      "duration_ms" : 1,
+      "trace.span_id" : "29c8cd00-f971-49aa-bed3-677574740612",
+      "trace.parent_id" : "7f8de43a-5aa3-49e5-8dda-158b6a74bab0",
+      "trace.trace_id" : "1f6721c6-d67d-41ed-9d26-20e65ec7b79f",
+      "span.kind" : "Internal",
+      "span.links" : [
+      ],
       "exit.case" : "succeeded",
       "children" : [
       ]
@@ -191,11 +199,14 @@ 
      
 
 
      
-The source code for this page can be found here.
+The source code for this page can be found here.
 
      
 
-
+
 
 
      
 
      Next: Mock
      
@@ -352,7 +363,7 @@ 
      
-© 2021
+© 2025
 
 
      
 -->
@@ -377,7 +388,7 @@ 
      
 
 
-
+
 
 
 
diff --git a/backends/mock.html b/backends/mock.html
index b545c7d0..af6c621a 100644
--- a/backends/mock.html
+++ b/backends/mock.html
@@ -6,7 +6,7 @@
 
 
 
-
+
 
 
 
@@ -32,7 +32,7 @@
 ⌂Natchez
 
 
      
-0.1.5
+0.3.7
      @@ -58,6 +58,7 @@
    • No-Op
    • Odin
    • OpenCensus
      • +
    • OpenTelemetry
  • Examples
      @@ -95,7 +96,7 @@ ⌂Natchez
      -0.1.5 +0.3.7
    • @@ -121,6 +122,7 @@
  • No-Op
  • Odin
  • OpenCensus
    • +
  • OpenTelemetry
  • Examples
  • Examples
      @@ -95,7 +96,7 @@ ⌂Natchez
      -0.1.5 +0.3.7
    • @@ -121,6 +122,7 @@
  • No-Op
  • Odin
  • OpenCensus
    • +
  • OpenTelemetry
  • Examples
    • @@ -58,6 +58,7 @@
  • No-Op
  • Odin
  • OpenCensus
    • +
  • OpenTelemetry
  • Examples
      @@ -95,7 +96,7 @@ ⌂Natchez
      -0.1.5 +0.3.7
    • @@ -121,6 +122,7 @@
  • No-Op
  • Odin
  • OpenCensus
    • +
  • OpenTelemetry
  • Examples
    • @@ -58,6 +58,7 @@
  • No-Op
  • Odin
  • OpenCensus
    • +
  • OpenTelemetry
  • Examples
      @@ -95,7 +96,7 @@ ⌂Natchez
      -0.1.5 +0.3.7
    • @@ -121,6 +122,7 @@
  • No-Op
  • Odin
  • OpenCensus
    • +
  • OpenTelemetry
  • Examples
  • Examples
      @@ -95,7 +96,7 @@ ⌂Natchez
      -0.1.5 +0.3.7
    • @@ -121,6 +122,7 @@
  • No-Op
  • Odin
  • OpenCensus
    • +
  • OpenTelemetry
  • Examples
      @@ -156,13 +158,13 @@

      -The source code for this page can be found here. +The source code for this page can be found here.
      - +
      -

      Next: Examples

      +

      Next: OpenTelemetry

    • @@ -203,7 +205,7 @@

    -© 2021 +© 2025

    --> @@ -228,7 +230,7 @@

    - + diff --git a/backends/opentelemetry.html b/backends/opentelemetry.html new file mode 100644 index 00000000..d45b61e4 --- /dev/null +++ b/backends/opentelemetry.html @@ -0,0 +1,274 @@ + + + + +OpenTelemetry · Natchez + + + + + + + + + + + + + + + + + +
    +
    + + + +
    + +
    +
    + + +
    Natchez
    + + +
    +
    + +
    + +
    + +
    + +
    +
    + + + +
    +
    +
    + +
    +
    +
    + +
    +
    +

    OpenTelemetry

    +

    The natchez-opentelemetry module provides a backend that uses OpenTelemetry to report spans.

    +

    To use it, add the following dependency.

    sbt
    libraryDependencies += "org.tpolecat" % "natchez-opentelemetry-2.13" % "0.3.7"
    Maven
    <dependencies>
+  <dependency>
+    <groupId>org.tpolecat</groupId>
+    <artifactId>natchez-opentelemetry-2.13</artifactId>
+    <version>0.3.7</version>
+  </dependency>
+</dependencies>
    Gradle
    dependencies {
+  implementation "org.tpolecat:natchez-opentelemetry-2.13:0.3.7"
+}
    +

    Then add any exporter, for example:

    sbt
    libraryDependencies += "io.opentelemetry" % "opentelemetry-exporter-otlp" % "1.12.0"
    Maven
    <dependencies>
+  <dependency>
+    <groupId>io.opentelemetry</groupId>
+    <artifactId>opentelemetry-exporter-otlp</artifactId>
+    <version>1.12.0</version>
+  </dependency>
+</dependencies>
    Gradle
    dependencies {
+  implementation "io.opentelemetry:opentelemetry-exporter-otlp:1.12.0"
+}
    +

    Configuring an OpenTelemetry entrypoint

    +

    There are two methods you’ll need to construct an OpenTelemetry EndPoint.

    +

    OpenTelemetry.lift is used to turn an F[_] that constructs a SpanExporter, SpanProcessor or SdkTraceProvider into a Resource that will shut it down cleanly. This takes a String of what you’ve constructed, so we can give a nice error if it fails to shut down cleanly.

    +

    The OpenTelemetry.entryPoint method takes a boolean called globallyRegister which tells it whether to register this OpenTelemetry globally. This may be helpful if you have other Java dependencies that use the global tracer. It defaults to false.

    +

    It also takes an OpenTelemetrySdkBuilder => Resource[F, OpenTelemetrySdkBuilder] so that you can configure the Sdk.

    +

    Here’s an example of configuring one with the otlp exporter with batch span processing:

    + + +
    +The source code for this page can be found here. +
    + + + +
    +

    Next: Examples

    +
    +
    +
    + +
    +
    + +
    +
    + +
    + +
    + +
    +
    +
    +
    + +
    +
    +
      + +
    +
    +
    + +
    +
    +
    +
    + +
    +
    +
    +
    + +
    + + +
    + +
    +
    +
    +
    +
    + +
    +
    +
    + + + + + + + + + + + + + + diff --git a/examples/http4s.html b/examples/http4s.html index 66013501..50911a26 100644 --- a/examples/http4s.html +++ b/examples/http4s.html @@ -6,7 +6,7 @@ - + @@ -32,7 +32,7 @@ ⌂Natchez
    -0.1.5 +0.3.7
    @@ -58,6 +58,7 @@
  • No-Op
  • Odin
  • OpenCensus
    • +
  • OpenTelemetry
  • Examples
      @@ -95,7 +96,7 @@ ⌂Natchez
      -0.1.5 +0.3.7
    • @@ -121,6 +122,7 @@
  • No-Op
  • Odin
  • OpenCensus
    • +
  • OpenTelemetry
  • Examples
    • @@ -58,6 +58,7 @@
  • No-Op
  • Odin
  • OpenCensus
    • +
  • OpenTelemetry
  • Examples
      @@ -95,7 +96,7 @@ ⌂Natchez
      -0.1.5 +0.3.7
    • @@ -121,6 +122,7 @@
  • No-Op
  • Odin
  • OpenCensus
    • +
  • OpenTelemetry
  • Examples
    • @@ -58,6 +58,7 @@
  • No-Op
  • Odin
  • OpenCensus
    • +
  • OpenTelemetry
  • Examples
      @@ -95,7 +96,7 @@ ⌂Natchez
      -0.1.5 +0.3.7
    • @@ -121,6 +122,7 @@
  • No-Op
  • Odin
  • OpenCensus
    • +
  • OpenTelemetry
  • Examples
      @@ -156,10 +158,10 @@

      -The source code for this page can be found here. +The source code for this page can be found here.
      - +

    • @@ -200,7 +202,7 @@

    -© 2021 +© 2025

    --> @@ -225,7 +227,7 @@

    - + diff --git a/index.html b/index.html index 7dfd3d73..21ec740e 100644 --- a/index.html +++ b/index.html @@ -6,7 +6,7 @@ - + @@ -32,7 +32,7 @@ ⌂Natchez
    -0.1.5 +0.3.7
    @@ -58,6 +58,7 @@
  • No-Op
  • Odin
  • OpenCensus
    • +
  • OpenTelemetry
  • Examples
      @@ -95,7 +96,7 @@ ⌂Natchez
      -0.1.5 +0.3.7
    • @@ -121,6 +122,7 @@
  • No-Op
  • Odin
  • OpenCensus
    • +
  • OpenTelemetry
  • Examples