From 685dfc83c1dfcdab4dadc95a2b07e655c6771880 Mon Sep 17 00:00:00 2001 From: Matthew Holt Date: Tue, 20 Sep 2022 13:27:27 -0600 Subject: [PATCH] docs: Update info about metrics for 2.6 Also add events.handlers namespace and fix dhall link. --- src/docs/markdown/caddyfile/directives/metrics.md | 2 +- src/docs/markdown/caddyfile/options.md | 6 ++++++ src/docs/markdown/config-adapters.md | 2 +- src/docs/markdown/extending-caddy/namespaces.md | 3 +++ src/docs/markdown/metrics.md | 14 ++++++++++++++ 5 files changed, 25 insertions(+), 2 deletions(-) diff --git a/src/docs/markdown/caddyfile/directives/metrics.md b/src/docs/markdown/caddyfile/directives/metrics.md index 938b31d..04df6f0 100644 --- a/src/docs/markdown/caddyfile/directives/metrics.md +++ b/src/docs/markdown/caddyfile/directives/metrics.md @@ -5,7 +5,7 @@ title: metrics (Caddyfile directive) # metrics Configures a Prometheus metrics exposition endpoint so the gathered metrics can -be exposed for scraping. +be exposed for scraping. **Metrics must be [turned on in your global options](/docs/caddyfile/options#metrics) first.** 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. diff --git a/src/docs/markdown/caddyfile/options.md b/src/docs/markdown/caddyfile/options.md index a6828c2..c790d9f 100644 --- a/src/docs/markdown/caddyfile/options.md +++ b/src/docs/markdown/caddyfile/options.md @@ -105,6 +105,7 @@ Possible options are: write idle } + metrics max_header_size log_credentials protocols [h1|h2|h2c|h3] @@ -381,6 +382,11 @@ listener_wrappers { - **idle** is a [duration value](/docs/conventions#durations) that sets the maximum time to wait for the next request when keep-alives are enabled. Defaults to 5 minutes to help avoid resource exhaustion. +##### `metrics` + +Enables Prometheus metrics collection; necessary before scraping metrics. Note that metrics reduce performance on really busy servers. (Our community is working on improving this. Please get involved!) + + ##### `max_header_size` The maximum size to parse from a client's HTTP request headers. It accepts all formats supported by [go-humanize](https://github.com/dustin/go-humanize/blob/master/bytes.go). diff --git a/src/docs/markdown/config-adapters.md b/src/docs/markdown/config-adapters.md index 7624d24..386765b 100644 --- a/src/docs/markdown/config-adapters.md +++ b/src/docs/markdown/config-adapters.md @@ -20,7 +20,7 @@ The following config adapters are currently available (some are third-party proj - [**cue**](https://github.com/caddyserver/cue-adapter) - [**toml**](https://github.com/awoodbeck/caddy-toml-adapter) - [**hcl**](https://github.com/francislavoie/caddy-hcl) -- [**dhall**](https://github.com/mholt/caddy-dhall) +- [**dhall**](https://github.com/mholt/dhall-adapter) ## Using config adapters diff --git a/src/docs/markdown/extending-caddy/namespaces.md b/src/docs/markdown/extending-caddy/namespaces.md index 2cc51c6..069725d 100644 --- a/src/docs/markdown/extending-caddy/namespaces.md +++ b/src/docs/markdown/extending-caddy/namespaces.md @@ -19,6 +19,7 @@ caddy.fs | [`fs.FS`](https://pkg.go.dev/io/fs#FS) | Virtual file system | caddy.logging.encoders.filter | [`logging.LogFieldFilter`](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/logging?tab=doc#LogFieldFilter) | Log field filter caddy.logging.writers | [`caddy.WriterOpener`](https://pkg.go.dev/github.com/caddyserver/caddy/v2?tab=doc#WriterOpener) | Log writers caddy.storage | [`caddy.StorageConverter`](https://pkg.go.dev/github.com/caddyserver/caddy/v2?tab=doc#StorageConverter) | Storage backends +events.handlers | [`caddyevents.Handler`](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyevents#Handler) | Event handlers | ⚠️ Experimental http.authentication.hashes | [`caddyauth.Comparer`](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/caddyauth?tab=doc#Comparer) | Password hashers/comparers http.authentication.providers | [`caddyauth.Authenticator`](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp/caddyauth?tab=doc#Authenticator) | HTTP authentication providers http.handlers | [`caddyhttp.MiddlewareHandler`](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddyhttp?tab=doc#MiddlewareHandler) | HTTP handlers @@ -32,3 +33,5 @@ tls.handshake_match | [`caddytls.ConnectionMatcher`](https://pkg.go.dev/github.c tls.issuance | [`certmagic.Issuer`](https://pkg.go.dev/github.com/caddyserver/certmagic?tab=doc#Issuer) | TLS certificate issuer
tls.get_certificate | [`certmagic.CertificateManager`](https://pkg.go.dev/github.com/caddyserver/certmagic?tab=doc#CertificateManager) | TLS certificate manager | ⚠️ Experimental tls.stek | [`caddytls.STEKProvider`](https://pkg.go.dev/github.com/caddyserver/caddy/v2/modules/caddytls?tab=doc#STEKProvider) | TLS session ticket key source + +Namespaces marked as "Experimental" are subject to change. (Please develop with them so we can finalize their interfaces!) diff --git a/src/docs/markdown/metrics.md b/src/docs/markdown/metrics.md index f8f0b74..75fb442 100644 --- a/src/docs/markdown/metrics.md +++ b/src/docs/markdown/metrics.md @@ -9,6 +9,20 @@ Caddy server on an embedded device, it's likely that at some point you'll want to have a high-level overview of what Caddy is doing, and how long it's taking. In other words, you're going to want to be able to _monitor_ Caddy. +## Enabling metrics + +You'll need to turn metrics on. If using a Caddyfile, enable metrics [in global options](/docs/caddyfile/options#metrics): + +```caddy +{ + servers { + metrics + } +} +``` + +If using JSON, enable metrics in your [server configuration](/docs/json/apps/http/servers/) by adding `"metrics": {}`. + ## Prometheus [Prometheus](https://prometheus.io) is a monitoring platform that collects