Skip to content

Commit 003c6fe

Browse files
dvdksndvdksn
committed
cli: initial otel support and usage
Signed-off-by: David Karlsson <[email protected]>
1 parent 6a41901 commit 003c6fe

File tree

2 files changed

+166
-0
lines changed

2 files changed

+166
-0
lines changed

‎content/config/otel.md‎

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
---
2+
title: OpenTelemetry for the Docker CLI
3+
description: Learn about how to capture OpenTelemetry metrics for the Docker command line
4+
keywords: otel, opentelemetry, telemetry, traces, tracing, metrics, logs
5+
---
6+
7+
{{< introduced engine 26.1.0 >}}
8+
9+
The Docker CLI supports [OpenTelemetry](https://opentelemetry.io/docs/) instrumentation
10+
for emitting metrics about command invocations. This is disabled by default.
11+
You can configure the CLI to start emitting metrics to the endpoint that you
12+
specify. This allows you to capture information about your `docker` command
13+
invocations for more insight into your Docker usage.
14+
15+
Exporting metrics is opt-in, and you control where data is being sent by
16+
specifying the destination address of the metrics collector.
17+
18+
## What is OpenTelemetry?
19+
20+
OpenTelemetry, or OTel for short, is an open observability framework for
21+
creating and managing telemetry data, such as traces, metrics, and logs.
22+
OpenTelemetry is vendor- and tool-agnostic, meaning that it can be used with a
23+
broad variety of Observability backends.
24+
25+
Support for OpenTelemetry instrumentation in the Docker CLI means that the CLI can emit
26+
information about events that take place, using the protocols and conventions
27+
defined in the Open Telemetry specification.
28+
29+
## How it works
30+
31+
The Docker CLI doesn't emit telemetry data by default. Only if you've set an
32+
environment variable on your system will Docker CLI attempt to emit OpenTelemetry
33+
metrics, to the endpoint that you specify.
34+
35+
```bash
36+
DOCKER_CLI_OTEL_EXPORTER_OTLP_ENDPOINT=<endpoint>
37+
```
38+
39+
The variable specifies the endpoint of an OpenTelemetry collector, where telemetry data
40+
about `docker` CLI invocation should be sent. To capture the data, you'll need
41+
an OpenTelemetry collector listening on that endpoint.
42+
43+
The purpose of a collector is to receive the telemetry data, process it, and
44+
exports it to a backend. The backend is where the telemetry data gets stored.
45+
You can choose from a number of different backends, such as Prometheus or
46+
InfluxDB.
47+
48+
Some backends provide tools for visualizing the metrics directly.
49+
Alternatively, you can also run a dedicated frontend with support for
50+
generating more useful graphs, such as Grafana.
51+
52+
## Setup
53+
54+
To get started capturing telemetry data for the Docker CLI, you'll need to:
55+
56+
- Set the `DOCKER_CLI_OTEL_EXPORTER_OTLP_ENDPOINT` environment variable to point to an OpenTelemetry collector endpoint
57+
- Run an OpenTelemetry collector that receives the signals from CLI command invocations
58+
- Run a backend for storing the data received from the collector
59+
60+
The following Docker Compose file bootstraps a set of services to get started with OpenTelemetry.
61+
It includes an OpenTelemetry collector that the CLI can send metrics to,
62+
and a Prometheus backend that scrapes the metrics off the collector.
63+
64+
```yaml {collapse=true,title=compose.yml}
65+
name: cli-otel
66+
services:
67+
prometheus:
68+
image: prom/prometheus
69+
command:
70+
- "--config.file=/etc/prometheus/prom.yml"
71+
ports:
72+
# Publish the Prometheus frontend on localhost:9091
73+
- 9091:9090
74+
restart: always
75+
volumes:
76+
# Store Prometheus data in a volume:
77+
- prom_data:/prometheus
78+
# Mount the prom.yml config file
79+
- ./prom.yml:/etc/prometheus/prom.yml
80+
otelcol:
81+
image: otel/opentelemetry-collector
82+
restart: always
83+
depends_on:
84+
- prometheus
85+
ports:
86+
- 4317:4317
87+
volumes:
88+
# Mount the otelcol.yml config file
89+
- ./otelcol.yml:/etc/otelcol/config.yaml
90+
91+
volumes:
92+
prom_data:
93+
```
94+
95+
This service assumes that the following two configuration files exist alongside
96+
`compose.yml`:
97+
98+
- ```yaml {collapse=true,title=otelcol.yml}
99+
# Receive signals over gRPC and HTTP
100+
receivers:
101+
otlp:
102+
protocols:
103+
grpc:
104+
http:
105+
106+
# Establish an endpoint for Prometheus to scrape from
107+
exporters:
108+
prometheus:
109+
endpoint: "0.0.0.0:8889"
110+
111+
service:
112+
pipelines:
113+
metrics:
114+
receivers: [otlp]
115+
exporters: [prometheus]
116+
```
117+
118+
- ```yaml {collapse=true,title=prom.yml}
119+
# Configure Prometheus to scrape the OpenTelemetry collector endpoint
120+
scrape_configs:
121+
- job_name: "otel-collector"
122+
scrape_interval: 1s
123+
static_configs:
124+
- targets: ["otelcol:8889"]
125+
```
126+
127+
With these files in place:
128+
129+
1. Start the Docker Compose services:
130+
131+
```console
132+
$ docker compose up
133+
```
134+
135+
2. Configure Docker CLI to export telemetry to the OpenTelemetry collector.
136+
137+
```console
138+
$ export DOCKER_CLI_OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
139+
```
140+
141+
3. Run a `docker` command to trigger the CLI into sending a metric signal to
142+
the OpenTelemetry collector.
143+
144+
```console
145+
$ docker version
146+
```
147+
148+
4. To view telemetry metrics created by the CLI, open the Prometheus expression
149+
browser by going to <http://localhost:9091/graph>.
150+
151+
5. In the **Query** field, enter `command_time_milliseconds_total`, and execute
152+
the query to see the telemetry data.
153+
154+
## Available metrics
155+
156+
Docker CLI currently exports a single metric, `command.time`, which measures
157+
the execution duration of a command in milliseconds. This metric has the
158+
following attributes:
159+
160+
- `command.name`: the name of the command
161+
- `command.status.code`: the exit code of the command
162+
- `command.stderr.isatty`: true if stderr is attached to a TTY
163+
- `command.stdin.isatty`: true if stdin is attached to a TTY
164+
- `command.stdout.isatty`: true if stdout is attached to a TTY

‎data/toc.yaml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1546,6 +1546,8 @@ Manuals:
15461546
title: Filter commands
15471547
- path: /config/formatting/
15481548
title: Format command and log output
1549+
- path: /config/otel/
1550+
title: OpenTelemetry
15491551
- sectiontitle: Manage resources
15501552
section:
15511553
- path: /config/pruning/

0 commit comments

Comments
 (0)