logbook下載 - logbook原始碼下載

日誌：HTTP 請求和回應日誌記錄

航海日誌名詞，/lɑɡ bʊk/：記錄船舶航海日誌測量結果以及航程其他重要細節的書。

Logbook是一個可擴展的 Java 程式庫，可為不同的用戶端和伺服器端技術啟用完整的請求和回應日誌記錄。它透過以下方式滿足了特殊需求：a) 允許 Web 應用程式開發人員記錄應用程式接收或發送的任何 HTTP 流量 b) 以便以後輕鬆保留和分析它。這對於傳統日誌分析、滿足審計要求或調查單一歷史流量問題非常有用。

日誌可立即用於大多數常見設定。即使對於不常見的應用程式和技術，實現連接庫/框架等所需的介面也應該很簡單。到它。

特徵

記錄：HTTP 請求和回應，包括正文；未經授權的請求的部分日誌記錄（無正文）
客製化：記錄格式、記錄目的地和請求記錄的條件
支援：Servlet 容器、Apache 的 HTTP 用戶端、Square 的 OkHttp 以及（透過其優雅的 API）其他框架
敏感資料的可選混淆
Spring Boot 自動配置
相容於 Scalyr
合理的預設值

依賴關係

Java 8（對於 Spring 6 / Spring Boot 3 和 JAX-RS 3.x，需要 Java 17）
任何使用 Maven Central 的建置工具，或直接下載
Servlet 容器（可選）
Apache HTTP 用戶端 4.x或 5.x （可選）
JAX-RS 3.x（又稱 Jakarta RESTful Web 服務）用戶端和伺服器（選用）
JAX-RS 2.x 客戶端和伺服器（選購）
Netty 4.x（選購）
OkHttp 2.x或 3.x （可選）
Spring 6.x或 Spring 5.x（可選，請參閱下方的說明）
Spring Boot 3.x或 2.x（可選）
科托爾（可選）
Logstash-logback-編碼器 5.x（可選）

安裝

將以下相依性新增至您的專案：

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

Spring 5 / Spring Boot 2 支持

為了 Spring 5 / Spring Boot 2 向後相容，請新增以下匯入：

< dependency >
    < groupId >org.zalando</ groupId >
    < artifactId >logbook-servlet</ artifactId >
    < version >${logbook.version}</ version >
    < classifier >javax</ classifier >
</ dependency >

日誌的其他模組/工件始終共用相同的版本號。

或者，您可以匯入我們的物料清單...

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

...這允許您省略版本：

< 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 >

日誌記錄器必須配置為追蹤等級才能記錄請求和回應。對於 Spring Boot 2（使用 Logback），這可以透過將以下行新增至您的application.properties來完成

 logging.level.org.zalando.logbook: TRACE

用法

所有整合都需要一個Logbook實例，它保存所有配置並將所有必要的部分連接在一起。您可以使用所有預設值建立一個：

 Logbook logbook = Logbook . create ();

或使用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 ();

策略

日誌曾經有一個非常嚴格的策略來記錄請求/回應：

請求/回應單獨記錄
盡快記錄請求/回應
請求/回應成對記錄或根本不記錄
（即不記錄部分流量）

其中一些限制可以透過自訂HttpLogWriter實作來緩解，但它們從來都不是理想的。

從 2.0 版開始，Logbook 現在以策略模式為核心。請務必閱讀Strategy介面的文檔以了解其意義。

日誌附帶一些內建策略：

BodyOnlyIfStatusAtLeastStrategy
StatusAtLeastStrategy
WithoutBodyStrategy

屬性提取器

從 3.4.0 版本開始，Logbook 配備了名為Attribute Extractor 的功能。屬性基本上是可以從請求和/或回應中提取並用它們記錄的鍵/值對清單。這個想法源自於問題 381，其中請求一個功能從授權標頭中的 JWT 令牌中提取主題聲明。

AttributeExtractor介面有兩種extract方法：一種只能從請求中提取屬性，另一種可以同時提取請求和回應。兩者都會傳回HttpAttributes類別的實例，它基本上是一個奇特的Map<String, Object> 。請注意，由於映射值的類型為Object ，因此它們應該具有適當的toString()方法，以便它們以有意義的方式出現在日誌中。或者，日誌格式化程式可以透過實作自己的序列化邏輯來解決此問題。例如，內建日誌格式化程式JsonHttpLogFormatter使用ObjectMapper來序列化值。

這是一個例子：

 final class OriginExtractor implements AttributeExtractor {

  @ Override
  public HttpAttributes extract ( final HttpRequest request ) {
    return HttpAttributes . of ( "origin" , request . getOrigin ());
  }
    
}

然後必須透過註冊此屬性提取器來建立日誌：

 final Logbook logbook = Logbook . builder ()
        . attributeExtractor ( new OriginExtractor ())
        . build ();

這將導致請求日誌包含以下內容：

 "attributes":{"origin":"LOCAL"}

有關更進階的範例，請查看JwtFirstMatchingClaimExtractor和JwtAllMatchingClaimsExtractor類別。前者從請求 JWT 令牌中提取與聲明名稱清單相符的第一個聲明。後者從請求 JWT 令牌中提取與聲明名稱清單相符的所有聲明。

如果您需要合併多個AttributeExtractor ，您可以使用CompositeAttributeExtractor類別：

 final List < AttributeExtractor > extractors = List . of (
    extractor1 ,
    extractor2 ,
    extractor3
);

final Logbook logbook = Logbook . builder ()
        . attributeExtractor ( new CompositeAttributeExtractor ( extractors ))
        . build ();

階段

日誌的工作分為幾個不同的階段：

有條件的，
過濾，
格式化和
寫作

每個階段都由一個或多個可用於自訂的介面表示。每個階段都有一個合理的預設值。

有條件的

記錄 HTTP 訊息並包含其正文是一項相當昂貴的任務，因此停用某些請求的日誌記錄非常有意義。一個常見的用例是忽略來自負載平衡器的運行狀況檢查請求，或通常由開發人員向管理端點發出的任何請求。

定義條件就像編寫一個特殊的Predicate一樣簡單，該謂詞決定是否應記錄請求（及其對應的回應）。或者，您可以使用並組合預定義謂詞：

 Logbook logbook = Logbook . builder ()
    . condition ( exclude (
        requestTo ( "/health" ),
        requestTo ( "/admin/**" ),
        contentType ( "application/octet-stream" ),
        header ( "X-Secret" , newHashSet ( "1" , "true" ):: contains )))
    . build ();

排除模式，例如/admin/** ，鬆散地遵循 Ant 的路徑模式風格，而不考慮 URL 的查詢字串。

濾

過濾的目標是防止記錄 HTTP 請求和回應的某些敏感部分。這通常包括授權標頭，但也可以應用於某些純文字查詢或表單參數 - 例如密碼。

日誌支援不同類型的過濾器：

類型	運行於	適用於	預設
`QueryFilter`	查詢字串	要求	`access_token`
`PathFilter`	小路	要求	不適用
`HeaderFilter`	標頭（單一鍵值對）	兩個都	`Authorization`
`BodyFilter`	內容類型和正文	兩個都	json： `access_token`和`refresh_token` 形式： `client_secret` ， `password`和`refresh_token`
`RequestFilter`	`HttpRequest`	要求	替換二進制、多部分和流主體。
`ResponseFilter`	`HttpResponse`	回覆	替換二進制、多部分和流主體。

QueryFilter 、 PathFilter 、 HeaderFilter和BodyFilter是相對較高等級的，應該能夠滿足大約 90% 的情況下的所有需求。對於更複雜的設置，應該回退到低階變體，分別為RequestFilter和ResponseFilter （與ForwardingHttpRequest / ForwardingHttpResponse結合使用）。

您可以像這樣配置過濾器：

 import static org . zalando . logbook . core . HeaderFilters . authorization ;
import static org . zalando . logbook . core . HeaderFilters . eachHeader ;
import static org . zalando . logbook . core . QueryFilters . accessToken ;
import static org . zalando . logbook . core . QueryFilters . replaceQuery ;

Logbook logbook = Logbook . builder ()
        . requestFilter ( RequestFilters . replaceBody ( message -> contentType ( "audio/*" ). test ( message ) ? "mmh mmh mmh mmh" : null ))
        . responseFilter ( ResponseFilters . replaceBody ( message -> contentType ( "*/*-stream" ). test ( message ) ? "It just keeps going and going..." : null ))
        . queryFilter ( accessToken ())
        . queryFilter ( replaceQuery ( "password" , "<secret>" ))
        . headerFilter ( authorization ())
        . headerFilter ( eachHeader ( "X-Secret" :: equalsIgnoreCase , "<secret>" ))
        . build ();

您可以根據需要配置任意數量的過濾器 - 它們將連續運行。

JsonPath 主體過濾（實驗）

您可以將 JSON 路徑過濾套用至 JSON 正文。以下是一些範例：

 import static org . zalando . logbook . json . JsonPathBodyFilters . jsonPath ;
import static java . util . regex . Pattern . compile ;

Logbook logbook = Logbook . builder ()
        . bodyFilter ( jsonPath ( "$.password" ). delete ())
        . bodyFilter ( jsonPath ( "$.active" ). replace ( "unknown" ))
        . bodyFilter ( jsonPath ( "$.address" ). replace ( "X" ))
        . bodyFilter ( jsonPath ( "$.name" ). replace ( compile ( "^( \ w).+" ), "$1." ))
        . bodyFilter ( jsonPath ( "$.friends.*.name" ). replace ( compile ( "^( \ w).+" ), "$1." ))
        . bodyFilter ( jsonPath ( "$.grades.*" ). replace ( 1.0 ))
        . build ();

看一下下面的範例，應用過濾之前和之後：

前

{
  "id" : 1 ,
  "name" : " Alice " ,
  "password" : " s3cr3t " ,
  "active" : true ,
  "address" : " Anhalter Straße 17 13, 67278 Bockenheim an der Weinstraße " ,
  "friends" : [
    {
      "id" : 2 ,
      "name" : " Bob "
    },
    {
      "id" : 3 ,
      "name" : " Charlie "
    }
  ],
  "grades" : {
    "Math" : 1.0 ,
    "English" : 2.2 ,
    "Science" : 1.9 ,
    "PE" : 4.0
  }
}

後

{
  "id" : 1 ,
  "name" : " Alice " ,
  "active" : " unknown " ,
  "address" : " XXX " ,
  "friends" : [
    {
      "id" : 2 ,
      "name" : " B. "
    },
    {
      "id" : 3 ,
      "name" : " C. "
    }
  ],
  "grades" : {
    "Math" : 1.0 ,
    "English" : 1.0 ,
    "Science" : 1.0 ,
    "PE" : 1.0
  }
}

格式化

格式基本上定義了請求和回應如何轉換為字串。格式化程式不指定請求和回應的記錄位置－編寫器負責這項工作。

Logbook 附帶兩種不同的預設格式化程式： HTTP和JSON 。

HTTP協定

HTTP是預設格式樣式，由DefaultHttpLogFormatter提供。它主要設計用於本地開發和調試，而不是用於生產用途。這是因為它不像 JSON 那樣容易被機器讀取。

要求

 Incoming Request: 2d66e4bc-9a0d-11e5-a84c-1f39510f0d6b
GET http://example.org/test HTTP/1.1
Accept: application/json
Host: localhost
Content-Type: text/plain

Hello world!

回覆

 Outgoing Response: 2d66e4bc-9a0d-11e5-a84c-1f39510f0d6b
Duration: 25 ms
HTTP/1.1 200
Content-Type: application/json

{ "value" : " Hello world! " }

JSON

JSON是一種替代格式樣式，由JsonHttpLogFormatter提供。與 HTTP 不同，它主要是為生產用途而設計的——解析器和日誌使用者可以輕鬆使用它。

需要以下依賴：

< dependency >
  < groupId >org.zalando</ groupId >
  < artifactId >logbook-json</ artifactId >
</ dependency >

要求

{
  "origin" : " remote " ,
  "type" : " request " ,
  "correlation" : " 2d66e4bc-9a0d-11e5-a84c-1f39510f0d6b " ,
  "protocol" : " HTTP/1.1 " ,
  "sender" : " 127.0.0.1 " ,
  "method" : " GET " ,
  "uri" : " http://example.org/test " ,
  "host" : " example.org " ,
  "path" : " /test " ,
  "scheme" : " http " ,
  "port" : null ,
  "headers" : {
    "Accept" : [ " application/json " ],
    "Content-Type" : [ " text/plain " ]
  },
  "body" : " Hello world! "
}

回覆

{
  "origin" : " local " ,
  "type" : " response " ,
  "correlation" : " 2d66e4bc-9a0d-11e5-a84c-1f39510f0d6b " ,
  "duration" : 25 ,
  "protocol" : " HTTP/1.1 " ,
  "status" : 200 ,
  "headers" : {
    "Content-Type" : [ " text/plain " ]
  },
  "body" : " Hello world! "
}

注意： application/json （和application/*+json ）類型的主體將內聯到產生的 JSON 樹中。即，JSON 回應正文不會被轉義並表示為字串：

{
  "origin" : " local " ,
  "type" : " response " ,
  "correlation" : " 2d66e4bc-9a0d-11e5-a84c-1f39510f0d6b " ,
  "duration" : 25 ,
  "protocol" : " HTTP/1.1 " ,
  "status" : 200 ,
  "headers" : {
    "Content-Type" : [ " application/json " ]
  },
  "body" : {
    "greeting" : " Hello, world! "
  }
}

通用日誌格式

通用日誌格式 (CLF) 是 Web 伺服器在產生伺服器日誌檔案時使用的標準化文字檔案格式。此格式透過CommonsLogFormatSink支援：

 185.85.220.253 - - [02/Aug/2019:08:16:41 0000] "GET /search?q=zalando HTTP/1.1" 200 -

擴充日誌格式

擴充日誌格式 (ELF) 是一種標準化文字檔案格式，與通用日誌格式 (CLF) 一樣，Web 伺服器在產生日誌檔案時使用該格式，但 ELF 檔案提供了更多資訊和靈活性。此格式透過ExtendedLogFormatSink支援。另請參閱 W3C 文件。

預設欄位：

 date time c-ip s-dns cs-method cs-uri-stem cs-uri-query sc-status sc-bytes cs-bytes time-taken cs-protocol cs(User-Agent) cs(Cookie) cs(Referrer)

預設日誌輸出範例：

 2019-08-02 08:16:41 185.85.220.253 localhost POST /search ?q=zalando 200 21 20 0.125 HTTP/1.1 "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0" "name=value" "https://example.com/page?q=123"

使用者可以透過ExtendedLogFormatSink的建構函式使用自訂欄位覆寫預設欄位：

 new ExtendedLogFormatSink ( new DefaultHttpLogWriter (), "date time cs(Custom-Request-Header) sc(Custom-Response-Header)" )

對於 Http 標頭欄位： cs(Any-Header)和sc(Any-Header) ，使用者可以指定他們想要從請求中提取的任何標頭。

其他支援的欄位列在ExtendedLogFormatSink.Field的值中，可以放入自訂欄位表達式中。

捲曲

cURL是一種替代格式樣式，由CurlHttpLogFormatter提供，它將請求呈現為可執行的cURL命令。與 JSON 不同，它主要是為人類設計的。

要求

curl -v -X GET ' http://localhost/test ' -H ' Accept: application/json '

回覆

請參閱 HTTP 或為回應提供自己的後備：

 new CurlHttpLogFormatter ( new JsonHttpLogFormatter ());

史普朗克

Splunk是一種替代格式樣式，由SplunkHttpLogFormatter提供，它將請求和回應呈現為鍵值對。

要求

 origin=remote type=request correlation=2d66e4bc-9a0d-11e5-a84c-1f39510f0d6b protocol=HTTP/1.1 sender=127.0.0.1 method=POST uri=http://example.org/test host=example.org scheme=http port=null path=/test headers={Accept=[application/json], Content-Type=[text/plain]} body=Hello world!

回覆

 origin=local type=response correlation=2d66e4bc-9a0d-11e5-a84c-1f39510f0d6b duration=25 protocol=HTTP/1.1 status=200 headers={Content-Type=[text/plain]} body=Hello world!

寫作

寫入定義了格式化請求和回應的寫入位置。 Logbook 提供了三種實作：Logger、Stream 和 Chunking。

記錄器

預設情況下，請求和回應是使用slf4j記錄器記錄的，該記錄器使用org.zalando.logbook.Logbook類別和日誌等級trace 。這可以客製化：

 Logbook logbook = Logbook . builder ()
    . sink ( new DefaultSink (
            new DefaultHttpLogFormatter (),
            new DefaultHttpLogWriter ()
    ))
    . build ();

溪流

另一種實作是將請求和回應記錄到PrintStream中，例如System.out或System.err 。對於在生產中運行來說，這通常是一個糟糕的選擇，但有時對於短期本地開發和/或調查可能很有用。

 Logbook logbook = Logbook . builder ()
    . sink ( new DefaultSink (
            new DefaultHttpLogFormatter (),
            new StreamHttpLogWriter ( System . err )
    ))
    . build ();

分塊

ChunkingSink會將長訊息分割成較小的區塊，並在委託給另一個接收器時單獨寫入它們：

 Logbook logbook = Logbook . builder ()
    . sink ( new ChunkingSink ( sink , 1000 ))
    . build ();

下沉

HttpLogFormatter和HttpLogWriter的組合非常適合大多數用例，但它也有其限制。直接實作Sink介面可以實現更複雜的用例，例如將請求/回應寫入資料庫等結構化持久性儲存。

可以使用CompositeSink將多個接收器合併為一個。

服務程式

您必須將LogbookFilter註冊為過濾器鏈中的Filter - 或在您的web.xml檔案中（請注意，xml 方法將使用所有預設值且無法設定）：

< filter >
    < filter-name >LogbookFilter</ filter-name >
    < filter-class >org.zalando.logbook.servlet.LogbookFilter</ filter-class >
</ filter >
< filter-mapping >
    < filter-name >LogbookFilter</ filter-name >
    < url-pattern >/*</ url-pattern >
    < dispatcher >REQUEST</ dispatcher >
    < dispatcher >ASYNC</ dispatcher >
</ filter-mapping >

或以程式設計方式，透過ServletContext ：

 context . addFilter ( "LogbookFilter" , new LogbookFilter ( logbook ))
    . addMappingForUrlPatterns ( EnumSet . of ( REQUEST , ASYNC ), true , "/*" );

注意：不支援ERROR調度。強烈建議您在REQUEST或ASNYC調度中產生錯誤回應。

預設情況下， LogbookFilter將處理帶有application/x-www-form-urlencoded主體的請求，該主體與任何其他請求沒有不同，即您將在日誌中看到請求主體。這種方法的缺點是您將無法使用任何HttpServletRequest.getParameter*(..)方法。有關更多詳細信息，請參閱問題 #94。

表格請求

從 Logbook 1.5.0 開始，現在可以使用logbook.servlet.form-request系統屬性指定定義 Logbook 如何處理這種情況的三種策略之一：

價值	優點	缺點
`body` （預設）	正文已記錄	下游程式碼*不能使用`getParameter()`**
`parameter`	主體已記錄（但它是根據參數重建的）	下游程式碼不能使用`getInputStream()`
`off`	下游程式碼可以決定要使用`getInputStream()`還是`getParameter*()`	正文未記錄

安全

安全應用程式通常需要稍微不同的設定。通常，您應該避免記錄未經授權的請求，尤其是正文，因為它很快就會讓攻擊者淹沒您的日誌文件，從而佔用您寶貴的磁碟空間。假設您的應用程式在另一個篩選器內處理授權，您有兩個選項：

不要記錄未經授權的請求
記錄沒有請求正文的未經授權的請求

將LogbookFilter放置在安全過濾器之後，您可以輕鬆實現前一種設定。後者稍微複雜一點。您將需要兩個LogbookFilter實例 - 一個在安全過濾器之前，一個在安全過濾器之後：

 context . addFilter ( "SecureLogbookFilter" , new SecureLogbookFilter ( logbook ))
    . addMappingForUrlPatterns ( EnumSet . of ( REQUEST , ASYNC ), true , "/*" );
context . addFilter ( "securityFilter" , new SecurityFilter ())
    . addMappingForUrlPatterns ( EnumSet . of ( REQUEST ), true , "/*" );
context . addFilter ( "LogbookFilter" , new LogbookFilter ( logbook ))
    . addMappingForUrlPatterns ( EnumSet . of ( REQUEST , ASYNC ), true , "/*" );

第一個日誌過濾器將僅記錄未經授權的請求。第二個過濾器將一如既往地記錄授權請求。

HTTP客戶端

logbook-httpclient模組包含與HttpClient一起使用的HttpRequestInterceptor和HttpResponseInterceptor ：

 CloseableHttpClient client = HttpClientBuilder . create ()
        . addInterceptorFirst ( new LogbookHttpRequestInterceptor ( logbook ))
        . addInterceptorFirst ( new LogbookHttpResponseInterceptor ())
        . build ();

由於LogbookHttpResponseInterceptor與HttpAsyncClient不相容，因此還有另一種方法來記錄回應：

 CloseableHttpAsyncClient client = HttpAsyncClientBuilder . create ()
        . addInterceptorFirst ( new LogbookHttpRequestInterceptor ( logbook ))
        . build ();
        
// and then wrap your response consumer
client . execute ( producer , new LogbookHttpAsyncResponseConsumer <>( consumer ), callback )

HTTP客戶端5

logbook-httpclient5模組包含一個與HttpClient一起使用的ExecHandler ：

 CloseableHttpClient client = HttpClientBuilder . create ()
        . addExecInterceptorFirst ( "Logbook" , new LogbookHttpExecHandler ( logbook ))
        . build ();

應先添加Handler，以便在記錄後進行壓縮，並在記錄前進行解壓。

為了避免重大更改，還有一個HttpRequestInterceptor和HttpResponseInterceptor與HttpClient一起使用，只要不使用壓縮（或其他 ExecHandlers），它們就可以正常工作：

 CloseableHttpClient client = HttpClientBuilder . create ()
        . addRequestInterceptorFirst ( new LogbookHttpRequestInterceptor ( logbook ))
        . addResponseInterceptorFirst ( new LogbookHttpResponseInterceptor ())
        . build ();

由於LogbookHttpResponseInterceptor與HttpAsyncClient不相容，因此還有另一種方法來記錄回應：

 CloseableHttpAsyncClient client = HttpAsyncClientBuilder . create ()
        . addRequestInterceptorFirst ( new LogbookHttpRequestInterceptor ( logbook ))
        . build ();
        
// and then wrap your response consumer
client . execute ( producer , new LogbookHttpAsyncResponseConsumer <>( consumer ), callback )

JAX-RS 2.x 和 3.x（又稱 Jakarta RESTful Web 服務）

筆記

支援 JAX-RS 2.x

Logbook 3.0 至 3.6 中刪除了 JAX-RS 2.x（舊版）支援。

從 Logbook 3.7 開始，JAX-RS 2.x 支援又回來了。

但是，您需要新增javax分類器才能使用正確的日誌模組：

< dependency >
    < groupId >org.zalando</ groupId >
    < artifactId >logbook-jaxrs</ artifactId >
    < version >${logbook.version}</ version >
    < classifier >javax</ classifier >
</ dependency >

您還應該確保以下依賴項位於您的類別路徑上。預設情況下， logbook-jaxrs導入jersey-client 3.x ，它與 JAX-RS 2.x 不相容：

球衣客戶端 2.x
球衣-hk2 2.x
javax.activation

logbook-jaxrs模組包含：

LogbookClientFilter用於發出 HTTP 請求的應用程式

 client . register ( new LogbookClientFilter ( logbook ));

用於 HTTP 伺服器的LogbookServerFilter

 resourceConfig . register ( new LogbookServerFilter ( logbook ));

JDK HTTP 伺服器

logbook-jdkserver模組提供對 JDK HTTP 伺服器的支持，並包含：

與內建伺服器一起使用的LogbookFilter

 httpServer . createContext ( path , handler ). getFilters (). add ( new LogbookFilter ( logbook ))

內蒂

logbook-netty模組包含：

與HttpClient一起使用的LogbookClientHandler ：

 HttpClient httpClient =
        HttpClient . create ()
                . doOnConnected (
                        ( connection -> connection . addHandlerLast ( new LogbookClientHandler ( logbook )))
                );

與HttpServer一起使用的LogbookServerHandler ：

 HttpServer httpServer =
        HttpServer . create ()
                . doOnConnection (
                        connection -> connection . addHandlerLast ( new LogbookServerHandler ( logbook ))
                );

Spring WebFlux

Spring WebFlux 的使用者可以選擇以下任一選項：

以程式設計方式建立NettyWebServer （傳遞HttpServer ）
註冊自訂NettyServerCustomizer
以程式設計方式建立ReactorClientHttpConnector （傳遞HttpClient ）
註冊自訂WebClientCustomizer
使用獨立的連接器獨立模組logbook-spring-webflux

米克羅特

Micronaut 使用者可以按照官方文件了解如何將 Logbook 與 Micronaut 整合。

️儘管 Quarkus 和 Vert.x 在底層使用 Netty，但不幸的是，它們都不允許存取或自訂它（還）。

OkHttp v2.x

logbook-okhttp2模組包含一個與OkHttpClient 2.x 版本一起使用的Interceptor ：

 OkHttpClient client = new OkHttpClient ();
client . networkInterceptors (). add ( new LogbookInterceptor ( logbook ));

如果您期望 gzip 壓縮的回應，您需要另外註冊我們的GzipInterceptor 。 OkHttp 內建的透明 gzip 支援將在任何網路攔截器之後運行，強制日誌記錄壓縮的二進位回應。

 OkHttpClient client = new OkHttpClient ();
client . networkInterceptors (). add ( new LogbookInterceptor ( logbook ));
client . networkInterceptors (). add ( new GzipInterceptor ());

OkHttp v3.x

logbook-okhttp模組包含一個與OkHttpClient 3.x 版本一起使用的Interceptor ：

 OkHttpClient client = new OkHttpClient . Builder ()
        . addNetworkInterceptor ( new LogbookInterceptor ( logbook ))
        . build ();

 OkHttpClient client = new OkHttpClient . Builder ()
        . addNetworkInterceptor ( new LogbookInterceptor ( logbook ))
        . addNetworkInterceptor ( new GzipInterceptor ())
        . build ();

克托爾

logbook-ktor-client模組包含：

與HttpClient一起使用的LogbookClient ：

 private val client = HttpClient ( CIO ) {
    install( LogbookClient ) {
        logbook = logbook
    }
}

logbook-ktor-server模組包含：

與Application一起使用的LogbookServer伺服器：

 private val server = embeddedServer( CIO ) {
    install( LogbookServer ) {
        logbook = logbook
    }
}

或者，您可以使用logbook-ktor ，它附帶logbook-ktor-client和logbook-ktor-server模組。

春天

logbook-spring模組包含一個與RestTemplate一起使用的ClientHttpRequestInterceptor ：

    LogbookClientHttpRequestInterceptor interceptor = new LogbookClientHttpRequestInterceptor ( logbook );
    RestTemplate restTemplate = new RestTemplate ();
    restTemplate . getInterceptors (). add ( interceptor );

春季啟動啟動器

Logbook 為 Spring Boot 使用者提供了方便的自動配置。它會使用合理的預設值自動設定以下所有部分：

小服務程序過濾器
用於未經授權請求的第二個 Servlet 過濾器（如果偵測到 Spring Security）
標頭/參數/正文過濾器
HTTP/JSON 風格的格式化程序
日誌編寫器

不要聲明對logbook-core依賴，而是向 Spring Boot Starter 宣告一個依賴：

< dependency >
    < groupId >org.zalando</ groupId >
    < artifactId >logbook-spring-boot-starter</ artifactId >
    < version >${logbook.version}</ version >
</ dependency >

如果需要，每個 bean 都可以被覆蓋和定制，例如：

 @ Bean
public BodyFilter bodyFilter () {
    return merge (
            defaultValue (), 
            replaceJsonStringProperty ( singleton ( "secret" ), "XXX" ));
}

請參閱LogbookAutoConfiguration或下表以查看可能的整合點清單：

類型	姓名	預設
`FilterRegistrationBean`	`secureLogbookFilter`	基於`LogbookFilter`
`FilterRegistrationBean`	`logbookFilter`	基於`LogbookFilter`
`Logbook`		基於條件、過濾器、格式化程式和編寫器
`Predicate<HttpRequest>`	`requestCondition`	無過濾器；稍後與`logbook.exclude`和`logbook.exclude`結合使用
`HeaderFilter`		基於`logbook.obfuscate.headers`
`PathFilter`		基於`logbook.obfuscate.paths`
`QueryFilter`		基於`logbook.obfuscate.parameters`
`BodyFilter`		`BodyFilters.defaultValue()` ，請參閱過濾
`RequestFilter`		`RequestFilters.defaultValue()` ，請參考過濾
`ResponseFilter`		`ResponseFilters.defaultValue()` ，請參閱過濾
`Strategy`		`DefaultStrategy`
`AttributeExtractor`		`NoOpAttributeExtractor`
`Sink`		`DefaultSink`
`HttpLogFormatter`		`JsonHttpLogFormatter`
`HttpLogWriter`		`DefaultHttpLogWriter`

多個過濾器合併為一個。

來自`logbook-spring`自動配置的 bean

logbook-spring中的一些類別包含在自動配置中。

您可以使用以下程式碼自動組裝LogbookClientHttpRequestInterceptor ：

 private final RestTemplate restTemplate ;
MyClient ( RestTemplateBuilder builder , LogbookClientHttpRequestInterceptor interceptor ){
  this . restTemplate = builder
    . additionalInterceptors ( interceptor )
    . build ();
}

配置

下表顯示了可用的配置（按字母順序排序）：

配置	描述	預設
`logbook.attribute-extractors`	AttributeExtractors 列表，包括`type` （目前為`JwtFirstMatchingClaimExtractor`或`JwtAllMatchingClaimsExtractor` ）、 `claim-names`和`claim-key`等配置。	`[]`
`logbook.filter.enabled`	啟用`LogbookFilter`器	`true`
`logbook.filter.form-request-mode`	確定如何處理表單請求	`body`
`logbook.filters.body.default-enabled`	啟用/停用 java.util.ServiceLoader 收集的預設主體過濾器	`true`
`logbook.format.style`	格式化樣式（ `http` 、 `json` 、 `curl`或`splunk` ）	`json`
`logbook.httpclient.decompress-response`	啟用/停用帶有 gzip 編碼正文的 HttpClient 的附加解壓縮過程（僅用於日誌記錄目的）。這意味著額外的減壓和可能的性能影響。	`false` （禁用）
`logbook.minimum-status`	啟用記錄的最低狀態（ `status-at-least`和`body-only-if-status-at-least` ）	`400`
`logbook.obfuscate.headers`	需要混淆的標頭名稱列表	`[Authorization]`
`logbook.obfuscate.json-body-fields`	要混淆的 JSON 正文字段列表	`[]`
`logbook.obfuscate.parameters`	需要混淆的參數名稱列表	`[access_token]`
`logbook.obfuscate.paths`	需要混淆的路徑列表。檢查語法過濾。	`[]`
`logbook.obfuscate.replacement`	要使用的值而不是混淆的值	`XXX`
`logbook.predicate.include`	僅包含某些路徑和方法（如果已定義）	`[]`
`logbook.predicate.exclude`	排除某些路徑和方法（覆蓋`logbook.predicate.include` ）	`[]`
`logbook.secure-filter.enabled`	啟用`SecureLogbookFilter`器	`true`
`logbook.strategy`	策略（ `default` 、 `status-at-least` 、 `body-only-if-status-at-least` 、 `without-body` ）	`default`
`logbook.write.chunk-size`	將日誌行分割成大小不超過`chunk-size`的較小區塊。	`0` （停用）
`logbook.write.max-body-size`	將正文截斷至`max-body-size`個字元並附加`...` 。 ️如果請求符合日誌記錄條件，則無論`logbook.write.max-body-size`值為何，日誌仍將緩衝完整正文	`-1` （停用）

配置範例

 logbook :
  predicate :
    include :
      - path : /api/**
        methods : 
         - GET
         - POST
      - path : /actuator/**
    exclude :
      - path : /actuator/health
      - path : /api/admin/**
        methods : 
         - POST
  filter.enabled : true
  secure-filter.enabled : true
  format.style : http
  strategy : body-only-if-status-at-least
  minimum-status : 400
  obfuscate :
    headers :
      - Authorization
      - X-Secret
    parameters :
      - access_token
      - password
  write :
    chunk-size : 1000
  attribute-extractors :
    - type : JwtFirstMatchingClaimExtractor
      claim-names : [ "sub", "subject" ]
      claim-key : Principal
    - type : JwtAllMatchingClaimsExtractor
      claim-names : [ "sub", "iat" ]

Logstash-logback-編碼器

對於基本的 Logback 配置

 <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
    <encoder class="net.logstash.logback.encoder.LogstashEncoder"/>
</appender>

使用LogstashLogbackSink配置日誌

 HttpLogFormatter formatter = new JsonHttpLogFormatter();
LogstashLogbackSink sink = new LogstashLogbackSink(formatter);

對於像這樣的輸出

 {
  "@timestamp" : "2019-03-08T09:37:46.239+01:00",
  "@version" : "1",
  "message" : "GET http://localhost/test?limit=1",
  "logger_name" : "org.zalando.logbook.Logbook",
  "thread_name" : "main",
  "level" : "TRACE",
  "level_value" : 5000,
  "http" : {
     // logbook request/response contents
  }
}

自訂預設日誌記錄級別

您可以透過使用特定等級初始化LogstashLogbackSink來靈活地自訂預設日誌記錄等級。例如：

 LogstashLogbackSink sink = new LogstashLogbackSink(formatter, Level.INFO);

已知問題

Logbook Servlet Filter 使用getWriter和/或getParameter*()幹擾下游程式碼。有關詳細信息，請參閱 Servlet。
日誌 Servlet 過濾器不支援ERROR調度。強烈建議您不要使用它來產生錯誤回應。

取得有關日誌的協助

如果您有疑問、疑慮、錯誤報告等，請在此儲存庫的問題追蹤器中提交問題。

參與/貢獻

要做出貢獻，只需提出拉取請求並添加有關添加或更改的簡短描述（1-2 句話）。有關更多詳細信息，請查看貢獻指南。

替代方案

Apache HttpClient 線路日誌記錄
- 僅限客戶端
- Apache HttpClient 獨有
- 支援 HTTP 正文
Spring Boot 存取日誌記錄
- 限春季應用
- 僅伺服器端
- Tomcat/Undertow/Jetty 獨有
- 不支援 HTTP 主體
Tomcat 請求轉儲器過濾器
- 僅伺服器端
- 雄貓專屬
- 不支援 HTTP 主體
登入訪問
- 僅伺服器端
- 任何 Servlet 容器
- 支援 HTTP 正文

學分和參考文獻

Grand Turk 是納爾遜時代一艘三桅六級護衛艦的複製品 - JoJan 的航海日誌和圖表已獲得知識共享許可（署名-相同方式共享 3.0 未移植）。

展開

logbook