How install telemetry is bounded

The install report exists to tell Altaira Labs how Omnia is deployed and which features are present. This page explains the limits that keep it from carrying anything else, and how to read what it does carry.

How the report is produced

The operator registers a TelemetryReporter whatever the licence state. The diagram shows what it reads, what it writes and where the report goes, next to the licence reconciler it stays independent of.

flowchart LR
  OP["operator (cmd/main.go)"] -->|registers| TR[TelemetryReporter]
  TR -->|"lists via cached client"| CRD["AgentRuntime, Workspace, PromptPack, Provider, ToolPolicy ..."]
  TR -->|reads UIDs| NS["Namespaces kube-system and install namespace"]
  TR -->|reads and writes| TCM["ConfigMap omnia-telemetry-state"]
  TR -->|reads| SEC["licence Secret"]
  TR -->|"prints once per start"| BAN["registration banner (operator log)"]
  TR -->|"POST /v1/reports"| LS["license.altairalabs.ai"]
  LAR["LicenseActivationReconciler (--enterprise)"] -->|watches| SEC
  LAR -->|reads and writes| ACM["ConfigMap arena-license-activation"]
  LAR -->|"POST /v1/licenses/activate"| LS

One rule at the type

The telemetry payload is a single Go struct, Telemetry. The operator sends it inside a ReportRequest that adds the cluster fingerprint, the Omnia version, and the licence ID on registered installs. The comment on the struct states the rule:

Counts, enums, booleans and coarse durations ONLY. Never names, content, credentials, endpoints, model names, namespaces or customer free text. If a value cannot be expressed as one of those four, it does not belong here.

A golden test, TestReportRequest_GoldenPayload in ee/pkg/license/report_test.go, marshals a populated ReportRequest and compares it with a fixed literal by JSON equality and by key set. A field added to Telemetry without omitempty, or populated in the test’s struct, breaks the test until the literal changes. An omitempty field that the test leaves unset does not break it, so review of the struct remains the main control. The comment on the type also asks for the reference page to be updated.

The rule excludes names of agents, workspaces, packs, namespaces and clusters. It excludes prompt, message, session and tool-call content, credentials, provider endpoints and model names, IP addresses, hostnames, user identities, and free text typed into a CRD. The provider type is sent. The model is not.

Why there is no cloud-provider field

The Kubernetes version string carries markers that identify a distribution, such as -gke. and -eks-. Self-managed builds of the same distributions carry the same markers: Anthos and EKS Distro run on customer hardware and other clouds.

Inferring a cloud from the marker would report the wrong cloud for those clusters. A wrong value misleads more than a missing one, so the report carries the distribution only.

Reading the version string also avoids a permission. The alternative, listing nodes to read provider IDs, would need cluster-wide node reads for the operator.

Presence is not use

ee_feature_crds_present lists a slug when at least one object of the matching Kind exists. A ToolPolicy left over from a demo and never evaluated counts the same as one enforced on every request. “12 installs report toolPolicy” does not mean 12 installs use policy enforcement, because the payload has no runtime signal that separates the two.

The list is also incomplete in the other direction. memoryEnterprise, privacyEnterprise and whiteLabel are licence flags, not CRDs, so they never appear however heavily they are used. The absence of a slug carries no information.

Separate from licence activation

The reporter is a runnable that the operator starts on its own timer, whatever the licence state. A reconciler driven by the licence Secret or the activation ConfigMap would never fire for an unregistered Core install, because neither object exists there. The report is also a separate request from the licence heartbeat, so an install that has used up its activation seats still reports.

The reporter keeps its first-seen timestamp in its own ConfigMap. The licence reconciler treats the presence of the activation ConfigMap as “already activated”, so telemetry state stored there would cause a later Enterprise licence to skip activation.

Registering an install

An unregistered install prints a banner once per operator start. The banner carries a registration URL with the cluster fingerprint as its last path segment. The reference page shows the banner text.

The operator treats an install as registered when a licence ID is attached to the report, so the banner and the payload cannot disagree about which installs are anonymous. Only the operator prints the banner, because only the operator computes the fingerprint.

Registering associates telemetry already sent under your fingerprint with your account. Those reports stop being anonymous at that point, because the fingerprint links them. In return you get release notes and security advisories. Registering gates no feature.

Trade-offs

Counts and enums limit what the report can answer. It cannot say how much an install is used.
Cheap collection keeps the operator’s permissions small. The report reads objects through the operator’s existing cache, and reads the Kubernetes version from the discovery endpoint, which needs no RBAC.
The banner advertises the opt-out in the same output as the collection. An install that disables telemetry never prints the banner, so it never receives the invitation to register.
The report never affects the operator. A failed send is logged at debug level and dropped, with no retry or queue.