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, Meter, 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. 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 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:

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:

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

Related modules

Some module families are usually added after you have chosen a backend:

• Use Semantic conventions when you want generated attribute keys or metric specs from the OpenTelemetry semantic conventions
• Use Testkit when you want to assert exported telemetry in tests
• Use The JVM backend 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
• To set up a Scala.js or Scala Native application, use the otel4s-sdk documentation
• To use an existing OpenTelemetry Java SDK instance, follow Use the global OpenTelemetry instance
• To record metrics or create spans, use the Metrics and Tracing how-to sections