Logbook

An extensible Java library for HTTP request and response logging

Generate Convert Improve

Install / Use

/learn @zalando/Logbook

About this skill

Quality Score

0/100

README

Logbook: HTTP request and response logging

Logbook noun, /lɑɡ bʊk/: A book in which measurements from the ship's log are recorded, along with other salient details of the voyage.

Logbook is an extensible Java library to enable complete request and response logging for different client- and server-side technologies. It satisfies a special need by a) allowing web application developers to log any HTTP traffic that an application receives or sends b) in a way that makes it easy to persist and analyze it later. This can be useful for traditional log analysis, meeting audit requirements or investigating individual historic traffic issues.

Logbook is ready to use out of the box for most common setups. Even for uncommon applications and technologies, it should be simple to implement the necessary interfaces to connect a library/framework/etc. to it.

Contents:

Features
Dependencies
- Jackson Version Support
Installation
Usage
Known Issues
Getting Help with Logbook
Getting Involved/Contributing
Alternatives
Credits and References

Features

Logging: of HTTP requests and responses, including the body; partial logging (no body) for unauthorized requests
Customization: of logging format, logging destination, and conditions that request to log
Support: for Servlet containers, Apache's HTTP client, Square's OkHttp, and (via its elegant API) other frameworks
Optional obfuscation of sensitive data
Spring Boot Auto Configuration
Scalyr compatible
Sensible defaults

Dependencies

Java 17 or higher (required - Spring 7 / Spring Boot 4 and JAX-RS 3.x)
Any build tool using Maven Central, or direct download
Servlet Container (optional)
Apache HTTP Client 4.x or 5.x (optional)
JAX-RS 3.x (aka Jakarta RESTful Web Services) Client and Server (optional)
Netty 4.x (optional)
OkHttp 2.x or 3.x (optional)
Spring 7.x (optional)
Spring Boot 4.x (optional)
Ktor (optional)
logstash-logback-encoder 5.x (optional)
Jackson 2.x or 3.x (optional, required for JSON formatting)

Jackson Version Support

Logbook's core functionality works without Jackson. JSON formatting (logbook-json) and JWT attribute extraction (JwtClaimsExtractor, etc.) are optional and support both Jackson 2 and Jackson 3 automatically.

How it works:

Logbook detects which Jackson version is available on the classpath and uses the appropriate implementation:

If Jackson 2 is available, Logbook uses Jackson 2 implementations (formatters, JWT extractors, and JSON compacting)
If Jackson 3 is available, Logbook uses Jackson 3 implementations (formatters, JWT extractors, and JSON compacting)
If both are available, Jackson 3 is preferred
If neither is available, JSON formatting is disabled but core logging still works

For Spring Boot 3.x:

Jackson 2 is provided by default via spring-boot-starter-web or spring-boot-starter-jackson
JSON formatting works out of the box with no additional configuration

For Spring Boot 4.x:

Jackson 3 is provided by default via spring-boot-starter-jackson
JSON formatting works out of the box with Jackson 3

If you want to use Jackson 2 instead, add it explicitly:

<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>2.X.X</version>
</dependency>

Manual configuration (if not using Spring Boot):

Add either Jackson 2 or Jackson 3 (or both):

Jackson 2:

<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>2.X.X</version>
</dependency>

Jackson 3:

<dependency>
    <groupId>tools.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>3.X.X</version>
</dependency>

Installation

Add the following dependency to your project:

<dependency>
    <groupId>org.zalando</groupId>
    <artifactId>logbook-core</artifactId>
    <version>${logbook.version}</version>
</dependency>

Additional modules/artifacts of Logbook always share the same version number.

Alternatively, you can import our bill of materials...

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.zalando</groupId>
      <artifactId>logbook-bom</artifactId>
      <version>${logbook.version}</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<details> <summary>... which allows you to omit versions:</summary>

<dependency>
    <groupId>org.zalando</groupId>
    <artifactId>logbook-core</artifactId>
</dependency>
<dependency>
    <groupId>org.zalando</groupId>
    <artifactId>logbook-httpclient</artifactId>
</dependency>
<dependency>
    <groupId>org.zalando</groupId>
    <artifactId>logbook-jaxrs</artifactId>
</dependency>
<dependency>
    <groupId>org.zalando</groupId>
    <artifactId>logbook-json</artifactId>
</dependency>
<dependency>
    <groupId>org.zalando</groupId>
    <artifactId>logbook-netty</artifactId>
</dependency>
<dependency>
    <groupId>org.zalando</groupId>
    <artifactId>logbook-okhttp</artifactId>
</dependency>
<dependency>
    <groupId>org.zalando</groupId>
    <artifactId>logbook-okhttp2</artifactId>
</dependency>
<dependency>
    <groupId>org.zalando</groupId>
    <artifactId>logbook-servlet</artifactId>
</dependency>
<dependency>
    <groupId>org.zalando</groupId>
    <artifactId>logbook-spring-boot-starter</artifactId>
</dependency>
<dependency>
    <groupId>org.zalando</groupId>
    <artifactId>logbook-ktor-common</artifactId>
</dependency>
<dependency>
    <groupId>org.zalando</groupId>
    <artifactId>logbook-ktor-client</artifactId>
</dependency>
<dependency>
    <groupId>org.zalando</groupId>
    <artifactId>logbook-ktor-server</artifactId>
</dependency>
<dependency>
    <groupId>org.zalando</groupId>
    <artifactId>logbook-ktor</artifactId>
</dependency>
<dependency>
    <groupId>org.zalando</groupId>
    <artifactId>logbook-logstash</artifactId>
</dependency>

</details>

The logbook logger must be configured to trace level in order to log the requests and responses. With Spring Boot (using Logback) this can be accomplished by adding the following line to your application.properties:

logging.level.org.zalando.logbook: TRACE

Usage

All integrations require an instance of Logbook which holds all configuration and wires all necessary parts together. You can either create one using all the defaults:

Logbook logbook = Logbook.create();

or create a customized version using the LogbookBuilder:

Logbook logbook = Logbook.builder()
    .condition(new CustomCondition())
    .queryFilter(new CustomQueryFilter())
    .pathFilter(new CustomPathFilter())
    .headerFilter(new CustomHeaderFilter())
    .bodyFilter(new CustomBodyFilter())
    .requestFilter(new CustomRequestFilter())
    .responseFilter(new CustomResponseFilter())
    .sink(new DefaultSink(
            new CustomHttpLogFormatter(),
            new CustomHttpLogWriter()
    ))
    .build();

Strategy

Logbook used to have a very rigid strategy how to do request/response logging:

Requests/responses are logged separately
Requests/responses are logged soon as possible
Requests/responses are logged as a pair or not logged at all
(i.e. no partial logging of traffic)

Some of those restrictions could be mitigated with custom HttpLogWriter implementations, but they were never ideal.

Starting with version 2.0 Logbook now comes with a Strategy pattern at its core. Make sure you read the documentation of the Strategy interface to understand the implications.

Logbook comes with some built-in strategies: