Configuring Telemetry

See how to download example files from the helm chart here.

Configuration

For a quick setup using the default settings, see the minimal fragment example in charts/matrix-stack/ci/fragments/telemetry-minimal.yaml.

By default Telemetry only stores the Telemetry data in the cluster in a Secret named <release name>-telemetry-data.

The Telemetry service gets deployed by default (but does not automatically send any data), however it can be disabled with the following values:

telemetry:
  enabled: false

Automatic Reporting

The Telemetry component can also be configured to automatically send the Telemetry data to Element. This will cause the service to reach out to Element servers regularly and submit the telemetry data. Depending on your setup you might also want to check whether the service can reach the public internet (i.e., firewall rules). This is done with

telemetry:
  automaticReporting:
    enabled: true

It requires either essCredentials to be correctly populated at the top-level or, if you haven't configured that because you're running with the container images sourced from your private registry, to be configured like one of the below:

From charts/matrix-stack/ci/fragments/telemetry-secrets-in-helm.yaml

telemetry:
  automaticReporting:
    enabled: true
    credentials:
      username: "<ESS username>"
      password:
        value: "<ESS password>"

Or from charts/matrix-stack/ci/fragments/telemetry-secrets-externally.yaml

telemetry:
  automaticReporting:
    enabled: true
    credentials:
      username: "<ESS username>"
      password:
        secret: "{{ $.Release.Name }}-telemetry-external"
        secretKey: telemetrypassword

Where that Secret already exists in the cluster with your ESS password.

The frequency with which the Telemetry data is reported to Element is configured with

telemetry:
  automaticReporting:
    reportingPeriod: 5m

Persistent Storage

The Telemetry component saves the current Telemetry data in a Secret named <release name>-telemetry-data. By default is also configured to store snapshots of the Telemetry data in a PersistentVolumeClaim named <release name>-telemetry-storage. When this is enabled, the default configuration is to take a snapshot daily at just after midnight UTC. The frequency and time can be configured with

telemetry:
  persistHistoricalTelemetry:
    # # Cron Expression to run the persistence job. The default value can be seen below
    # Daily at 00:05 save the Telemetry
    schedule: "5 0 * * *"

This functionality can be disabled with

telemetry:
  persistHistoricalTelemetry:
    enabled: false

If you don't have access to the backing filesystem for PersistentVolumeClaims in your cluster, the storage can be accessed with

# Create a access pod with the Telemetry PVC mounted
kubectl -n ess run telemetry-storage-access --image registry.element.io/matrix-tools:0.18.0-debug --restart=Never --overrides='{
    "spec": {
      "securityContext": {
        "runAsNonRoot": true,
        "seccompProfile": {
          "type": "RuntimeDefault"
        }
      },
      "imagePullSecrets": [
        {
          "name": "ess-registry-element-io"
        }
      ],
      "containers": [
        {
          "name": "access",
          "image": "registry.element.io/matrix-tools:0.18.0-debug",
          "command": [
            "sleep",
            "infinity"
          ],
          "securityContext": {
            "allowPrivilegeEscalation": false,
            "capabilities": {
              "drop": [
                "ALL"
              ]
            },
            "runAsNonRoot": true,
            "fsGroup": 10113,
            "runAsUser": 10113,
            "runAsGroup": 10113
          },
          "volumeMounts": [
            {
              "name": "telemetry-storage",
              "mountPath": "/storage"
            }
          ]
        }
      ],
      "volumes": [
        {
          "name": "telemetry-storage",
          "persistentVolumeClaim": {
            "claimName": "ess-telemetry-storage"
          }
        }
      ]
    }
  }'

# Wait for the pod to be ready
kubectl -n ess wait --for=condition=ready pod/telemetry-storage-access --timeout=300s

# List the files in stores
kubectl -n ess exec telemetry-storage-access -- ls -l /storage

# Copy out the Telemetry JSON you desire to the current working directory
kubectl -n ess exec telemetry-storage-access -- cat /storage/<telemetry filename from above> > <telemetry filename from above>

# Clean up the pod
kubectl -n ess delete pod telemetry-storage-access