Better describe the metrics we capture (self-hosted)

configuration/powersync-service/self-hosted-instances.mdx

@@ -72,7 +72,7 @@ client_auth:
   audience: ['powersync-dev', 'powersync']
 
   # Settings for telemetry reporting
-  # See https://docs.powersync.com/self-hosting/telemetry
+  # See https://docs.powersync.com/maintenance-ops/self-hosting/usage-reporting
   telemetry:
     # Opt out of reporting anonymized usage metrics to PowerSync telemetry service
     disable_telemetry_sharing: false

docs.json

@@ -429,8 +429,8 @@
                   "maintenance-ops/self-hosting/update-sync-rules",
                   "maintenance-ops/self-hosting/healthchecks",
                   "maintenance-ops/self-hosting/securing-your-deployment",
-                  "maintenance-ops/self-hosting/metrics",
-                  "maintenance-ops/self-hosting/telemetry",
+                  "maintenance-ops/self-hosting/monitoring",
+                  "maintenance-ops/self-hosting/usage-reporting",
                   "maintenance-ops/self-hosting/diagnostics",
                   "maintenance-ops/self-hosting/multiple-instances",
                   "maintenance-ops/self-hosting/migrating-instances"
@@ -1218,19 +1218,27 @@
     },
     {
       "source": "/self-hosting/metrics",
-      "destination": "/maintenance-ops/self-hosting/metrics"
+      "destination": "/maintenance-ops/self-hosting/monitoring"
     },
     {
       "source": "/self-hosting/lifecycle-maintenance/metrics",
-      "destination": "/maintenance-ops/self-hosting/metrics"
+      "destination": "/maintenance-ops/self-hosting/monitoring"
+    },
+    {
+      "source": "/maintenance-ops/self-hosting/metrics",
+      "destination": "/maintenance-ops/self-hosting/monitoring"
     },
     {
       "source": "/self-hosting/telemetry",
-      "destination": "/maintenance-ops/self-hosting/telemetry"
+      "destination": "/maintenance-ops/self-hosting/usage-reporting"
     },
     {
       "source": "/self-hosting/lifecycle-maintenance/telemetry",
-      "destination": "/maintenance-ops/self-hosting/telemetry"
+      "destination": "/maintenance-ops/self-hosting/usage-reporting"
+    },
+    {
+      "source": "/maintenance-ops/self-hosting/telemetry",
+      "destination": "/maintenance-ops/self-hosting/usage-reporting"
     },
     {
       "source": "/self-hosting/diagnostics",

maintenance-ops/self-hosting/aws-ecs.mdx

@@ -23,7 +23,7 @@ Your configuration must include:
 - [Sync Streams](/sync/streams/overview) (or legacy [Sync Rules](/sync/rules/overview)): Define which data to sync to clients
 - [Client Auth](/configuration/auth/overview): Your authentication provider's JWKS
 - [Source Database](/configuration/source-db/setup): Connection details for your source database
-- [Telemetry](/maintenance-ops/self-hosting/telemetry): Enable the Prometheus metrics endpoint for connection-based auto-scaling (used in the [Auto Scaling](#auto-scaling-high-availability-setup) section):
+- [Monitoring](/maintenance-ops/self-hosting/monitoring): Enable the Prometheus metrics endpoint for connection-based auto-scaling (used in the [Auto Scaling](#auto-scaling-high-availability-setup) section):
   ```yaml
   telemetry:
     prometheus_port: 9090

maintenance-ops/self-hosting/aws-eks.mdx

@@ -39,7 +39,7 @@
 | `powersync_operation_storage_size_bytes` | Track operation storage growth. Capacity-plan from the slope. |
 | `powersync_data_sent_bytes_total` | Egress cost driver. |
 
-See [Metrics](/maintenance-ops/self-hosting/metrics) for the full metric catalog.
+See [Usage Reporting](/maintenance-ops/self-hosting/usage-reporting#whatiscollected) for the full metric catalog.
 
 Use the file-based probes (`MICRO_PROBE_TYPE=fs`) shipped in the chart unless your platform requires HTTP probes. The chart bundles a `NetworkPolicy` (disabled by default via `networkPolicy.enabled: false`) that allows Prometheus scrapes on port `9464`. Enable it in production.
 
@@ -63,7 +63,7 @@
 
 - Target roughly 100 connections per pod with a hard cap of 200. Past 200 connections you will see `PSYNC_S2304` errors.
 - The HPA template is bundled but disabled by default. Set `api.autoscaling.enabled: true` once you have the connections metric flowing.
 - Bridge the Prometheus metric to the HPA using `prometheus-adapter` (the rule is in the chart README) or KEDA's Prometheus scaler.
 - Keep the 70% CPU fallback. It catches load patterns the connection count alone misses, such as heavy queries or slow clients.
 - Default scale-up stabilization of 60s reacts to traffic spikes. The 300s scale-down prevents flapping. Lengthen scale-down further if you see thrashing.
 
@@ -90,4 +90,4 @@
 
 - Review the [chart repository](https://github.com/powersync-community/powersync-helm-chart) for `values.yaml`, install instructions, and version compatibility.
 - Read the [deployment architecture](/maintenance-ops/self-hosting/deployment-architecture) reference for the broader context behind these recommendations.
-- Configure [telemetry](/maintenance-ops/self-hosting/telemetry) so the HPA has a connections metric to scale on.
+- Configure [monitoring](/maintenance-ops/self-hosting/monitoring) so the HPA has a connections metric to scale on.

maintenance-ops/self-hosting/coolify.mdx

@@ -252,7 +252,7 @@ The following Compose file serves as a universal starting point for deploying th
             #   disable_auto_migration: true
 
             # Settings for telemetry reporting
-            # See https://docs.powersync.com/self-hosting/telemetry
+            # See https://docs.powersync.com/maintenance-ops/self-hosting/usage-reporting
             telemetry:
                 # Opt out of reporting anonymized usage metrics to PowerSync telemetry service
                 disable_telemetry_sharing: false

maintenance-ops/self-hosting/metrics.mdx → maintenance-ops/self-hosting/monitoring.mdx

@@ -1,6 +1,6 @@
 ---
-title: "Metrics"
-description: "Collect PowerSync Service metrics via Prometheus-compatible endpoints."
+title: "Monitoring"
+description: "Monitor a self-hosted PowerSync Service by scraping metrics from a Prometheus-compatible endpoint."
 ---
 
 ## Metrics Endpoint
@@ -29,6 +29,6 @@ ports:
   - 9090:9090
 ```
 
-Once enabled, restart the service and the metrics endpoint will return Prometheus-formatted metrics, as described in the [What is Collected](/maintenance-ops/self-hosting/telemetry#whatiscollected) section of the [Telemetry](/maintenance-ops/self-hosting/telemetry) docs.
+Once enabled, restart the service and the metrics endpoint will return Prometheus-formatted metrics, as described in the [What is Collected](/maintenance-ops/self-hosting/usage-reporting#whatiscollected) section of the [Usage Reporting](/maintenance-ops/self-hosting/usage-reporting) docs.
 
 <Note>If you're running multiple containers (e.g. splitting up replication containers and API containers) you need to scrape the metrics separately for each container.</Note>

maintenance-ops/self-hosting/overview.mdx

@@ -24,9 +24,9 @@ Details for production self-hosted PowerSync deployments, including architecture
 
   <Card title="Securing Your Deployment" icon="lock" href="/maintenance-ops/self-hosting/securing-your-deployment" horizontal />
 
-  <Card title="Metrics" icon="chart-line" href="/maintenance-ops/self-hosting/metrics" horizontal />
+  <Card title="Monitoring" icon="chart-line" href="/maintenance-ops/self-hosting/monitoring" horizontal />
 
-  <Card title="Telemetry" icon="signal" href="/maintenance-ops/self-hosting/telemetry" horizontal />
+  <Card title="Usage Reporting" icon="signal" href="/maintenance-ops/self-hosting/usage-reporting" horizontal />
 
   <Card title="Diagnostics" icon="bug" href="/maintenance-ops/self-hosting/diagnostics" horizontal />
 

maintenance-ops/self-hosting/telemetry.mdx → maintenance-ops/self-hosting/usage-reporting.mdx

@@ -1,13 +1,11 @@
 ---
-title: "Telemetry"
-description: "Integrate self-hosted PowerSync with OpenTelemetry for distributed observability."
+title: "Usage Reporting"
+description: "How self-hosted PowerSync collects anonymous usage metrics, and how to opt out."
 ---
 
 ## Overview
 
-PowerSync uses OpenTelemetry to gather metrics about usage and health.
-
-This telemetry is shared with the PowerSync team unless you opt-out. This allows us to gauge adoption and usage patterns across deployments so that we can better allocate R&D capacity and ultimately better serve our customers (including you!). The metrics are linked to a random UUID and are therefore completely anonymous.
+PowerSync uses OpenTelemetry to gather certain usage metrics. These metrics are shared with PowerSync unless you opt-out. This allows us to gauge adoption and usage patterns across deployments so that we can better allocate R&D capacity and ultimately better serve our customers (including you!). The metrics are linked to a random UUID and are therefore completely anonymous.
 
 ## What is Collected
 
@@ -28,11 +26,11 @@ Below are the data points collected every few minutes and associated with a rand
 | parameter\_storage\_size\_bytes   | gauge   |
 | concurrent\_connections           | gauge   |
 
-<Tip>To scrape your self-hosted PowerSync Service metrics, please see the [Metrics](/maintenance-ops/self-hosting/metrics) docs page for more details.</Tip>
+<Tip>To scrape your self-hosted PowerSync Service metrics, please see the [Monitoring](/maintenance-ops/self-hosting/monitoring) docs page for more details.</Tip>
 
 ### Opting Out
 
-To disable the sending of telemetry to PowerSync, set the `disable_telemetry_sharing` key in your [`service.yaml`](/configuration/powersync-service/self-hosted-instances) to `true`:
+To opt out of sharing metrics with PowerSync, set the `disable_telemetry_sharing` key in your [`service.yaml`](/configuration/powersync-service/self-hosted-instances) to `true`:
 
 ```yaml service.yaml
 telemetry: