h4sbl is a Scala 3 library that provides enhanced logging middleware for http4s applications. It offers colorful, configurable, and comprehensive logging for HTTP operations.

The standard http4s logger is functional but limited. h4sbl provides a cleaner, more informative logging experience with color-coded output, sensitive header redaction, and log level-aware verbosity.

• Colorful Output - Color-coded HTTP methods, status codes, and headers for easy visual parsing
• Configurable - Full control over colors, header redaction, and body logging
• Log Level Aware - Automatically adjusts verbosity based on your logger configuration
• Header Redaction - Automatically redacts sensitive headers (Authorization, Cookie, etc.)
• Body Capture - Optionally logs request and response bodies at TRACE level
• Minimal Boilerplate - Simple API that wraps your existing http4s client

Add the following dependencies to your build.sbt:

libraryDependencies ++= Seq(
  "com.colofabrix.scala" %% "h4sbl"         % "1.0.0",
  "org.http4s"           %% "http4s-client" % <version>,  // Required peer dependency
  "org.typelevel"        %% "cats-effect"   % <version>,  // Required peer dependency
)

Note: h4sbl uses Provided scope for http4s and Cats Effect, giving you full control over the versions in your project.

Wrap your http4s client with the logging middleware:

import cats.effect.*
import com.colofabrix.scala.http4s.middleware.betterlogger.*
import org.http4s.ember.client.EmberClientBuilder

object MyApp extends IOApp.Simple:

  def run: IO[Unit] =
    EmberClientBuilder
      .default[IO]
      .build
      .map(ClientLogger(_))  // Wrap with logging
      .use { client =>
        client.expect[String]("https://httpbin.org/get").flatMap(IO.println)
      }

Control whether sensitive headers are redacted in logs:

import com.colofabrix.scala.http4s.middleware.betterlogger.*

// Show all headers (useful for debugging)
val loggingClient = ClientLogger(redactHeaders = false)(httpClient)

// Redact sensitive headers (default behavior)
val safeLoggingClient = ClientLogger(redactHeaders = true)(httpClient)

For complete control over logging behavior:

import com.colofabrix.scala.http4s.middleware.betterlogger.*

val config =
  LogConfig(
    redactHeaders = true,
    colors = LogColors.default,
    logRequestBody = true,
    logResponseBody = true,
  )

val loggingClient = ClientLogger.withConfig(config)(httpClient)

For log files or environments that don't support ANSI colors:

import com.colofabrix.scala.http4s.middleware.betterlogger.*

val config = LogConfig(colors = LogColors.noColors)
val loggingClient = ClientLogger.withConfig(config)(httpClient)

The main entry point for creating a logging middleware.

Configuration case class for logging behavior.

Color scheme configuration for log output.

Presets:

• LogColors.default - Full ANSI color support
• LogColors.noColors - Plain text output

h4sbl adjusts its output based on the configured log level:

Create a custom color scheme for your logs:

import scala.Console.*

val customColors =
  LogColors(
    httpVersion = CYAN,
    safeMethod = BLUE,
    unsafeMethod = RED,
    uri = s"$WHITE$BOLD",
    headers = YELLOW,
    body = WHITE,
    successStatus = GREEN,
    clientErrorStatus = MAGENTA,
    serverErrorStatus = s"$RED$BOLD",
    reset = RESET,
  )

val config = LogConfig(colors = customColors)
val loggingClient = ClientLogger.withConfig(config)(httpClient)

Configure your logback.xml to control logging verbosity:

<configuration>
  <!-- Show full details including bodies -->
  <logger name="com.colofabrix.scala.http4s.middleware.betterlogger" level="TRACE"/>

  <!-- Or just headers, no bodies -->
  <logger name="com.colofabrix.scala.http4s.middleware.betterlogger" level="DEBUG"/>
</configuration>

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

h4sbl is released under the MIT license. See LICENSE for details.

Fabrizio Colonna

• http4s - Typeful, functional HTTP for Scala
• Cats Effect - The pure asynchronous runtime for Scala
• log4cats - Logging for Cats Effect