docs: Monitoring and metrics (#86)

* metrics: Adding docs for metrics

Signed-off-by: Dave Henderson <dhenderson@gmail.com>

* Addressing review comments

Signed-off-by: Dave Henderson <dhenderson@gmail.com>

* Apply suggestions from code review

Co-authored-by: Matt Holt <mholt@users.noreply.github.com>

* Update src/docs/markdown/metrics.md

Co-authored-by: Dave Henderson <dhenderson@gmail.com>

Co-authored-by: Matt Holt <mholt@users.noreply.github.com>

src/docs/markdown/caddyfile/directives.md

@@ -19,6 +19,7 @@ Directive | Description
 **[header](/docs/caddyfile/directives/header)** | Sets or removes response headers
 **[import](/docs/caddyfile/directives/import)** | Include snippets or files
 **[log](/docs/caddyfile/directives/log)** | Enables access/request logging
+**[metrics](/docs/caddyfile/directives/metrics)** | Configures the Prometheus metrics exposition endpoint
 **[php_fastcgi](/docs/caddyfile/directives/php_fastcgi)** | Serve PHP sites over FastCGI
 **[redir](/docs/caddyfile/directives/redir)** | Issues an HTTP redirect to the client
 **[request_header](/docs/caddyfile/directives/request_header)** | Manipulates request headers
@@ -90,10 +91,11 @@ handle_path
 route
 
 respond
+metrics
 reverse_proxy
 php_fastcgi
 file_server
 acme_server
 ```
 
-You can override/customize this ordering by using the [`order` global option](/docs/caddyfile/options) or the [`route` directive](/docs/caddyfile/directives/route).
+You can override/customize this ordering by using the [`order` global option](/docs/caddyfile/options) or the [`route` directive](/docs/caddyfile/directives/route).

src/docs/markdown/caddyfile/directives/metrics.md

@@ -0,0 +1,45 @@
+---
+title: metrics (Caddyfile directive)
+---
+
+# metrics
+
+Configures a Prometheus metrics exposition endpoint so the gathered metrics can
+be exposed for scraping.
+
+Note that a `/metrics` endpoint is also attached to the [admin API](/docs/api),
+which is not configurable, and is not available when the admin API is disabled.
+
+This endpoint will return metrics in the [Prometheus exposition format](https://prometheus.io/docs/instrumenting/exposition_formats/#text-based-format)
+or, if negotiated, in the [OpenMetrics exposition format](https://pkg.go.dev/github.com/prometheus/client_golang@v1.7.1/prometheus/promhttp#HandlerOpts)
+(`application/openmetrics-text`).
+
+See also [Monitoring Caddy with Prometheus metrics](/docs/metrics).
+
+## Syntax
+
+```caddy-d
+metrics [<matcher>]
+```
+
+## Examples
+
+Expose metrics at the default `/metrics` path:
+
+```caddy-d
+metrics /metrics
+```
+
+Expose metrics at another path:
+
+```caddy-d
+metrics /foo/bar/baz
+```
+
+Serve metrics at a separate subdomain:
+
+```caddy
+metrics.example.com {
+	metrics
+}
+```