From c334df8f432e22c5d462b98faee2b7e32d59bed6 Mon Sep 17 00:00:00 2001
From: Daenney <daenney@users.noreply.github.com>
Date: Sun, 26 Nov 2023 15:53:53 +0100
Subject: [PATCH] [docs] Explain how to secure metrics endpoints (#2382)

---
 docs/advanced/metrics.md            | 52 ++++++++++++++++++++---------
 docs/configuration/observability.md |  4 +++
 2 files changed, 40 insertions(+), 16 deletions(-)

diff --git a/docs/advanced/metrics.md b/docs/advanced/metrics.md
index 6c1cddd61..13eb84e46 100644
--- a/docs/advanced/metrics.md
+++ b/docs/advanced/metrics.md
@@ -1,37 +1,57 @@
 # Metrics
 
-GoToSocial comes with [OpenTelemetry][otel] based metrics built-in with pull-style Prometheus exporter. Currently the following metrics are collected:
+GoToSocial comes with [OpenTelemetry][otel] based metrics. The metrics are exposed using the [Prometheus exposition format][prom] on the `/metrics` path. The configuration settings are documented in the [Observability configuration reference][obs].
+
+Currently the following metrics are collected:
 
 * Go performance and runtime metrics
 * Gin (HTTP) metrics
 * Bun (database) metrics
 
-How to configure metrics is explained in the [Observability configuration reference][obs].
-
-For a quickstart, add the following to your GoToSocial configuration and restart your instance:
+Metrics can be enable with the following configuration:
 
 ```yaml
 metrics-enabled: true
+```
+
+Though metrics do not contain anything privacy sensitive, you may not want to allow just anyone to view and scrape operational metrics of your instance.
+
+## Enabling basic authentication
+
+You can enable basic authentication for the metrics endpoint. On the GoToSocial, side you'll need the following configuration:
+
+```yaml
 metrics-auth-enabled: true
 metrics-auth-username: some_username
 metrics-auth-password: some_password
 ```
 
-This will expose the metrics under the endpoint `/metrics`, protected with HTTP Basic Authentication.
-
-A following is an example how to configure a job for collecting the metrics in Prometheus `scrape_configs`:
+You can scrape that endpoint with a Prometheus instance using the following configuration in your `scrape_configs`:
 
 ```yaml
-  - job_name: gotosocial
-    metrics_path: /metrics
-    scheme: https
-    basic_auth:
-        username: some_username
-        password: some_password
-    static_configs:
-    - targets:
-      - example.org
+- job_name: gotosocial
+  metrics_path: /metrics
+  scheme: https
+  basic_auth:
+    username: some_username
+    password: some_password
+  static_configs:
+  - targets:
+    - example.org
+```
+
+## Blocking external scraping
+
+When running with a reverse proxy you can use it to block external access to metrics. You can use this approach if your Prometheus scraper runs on the same machine as your GoToSocial instance and can thus access it internally.
+
+For example with nginx, block the `/metrics` endpoint by returning a 404:
+
+```nginx
+location /metrics {
+    return 404;
+}
 ```
 
 [otel]: https://opentelemetry.io/
+[prom]: https://prometheus.io/docs/instrumenting/exposition_formats/
 [obs]: ../configuration/observability.md
\ No newline at end of file
diff --git a/docs/configuration/observability.md b/docs/configuration/observability.md
index 0d85ccb3f..0fcf4710e 100644
--- a/docs/configuration/observability.md
+++ b/docs/configuration/observability.md
@@ -2,6 +2,10 @@
 
 These settings let you tune and configure certain observability related behaviours.
 
+## Metrics
+
+Before enabling metrics, [read the guide](../advanced/metrics.md) and ensure you've taken the appropriate security measures for your setup.
+
 ## Settings
 
 ```yaml