docs: document service ping configuration and data sent (#10167)

# Which Problems Are Solved

With the introduction of the service ping, we'll send data from all
systems back to a central endpoint for analytics and getting insights
about usage. To make it visible what data is sent and provide the users
an easy way to opt-out, we need a small documentation to tell them what
and how.

# How the Problems Are Solved

Document the service ping including what data is sent and how to opt-out
or configure most important settings.

# Additional Changes

None

# Additional Context

relates to #9869
This commit is contained in:
Livio Spring
2025-07-31 06:23:19 -04:00
committed by GitHub
parent b06e4e2f9c
commit 28d70db6ae
2 changed files with 84 additions and 0 deletions

View File

@@ -0,0 +1,83 @@
---
title: Service Ping
sidebar_label: Service Ping
---
Service Ping is a feature that periodically sends anonymized analytics and usage data from your ZITADEL system to a central endpoint.
This data helps improve ZITADEL by providing insights into its usage patterns.
The feature is enabled by default, but can be disabled either completely or for specific reports.
Checkout the configuration options below.
## Data Sent by Service Ping
### Base Information
If the feature is enabled, the base information will always be sent. To prevent that, you can opt out by disabling the entire Service Ping:
```yaml
ServicePing:
Enabled: false # ZITADEL_SERVICEPING_ENABLED
```
The base information sent back includes the following:
- your systemID
- the currently run version of ZITADEL
- information on all instances
- id
- creation date
- domains
### Resource Counts
Resource counts is a report that provides us with information about the number of resources in your ZITADEL instances.
The following resources are counted:
- Instances
- Organizations
- Projects per organization
- Users per organization
- Instance Administrators
- Identity Providers
- LDAP Identity Providers
- Actions (V1)
- Targets and set up executions
- Login Policies
- Password Complexity Policies
- Password Expiry Policies
- Lockout Policies
The list might be extended in the future to include more resources.
To disable this report, set the following in your configuration file:
```yaml
ServicePing:
Telemetry:
ResourceCounts:
Enabled: false # ZITADEL_SERVICEPING_TELEMETRY_RESOURCECOUNT_ENABLED
```
## Configuration
The Service Ping feature can be configured through the runtime configuration. Please check out the configuration file
for all available options. Below is a list of the most important options:
### Interval
This defines at which interval the Service Ping feature sends data to the central endpoint. It supports the extended cron syntax
and by default is set to `@daily`, which means it will send data every day. The time is randomized on startup to prevent
all systems from sending data at the same time.
You can adjust it to your needs to make sure there is no performance impact on your system.
For example, if you already have some scheduled job syncing data in and out of ZITADEL around a specific time or have regularly a
lot of traffic during the day, you might want to change it to a different time, e.g. `15 4 * * *` to send it every day at 4:15 AM.
The interval must be at least 30 minutes to prevent too frequent requests to the central endpoint.
### MaxAttempts
This defines how many attempts the Service Ping feature will make to send data to the central endpoint before giving up
for a specific interval and report. If one report fails, it will be retried up to this number of times.
Other reports will still be handled in parallel and have their own retry count. This means if the base information
only succeeded after three attempts, the resource count still has five attempts to be sent.

View File

@@ -1117,6 +1117,7 @@ module.exports = {
"self-hosting/manage/tls_modes",
"self-hosting/manage/database/database",
"self-hosting/manage/cache",
"self-hosting/manage/service_ping",
"self-hosting/manage/updating_scaling",
"self-hosting/manage/usage_control",
{