cli: document initial otel support and usage

[dvdksn]

Description

Information about initial OTel support in the Docker CLI, for collecting telemetry data about Docker CLI command invocations

Reviews

• Technical review
• Editorial review
• Product review

[netlify]

✅ Deploy Preview for docsdocker ready!

Name	Link
🔨 Latest commit	003c6fe
🔍 Latest deploy log	https://app.netlify.com/sites/docsdocker/deploys/66216c2fbadacc0008abb4e3
😎 Deploy Preview	https://deploy-preview-19776--docsdocker.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[laurazard]

@milas @jsternberg does this LGTY? (the idea is to have a basic explanation of what is there right now, together with a minimal+easy to follow example)

[thaJeztah]

Wondering if it would work to mount the config over the default one that's provided; I noticed the image has some default options set, and this would mean that we're currently removing some of the other ones (do we know if that has an effect on what it does? At least it looks like this would mean changing the default storage location);

docker image inspect --format '{{json .Config.Cmd}}' prom/prometheus | jq .
[
  "--config.file=/etc/prometheus/prometheus.yml",
  "--storage.tsdb.path=/prometheus",
  "--web.console.libraries=/usr/share/prometheus/console_libraries",
  "--web.console.templates=/usr/share/prometheus/consoles"
]

[laurazard]

The idea was more to provide a smallest working example than to provide an exhaustive guide on prometheus, so I removed anything that wasn't essential. Maybe we could mount the new one on top of that so we don't need to specify --config.file, but I don't think we should worry about removing any configurations as long as they don't break the setup.

[thaJeztah]

Yeah, I was indeed looking if we could use more of the defaults (to simplify the compose-file even further). Definitely not critical, just was curious (and went looking; doesn't it have a default location to look for?)

[sam-thibault]

This wording seems strange to me. I want this to be described more like below (with time listed with the other attributes):

The Docker CLI currently collects telemetry on each command executed. Each record has the following attributes:

• command.name: the name of the command
• command.time: the execution duration of the command in milliseconds
• etc..

[dvdksn]

I see what you mean. I think we do need to separate the metric (IIUC: a floating point counter measurement) and its attributes (the key-value pairs associated with the primary data point, the time measurements). I will try to improve the wording

[laurazard]

This wording seems strange to me

this doesn't match the technical concepts though @sam-thibault.

OTel has a concept of metrics, and metrics have both names and attributes. Our naming is a little weird (also it's copied over from what is used in Buildx, etc. iirc) but in fact the metric is called command.time and, as attributes, contains command.name and the other ones mentioned.

Not sure how to get this across better, but it is important to explain that one is the metric name, since that's what users would have to use to look for the metrics in prometheus/anywhere else.

[laurazard]

LGTM

[milas]

LGTM! I had some pedantic comments about the OpenTelemetry "brand" name but the content is solid & comprehensive (😭 that a minimal OTel+Prom Compose project is still pretty complex, but not much we can do there)

[craig-osterhout]

LGTM