Topics

2. The Metrics

Site owners: Telemetry data makes it possible for operators to have a white-box understanding of their web servers. Traditional monitoring tools usually require tedious analysis when anomalies occur because they have only an external perspective of the process. Caddy telemetry, on the other hand, operates from within the process and can give detailed insights when you need answers. And when everything is nominal, it’s also just really interesting to see how and what your web server is doing. Telemetry is useful beyond access logging because it gives unique data points over time about the effects your clients have on your servers.

Researchers: While client-side scans of the Internet are not uncommon, for the first time you now have access to a global, server-side perspective from which to observe the behavior and health of the Internet. Caddy telemetry is uniquely positioned to offer anonymized aggregate data about clients on the Internet in conjunction together with an internal view of the web servers which answer them. Our long-term hope is that with your participation and feedback, we can build methods to detect emerging botnets, DDoS attacks, and other threats in real-time and work to automatically mitigate them.

Industry experts: Information provided by Caddy telemetry can certainly be useful when making decisions about new Web standards, building out or monitoring network infrastructure, and developing Internet software.

Telemetry is implemented in a way that makes it unobtrusive and non-blocking to your process. Your Caddy instance should not suffer any noticable performance degredation. It has several safety measures built-in to ensure optimal performance, even at the expense of the data, including a limit to the number of data points that can be buffered. The collection endpoint may notice if certain metrics are too expensive and temporarily disable them on a per-instance basis to improve performance. The collection endpoint may also entirely terminate telemetry reporting from any instance. In addition, collection updates are tightly rate-limited, ensuring that telemetry never interferes with network throughput.

Each Caddy instance generates its own unique, random ID called a UUID. It is stored in a file called (the default CADDYPATH is ). This UUID is NOT generated in connection with the collection endpoint in any way, and does NOT associate with any individual person. We recommend that each Caddy instance you run have its own CADDYPATH so that your reports are more discernable when you go to look up your instance.

As you would expect, all transmissions are encrypted with HTTPS.

Telemetry is enabled by default in the source code and disabled by default on our download page. In order to better know how representative the aggregate data is, telemetry may be toggled at compile-time or customized at run-time.

Note that telemetry does NOT target personal information. Telemetry is programmed to report only technical data about machines, connections, and Caddy instances; NOT end users, session IDs, cookies, etc. If you are considering turning off telemetry because of applicable laws, make sure the laws actually apply to you.

The recommended way to disable telemetry is to turn off only the metrics that you do not want to report. You can do this with the . (The disabled_metrics, timestamp, and instance_id metrics cannot be disabled individually.) This will prevent Caddy from collecting the specified information throughout the lifetime of the process, and is useful if, for example, you discover that a particular metric is causing your telemetry buffer to fill up too quickly under heavy load (there is a limit to how many items can be buffered for emission).