From 5a39240cddc1b0ea4318f344f302b42fa5067bff Mon Sep 17 00:00:00 2001 From: Elio Bischof Date: Wed, 14 Jun 2023 08:49:50 +0200 Subject: [PATCH] document analytics config --- cmd/defaults.yaml | 50 ++++++++++++++++++- .../deploy/docker-compose-sa.yaml | 1 + .../self-hosting/deploy/docker-compose.yaml | 1 + docs/docs/self-hosting/deploy/knative.mdx | 3 +- docs/docs/self-hosting/deploy/kubernetes.mdx | 2 + docs/docs/self-hosting/deploy/linux.mdx | 4 +- .../example-zitadel-config.yaml | 5 ++ docs/docs/self-hosting/deploy/macos.mdx | 4 +- docs/docs/self-hosting/manage/production.md | 10 ++++ .../manage/productionchecklist.md | 1 + 10 files changed, 74 insertions(+), 7 deletions(-) diff --git a/cmd/defaults.yaml b/cmd/defaults.yaml index 4cc990b34b..212c0badeb 100644 --- a/cmd/defaults.yaml +++ b/cmd/defaults.yaml @@ -14,6 +14,44 @@ 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 + # Port ZITADEL will listen on Port: 8080 # Port ZITADEL is exposed on, it can differ from port e.g. if you proxy the traffic @@ -169,17 +207,25 @@ Projections: BulkLimit: 2000 # The Notifications projection is used for sending emails and SMS to users Notifications: - # As notification projections don't result in database statements, retries don't have an effect + # As notification projections don't result in database statements, retries don't have any effects MaxFailureCount: 0 # The NotificationsQuotas projection is used for calling quota webhooks NotificationsQuotas: # Delivery guarantee requirements are probably higher for quota webhooks # Defaults to 45 days HandleActiveInstances: 1080h - # As quota notification projections don't result in database statements, retries don't have an effect + # 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. RequeueEvery: 300s + Analytics: + # Analytics 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 + MaxFailureCount: 0 + # Analytics data synchronization is not time critical. Setting RequeueEvery every 55 minutes doesn't annoy the db too much. + RequeueEvery: 3300s Auth: SearchLimit: 1000 diff --git a/docs/docs/self-hosting/deploy/docker-compose-sa.yaml b/docs/docs/self-hosting/deploy/docker-compose-sa.yaml index 38f9b25122..df88ea4633 100644 --- a/docs/docs/self-hosting/deploy/docker-compose-sa.yaml +++ b/docs/docs/self-hosting/deploy/docker-compose-sa.yaml @@ -14,6 +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' depends_on: crdb: condition: 'service_healthy' diff --git a/docs/docs/self-hosting/deploy/docker-compose.yaml b/docs/docs/self-hosting/deploy/docker-compose.yaml index b7c11d8dce..67a0df2232 100644 --- a/docs/docs/self-hosting/deploy/docker-compose.yaml +++ b/docs/docs/self-hosting/deploy/docker-compose.yaml @@ -10,6 +10,7 @@ services: environment: - 'ZITADEL_DATABASE_COCKROACH_HOST=crdb' - 'ZITADEL_EXTERNALSECURE=false' + - 'ZITADEL_ANALYTICS_PUSH_ALLENABLED=true' depends_on: crdb: condition: 'service_healthy' diff --git a/docs/docs/self-hosting/deploy/knative.mdx b/docs/docs/self-hosting/deploy/knative.mdx index 54f22ab173..65cd2fe328 100644 --- a/docs/docs/self-hosting/deploy/knative.mdx +++ b/docs/docs/self-hosting/deploy/knative.mdx @@ -31,7 +31,8 @@ kn service create zitadel \ --env ZITADEL_EXTERNALPORT=80 \ --env ZITADEL_TLS_ENABLED=false \ --env ZITADEL_EXTERNALDOMAIN=zitadel.default.127.0.0.1.sslip.io \ ---arg "start-from-init" --arg "--masterkey" --arg "MasterkeyNeedsToHave32Characters" +--env ZITADEL_ANALYTICS_PUSH_ALLENABLED=true \ +--arg "start-from-init" --arg "--masterkey" --arg "MasterkeyNeedsToHave32Characters" ``` ### Knavite yaml diff --git a/docs/docs/self-hosting/deploy/kubernetes.mdx b/docs/docs/self-hosting/deploy/kubernetes.mdx index fa214d5774..d78e813e51 100644 --- a/docs/docs/self-hosting/deploy/kubernetes.mdx +++ b/docs/docs/self-hosting/deploy/kubernetes.mdx @@ -38,6 +38,7 @@ helm install my-zitadel zitadel/zitadel \ --set zitadel.configmapConfig.ExternalSecure=false \ --set zitadel.configmapConfig.TLS.Enabled=false \ --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,6 +71,7 @@ helm install --namespace zitadel --create-namespace my-zitadel zitadel/zitadel \ --set zitadel.configmapConfig.ExternalSecure=false \ --set zitadel.configmapConfig.TLS.Enabled=false \ --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" \ diff --git a/docs/docs/self-hosting/deploy/linux.mdx b/docs/docs/self-hosting/deploy/linux.mdx index c1b9597939..bc2d015f51 100644 --- a/docs/docs/self-hosting/deploy/linux.mdx +++ b/docs/docs/self-hosting/deploy/linux.mdx @@ -33,7 +33,7 @@ LATEST=$(curl -i https://github.com/zitadel/zitadel/releases/latest | grep locat ## Run ZITADEL ```bash -ZITADEL_EXTERNALSECURE=false zitadel start-from-init --masterkey "MasterkeyNeedsToHave32Characters" --tlsMode disabled +ZITADEL_EXTERNALSECURE=false ZITADEL_ANALYTICS_PUSH_ALLENABLED=true zitadel start-from-init --masterkey "MasterkeyNeedsToHave32Characters" --tlsMode disabled ``` @@ -44,7 +44,7 @@ ZITADEL_EXTERNALSECURE=false zitadel start-from-init --masterkey "MasterkeyNeeds ### Setup ZITADEL with a service account ```bash -ZITADEL_EXTERNALSECURE=false 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_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 # then you can move your machine key mv /tmp/zitadel-admin-sa.json $HOME/zitadel-admin-sa.json diff --git a/docs/docs/self-hosting/deploy/loadbalancing-example/example-zitadel-config.yaml b/docs/docs/self-hosting/deploy/loadbalancing-example/example-zitadel-config.yaml index 6c45449cf5..463a648339 100644 --- a/docs/docs/self-hosting/deploy/loadbalancing-example/example-zitadel-config.yaml +++ b/docs/docs/self-hosting/deploy/loadbalancing-example/example-zitadel-config.yaml @@ -2,6 +2,11 @@ Log: Level: 'info' +# Help the ZITADEL maintainers improve the products usability by giving them some insights +Analytics: + Push: + AllEnabled: true + # Make ZITADEL accessible over HTTP, not HTTPS ExternalSecure: true ExternalDomain: my.domain diff --git a/docs/docs/self-hosting/deploy/macos.mdx b/docs/docs/self-hosting/deploy/macos.mdx index f00bdd3931..8325c22742 100644 --- a/docs/docs/self-hosting/deploy/macos.mdx +++ b/docs/docs/self-hosting/deploy/macos.mdx @@ -40,7 +40,7 @@ LATEST=$(curl -i https://github.com/zitadel/zitadel/releases/latest | grep locat ## Run ZITADEL ```bash -ZITADEL_EXTERNALSECURE=false zitadel start-from-init --masterkey "MasterkeyNeedsToHave32Characters" --tlsMode disabled +ZITADEL_EXTERNALSECURE=false ZITADEL_ANALYTICS_PUSH_ALLENABLED=true zitadel start-from-init --masterkey "MasterkeyNeedsToHave32Characters" --tlsMode disabled ``` @@ -51,7 +51,7 @@ ZITADEL_EXTERNALSECURE=false zitadel start-from-init --masterkey "MasterkeyNeeds ### Setup ZITADEL with a service account ```bash -ZITADEL_EXTERNALSECURE=false 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 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 # then you can move your machine key mv /tmp/zitadel-admin-sa.json $HOME/zitadel-admin-sa.json diff --git a/docs/docs/self-hosting/manage/production.md b/docs/docs/self-hosting/manage/production.md index acdbb96888..9522b53023 100644 --- a/docs/docs/self-hosting/manage/production.md +++ b/docs/docs/self-hosting/manage/production.md @@ -61,6 +61,16 @@ 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 + +If you want some usage metrics pushed to external systems, enable the metrics you need 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. + +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 + ## Database ### Prefer CockroachDB diff --git a/docs/docs/self-hosting/manage/productionchecklist.md b/docs/docs/self-hosting/manage/productionchecklist.md index 2f02361b77..47d1219a33 100644 --- a/docs/docs/self-hosting/manage/productionchecklist.md +++ b/docs/docs/self-hosting/manage/productionchecklist.md @@ -42,6 +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. ### Security