3 files changed, 55 insertions, 1 deletions
diff --git a/docs/advanced/index.md b/docs/advanced/index.md
index 351190227..81773801f 100644
--- a/docs/advanced/index.md
+++ b/docs/advanced/index.md
@@ -14,3 +14,4 @@ We consider these topics advanced because applying them incorrectly does have th
 * [Process sandboxing](security/sandboxing.md)
 * [Firewall configuration](security/firewall.md)
 * [Tracing](tracing.md)
+* [Metrics](metrics.md)
diff --git a/docs/advanced/metrics.md b/docs/advanced/metrics.md
new file mode 100644
index 000000000..6c1cddd61
--- /dev/null
+++ b/docs/advanced/metrics.md
@@ -0,0 +1,37 @@
+# Metrics
+
+GoToSocial comes with [OpenTelemetry][otel] based metrics built-in with pull-style Prometheus exporter. 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:
+
+```yaml
+metrics-enabled: true
+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`:
+
+```yaml
+  - job_name: gotosocial
+    metrics_path: /metrics
+    scheme: https
+    basic_auth:
+        username: some_username
+        password: some_password
+    static_configs:
+    - targets:
+      - example.org
+```
+
+[otel]: https://opentelemetry.io/
+[obs]: ../configuration/observability.md
+\ No newline at end of file
diff --git a/docs/configuration/observability.md b/docs/configuration/observability.md
index c29074d1a..0d85ccb3f 100644
--- a/docs/configuration/observability.md
+++ b/docs/configuration/observability.md
@@ -34,4 +34,20 @@ tracing-endpoint: ""
 # Bool. Disable TLS for the gRPC and HTTP transport protocols.
 # Default: false
 tracing-insecure-transport: false
-```
+
+# Bool. Enable OpenTelemetry based metrics support.
+# Default: false
+metrics-enabled: false
+
+# Bool. Enable HTTP Basic Authentication for Prometheus metrics endpoint.
+# Default: false
+metrics-auth-enabled: false
+
+# String. Username for Prometheus metrics endpoint.
+# Default: ""
+metrics-auth-username: ""
+
+# String. Password for Prometheus metrics endpoint.
+# Default: ""
+metrics-auth-password: ""
+```
+\ No newline at end of file