rework configuration and docs

2025-12-05 09:02:04 +00:00 · 2023-06-16 14:37:27 +02:00
parent 5a39240cdd
commit 995420626c
9 changed files with 43 additions and 55 deletions
--- a/cmd/defaults.yaml
+++ b/cmd/defaults.yaml
@@ -14,43 +14,19 @@ Tracing:
  Fraction: 1.0
  MetricPrefix: zitadel

-Analytics:
-  # Push analytics data to defined endpoints
-  Push:
-    # Push the data to all these endpoints at least once.
-    # If one endpoint returns an unsuccessful response code or times out,
-    # ZITADEL retries to push the data point to all configured endpoints again until it succeeds.
-    # The endpoints can be reconfigured at runtime.
-    # Three redirects are followed.
-    # Configure delivery guarantees and intervals in the section Projections.Customizations.Analytics
-    Endpoints:
-      # Include https://zitadel.com/usage if you want to help the ZITADEL maintainers improve the product's usability by giving them some insights.
-      # Don't forget to opt in by setting AllEnabled to true.
-      - https://zitadel.com/usage
-    # If AllEnabled is true, all data listed below is pushed, regardless if they have the value true or false
-    AllEnabled: false
-    EnabledMetrics:
-      # InstanceCreated is sent when a new virtual instance is created.
-      # It is also emitted, when the first instance is created during the setup phase.
-      # If InstanceCreated is false and AllEnabled is false, then the data points about created instances are omitted.
-      InstanceCreated: false
-      # FirstInstanceAuthenticationSucceeded is sent when the first authentication to a virtual instance succeeds.
-      # This is the first authentication with the instances automatically setupped admin user, which can be a human or a machine.
-      # If FirstInstanceAuthenticationSucceeded is false and AllEnabled is false, then the data points about first instance logins are omitted.
-      FirstInstanceAuthenticationSucceeded: false
-      # FirstProjectCreated is sent when a first project after the automatically setupped ZITADEL project is created in a virtual instance.
-      # If FirstProjectCreated is false and AllEnabled is false, then the data points about first projects created are omitted.
-      FirstProjectCreated: false
-      # FirstApplicationCreated is sent when a first application after the automatically setupped applications in the ZITADEL project are created in a virtual instance.
-      # If FirstApplicationCreated is false and AllEnabled is false, then the data points about first applications created are omitted.
-      FirstApplicationCreated: false
-      # FirstApplicationAuthenticationSucceeded is sent when the first login to a self-created application succeeds.
-      # This can be a human users login or a machine user authentication.
-      # If FirstApplicationAuthenticationSucceeded is false and AllEnabled is false, then the data points about first application logins are omitted.
-      FirstApplicationAuthenticationSucceeded: false
-      # InstanceDeleted is sent when a virtual instance is deleted.
-      # If InstanceDeleted is false and AllEnabled is false, then the data points about deleted instances are omitted.
-      InstanceDeleted: false
+Telemetry:
+  # If Enabled is true, usage data is sent to the configured Telemetry.Endponts
+  Enabled: false
+  # Push telemetry data to all these endpoints at least once.
+  # If one endpoint returns an unsuccessful response code or times out,
+  # ZITADEL retries to push the data point to all configured endpoints again until it succeeds.
+  # Configure delivery guarantees and intervals in the section Projections.Customizations.Analytics
+  # The endpoints can be reconfigured at runtime.
+  # Three redirects are followed.
+  Endpoints:
+    # Include https://zitadel.com/usage if you want to help the ZITADEL maintainers improve the product's usability by giving them some insights.
+    # Don't forget to opt in by setting Telemetry.Enabled to true.
+    - https://zitadel.com/usage

 # Port ZITADEL will listen on
 Port: 8080
@@ -216,15 +192,15 @@ Projections:
      HandleActiveInstances: 1080h
      # As quota notification projections don't result in database statements, retries don't have any effects
      MaxFailureCount: 0
-      # Quota notifications are not so time critical. Setting RequeueEvery every five minutes doesn't annoy the db too much.
+      # Quota notifications are not so time critical. Setting RequeueEvery every five minutes doesn't annoy the database too much.
      RequeueEvery: 300s
-    Analytics:
-      # Analytics delivery guarantee requirements are a bit higher, as they are not interactively retryable
+    Telemetry:
+      # Telemetry delivery guarantee requirements are a bit higher, as they are not interactively retryable
      # Defaults to 15 days
      HandleActiveInstances: 360h
-      # As sending analytics data doesn't result in database statements, retries don't have any effects
+      # As sending telemetry data doesn't result in database statements, retries don't have any effects
      MaxFailureCount: 0
-      # Analytics data synchronization is not time critical. Setting RequeueEvery every 55 minutes doesn't annoy the db too much.
+      # Telemetry data synchronization is not time critical. Setting RequeueEvery every 55 minutes doesn't annoy the database too much.
      RequeueEvery: 3300s

 Auth:
--- a/docs/docs/self-hosting/deploy/docker-compose-sa.yaml
+++ b/docs/docs/self-hosting/deploy/docker-compose-sa.yaml
@@ -14,7 +14,7 @@ services:
      - 'ZITADEL_FIRSTINSTANCE_ORG_MACHINE_MACHINE_USERNAME=zitadel-admin-sa'
      - 'ZITADEL_FIRSTINSTANCE_ORG_MACHINE_MACHINE_NAME=Admin'
      - 'ZITADEL_FIRSTINSTANCE_ORG_MACHINE_MACHINEKEY_TYPE=1'
-      - 'ZITADEL_ANALYTICS_PUSH_ALLENABLED=true'
+      - 'ZITADEL_TELEMETRY_ENABLED=true'
    depends_on:
      crdb:
        condition: 'service_healthy'
--- a/docs/docs/self-hosting/deploy/docker-compose.yaml
+++ b/docs/docs/self-hosting/deploy/docker-compose.yaml
@@ -10,7 +10,7 @@ services:
    environment:
      - 'ZITADEL_DATABASE_COCKROACH_HOST=crdb'
      - 'ZITADEL_EXTERNALSECURE=false'
-      - 'ZITADEL_ANALYTICS_PUSH_ALLENABLED=true'
+      - 'ZITADEL_TELEMETRY_ENABLED=true'
    depends_on:
      crdb:
        condition: 'service_healthy'
--- a/docs/docs/self-hosting/deploy/knative.mdx
+++ b/docs/docs/self-hosting/deploy/knative.mdx
@@ -31,7 +31,7 @@ kn service create zitadel \
 --env ZITADEL_EXTERNALPORT=80 \
 --env ZITADEL_TLS_ENABLED=false \
 --env ZITADEL_EXTERNALDOMAIN=zitadel.default.127.0.0.1.sslip.io \
--env ZITADEL_ANALYTICS_PUSH_ALLENABLED=true \
+--env ZITADEL_TELEMETRY_ENABLED=true \
 --arg "start-from-init" --arg "--masterkey" --arg "MasterkeyNeedsToHave32Characters"
 ```

--- a/docs/docs/self-hosting/deploy/kubernetes.mdx
+++ b/docs/docs/self-hosting/deploy/kubernetes.mdx
@@ -37,8 +37,8 @@ helm install my-zitadel zitadel/zitadel \
  --set zitadel.masterkey="MasterkeyNeedsToHave32Characters" \
  --set zitadel.configmapConfig.ExternalSecure=false \
  --set zitadel.configmapConfig.TLS.Enabled=false \
+  --set zitadel.configmapConfig.Telemetry.Enabled=true \
  --set zitadel.secretConfig.Database.cockroach.User.Password="a-zitadel-db-user-password" \
-  --set zitadel.configmapConfig.Analytics.Push.AllEnabled=true \
  --set replicaCount=1

 # Make ZITADEL locally accessible
@@ -70,8 +70,8 @@ helm install --namespace zitadel --create-namespace my-zitadel zitadel/zitadel \
  --set zitadel.masterkey="MasterkeyNeedsToHave32Characters" \
  --set zitadel.configmapConfig.ExternalSecure=false \
  --set zitadel.configmapConfig.TLS.Enabled=false \
+  --set zitadel.configmapConfig.Telemetry.Enabled=true \
  --set zitadel.secretConfig.Database.cockroach.User.Password="a-zitadel-db-user-password" \
-  --set zitadel.configmapConfig.Analytics.Push.AllEnabled=true \
  --set replicaCount=1 \
  --set zitadel.configmapConfig.FirstInstance.MachineKeyPath="/machinekey/zitadel-admin-sa.json" \
  --set zitadel.configmapConfig.FirstInstance.Org.Machine.Machine.Username="zitadel-admin-sa" \
--- a/docs/docs/self-hosting/deploy/linux.mdx
+++ b/docs/docs/self-hosting/deploy/linux.mdx
@@ -44,7 +44,7 @@ ZITADEL_EXTERNALSECURE=false ZITADEL_ANALYTICS_PUSH_ALLENABLED=true zitadel star
 ### Setup ZITADEL with a service account

 ```bash
-ZITADEL_EXTERNALSECURE=false ZITADEL_ANALYTICS_PUSH_ALLENABLED=true ZITADEL_FIRSTINSTANCE_MACHINEKEYPATH=/tmp/zitadel-admin-sa.json ZITADEL_FIRSTINSTANCE_ORG_MACHINE_MACHINE_USERNAME=zitadel-admin-sa ZITADEL_FIRSTINSTANCE_ORG_MACHINE_MACHINE_NAME=Admin ZITADEL_FIRSTINSTANCE_ORG_MACHINE_MACHINEKEY_TYPE=1 zitadel start-from-init --masterkey "MasterkeyNeedsToHave32Characters" --tlsMode disabled
+ZITADEL_EXTERNALSECURE=false ZITADEL_TELEMETRY_ENABLED=true ZITADEL_FIRSTINSTANCE_MACHINEKEYPATH=/tmp/zitadel-admin-sa.json ZITADEL_FIRSTINSTANCE_ORG_MACHINE_MACHINE_USERNAME=zitadel-admin-sa ZITADEL_FIRSTINSTANCE_ORG_MACHINE_MACHINE_NAME=Admin ZITADEL_FIRSTINSTANCE_ORG_MACHINE_MACHINEKEY_TYPE=1 zitadel start-from-init --masterkey "MasterkeyNeedsToHave32Characters" --tlsMode disabled

 # then you can move your machine key
 mv /tmp/zitadel-admin-sa.json $HOME/zitadel-admin-sa.json
--- a/docs/docs/self-hosting/deploy/macos.mdx
+++ b/docs/docs/self-hosting/deploy/macos.mdx
@@ -51,7 +51,7 @@ ZITADEL_EXTERNALSECURE=false ZITADEL_ANALYTICS_PUSH_ALLENABLED=true zitadel star
 ### Setup ZITADEL with a service account

 ```bash
-ZITADEL_EXTERNALSECURE=false ZZITADEL_ANALYTICS_PUSH_ALLENABLED=true ITADEL_FIRSTINSTANCE_MACHINEKEYPATH=/tmp/zitadel-admin-sa.json ZITADEL_FIRSTINSTANCE_ORG_MACHINE_MACHINE_USERNAME=zitadel-admin-sa ZITADEL_FIRSTINSTANCE_ORG_MACHINE_MACHINE_NAME=Admin ZITADEL_FIRSTINSTANCE_ORG_MACHINE_MACHINEKEY_TYPE=1 zitadel start-from-init --masterkey "MasterkeyNeedsToHave32Characters" --tlsMode disabled
+ZITADEL_EXTERNALSECURE=false ZITADEL_TELEMETRY_ENABLED=true ZITADEL_FIRSTINSTANCE_MACHINEKEYPATH=/tmp/zitadel-admin-sa.json ZITADEL_FIRSTINSTANCE_ORG_MACHINE_MACHINE_USERNAME=zitadel-admin-sa ZITADEL_FIRSTINSTANCE_ORG_MACHINE_MACHINE_NAME=Admin ZITADEL_FIRSTINSTANCE_ORG_MACHINE_MACHINEKEY_TYPE=1 zitadel start-from-init --masterkey "MasterkeyNeedsToHave32Characters" --tlsMode disabled

 # then you can move your machine key
 mv /tmp/zitadel-admin-sa.json $HOME/zitadel-admin-sa.json
--- a/docs/docs/self-hosting/manage/production.md
+++ b/docs/docs/self-hosting/manage/production.md
@@ -61,15 +61,27 @@ Instead, your execution environment should provide tooling for managing logs in
 This includes tasks like rotating files, routing, collecting, archiving and cleaning-up.
 For example, systemd has journald and kubernetes has fluentd and fluentbit.

-## Analytics
+## Telemetry

-If you want some usage metrics pushed to external systems, enable the metrics you need in the ZITADEL configuration.
+If you want to have some usage data pushed to external systems, enable telemetry in the ZITADEL configuration.
 Include https://zitadel.com/usage in the list of endpoints if you want to help the ZITADEL maintainers improve the product's usability by giving them some insights.
-Don't forget to opt in by setting Analytics.Push.AllEnabled to true.
+Don't forget to opt in by setting Telemetry.Enabled to true.
+
+The following table describes the data points that are sent to the endpoints:
+
+| Trigger                                                                           | Description                                                                                                                                        |
+|-----------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------|
+| A virtual instance is created.                                                    | This data point is also sent when the first instance is automatically created during the ZITADEL binaries setup phase in a self-hosting scenario.  |
+| An authentication succeeded for the first time on an instance.                    | This is the first authentication with the instances automatically created admin user during the instance setup, which can be a human or a machine. |
+| A project is created for the first time in a virtual instance.                    | The ZITADEL project that is automatically created during the instance setup is omitted.                                                            |
+| An application is created for the first time in a virtual instance.               | The applications in the ZITADEL project that are automatically created during the instance setup are omitted.                                      |
+| An authentication succeeded for the first time in a virtal instances application. | This is the first authentication using a ZITADEL application that is not created during the instance setup phase.                                  |
+| A virtual instance is deleted.                                                    | This data point is sent when a virtual instance is deleted via ZITADELs system API                                                                 |
+

 ZITADEL pushes the metrics by projecting certain events.
-Therefore, you can configure delivery guarantees not in the Analytics section of the ZITADEL configuration,
-but in the Projections.Customizations.Analytics section
+Therefore, you can configure delivery guarantees not in the Telemetry section of the ZITADEL configuration,
+but in the Projections.Customizations.Telemetry section

 ## Database

--- a/docs/docs/self-hosting/manage/productionchecklist.md
+++ b/docs/docs/self-hosting/manage/productionchecklist.md
@@ -42,7 +42,7 @@ To apply best practices to your production setup we created a step by step check
 - [ ] Configure your privacy policy, terms of service and a help Link if needed
 - [ ] Keep your [masterkey](https://zitadel.com/docs/self-hosting/manage/configure) in a secure storage
 - [ ] Declare and apply zitadel configuration using the zitadel terraform [provider](https://github.com/zitadel/terraform-provider-zitadel) 
- [ ] Opt in to sending analytics to the ZITADEL maintainers by setting Analytics.Push.AllEnabled to true in the runtime configuration.
+- [ ] Opt in to sending telemetry data to the ZITADEL maintainers by setting Telemetry.Enabled to true in the runtime configuration.

 ### Security