Docker 日誌驅動程式外掛

本文件介紹 Docker 的日誌驅動程式外掛。

日誌驅動程式讓使用者能將容器日誌轉發至其他服務進行處理。Docker 內建多種日誌驅動程式，但永遠無法滿足所有應用場景。外掛機制允許 Docker 在不需將各種服務的客戶端程式庫嵌入 Docker 核心程式碼的情況下，支援多樣化的日誌服務。詳細資訊請參閱外掛文件。

建立日誌外掛

日誌外掛的主要介面與其他外掛類型使用相同的 JSON+HTTP RPC 協定。有關日誌外掛的參考實作，請參閱此範例外掛。該範例封裝了內建的 jsonfilelog 日誌驅動程式。

LogDriver 協定

日誌外掛必須在啟動時註冊為 LogDriver。啟用後，使用者即可將該外掛指定為日誌驅動程式。

日誌外掛必須實作兩個 HTTP 端點：

/LogDriver.StartLogging

通知外掛有一個容器即將啟動，外掛應開始接收其日誌。

日誌將透過請求中定義的檔案進行串流傳輸。在 Linux 上，此檔案為 FIFO（具名管道）。目前 Windows 不支援日誌外掛。

請求 (Request)

{
  "File": "/path/to/file/stream",
  "Info": {
          "ContainerID": "123456"
  }
}

File 是需要消耗的日誌串流路徑。即使是外掛先前已接收過日誌的容器，每次呼叫 StartLogging 時都應提供不同的檔案路徑。該檔案由 Docker 建立，並帶有隨機生成的名稱。

Info 是關於正在被記錄的容器的詳細資訊。格式較為靈活，由以下結構定義：

type Info struct {
	Config              map[string]string
	ContainerID         string
	ContainerName       string
	ContainerEntrypoint string
	ContainerArgs       []string
	ContainerImageID    string
	ContainerImageName  string
	ContainerCreated    time.Time
	ContainerEnv        []string
	ContainerLabels     map[string]string
	LogPath             string
	DaemonName          string
}

ContainerID 必定會隨此結構提供，但其他欄位可能為空或缺失。

回應 (Response)

{
  "Err": ""
}

若請求過程中發生錯誤，請在回應的 Err 欄位中添加錯誤訊息。若無錯誤，則可發送空回應 ({}) 或將 Err 欄位留空。

此時驅動程式應開始從傳入的檔案中讀取日誌訊息。若訊息未被消耗，可能會導致容器在嘗試寫入 stdio 串流時發生阻塞。

日誌串流訊息以 Protocol Buffers 編碼。Protobuf 定義位於 moby 儲存庫中。

由於 Protocol Buffers 並非自定界限 (self-delimited)，您必須使用以下串流格式從串流中進行解碼：

[size][message]

其中 size 為 4 位元組 Big-endian 二進位編碼的 uint32。在此處，size 定義了下一條訊息的大小。message 則是實際的日誌條目。

Golang 的串流編碼器/解碼器參考實作可於此處找到。

/LogDriver.StopLogging

通知外掛停止從指定檔案收集日誌。一旦收到回應，Docker 將刪除該檔案。您必須確保在回應此請求前已收集串流上的所有日誌，否則可能會遺失日誌資料。

此端點的請求並不意味著容器已被移除，僅表示它已停止。

請求 (Request)

{
  "File": "/path/to/file/stream"
}

回應 (Response)

{
  "Err": ""
}

若請求過程中發生錯誤，請在回應的 Err 欄位中添加錯誤訊息。若無錯誤，則可發送空回應 ({}) 或將 Err 欄位留空。

選用端點

日誌外掛可以實作兩個額外的日誌端點：

/LogDriver.Capabilities

定義日誌驅動程式的功能。您必須實作此端點，Docker 才能利用定義的任何功能。

請求 (Request)

{}

回應 (Response)

{
  "ReadLogs": true
}

支援的功能：

• ReadLogs - 此功能告知 Docker 外掛具備向客戶端讀取日誌的能力。回報支援 ReadLogs 的外掛必須實作 /LogDriver.ReadLogs 端點。

/LogDriver.ReadLogs

將日誌讀回給客戶端。此功能用於執行 docker logs <container> 時。

若要讓 Docker 使用此端點，外掛必須在呼叫 /LogDriver.Capabilities 時明確指定。

請求 (Request)

{
  "ReadConfig": {},
  "Info": {
    "ContainerID": "123456"
  }
}

ReadConfig 是讀取選項列表，由以下 Golang 結構定義：

type ReadConfig struct {
	Since  time.Time
	Tail   int
	Follow bool
}

• Since 定義了應發送的最舊日誌。
• Tail 定義了要讀取的行數（例如類似指令 tail -n 10）。
• Follow 表示客戶端希望保持連接，以便在讀取現有日誌後，持續接收新產生的日誌訊息。

Info 與 /LogDriver.StartLogging 中定義的類型相同。它應用於確定要讀取哪組日誌。

回應 (Response)

{{ log stream }}

回應應為使用與外掛從 Docker 消耗訊息時相同格式進行編碼的日誌訊息。