coder · mtojek · Nov 30, 2022 · Nov 28, 2022 · Nov 28, 2022 · Nov 28, 2022
diff --git a/docs/admin/prometheus.md b/docs/admin/prometheus.md
@@ -0,0 +1,39 @@
+# Prometheus
+
+Coder exposes many metrics which can be consumed by a Prometheus server, and give insight into the current state of a live Coder deployment.
+
+If you don't have an Prometheus server installed, you can follow the Prometheus [Getting started](https://prometheus.io/docs/prometheus/latest/getting_started/) guide.
+
+## Enable Prometheus metrics
+
+Coder server exports metrics via the HTTP endpoint, which can be enabled using either the environment variable `CODER_PROMETHEUS_ENABLE` or the flag `--prometheus-enable`.
+
+The Prometheus endpoint address is `http://localhost:2112/` by default. You can use either the environment variable `CODER_PROMETHEUS_ADDRESS` or the flag ` --prometheus-address <network-interface>:<port>` to select a different listen address.
+
+If `coder server --prometheus-enable` is started locally, you can preview the metrics endpoint in your browser or by using curl: <!-- markdown-link-check-disable -->http://localhost:2112/<!-- markdown-link-check-enable -->.
+
+```
+$ curl http://localhost:2112/
+# HELP coderd_api_active_users_duration_hour The number of users that have been active within the last hour.
+# TYPE coderd_api_active_users_duration_hour gauge
+coderd_api_active_users_duration_hour 0
+...
+```
+
+## Available collectors
+
+### Coderd
+
+[Coderd](../about/architecture.md#coderd) is the service responsible for managing workspaces, provisioners, and users. Coder resources are controlled using the authorized HTTP API - Coderd API.
+
+The Prometheus collector tracks and exposes activity statistics for [platform users](https://github.com/coder/coder/blob/main/coderd/prometheusmetrics/prometheusmetrics.go#L15-L54) and [workspace](https://github.com/coder/coder/blob/main/coderd/prometheusmetrics/prometheusmetrics.go#L57-L108).
+
+It also exposes [operational metrics](https://github.com/coder/coder/blob/main/coderd/httpmw/prometheus.go#L21-L61) for HTTP requests and WebSocket connections, including a total number of calls, HTTP status, active WebSockets, request duration, etc.
+
+### Provisionerd
+
+[Provisionerd](../about/architecture.md#provisionerd) is the execution context for infrastructure providers. The runner exposes [statistics for executed jobs](https://github.com/coder/coder/blob/main/provisionerd/provisionerd.go#L133-L154) - a number of jobs currently running, and execution timings.
+
+### Go runtime, process stats
+
+[Common collectors](https://github.com/coder/coder/blob/main/cli/server.go#L555-L556) monitor the Go runtime - memory usage, garbage collection, active threads, goroutines, etc. Additionally, on Linux and on Windows, they collect CPU stats, memory, file descriptors, and process uptime.
diff --git a/docs/images/icons/speed.svg b/docs/images/icons/speed.svg
diff --git a/docs/manifest.json b/docs/manifest.json
@@ -274,6 +274,12 @@
           "path": "./admin/high-availability.md",
           "state": "enterprise"
         },
+        {
+          "title": "Prometheus",
+          "description": "Learn how to collect Prometheus metrics",
+          "icon_path": "./images/icons/speed.svg",
+          "path": "./admin/prometheus.md"
+        },
         {
           "title": "Telemetry",
           "description": "Learn what usage telemetry Coder collects",