Share via

az iot central diagnostics

  • Preview
  • Reference

Note

This reference is part of the azure-iot extension for the Azure CLI (version 2.46.0 or higher). The extension will automatically install the first time you run an az iot central diagnostics command. Learn more about extensions.

This command group is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

Perform application and device level diagnostics.

Commands

Name Description Type Status
az iot central diagnostics monitor-events

View device telemetry messages sent to the IoT Central app.

 Extension Preview
az iot central diagnostics monitor-properties

View desired and reported properties sent to/from the IoT Central app.

 Extension Preview
az iot central diagnostics registration-summary

View the registration summary of all the devices in an app.

 Extension Preview
az iot central diagnostics validate-messages

Validate messages sent to the IoT Hub for an IoT Central app.

 Extension Preview
az iot central diagnostics validate-properties

Validate reported properties sent to the IoT Central application.

 Extension Preview

az iot central diagnostics monitor-events

Preview

Command group 'iot central diagnostics' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

View device telemetry messages sent to the IoT Central app.

Shows the telemetry data sent to IoT Central application. By default, it shows all the data sent by all devices. Use the --device-id parameter to filter to a specific device.

az iot central diagnostics monitor-events --app-id
                                          [--central-api-uri]
                                          [--cg]
                                          [--device-id]
                                          [--enqueued-time]
                                          [--module-id]
                                          [--properties {all, anno, app, sys}]
                                          [--repair {false, true}]
                                          [--timeout]
                                          [--token]
                                          [--yes {false, true}]

Examples

Basic usage

az iot central diagnostics monitor-events --app-id {app_id}

Basic usage when filtering on target device

az iot central diagnostics monitor-events --app-id {app_id} -d {device_id}

Basic usage when filtering targeted devices with a wildcard in the ID

az iot central diagnostics monitor-events --app-id {app_id} -d Device*d

Basic usage when filtering on module.

az iot central diagnostics monitor-events --app-id {app_id} -m {module_id}

Basic usage when filtering targeted modules with a wildcard in the ID

az iot central diagnostics monitor-events --app-id {app_id} -m Module*

Filter device and specify an Event Hub consumer group to bind to.

az iot central diagnostics monitor-events --app-id {app_id} -d {device_id} --cg {consumer_group_name}

Receive message annotations (message headers)

az iot central diagnostics monitor-events --app-id {app_id} -d {device_id} --properties anno

Receive message annotations + system properties. Never time out.

az iot central diagnostics monitor-events --app-id {app_id} -d {device_id} --properties anno sys --timeout 0

Receive all message attributes from all device messages

az iot central diagnostics monitor-events --app-id {app_id} --props all

Receive all messages and parse message payload as JSON

az iot central diagnostics monitor-events --app-id {app_id} --output json

Required Parameters

--app-id -n

The App ID of the IoT Central app you want to manage. You can find the App ID in the "About" page for your application under the help menu.

Optional Parameters

--central-api-uri --central-dns-suffix

The IoT Central DNS suffix associated with your application.

Default value: azureiotcentral.com
--cg --consumer-group -c

Specify the consumer group to use when connecting to event hub endpoint.

Default value: $Default
--device-id -d

The device ID of the target device.You can find the device ID by, clicking on the Connect button on the Device Details page.

--enqueued-time --et -e

Indicates the time that should be used as a starting point to read messages from the partitions. Units are milliseconds since unix epoch. If no time is indicated "now" is used.

--module-id -m

The IoT Edge Module ID if the device type is IoT Edge.

--properties --props -p

Indicate key message properties to output. sys = system properties, app = application properties, anno = annotations.

Accepted values: all, anno, app, sys
--repair -r

Reinstall uamqp dependency compatible with extension version. Default: false.

Accepted values: false, true
Default value: False
--timeout --to -t

Maximum seconds to maintain connection without receiving message. Use 0 for infinity.

Default value: 300
--token

If you'd prefer to submit your request without authenticating against the Azure CLI, you can specify a valid user token to authenticate your request. You must specify the type of key as part of the request. Learn more at https://aka.ms/iotcentraldocsapi.

--yes -y

Skip user prompts. Indicates acceptance of action. Used primarily for automation scenarios. Default: false.

Accepted values: false, true
Default value: False
Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
Default value: json
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

az iot central diagnostics monitor-properties

Preview

Command group 'iot central diagnostics' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

View desired and reported properties sent to/from the IoT Central app.

Polls device-twin from central and compares it to the last device-twin Parses out properties from device-twin, and detects if changes were made Prints subset of properties that were changed within the polling interval.

az iot central diagnostics monitor-properties --app-id
                                              --device-id
                                              [--central-api-uri]
                                              [--token]

Examples

Basic usage

az iot central diagnostics monitor-properties --app-id {app_id} -d {device_id}

Required Parameters

--app-id -n

The App ID of the IoT Central app you want to manage. You can find the App ID in the "About" page for your application under the help menu.

--device-id -d

The device ID of the target device.You can find the device ID by, clicking on the Connect button on the Device Details page.

Optional Parameters

--central-api-uri --central-dns-suffix

The IoT Central DNS suffix associated with your application.

Default value: azureiotcentral.com
--token

If you'd prefer to submit your request without authenticating against the Azure CLI, you can specify a valid user token to authenticate your request. You must specify the type of key as part of the request. Learn more at https://aka.ms/iotcentraldocsapi.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
Default value: json
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

az iot central diagnostics registration-summary

Preview

Command group 'iot central diagnostics' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

View the registration summary of all the devices in an app.

Note: This command can take a significant amount of time to return if your app contains a lot of devices.

az iot central diagnostics registration-summary --app-id
                                                [--api-version {2022-06-30-preview, 2022-07-31}]
                                                [--central-api-uri]
                                                [--token]

Examples

Registration summary

az iot central diagnostics registration-summary --app-id {appid}

Required Parameters

--app-id -n

The App ID of the IoT Central app you want to manage. You can find the App ID in the "About" page for your application under the help menu.

Optional Parameters

--api-version --av
Deprecated

Argument 'api_version' has been deprecated and will be removed in a future release.

This command parameter has been deprecated and will be ignored.In the future release, we will only support IoT Central APIs from latest GA version.If any API is not GA yet, we will call latest preview version.

Accepted values: 2022-06-30-preview, 2022-07-31
Default value: 2022-07-31
--central-api-uri --central-dns-suffix

The IoT Central DNS suffix associated with your application.

Default value: azureiotcentral.com
--token

If you'd prefer to submit your request without authenticating against the Azure CLI, you can specify a valid user token to authenticate your request. You must specify the type of key as part of the request. Learn more at https://aka.ms/iotcentraldocsapi.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
Default value: json
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

az iot central diagnostics validate-messages

Preview

Command group 'iot central diagnostics' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

Validate messages sent to the IoT Hub for an IoT Central app.

Performs validations on the telemetry messages and reports back data that is not modeled in the device template or data where the data type doesn’t match what is defined in the device template.

az iot central diagnostics validate-messages --app-id
                                             [--central-api-uri]
                                             [--cg]
                                             [--device-id]
                                             [--dr]
                                             [--enqueued-time]
                                             [--max-messages]
                                             [--minimum-severity {error, info, warning}]
                                             [--module-id]
                                             [--properties {all, anno, app, sys}]
                                             [--repair {false, true}]
                                             [--style {csv, json, scroll}]
                                             [--timeout]
                                             [--token]
                                             [--yes {false, true}]

Examples

Basic usage

az iot central diagnostics validate-messages --app-id {app_id}

Output errors as they are detected

az iot central diagnostics validate-messages --app-id {app_id} --style scroll

Basic usage when filtering on target device

az iot central diagnostics validate-messages --app-id {app_id} -d {device_id}

Basic usage when filtering targeted devices with a wildcard in the ID

az iot central diagnostics validate-messages --app-id {app_id} -d Device*

Basic usage when filtering on module.

az iot central diagnostics validate-messages --app-id {app_id} -m {module_id}

Basic usage when filtering targeted modules with a wildcard in the ID

az iot central diagnostics validate-messages --app-id {app_id} -m Module*

Filter device and specify an Event Hub consumer group to bind to.

az iot central diagnostics validate-messages --app-id {app_id} -d {device_id} --cg {consumer_group_name}

Required Parameters

--app-id -n

The App ID of the IoT Central app you want to manage. You can find the App ID in the "About" page for your application under the help menu.

Optional Parameters

--central-api-uri --central-dns-suffix

The IoT Central DNS suffix associated with your application.

Default value: azureiotcentral.com
--cg --consumer-group -c

Specify the consumer group to use when connecting to event hub endpoint.

Default value: $Default
--device-id -d

The device ID of the target device.You can find the device ID by, clicking on the Connect button on the Device Details page.

--dr --duration

Maximum duration to receive messages from target device before terminating connection.Use 0 for infinity.

Default value: 300
--enqueued-time --et -e

Indicates the time that should be used as a starting point to read messages from the partitions. Units are milliseconds since unix epoch. If no time is indicated "now" is used.

--max-messages --mm

Maximum number of messages to recieve from target device before terminating connection.Use 0 for infinity.

Default value: 10
--minimum-severity

Minimum severity of issue required for reporting.

Accepted values: error, info, warning
Default value: warning
--module-id -m

The IoT Edge Module ID if the device type is IoT Edge.

--properties --props -p

Indicate key message properties to output. sys = system properties, app = application properties, anno = annotations.

Accepted values: all, anno, app, sys
--repair -r

Reinstall uamqp dependency compatible with extension version. Default: false.

Accepted values: false, true
Default value: False
--style

Indicate output stylescroll = deliver errors as they arrive, json = summarize results as json, csv = summarize results as csv.

Accepted values: csv, json, scroll
Default value: scroll
--timeout --to -t

Maximum seconds to maintain connection without receiving message. Use 0 for infinity.

Default value: 300
--token

If you'd prefer to submit your request without authenticating against the Azure CLI, you can specify a valid user token to authenticate your request. You must specify the type of key as part of the request. Learn more at https://aka.ms/iotcentraldocsapi.

--yes -y

Skip user prompts. Indicates acceptance of action. Used primarily for automation scenarios. Default: false.

Accepted values: false, true
Default value: False
Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
Default value: json
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

az iot central diagnostics validate-properties

Preview

Command group 'iot central diagnostics' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

Validate reported properties sent to the IoT Central application.

Performs validations on reported property updates:

  1. Warning - Properties sent by device that are not modeled in central.
  2. Warning - Properties with same name declared in multiple interfaces should have interface name included as part of the property update.
az iot central diagnostics validate-properties --app-id
                                               --device-id
                                               [--central-api-uri]
                                               [--minimum-severity {error, info, warning}]
                                               [--token]

Examples

Basic usage

az iot central diagnostics validate-properties --app-id {app_id} -d {device_id}

Required Parameters

--app-id -n

The App ID of the IoT Central app you want to manage. You can find the App ID in the "About" page for your application under the help menu.

--device-id -d

The device ID of the target device.You can find the device ID by, clicking on the Connect button on the Device Details page.

Optional Parameters

--central-api-uri --central-dns-suffix

The IoT Central DNS suffix associated with your application.

Default value: azureiotcentral.com
--minimum-severity

Minimum severity of issue required for reporting.

Accepted values: error, info, warning
Default value: warning
--token

If you'd prefer to submit your request without authenticating against the Azure CLI, you can specify a valid user token to authenticate your request. You must specify the type of key as part of the request. Learn more at https://aka.ms/iotcentraldocsapi.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
Default value: json
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.