mirror of
https://github.com/moby/moby.git
synced 2022-11-09 12:21:53 -05:00
0e8e8f0f31
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 <cpuguy83@gmail.com>
85 lines
2.4 KiB
Markdown
85 lines
2.4 KiB
Markdown
---
|
|
title: "Docker metrics collector plugins"
|
|
description: "Metrics plugins."
|
|
keywords: "Examples, Usage, plugins, docker, documentation, user guide, metrics"
|
|
---
|
|
|
|
<!-- This file is maintained within the docker/docker Github
|
|
repository at https://github.com/docker/docker/. Make all
|
|
pull requests against that repo. If you see this file in
|
|
another repository, consider it read-only there, as it will
|
|
periodically be overwritten by the definitive file. Pull
|
|
requests which include edits to this file in other repositories
|
|
will be rejected.
|
|
-->
|
|
|
|
# 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.
|