Updater History Event Schema

This document describes the JSON schema for events recorded by the updater. Each

event is a record of an updater action. Events are serialized as JSON objects in a JSONL file (one object per line).

Required Fields

The schema indicates that some fields are required, to clarify this indicates that:

1. A compliant serialization implementation will refuse messages which do not contain all required fields.
2. Deserialization process may consider a message missing one or more required fields as ill-formed, but need not reject the message when data recovery is best-effort.

Base Event Properties

All events share a common set of base properties:

| Property | Type | Description | Required | |-:---------------|-:-------|-:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-:--------| | eventType | string | The type of event being recorded. See the Event Types section below for possible values. | Yes | | eventId | string | A unique identifier for the event. For events with a duration, this ID links the START and END records. | Yes | | deviceUptime | string | The uptime of the device in integer microseconds. | Yes | | pid | integer | The process ID of the updater instance that emitted the event. | Yes | | processToken | string | A per-process random value to discriminate between processes with the same PID due to OS-reuse. | Yes | | bound | string | Indicates if the record marks the beginning (START), end (END), or an instantaneous event (INSTANT). Defaults to INSTANT. | No | | errors | array | An array of error objects encountered during the event. Each object has: category (integer), code (integer), extracode1 (integer). An empty array has the same meaning as an unset array. | No |

Event Types

The specific details of an event are determined by its eventType and bound. The schema defines the following event types:

INSTALL: Application Installation

• Description: Recorded when an application installation starts or completes.
• Bounds:
  • START:
    • appId (string, required): The ID of the application being installed.
  • END: No specific properties.
    • version (string): The version of the application that the updater tried to install.

UNINSTALL: Application Uninstallation

• Description: Recorded when an application uninstallation starts or completes.
• Bounds:
  • START:
    • appId (string, required): The ID of the application being uninstalled.
    • version (string, required): The version of the application being uninstalled.
    • reason (string, required): Enum: ”UNINSTALLED”, ”USER_NOT_AN_OWNER”, ”NO_APPS_REMAIN”, ”NEVER_HAD_APPS”.
  • END: No specific properties.

QUALIFY: Updater Qualification

• Description: Recorded when the updater starts or completes its self-qualification process to become the active version.
• Bounds:
  • START: No specific properties.
  • END:
    • qualified (boolean): Whether the updater version successfully qualified.

ACTIVATE: Updater Activation

• Description: Recorded when the updater starts or completes its activation process.
• Bounds:
  • START: No specific properties.
  • END:
    • activated (boolean, required): Whether the running updater version was activated.

PERSISTED_DATA: Persisted Data Snapshot

• Description: Records a snapshot of data persisted by the updater, such as application registrations and policy states. This is an INSTANT event.
• Properties:
  • eulaRequired (boolean, required): Whether a user responsible for this system needs to accept a EULA.
  • lastChecked (string): Timestamp of the last successful update check (RFC 3339 date-time).
  • lastStarted (string): Timestamp of the last time the updater ran its periodic tasks (RFC 3339 date-time).
  • registeredApps (array): A list of applications registered with the updater. Each item is an object with:
    • appId (string, required): The app's unique identifier.
    • version (string, required): The registered version of the app.
    • cohort (string): The cohort assignment of the app.
    • brandCode (string): The brand code of the app.

POST_REQUEST: HTTP Post Request

• Description: Recorded when an HTTP POST request is initiated or completed.
• Bounds:
  • START:
    • request (string, required): The base64-encoded HTTP request body.
  • END:
    • response (string): The base64-encoded HTTP response body.

LOAD_POLICY: Load Policy

• Description: Recorded when the updater begins or finishes computing the effective enterprise policy set.
• Bounds:
  • START: No specific properties.
  • END:
    • policySet (object): The enterprise policy set. See the Policy Set section below.

UPDATE: Application Update Check

• Description: Recorded when the updater starts or finishes an update check/process for an application.
• Bounds:
  • START:
    • appId (string): The ID of the application being checked.
    • priority (string): Enum: "BACKGROUND", "FOREGROUND".
  • END:
    • nextVersion (string): The version of the application which the updater tried to update to.
    • updateStates (array): A sequence of details on the state of an update. Each item is an object with:
      • deviceUptime (string): The uptime of the system when the state change was observed in integer microseconds.
      • state (string, required): The state of the update. Enum: possible values are the upper snake case UpdaterState::State enum labels defined in UpdateService. Includes "UPDATED", "NO_UPDATE", and "UPDATE_ERROR".
    • result (string): The value returned by the completion callback of the update operation as a result of the non-blocking invocation of the service functions. Enum: possible values are the upper snake case UpdaterState::Result enum labels defined in UpdateService. Includes "SUCCESS" and "UPDATE_IN_PROGRESS".

UPDATER_PROCESS: Updater Process Lifetime

• Description: Recorded when an updater process starts or terminates.
• Bounds:
  • START:
    • commandLine (string): The full command line of the updater process invocation.
    • timestamp (string): The system time when the event began (RFC 3339 date-time).
    • updaterVersion (string): The version of the updater.
    • scope (string): The scope in which the updater is running. Enum: "USER", "SYSTEM".
    • osPlatform (string): The operating system platform.
    • osVersion (string): The operating system version.
    • osArchitecture (string): The architecture of the operating system.
    • updaterArchitecture (string): The architecture of the updater binary.
    • deviceUptime (string): The uptime of the system in integer microseconds.
    • parentPid (integer): The parent process id, which allows the process tree of the updater to be reconstructed.
  • END: No specific properties.
    • exitCode (integer): The exit code of the process.

APP_COMMAND: App Command Invocation

• Description: Recorded when an app command is invoked by the updater.
• Bounds:
  • START:
    • appId (string, required): The ID of the app owning the command.
    • commandLine (string): The full command line used to invoke the app command.
  • END:
    • exitCode (integer): The exit code of the app command.
    • output (string): The output generated by the app command.

Common Complex Types

Policy Set

• Description: Represents the enterprise policy set governing the updater's behavior.
• Properties:
  • policiesByName (object, required): An object mapping policy names to their details. Each value in this map is an object with:
    • valuesBySource (object, required): Policy values provided by different sources. Values are of arbitrary type. Potential keys include:
      • default: The built-in default value.
      • externalConstants: Value from external constants file (test only).
      • platform: Value from OS policy manager (e.g., Group Policy, Managed Preferences).
      • cloud: Value from cloud service.
    • prevailingSource (string, required): A indicating which key within valuesBySource contains the authoritative value used by the updater (e.g., platform).
  • policiesByAppId (object, required): An object mapping application identifiers to per-app policy sets. Each value in this map is an object with the same structure as policiesByName, as defined above.