This guide uses two related official documentation pages: the API usage reference and the local FAQ. It proposes an application-owned labeling policy for telemetry, limited to the supplied excerpts rather than any numbered release history.
Choose the evidence boundary
The FAQ says the macOS and Windows applications obtain updates automatically; selecting Restart to update is the documented application step. For Linux, the documented upgrade route is to run the installation script again.
Use an applied-update boundary: treat a download as acquisition evidence, and reserve a post-upgrade label for a retained record of the relevant application event. This is a suggested local design, not a provider-prescribed implementation.
Neither supplied excerpt offers a field or event that associates one usage record with an exact running release. Therefore, an applied-event label should not be read as proof of a numbered release.
Decision table
| Case | Platform path | Acquisition evidence | Application evidence | Telemetry collection point | Supported release label | Inference to reject | Evidence owner | Bounded action |
|---|---|---|---|---|---|---|---|---|
| macOS or Windows update downloaded without a recorded restart | Automatic desktop download; restart is the documented application step. | Retained download event. | No restart record. | Response body for a non-streaming reply; terminal done-true chunk for a streaming reply. | Unattributed; no post-upgrade label. | A download proves that the responding service changed. | Local telemetry and update-evidence custodian. | Keep the usage record, remove any post-upgrade label, and request restart evidence. |
| macOS or Windows restart to apply recorded | Automatic desktop download followed by the documented restart action. | Retained download event, if available. | Retained restart-to-apply event. | Response body for a non-streaming reply; terminal done-true chunk for a streaming reply. | Applied-update event recorded; exact release unknown. | A restart record identifies a numbered release. | Local telemetry and update-evidence custodian. | Retain the event beside the usage record and use the bounded applied-event label. |
| Linux upgrade rerun not recorded | The documented Linux route is another installation-script run. | An asserted rerun without a durable record. | No retained rerun record. | Response body for a non-streaming reply; terminal done-true chunk for a streaming reply. | Unattributed; no post-upgrade label. | An unrecorded rerun establishes which service produced the reply. | Local telemetry and upgrade-evidence custodian. | Preserve telemetry without the label and seek independently retained rerun evidence. |
| Linux upgrade rerun recorded | The documented Linux route is another installation-script run. | Retained record of the rerun. | Recorded rerun, used here as the local application proxy. | Response body for a non-streaming reply; terminal done-true chunk for a streaming reply. | Linux upgrade-rerun evidence recorded; exact release unknown. | A rerun record alone supplies a release identifier. | Local telemetry and upgrade-evidence custodian. | Keep the proxy label with its caveat and escalate if exact release attribution is required. |
Collect the usage record at completion
A non-streaming response carries usage information in its response body. With streaming replies, the usage information arrives in the terminal chunk, identified by done set to true.
Collect that completion record before applying an upgrade-related label. The usage reference describes duration and token-count measures, so preserving the complete returned usage fields is preferable to retaining only a derived label.
Hypothetical labeling failure
Suppose a desktop update download is recorded and a later streaming completion record is marked post-upgrade solely because of that download. If review finds no retained restart-to-apply event, the record remains useful as usage telemetry, but the post-upgrade label should be withdrawn.
Under this proposed policy, the reviewer preserves the terminal usage record, records why its label changed, and requires applied-release evidence before restoring a release-related label. The scenario is illustrative; it does not represent a test or an observed service outcome.
Retention, review, and alternatives
Retention and review are proposed application policy. Keep the usage payload, its collection time, the acquisition or application evidence, the label history, and the reviewer decision together. Define who may remove or restore a label and how long the evidence bundle is retained.
An acquisition-time approach can be simpler: label a record after a download or upgrade initiation. Reject it for release attribution because the documented desktop flow separates downloading from the restart used to apply the update, while the supplied Linux excerpt does not provide a distinct confirmation signal beyond rerunning the installer.
If exact release attribution matters, leave the label bounded until a durable artifact can connect the running service to a specific release and to the collected response. The supplied excerpts do not establish such an artifact or correlation method.
Limitations and review triggers
This policy is constrained to the supplied official-documentation excerpts. They describe update paths and usage-field placement, but they do not establish a complete method for proving the exact release behind an individual usage record.
- Reassess the boundary when the referenced source material changes.
- Reassess it when a version retirement or incompatibility changes the deployment assumptions.
- Decide separately how a Linux rerun will be independently retained and tied to the running service.
- Decide whether another supported diagnostic artifact can identify the running release without weakening the evidence boundary.
The separation is sound, but could the label be modeled as an immutable, typed evidence record rather than a single “applied-update” flag? The documented desktop transition is specifically Restart to update, while Linux uses a rerun of the install script; neither event has the same semantics as acquisition, and neither is a version identifier. A minimal boundary might therefore retain
evidence_kind(desktop_restart_to_updateorlinux_install_script_rerun),observed_at, and an artifact reference, while keepingrunning_releasenull. That prevents later consumers from coupling “applied” to either a download or a release number, and leaves room for a separately captured running-release artifact if one becomes available. Does the proposed policy require this distinction at the schema boundary, rather than only in reviewer guidance? The FAQ supports the differing update paths but does not provide a per-response release correlation.