Azure-docs: Monitor the health of Azure IoT Hub and diagnose problems quickly - wrong JSON schema provided

[vladislav-mitev]

The documentation seems to be out of sync with the actual implementation.
For example this one: https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-monitor-resource-health#connections
The real event message is:

{
  "records": [
    {
      "time": "UTC timestamp",
      "resourceId": "Resource Id",
      "operationName": "deviceConnect",
      "category": "Connections",
      "level": "Information",
      "properties": "{\"deviceId\":\"<deviceId>\",\"protocol\":\"<protocol>\",\"authType\":\"{\\\"scope\\\":\\\"device\\\",\\\"type\\\":\\\"sas\\\",\\\"issuer\\\":\\\"iothub\\\",\\\"acceptingIpFilterRule\\\":null}\",\"maskedIpAddress\":\"<maskedIpAddress>\"}",
      "location": "Resource location"
    },
    {
      "time": "UTC timestamp",
      "resourceId": "Resource Id",
      "operationName": "deviceConnect",
      "category": "Connections",
      "level": "Information",
      "properties": "{\"deviceId\":\"<deviceId>\",\"protocol\":\"<protocol>\",\"authType\":\"{\\\"scope\\\":\\\"device\\\",\\\"type\\\":\\\"sas\\\",\\\"issuer\\\":\\\"iothub\\\",\\\"acceptingIpFilterRule\\\":null}\",\"maskedIpAddress\":\"<maskedIpAddress>\"}",
      "location": "Resource location"
    }
  ],
  "EventProcessedUtcTime": "2018-08-31T12:45:07.2968273Z",
  "PartitionId": 1,
  "EventEnqueuedUtcTime": "2018-08-31T12:36:46.0780000Z"
}

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: 27773d69-fdb5-ba10-d488-21448cbe6089
• Version Independent ID: 7eac3fa1-b748-531d-e880-00cefd59d3c3
• Content: Monitor the health of your Azure IoT Hub
• Content Source: articles/iot-hub/iot-hub-monitor-resource-health.md
• Service: iot-hub
• GitHub Login: @kgremban
• Microsoft Alias: kgremban

[Mike-Ubezzi-MSFT]

@vladislav-mitev Thank you very much for bringing this to our attention. We are investigating and will have an update for you shortly.

[Mike-Ubezzi-MSFT]

Thanks for the feedback! I have assigned the issue to the content author to evaluate and update as appropriate.

[Mike-Ubezzi-MSFT]

Verified that what is in the documentation is not what has been provided by the customer.

[kgremban]

@vladislav-mitev The JSON provided in the article does match the "record" value in your sample. But you're saying that's not sufficient, that you want the whole message output? I'm not sure that it adds significant clarity to include the extra JSON formatting around each event type. If anything, maybe we could include a sample log in the "Read logs from Azure Event Hubs" section, after the sample code to retrieve logs.

What do you think?

[vladislav-mitev]

Not sure what you mean, because e.g. the three system properties (EventProcessedUtcTime, PartitionId, EventEnqueuedUtcTime) are not documented at all. Furthermore, from the current documentation there is no hint that a single message contains multiple events. That eventually breaks your parser.

[kgremban]

Hi again @vladislav-mitev. Sorry for the delay. I updated the document to show to larger JSON format. However, all the outputs that I looked at (including for category: Connections) didn't have the three system properties at the end that you included in your sample. Can you confirm whether you still receive those properties in event messages?

[vladislav-mitev]

Hello, thank you for considering my ticket.

It is interesting because it appears there are two "versions" of the messages received:

1. When a function trigger is attached, then the three metadata properties are not received
2. When a Stream Analytics Job is attached, then the three properties are received. Both run-time and through sampling.

This leads to the question Why there is a difference?

[asergaz]

@Mike-Ubezzi-MSFT can you confirm if you were able to see the system properties on your tests? @kgremban let us know if you were able to repro this scenario and if the documentation should be enhanced to reference it?

Thanks both!

[jlian]

@vladislav-mitev when you say services (Functions, Stream Analytics) attached, how are you attaching them? Those system properties look like the specific properties that occur when Event Hub interacts with Stream Analytics.

https://docs.microsoft.com/en-us/azure/stream-analytics/stream-analytics-define-inputs

[vladislav-mitev]

Hello,
"attached" meaning:

• stream input for ASA
• trigger for Function

The documentation you gave seems to explain what is really happening. I have missed that point. Thank you a lot for quoting it.
I think we are done here, except for the still missing fix on this JSON message: https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-monitor-resource-health#connections . All others have been fixed.

Thanks a lot!

[kgremban]

Thanks @jlian for helping clear this up. And thanks @vladislav-mitev for pointing out the JSON sample that I missed. I'll make the update to the Connections sample, then close this issue as resolved.