Docker 日誌驅動程式插件

本文檔說明 Docker 的記錄驅動程式外掛程式。

記錄驅動程式讓使用者可以將容器日誌轉發到其他服務進行處理。 Docker 包含幾個內建的記錄驅動程式，但是永遠無法期望使用內建驅動程式支援所有使用案例。外掛程式允許 Docker 支援各種記錄服務，而無需在主要的 Docker 程式碼庫中嵌入這些服務的用戶端程式庫。如需更多資訊，請參閱外掛程式文件。

建立記錄外掛程式

記錄外掛程式的主要介面使用與其他外掛程式類型相同的 JSON+HTTP RPC 協定。請參閱範例

記錄外掛程式必須在plugin啟動期間註冊為 `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 串流時阻塞。

日誌串流訊息編碼為 protocol buffer。 protobuf 定義位於moby 儲存庫

[size][message]

其中 `size` 是一個 4 位元組大端序二進位編碼的 uint32。在這種情況下，`size` 定義下一個訊息的大小。 `message` 是實際的日誌項目。

可以在這裡/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 使用的訊息相同的格式編碼日誌訊息。