azure-cli/doc/telemetry/README.md

Telemetry Documentation

Two types of telemetry are used to monitor and analyze execution of Azure CLI commands. One called ARM telemetry is recorded basing on HTTP traffic by ARM, and another is client side telemetry sent by Azure CLI.

ARM Telemetry

ARM telemetry tracks all HTTP requests and responses through ARM endpoint. As far as we know, below cases don't have ARM telemetry record.

• Command doesn't create request successfully, for instance, parameter cannot pass validation, request or payload cannot be constructed.
• Command calls data plane service API.
• Network is inaccessible.
• No request is needed during execution.

CLI Client Telemetry

Client side telemetry is sent at the end of Azure CLI command execution. It covers all commands, no matter if it has HTTP requests or just has local operations. Sanitized data is stored in Kusto cluster which is managed by DevDiv Data team.

All Azure CLI data is stored in a large json named Properties in table RawEventsAzCli. Some properties are flatten, some are not. Here are some useful fields:

The telemetry has different schema pre Azure CLI 2.0.28. All the fields explained below are for new schema, in other words, CLI version > 2.0.28.

• EventName: azurecli/command or azurecli/fault or azurecli/extension
  • azurecli/command means this is common event record with general Properties field.
  • azurecli/fault means this is additional event record with extra exception info in Properties field.
  • azurecli/extension means this is additional event record with customized info in Properties field.
  • Additional event record can be joined with common event record using CorrelationId.
• CorrelationId: GUID to join additional event records with common event record
  • azurecli/extension event records have the same CorrelationId with related azurecli/command event record.
  • azurecli/fault event has Properties['reserved.datamodel.correlation.1'] field. The field value is {correlationId},UserTask, where {correlationId} is CorrelationId field of related azurecli/command record.
• EntityType: UserTask/Fault
  • For EventName == 'azurecli/command', the EntityType is UserTask.
  • For EventName == 'azurecli/fault', the EntityType is Fault.
• EventTimeStamp: time when the telemetry record is sent
• ProductVersion: CLI core version in the format of azurecli@{version}
• CoreVersion: CLI core version
• ExeVersion: {cli_core_version}@{module_version}. In the new schema (CLI version > 2.0.28), all module versions are none. Hence this field is {cli_core_version}@none
• OsType: OS system, e.g., linux, windows
• OsVersion: OS platform version, e.g., 10.0.14942
• PythonVersion: platform python version
• ShellType: cmd/bash/ksh/zsh/cloud-shell/... Note: may not be accurate.
• MacAddressHash: SHA256 hashed MAC address
• MachineId: GUID coming from the first 128bit of MacAddressHash
• UserId: CLI installation id. Each CLI client installed locally will have a GUID as installation id. It's stored in $homeFolder/.azure/azureProfile.json
• SessionId: SHA256 hashed result of CLI installation id, parent process (terminal session) creation time and parent process (terminal session) id. Note: may not be accurate.
• RawCommand: CLI command name
• Params: CLI command arguments (without argument value)
• AzureSubscriptionId: current subscription id
• ClientRequestId: GUID which is set on HTTP header
• StartTime: time when the command begins executing
• EndTime: time when the command exits
• ActionResult:
  • For EntityType == 'UserTask', it could be Success/Failure/UserFault/None. All others besides Success means failure.
  • For EntityType == 'Fault', it's empty.
• ResultSummary: details of result, may be suppressed to meet security & privacy requirements.
• ExceptionMessage: details of exception, may be suppressed to meet security & privacy requirements.
• Properties: large json with all constructed fields. Below is to explain some unflattened fields not introduced before.
  • reserved.datamodel.entityname: CLI command name with hyphens
  • reserved.datamodel.correlation.1: Additional field when EventName == 'azurecli/fault'. It's in the format of {correlationId},UserTask, where {correlationId} is CorrelationId field of related EventName == 'azurecli/command' record.
  • reserved.datamodel.fault.typestring: Additional field when EventName == 'azurecli/fault'. It logs the exception class.
  • reserved.datamodel.fault.description: Additional field when EventName == 'azurecli/fault'. It logs exception description or fault type.
  • context.default.vs.core.os.platform: OS platform
  • context.default.azurecli.source: az/completer. It's completer if we found argument auto complete settings in OS environment variable.
  • context.default.azurecli.environmentvariables: It logs customer's environment variables starting with AZURE_CLI
  • context.default.azurecli.extensionname: It logs the extension name and version in the format of {extension_name}@{extension_version} if the command is from CLI extension.
  • context.default.azurecli.installer: value of os environment variable AZ_INSTALLER
  • context.default.azurecli.error_type: It logs the exception class name.
  • context.default.azurecli.exception_name: A supplementation for context.default.azurecli.error_type

Doc Sections

• Kusto Examples - Samples for kusto query

• FAQ - Frequently Asked Questions