Logs API reference

The core logs API is in org.typelevel.otel4s.logs.

It is intended for adapters that forward records from an existing logging framework into OpenTelemetry. Application code continues to use its logging facade or implementation for log levels, formatting, appenders, and output.

The main types form this construction and emission chain:

Ctx is the context type supplied by the backend. The OpenTelemetry Java backend uses org.typelevel.otel4s.oteljava.context.Context.

For setup and task-oriented examples, see:

• Set up otel4s in a JVM application
• Bridge Scribe logs into OpenTelemetry
• Test logs emitted by your code

LoggerProvider[F, Ctx]

LoggerProvider[F, Ctx] is the entry point for creating Logger[F, Ctx] instances.

The name identifies the instrumentation scope that emits log records. Use a stable library, module, or fully qualified class name.

The companion object provides:

• LoggerProvider[F, Ctx] to summon an implicit provider
• LoggerProvider.noop[F, Ctx] to create a provider whose loggers are no-op

LoggerBuilder[F, Ctx]

LoggerBuilder[F, Ctx] adds instrumentation-scope metadata before creating a logger.

Use LoggerProvider.get when the logger does not need a version or schema URL.

LoggerBuilder.noop[F, Ctx] creates a builder that returns a no-op logger. It is also the builder returned by LoggerProvider.noop[F, Ctx].

import cats.effect.IO
import org.typelevel.otel4s.AnyValue
import org.typelevel.otel4s.logs.Severity
import org.typelevel.otel4s.oteljava.OtelJava

val program: IO[Unit] =
  OtelJava.autoConfigured[IO]().use { otel4s =>
    otel4s.loggerProvider
      .logger("com.example.logging-bridge")
      .withVersion("1.0.0")
      .get
      .flatMap { logger =>
        logger.logRecordBuilder
          .withSeverity(Severity.error)
          .withSeverityText("ERROR")
          .withBody(AnyValue.string("request failed"))
          .emit
      }
  }

Logger[F, Ctx]

Logger[F, Ctx] creates records for one instrumentation scope.

When LogRecordBuilder.withContext is not called, emit uses the current context. Use currentContext and withContext when the adapter captures a logging event in one context and emits it later.

The companion object provides:

• Logger[F, Ctx] to summon an implicit logger
• Logger.noop[F, Ctx] to create a no-op logger
• Logger.Implicits.noop to supply a no-op implicit logger

InstrumentMeta[F, Ctx]

Logger.meta returns logs-specific InstrumentMeta[F, Ctx] from org.typelevel.otel4s.logs.meta.

Both checks accept Option[Severity] and Option[String]. They return F[Boolean].

Call isEnabled before formatting messages, converting attributes, or rendering exception stack traces. It is a pipeline-level check: an active OpenTelemetry logs pipeline returns true, while a no-op implementation returns false. It does not apply per-logger severity filtering. The source logging framework remains responsible for deciding whether a record's level is enabled.

LogRecordBuilder[F, Ctx]

LogRecordBuilder[F, Ctx] configures and emits one log record. It provides these setters:

Repeated calls to a field setter retain the value from the last call. Adding an attribute whose key already exists replaces the previous value for that key.

LogRecordBuilder.noop[F, Ctx] creates a builder whose setters return the same no-op builder and whose emit returns F[Unit] without producing a record.

Severity

Severity represents the OpenTelemetry severity number and display name. Each value exposes value: Int and name: String.

The companion object also provides Hash[Severity] and Show[Severity] instances. Show renders the severity name.

Effect lifting

LoggerProvider, LoggerBuilder, Logger, InstrumentMeta, and LogRecordBuilder provide liftTo[G] methods backed by cats.mtl.LiftValue. The target effect requires a Monad; the source effect's Applicative comes from the LiftValue instance.

Related material

• Bridge Scribe logs into OpenTelemetry
• Test logs emitted by your code
• How otel4s context propagation works
• OpenTelemetry Logs API specification
• OpenTelemetry Logs data model