From 5f6848ae8b8592290948307e71205c02918e1ee4 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Thu, 11 Apr 2024 16:19:06 +0200 Subject: [PATCH 1/3] hugo: add support for code block titles Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- .../_default/_markup/render-codeblock.html | 67 ++++++++++--------- 1 file changed, 36 insertions(+), 31 deletions(-) diff --git a/layouts/_default/_markup/render-codeblock.html b/layouts/_default/_markup/render-codeblock.html index 0d940e1b2e..bcd93b5c11 100644 --- a/layouts/_default/_markup/render-codeblock.html +++ b/layouts/_default/_markup/render-codeblock.html @@ -1,36 +1,41 @@ -
- - {{ $lang := .Type | default "text" }} {{ $result := transform.Highlight .Inner - $lang .Options }} -
- {{ with .Attributes.collapse }} -
-
- +
+ {{ with .Attributes.title }} +
{{ . }}
+ {{ end }} +
+ + {{ $lang := .Type | default "text" }} {{ $result := transform.Highlight .Inner + $lang .Options }} +
+ {{ with .Attributes.collapse }} +
+
+ +
+
+ {{ $result }} + +
-
+ {{ else }} {{ $result }} - -
+ {{ end }}
- {{ else }} - {{ $result }} - {{ end }}
From 6a419015f84ff2b89f7b06c06e391b134d3beed6 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Thu, 11 Apr 2024 16:37:21 +0200 Subject: [PATCH 2/3] vale: add otel, grafana to vocabulary Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- .github/vale/config/vocabularies/Docker/accept.txt | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/vale/config/vocabularies/Docker/accept.txt b/.github/vale/config/vocabularies/Docker/accept.txt index 775f1cf3da..b884e07772 100644 --- a/.github/vale/config/vocabularies/Docker/accept.txt +++ b/.github/vale/config/vocabularies/Docker/accept.txt @@ -54,6 +54,7 @@ GeoNetwork Git GitHub( Actions)? Google +Grafana HTTP HyperKit IPs? @@ -77,6 +78,7 @@ Nginx Nuxeo OAuth OCI +OTel Okta Postgres PowerShell From 003c6fe251e7f88c664e55edc1a1d04f59d707bf Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Wed, 10 Apr 2024 18:49:27 +0200 Subject: [PATCH 3/3] cli: initial otel support and usage Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- content/config/otel.md | 164 +++++++++++++++++++++++++++++++++++++++++ data/toc.yaml | 2 + 2 files changed, 166 insertions(+) create mode 100644 content/config/otel.md diff --git a/content/config/otel.md b/content/config/otel.md new file mode 100644 index 0000000000..cf57523cbe --- /dev/null +++ b/content/config/otel.md @@ -0,0 +1,164 @@ +--- +title: OpenTelemetry for the Docker CLI +description: Learn about how to capture OpenTelemetry metrics for the Docker command line +keywords: otel, opentelemetry, telemetry, traces, tracing, metrics, logs +--- + +{{< introduced engine 26.1.0 >}} + +The Docker CLI supports [OpenTelemetry](https://opentelemetry.io/docs/) instrumentation +for emitting metrics about command invocations. This is disabled by default. +You can configure the CLI to start emitting metrics to the endpoint that you +specify. This allows you to capture information about your `docker` command +invocations for more insight into your Docker usage. + +Exporting metrics is opt-in, and you control where data is being sent by +specifying the destination address of the metrics collector. + +## What is OpenTelemetry? + +OpenTelemetry, or OTel for short, is an open observability framework for +creating and managing telemetry data, such as traces, metrics, and logs. +OpenTelemetry is vendor- and tool-agnostic, meaning that it can be used with a +broad variety of Observability backends. + +Support for OpenTelemetry instrumentation in the Docker CLI means that the CLI can emit +information about events that take place, using the protocols and conventions +defined in the Open Telemetry specification. + +## How it works + +The Docker CLI doesn't emit telemetry data by default. Only if you've set an +environment variable on your system will Docker CLI attempt to emit OpenTelemetry +metrics, to the endpoint that you specify. + +```bash +DOCKER_CLI_OTEL_EXPORTER_OTLP_ENDPOINT= +``` + +The variable specifies the endpoint of an OpenTelemetry collector, where telemetry data +about `docker` CLI invocation should be sent. To capture the data, you'll need +an OpenTelemetry collector listening on that endpoint. + +The purpose of a collector is to receive the telemetry data, process it, and +exports it to a backend. The backend is where the telemetry data gets stored. +You can choose from a number of different backends, such as Prometheus or +InfluxDB. + +Some backends provide tools for visualizing the metrics directly. +Alternatively, you can also run a dedicated frontend with support for +generating more useful graphs, such as Grafana. + +## Setup + +To get started capturing telemetry data for the Docker CLI, you'll need to: + +- Set the `DOCKER_CLI_OTEL_EXPORTER_OTLP_ENDPOINT` environment variable to point to an OpenTelemetry collector endpoint +- Run an OpenTelemetry collector that receives the signals from CLI command invocations +- Run a backend for storing the data received from the collector + +The following Docker Compose file bootstraps a set of services to get started with OpenTelemetry. +It includes an OpenTelemetry collector that the CLI can send metrics to, +and a Prometheus backend that scrapes the metrics off the collector. + +```yaml {collapse=true,title=compose.yml} +name: cli-otel +services: + prometheus: + image: prom/prometheus + command: + - "--config.file=/etc/prometheus/prom.yml" + ports: + # Publish the Prometheus frontend on localhost:9091 + - 9091:9090 + restart: always + volumes: + # Store Prometheus data in a volume: + - prom_data:/prometheus + # Mount the prom.yml config file + - ./prom.yml:/etc/prometheus/prom.yml + otelcol: + image: otel/opentelemetry-collector + restart: always + depends_on: + - prometheus + ports: + - 4317:4317 + volumes: + # Mount the otelcol.yml config file + - ./otelcol.yml:/etc/otelcol/config.yaml + +volumes: + prom_data: +``` + +This service assumes that the following two configuration files exist alongside +`compose.yml`: + +- ```yaml {collapse=true,title=otelcol.yml} + # Receive signals over gRPC and HTTP + receivers: + otlp: + protocols: + grpc: + http: + + # Establish an endpoint for Prometheus to scrape from + exporters: + prometheus: + endpoint: "0.0.0.0:8889" + + service: + pipelines: + metrics: + receivers: [otlp] + exporters: [prometheus] + ``` + +- ```yaml {collapse=true,title=prom.yml} + # Configure Prometheus to scrape the OpenTelemetry collector endpoint + scrape_configs: + - job_name: "otel-collector" + scrape_interval: 1s + static_configs: + - targets: ["otelcol:8889"] + ``` + +With these files in place: + +1. Start the Docker Compose services: + + ```console + $ docker compose up + ``` + +2. Configure Docker CLI to export telemetry to the OpenTelemetry collector. + + ```console + $ export DOCKER_CLI_OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317 + ``` + +3. Run a `docker` command to trigger the CLI into sending a metric signal to + the OpenTelemetry collector. + + ```console + $ docker version + ``` + +4. To view telemetry metrics created by the CLI, open the Prometheus expression + browser by going to . + +5. In the **Query** field, enter `command_time_milliseconds_total`, and execute + the query to see the telemetry data. + +## Available metrics + +Docker CLI currently exports a single metric, `command.time`, which measures +the execution duration of a command in milliseconds. This metric has the +following attributes: + +- `command.name`: the name of the command +- `command.status.code`: the exit code of the command +- `command.stderr.isatty`: true if stderr is attached to a TTY +- `command.stdin.isatty`: true if stdin is attached to a TTY +- `command.stdout.isatty`: true if stdout is attached to a TTY diff --git a/data/toc.yaml b/data/toc.yaml index df796a72eb..7731c6bdbb 100644 --- a/data/toc.yaml +++ b/data/toc.yaml @@ -1546,6 +1546,8 @@ Manuals: title: Filter commands - path: /config/formatting/ title: Format command and log output + - path: /config/otel/ + title: OpenTelemetry - sectiontitle: Manage resources section: - path: /config/pruning/