Docker 日誌驅動程式外掛

目錄

本文件描述了 Docker 的日誌驅動外掛。

日誌驅動使使用者能夠將容器日誌轉發到另一個服務進行處理。Docker 內建了幾個日誌驅動，但內建驅動無法滿足所有用例。外掛允許 Docker 支援廣泛的日誌記錄服務，而無需將這些服務的客戶端庫嵌入到 Docker 的主程式碼庫中。有關更多資訊，請參閱外掛文件。

建立一個日誌記錄外掛

日誌記錄外掛的主要介面使用與其他外掛型別相同的 JSON+HTTP RPC 協議。請參閱示例外掛以獲取日誌記錄外掛的參考實現。該示例包裝了內建的 jsonfilelog 日誌驅動程式。

LogDriver 協議

日誌記錄外掛必須在外掛啟用期間註冊為 LogDriver。一旦啟用，使用者就可以將該外掛指定為日誌驅動。

日誌記錄外掛必須實現兩個 HTTP 端點

/LogDriver.StartLogging

向外掛發出訊號，表示一個容器正在啟動，外掛應該開始接收該容器的日誌。

日誌將透過請求中定義的檔案進行流式傳輸。在 Linux 上，此檔案是一個 FIFO。目前在 Windows 上不支援日誌記錄外掛。

請求

{
  "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 將始終隨此結構提供，但其他欄位可能為空或缺失。

響應

{
  "Err": ""
}

如果在此請求期間發生錯誤，請在響應的 Err 欄位中新增一條錯誤訊息。如果沒有錯誤，您可以傳送一個空響應（{}）或一個空的 Err 欄位值。

此時，驅動程式應該正在從傳入的檔案中消費日誌訊息。如果訊息未被消費，可能會導致容器在嘗試寫入其 stdio 流時阻塞。

日誌流訊息被編碼為協議緩衝區。protobuf 定義位於 moby 倉庫中。

由於協議緩衝區不是自定界的，您必須使用以下流格式從流中解碼它們

[size][message]

其中 size 是一個 4 位元組大端二進位制編碼的 uint32。size 在這裡定義了下一條訊息的大小。message 是實際的日誌條目。

流編碼器/解碼器的參考 golang 實現可以在這裡找到

/LogDriver.StopLogging

向外掛發出訊號，停止從定義的檔案中收集日誌。收到響應後，Docker 將刪除該檔案。您必須確保在響應此請求之前收集流上的所有日誌，否則可能會丟失日誌資料。

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

請求

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

響應

{
  "Err": ""
}

如果在此請求期間發生錯誤，請在響應的 Err 欄位中新增一條錯誤訊息。如果沒有錯誤，您可以傳送一個空響應（{}）或一個空的 Err 欄位值。

可選端點

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

/LogDriver.Capabilities

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

請求

{}

響應

{
  "ReadLogs": true
}

支援的功能

  • ReadLogs - 這告訴 Docker 該外掛能夠將日誌讀回給客戶端。報告支援 ReadLogs 的外掛必須實現 /LogDriver.ReadLogs 端點。

/LogDriver.ReadLogs

將日誌讀回給客戶端。當呼叫 docker logs <container> 時使用。

為了讓 Docker 使用此端點，外掛必須在呼叫 /LogDriver.Capabilities 時指明。

請求

{
  "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 中定義的相同型別。它應用於確定要讀取哪組日誌。

響應

{{ log stream }}

響應應該是使用與外掛從 Docker 消費的訊息相同的格式編碼的日誌訊息。