From aa8e64afe36893abef75273cdd15b230e0591578 Mon Sep 17 00:00:00 2001 From: Benita Volkmann Date: Thu, 4 Jun 2026 17:45:39 +0200 Subject: [PATCH 1/3] Better describe the metrics we capture --- maintenance-ops/self-hosting/telemetry.mdx | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/maintenance-ops/self-hosting/telemetry.mdx b/maintenance-ops/self-hosting/telemetry.mdx index cbebaa07..f7b73345 100644 --- a/maintenance-ops/self-hosting/telemetry.mdx +++ b/maintenance-ops/self-hosting/telemetry.mdx @@ -1,13 +1,11 @@ --- title: "Telemetry" -description: "Integrate self-hosted PowerSync with OpenTelemetry for distributed observability." +description: "How self-hosted PowerSync collects anonymous usage metrics, and how to opt out of sharing them." --- ## 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 @@ -32,7 +30,7 @@ Below are the data points collected every few minutes and associated with a rand ### 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: From 798565486058a7d1c8736a94a38ff3fa25da44a3 Mon Sep 17 00:00:00 2001 From: Benita Volkmann Date: Thu, 4 Jun 2026 17:55:31 +0200 Subject: [PATCH 2/3] Rename both pages --- .../self-hosted-instances.mdx | 2 +- docs.json | 20 +++++++++++++------ maintenance-ops/self-hosting/aws-ecs.mdx | 2 +- maintenance-ops/self-hosting/aws-eks.mdx | 4 ++-- maintenance-ops/self-hosting/coolify.mdx | 2 +- .../{metrics.mdx => monitoring.mdx} | 6 +++--- maintenance-ops/self-hosting/overview.mdx | 4 ++-- .../{telemetry.mdx => usage-reporting.mdx} | 4 ++-- 8 files changed, 26 insertions(+), 18 deletions(-) rename maintenance-ops/self-hosting/{metrics.mdx => monitoring.mdx} (80%) rename maintenance-ops/self-hosting/{telemetry.mdx => usage-reporting.mdx} (93%) diff --git a/configuration/powersync-service/self-hosted-instances.mdx b/configuration/powersync-service/self-hosted-instances.mdx index babb0395..5025a2fc 100644 --- a/configuration/powersync-service/self-hosted-instances.mdx +++ b/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 diff --git a/docs.json b/docs.json index c81b5787..6af31239 100644 --- a/docs.json +++ b/docs.json @@ -445,8 +445,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" @@ -1236,19 +1236,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", diff --git a/maintenance-ops/self-hosting/aws-ecs.mdx b/maintenance-ops/self-hosting/aws-ecs.mdx index 9fc6f778..6632a7b3 100644 --- a/maintenance-ops/self-hosting/aws-ecs.mdx +++ b/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 diff --git a/maintenance-ops/self-hosting/aws-eks.mdx b/maintenance-ops/self-hosting/aws-eks.mdx index 2e2ab624..1a3457ec 100644 --- a/maintenance-ops/self-hosting/aws-eks.mdx +++ b/maintenance-ops/self-hosting/aws-eks.mdx @@ -39,7 +39,7 @@ Wire monitoring up before you take traffic. Scrape Prometheus metrics from port | `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. @@ -90,4 +90,4 @@ Open these flows before deploying: - 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. diff --git a/maintenance-ops/self-hosting/coolify.mdx b/maintenance-ops/self-hosting/coolify.mdx index 1df2fc4e..3d9609c4 100644 --- a/maintenance-ops/self-hosting/coolify.mdx +++ b/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 diff --git a/maintenance-ops/self-hosting/metrics.mdx b/maintenance-ops/self-hosting/monitoring.mdx similarity index 80% rename from maintenance-ops/self-hosting/metrics.mdx rename to maintenance-ops/self-hosting/monitoring.mdx index 8053a05f..0147398a 100644 --- a/maintenance-ops/self-hosting/metrics.mdx +++ b/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. 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. diff --git a/maintenance-ops/self-hosting/overview.mdx b/maintenance-ops/self-hosting/overview.mdx index afc266ce..44b1ab81 100644 --- a/maintenance-ops/self-hosting/overview.mdx +++ b/maintenance-ops/self-hosting/overview.mdx @@ -24,9 +24,9 @@ Details for production self-hosted PowerSync deployments, including architecture - + - + diff --git a/maintenance-ops/self-hosting/telemetry.mdx b/maintenance-ops/self-hosting/usage-reporting.mdx similarity index 93% rename from maintenance-ops/self-hosting/telemetry.mdx rename to maintenance-ops/self-hosting/usage-reporting.mdx index f7b73345..a0579427 100644 --- a/maintenance-ops/self-hosting/telemetry.mdx +++ b/maintenance-ops/self-hosting/usage-reporting.mdx @@ -1,5 +1,5 @@ --- -title: "Telemetry" +title: "Usage Reporting" description: "How self-hosted PowerSync collects anonymous usage metrics, and how to opt out of sharing them." --- @@ -26,7 +26,7 @@ Below are the data points collected every few minutes and associated with a rand | parameter\_storage\_size\_bytes | gauge | | concurrent\_connections | gauge | -To scrape your self-hosted PowerSync Service metrics, please see the [Metrics](/maintenance-ops/self-hosting/metrics) docs page for more details. +To scrape your self-hosted PowerSync Service metrics, please see the [Monitoring](/maintenance-ops/self-hosting/monitoring) docs page for more details. ### Opting Out From 9b26deae3bd28b61c5e7fc11ff4687979d08b250 Mon Sep 17 00:00:00 2001 From: Benita Volkmann Date: Mon, 8 Jun 2026 11:21:06 +0200 Subject: [PATCH 3/3] Wording --- maintenance-ops/self-hosting/usage-reporting.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/maintenance-ops/self-hosting/usage-reporting.mdx b/maintenance-ops/self-hosting/usage-reporting.mdx index a0579427..bd7631e1 100644 --- a/maintenance-ops/self-hosting/usage-reporting.mdx +++ b/maintenance-ops/self-hosting/usage-reporting.mdx @@ -1,6 +1,6 @@ --- title: "Usage Reporting" -description: "How self-hosted PowerSync collects anonymous usage metrics, and how to opt out of sharing them." +description: "How self-hosted PowerSync collects anonymous usage metrics, and how to opt out." --- ## Overview