diff --git a/docs/directory.conf b/docs/directory.conf index dad8a3b17..e90a81f91 100644 --- a/docs/directory.conf +++ b/docs/directory.conf @@ -2,7 +2,6 @@ laika.title = otel4s laika.navigationOrder = [ index.md - modules-structure.md ecosystem.md how-to-jvm-setup how-to-tracing diff --git a/docs/explanations/directory.conf b/docs/explanations/directory.conf index c26887162..4283a161f 100644 --- a/docs/explanations/directory.conf +++ b/docs/explanations/directory.conf @@ -1,6 +1,7 @@ laika.title = Explanations laika.navigationOrder = [ + modules-and-module-families.md how-otel4s-context-propagation-works.md choosing-parent-spans-and-tracing-scopes.md tracing-resource-and-fs2-stream-scopes.md diff --git a/docs/explanations/modules-and-module-families.md b/docs/explanations/modules-and-module-families.md new file mode 100644 index 000000000..70985b321 --- /dev/null +++ b/docs/explanations/modules-and-module-families.md @@ -0,0 +1,97 @@ +# Modules and module families + +otel4s splits its published artifacts into module families so libraries and applications can depend on only the +pieces they need. + +The main distinction is between: + +- API modules, which define backend-agnostic tracing, metrics, and logs interfaces +- backend modules, which implement those interfaces +- supporting modules, which provide semantic conventions, instrumentation helpers, and testing utilities + +That split keeps application dependencies explicit and lets library authors instrument code without forcing a +specific telemetry backend on their users. + +## Main entry points + +Most users start with one of these module families: + +- `otel4s-core*` defines the core otel4s APIs such as [Tracer][tracer-github], [Meter][meter-github], and logging + interfaces. Use these modules when you are instrumenting a library or writing backend-agnostic code. +- `otel4s-oteljava*` implements those APIs on top of [OpenTelemetry Java][otel-java]. Use these modules when you are + building a JVM application that needs a production telemetry backend. + +Within this repository, `otel4s-oteljava` is the main backend. It is JVM-only. + +If you need a backend for Scala.js or Scala Native, use the separate +[`otel4s-sdk`](https://typelevel.org/otel4s-sdk/sdk/overview.html) project. It builds on `otel4s-core`, but it is +published from a different repository. + +## How the families relate + +The published modules in this repository fall into a few groups: + +- `otel4s-core*` provides backend-agnostic APIs and no-op implementations +- `otel4s-oteljava*` provides the JVM backend and OpenTelemetry Java integration +- `otel4s-semconv*` provides generated semantic attribute keys and metric specs +- `otel4s-instrumentation-*` provides ready-to-use instrumentation helpers +- `otel4s-oteljava-testkit` and the signal-specific testkits provide in-memory exporters and expectation APIs for + tests +- `otel4s-oteljava-context-storage` supports JVM interop scenarios where otel4s context must stay aligned with + OpenTelemetry Java context + +At a high level, the dependency flow looks like this: + +```mermaid +graph BT + otel4s-oteljava --> otel4s-core + otel4s-semconv --> otel4s-core + otel4s-instrumentation-metrics --> otel4s-core +``` + +Some families are further split by signal. For example, `otel4s-core` and `otel4s-oteljava` both have tracing, +metrics, and logs variants, plus shared internal modules such as `*-common`. Most users do not need to think about +that structure until they want a smaller dependency surface for one specific signal. + +## Which module do I need? + +Use the smallest module that matches your job: + +| Use case | Start with | Why | +|---|---|---| +| Library instrumentation for tracing only | `otel4s-core-trace` | Depends only on the tracing API | +| Library instrumentation for metrics only | `otel4s-core-metrics` | Depends only on the metrics API | +| Library instrumentation for logs only | `otel4s-core-logs` | Depends only on the logs API | +| Library instrumentation for multiple signals | `otel4s-core` | Aggregates the core signal APIs | +| JVM application exporting telemetry | `otel4s-oteljava` | Main backend in this repo | +| Scala.js or Scala Native application exporting telemetry | `otel4s-sdk` | Cross-platform backend published from the separate `otel4s-sdk` repo | +| JVM tests that need to assert exported telemetry | `otel4s-oteljava-testkit` | Provides in-memory exporters and expectation APIs | + +If you are unsure, a useful rule of thumb is: + +- if you are publishing a library, start with `otel4s-core*` +- if you are running a JVM application, start with `otel4s-oteljava` +- if you are running a Scala.js or Scala Native application, start with + [`otel4s-sdk`](https://typelevel.org/otel4s-sdk/sdk/overview.html) + +## Related modules + +Some module families are usually added after you have chosen a backend: + +- Use [Semantic conventions](../instrumentation/semantic-conventions.md) when you want generated attribute keys or + metric specs from the OpenTelemetry semantic conventions +- Use [Testkit](../oteljava/testkit.md) when you want to assert exported telemetry in tests +- Use [OtelJava](../oteljava/overview.md) when you need JVM-specific backend details + +## Next steps + +- To set up the JVM backend in an application, follow [Set up otel4s in a JVM application](../how-to-jvm-setup/set-up-otel4s-in-a-jvm-application.md) +- To set up a Scala.js or Scala Native application, use the + [`otel4s-sdk` documentation](https://typelevel.org/otel4s-sdk/sdk/overview.html) +- To use an existing OpenTelemetry Java SDK instance, follow [Use the global OpenTelemetry instance](../how-to-jvm-setup/use-the-global-opentelemetry-instance.md) +- To record metrics or create spans, use the [Metrics](../how-to-metrics/index.md) and [Tracing](../how-to-tracing/index.md) + how-to sections + +[tracer-github]: https://github.com/typelevel/otel4s/blob/main/core/trace/src/main/scala/org/typelevel/otel4s/trace/Tracer.scala +[meter-github]: https://github.com/typelevel/otel4s/blob/main/core/metrics/src/main/scala/org/typelevel/otel4s/metrics/Meter.scala +[otel-java]: https://github.com/open-telemetry/opentelemetry-java diff --git a/docs/how-to-jvm-setup/index.md b/docs/how-to-jvm-setup/index.md index 3177a02a7..a47cce5ee 100644 --- a/docs/how-to-jvm-setup/index.md +++ b/docs/how-to-jvm-setup/index.md @@ -12,11 +12,11 @@ Use this section when you want to get otel4s running on the JVM with the OpenTel [Use the global OpenTelemetry instance](use-the-global-opentelemetry-instance.md) - Use the otel4s Java agent and still access the same SDK from otel4s: [Use the otel4s Java agent](use-the-otel4s-java-agent.md) -- Choose the right published module for your application or library: - [Modules structure](../modules-structure.md#which-module-do-i-need) ## Related material +- Choose the right published module for your application or library: + [Modules and module families](../explanations/modules-and-module-families.md#which-module-do-i-need) - Backend overview and existing JVM-specific pages: [OtelJava](../oteljava/overview.md) - Local verification examples: diff --git a/docs/index.md b/docs/index.md index d1e7aa05d..35098e7e9 100644 --- a/docs/index.md +++ b/docs/index.md @@ -82,7 +82,7 @@ the separate [otel4s-sdk][otel4s-sdk] project. ## Getting started If you develop an application and want to export the telemetry, use `otel4s-oteljava` module. -If you develop a library, check out this [recommendation](modules-structure.md#which-module-do-i-need). +If you develop a library, check out this [recommendation](explanations/modules-and-module-families.md#which-module-do-i-need). @:select(build-tool) diff --git a/docs/modules-structure.md b/docs/modules-structure.md deleted file mode 100644 index 6192e4fd4..000000000 --- a/docs/modules-structure.md +++ /dev/null @@ -1,68 +0,0 @@ -# Modules structure - -The `otel4s` repository is designed with modularity in mind. Its published -artifacts are organized into distinct module families that serve different -roles, with `otel4s-core` and `otel4s-oteljava` as the primary entry points in -this repo. - -The primary motivation behind this modular architecture is to keep the classpath small. - -## High-level modules - -```mermaid -graph BT - otel4s-oteljava --> otel4s-core -``` - -### 1) `otel4s-core` - -Defines the interfaces: [Tracer][tracer-github], -[Meter][meter-github], and others. -It also offers no-op implementations. - -### 2) `otel4s-oteljava` - -The implementation of `otel4s-core` interfaces. Uses [OpenTelemetry Java][otel-java] under the hood. - -## Related project - -If you need a pure Scala backend, use the separate -[`otel4s-sdk`](https://typelevel.org/otel4s-sdk/sdk/overview.html) project. -It depends on `otel4s-core` but is released from a different repository. - -## High-level module structure - -Each module family has several submodules: -1. `{x}-common` - the shared code, used by `{x}-trace` and `{x}-metrics` -2. `{x}-trace` - the tracing-specific code -3. `{x}-metrics` - the metrics-specific code -4. `{x}` - the high-level module itself - aggregates all of the above - -The current structure of the modules: -```mermaid -graph BT - otel4s-core --> otel4s-core-metrics - otel4s-core --> otel4s-core-trace - otel4s-core-metrics --> otel4s-core-common - otel4s-core-trace --> otel4s-core-common - - otel4s-oteljava --> otel4s-oteljava-metrics - otel4s-oteljava --> otel4s-oteljava-trace - otel4s-oteljava-metrics --> otel4s-oteljava-common - otel4s-oteljava-trace --> otel4s-oteljava-common -``` - -The repo also publishes supporting modules such as semantic conventions, -instrumentation helpers, and testkit artifacts. - -## Which module do I need? - -Let's take a look into common scenarios: - -1. You develop a library, and you will use only trace-specific interfaces - use `otel4s-core-trace` -2. You develop a library, and you will use both tracing and metrics interfaces - use `otel4s-core` -3. You develop an app and want to export your telemetry - use `otel4s-oteljava` module - -[tracer-github]: https://github.com/typelevel/otel4s/blob/main/core/trace/src/main/scala/org/typelevel/otel4s/trace/Tracer.scala -[meter-github]: https://github.com/typelevel/otel4s/blob/main/core/metrics/src/main/scala/org/typelevel/otel4s/metrics/Meter.scala -[otel-java]: https://github.com/open-telemetry/opentelemetry-java