From c564ad3f69b706c01efb87c2ac5fa037a32d443d Mon Sep 17 00:00:00 2001 From: Brian Goff Date: Thu, 13 Apr 2017 21:56:50 -0400 Subject: [PATCH] Add support for metrics plugins Allows for a plugin type that can be used to scrape metrics. This is useful because metrics are not neccessarily at a standard location... `--metrics-addr` must be set, and must currently be a TCP socket. Even if metrics are done via a unix socket, there's no guarentee where the socket may be located on the system, making bind-mounting such a socket into a container difficult (and racey, failure-prone on daemon restart). Metrics plugins side-step this issue by always listening on a unix socket and then bind-mounting that into a known path in the plugin container. Note there has been similar work in the past (and ultimately punted at the time) for consistent access to the Docker API from within a container. Why not add metrics to the Docker API and just provide a plugin with access to the Docker API? Certainly this can be useful, but gives a lot of control/access to a plugin that may only need the metrics. We can look at supporting API plugins separately for this reason. Signed-off-by: Brian Goff Upstream-commit: d8e04f68d3cba0a65f6b624db0dff40db9f6ca15 Component: cli --- components/cli/docs/extend/config.md | 2 + components/cli/docs/extend/plugins_metrics.md | 85 +++++++++++++++++++ .../docs/reference/commandline/plugin_ls.md | 4 +- 3 files changed, 89 insertions(+), 2 deletions(-) create mode 100644 components/cli/docs/extend/plugins_metrics.md diff --git a/components/cli/docs/extend/config.md b/components/cli/docs/extend/config.md index c7444525fc..bb6c7f2ceb 100644 --- a/components/cli/docs/extend/config.md +++ b/components/cli/docs/extend/config.md @@ -61,6 +61,8 @@ Config provides the base accessible fields for working with V0 plugin format - **docker.logdriver/1.0** + - **docker.metricscollector/1.0** + - **`socket`** *string* socket is the name of the socket the engine should use to communicate with the plugins. diff --git a/components/cli/docs/extend/plugins_metrics.md b/components/cli/docs/extend/plugins_metrics.md new file mode 100644 index 0000000000..a86c7f22d2 --- /dev/null +++ b/components/cli/docs/extend/plugins_metrics.md @@ -0,0 +1,85 @@ +--- +title: "Docker metrics collector plugins" +description: "Metrics plugins." +keywords: "Examples, Usage, plugins, docker, documentation, user guide, metrics" +--- + + + +# Metrics Collector Plugins + +Docker exposes internal metrics based on the prometheus format. Metrics plugins +enable accessing these metrics in a consistent way by providing a Unix +socket at a predefined path where the plugin can scrape the metrics. + +> **Note**: that while the plugin interface for metrics is non-experimental, the naming +of the metrics and metric labels is still considered experimental and may change +in a future version. + +## Creating a metrics plugin + +You must currently set `PropagatedMount` in the plugin `config.json` to +`/run/docker`. This allows the plugin to receive updated mounts +(the bind-mounted socket) from Docker after the plugin is already configured. + +## MetricsCollector protocol + +Metrics plugins must register as implementing the`MetricsCollector` interface +in `config.json`. + +On Unix platforms, the socket is located at `/run/docker/metrics.sock` in the +plugin's rootfs. + +`MetricsCollector` must implement two endpoints: + +### `MetricsCollector.StartMetrics` + +Signals to the plugin that the metrics socket is now available for scraping + +**Request** +```json +{} +``` + +The request has no playload. + +**Response** +```json +{ + "Err": "" +} +``` + +If an error occurred during this request, add an error message to the `Err` field +in the response. If no error then you can either send an empty response (`{}`) +or an empty value for the `Err` field. Errors will only be logged. + +### `MetricsCollector.StopMetrics` + +Signals to the plugin that the metrics socket is no longer available. +This may happen when the daemon is shutting down. + +**Request** +```json +{} +``` + +The request has no playload. + +**Response** +```json +{ + "Err": "" +} +``` + +If an error occurred during this request, add an error message to the `Err` field +in the response. If no error then you can either send an empty response (`{}`) +or an empty value for the `Err` field. Errors will only be logged. diff --git a/components/cli/docs/reference/commandline/plugin_ls.md b/components/cli/docs/reference/commandline/plugin_ls.md index 7808c79f6d..3ba29fee03 100644 --- a/components/cli/docs/reference/commandline/plugin_ls.md +++ b/components/cli/docs/reference/commandline/plugin_ls.md @@ -55,7 +55,7 @@ than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "b The currently supported filters are: * enabled (boolean - true or false, 0 or 1) -* capability (string - currently `volumedriver`, `networkdriver`, `ipamdriver`, or `authz`) +* capability (string - currently `volumedriver`, `networkdriver`, `ipamdriver`, `logdriver`, `metricscollector`, or `authz`) #### enabled @@ -65,7 +65,7 @@ The `enabled` filter matches on plugins enabled or disabled. The `capability` filter matches on plugin capabilities. One plugin might have multiple capabilities. Currently `volumedriver`, `networkdriver`, -`ipamdriver`, and `authz` are supported capabilities. +`ipamdriver`, `logdriver`, `metricscollector`, and `authz` are supported capabilities. ```bash $ docker plugin install --disable tiborvass/no-remove