HealthMonitor Section

To send regular health status information for the producer component of Jade Event Streaming, include the HealthMonitor section in the configuration. For details about the format of the output health monitoring message, see "Health Monitoring Data Specification", in Chapter 4.

The "HealthMonitor" section provides configuration settings that enable you to run the Health Monitor for a producer.

"HealthMonitor" : 
   {
      "Heartbeat" : <period‑in‑seconds>,
      "AdditionalFields" : [
          "ProducerStarted",
          "LastEventSent",
          "EventsSentToDeadLetter",
          "ErrorsInPeriod",
          "EventsInPeriod"
      ],
      "Format" : {
          "AzureMonitor" : <true‑or‑false>,
          "CamelCasedPropertyNames" : <true‑or‑false>
      },
      "RestPublisher" : {
          "Endpoint" : "<https://<namespace>",
          "Authentication" : { "Type":"Authentication‑type" }, 
          "RetryOptions":{
             "MaxRetries" : <number‑of‑retries>,
             "RetryDelay" : <period‑in‑milliseconds>,  
             "MaxRetryDelay" : <period‑in‑milliseconds>,
             "StatusCodes" : [<number>, <number, ...>]
           },
          "HttpLogging" : <true‑or‑false>
     },
     "TopicPublisher": {
         "Topic" : "<topic-name>"
     }
}   

The "HealthMonitor" properties are listed in the following table.

Property Description
Heartbeat The cadence with which the health monitoring message is sent. This is a positive integer value specified in seconds. The default value is 60 seconds; the minimum value is 10 seconds.
AdditionalFields

An array of field names that are the names of the data properties in the health monitoring message. It is always assumed that Producer and TimeGenerated will be in the message. These are emitted even if the AdditionalFields property is not present.

The additional field options are:

  • "ProducerStarted", which is the time the producer was started.

  • "LastEventSent", which is the time of the last health monitoring message for a period that contained any events.

  • "EventsSentToDeadLetter", which is the number of events that have been sent to the FileReaderUndeliverableDirectory in the lifetime of this Producer run.

  • "ErrorsInPeriod", which is a count of any errors that have occurred while sending events to the broker since the last health message.

  • "EventsInPeriod", which is the count of event sends to all topics since the last health message.

Format

If present, this section allows the user to modify the packet from the standard schema. It has the following fields.

  • AzureMonitor. If present and true, the health monitoring message is inserted into a JSON array (which will then have the health monitoring message as its only member). This complies with the Azure Monitor data requirements.

  • CamelCasedPropertyNames. If present and true, the property names will switch from Pascal case to Camel case (that is, the property names will have a lowercase first character.) This could be useful for health consumers written in Jade.

RestPublisher

If present, this is an object that specifies a REST endpoint to which the health monitoring message is sent. It has the following fields.

  • Endpoint, which specifies the URL endpoint to which the health message is sent.

 
  • Authentication. The authentication Type can be one of the following.

    • AzureLogin

    • AzureClientSecret

    • AzureEnvironment

    • AzureManagedIdentity

    • None

    For details, see "Type‑Specific Parameters", later in this chapter.

 
  • RetryOptions, which optionally configures the retry behavior of the REST connection. It allows fine‑tuning of the retry mechanism to make the availability of the service more resilient. Even if you do not specify a RetryOptions value, the retry will occur using the default values in the following list. The retry options are:

    • "MaxRetries", which is the maximum number of retry attempts before reporting an error. The default value is 3.

    • "RetryDelay", which is the minimum delay in milliseconds between retry attempts. The default value is 800 milliseconds.

    • "MaxRetryDelay", which is the maximum delay in milliseconds between retry attempts. The default value is 60 seconds.

    • "StatusCodes", which is an array of status codes as Integers that indicate when an operation should be retried. The default values are HTTP status codes 408 (RequestTimeout), 500 (InternalServerError), 502 (BadGateway), 503 (ServiceUnavailable), 504 (GatewayTimeout).

      If you specify status codes, the default codes are not included; that is, if you do not specify any codes, you will get 408, 500, 502, 503, and 504. If you specify [500, 601], you will only get 500 and 601 (and not 408, 502, 503, or 504).

 
  • HttpLogging, which is a Boolean value that indicates whether Azure internal HTTP logging should be logged or reported for this connection. This parameter defaults to a value of false if unspecified. If true, logging will be sent to the logger specified in the "Logger" section of the configuration file and log‑level filtering will be performed based on the level of that log. (This logging can be quite verbose, so it is recommended to turn it on only for debug scenarios.)

TopicPublisher

If present, the health monitoring message will be produced to a topic in the current broker (either an Azure EventHub or a Kafka topic).

The Topic parameter specifies the name of the topic to which to send the health monitoring message.

When the configuration file is read on start up, if there is no HealthMonitor section specified or it contains an error, the error is logged and the producer will continue with no health monitoring.

Malformed or otherwise incorrect RestPublisher property Endpoint or TopicPublisher property Topic values are detected when the first message is sent. An error is logged and the producer will continue unmonitored.

The Health Monitor runs on a separate thread from the Reader and Senders. It will wake up with the cadence of the Heatbeat, construct the message, and then send it to the configured location. If an error occurs in the connection or sending of the message, the Health Monitor will log an error and operation will continue as normal on the next heartbeat. If an unexpected error occurs, health monitoring will cease and the producer will continue unmonitored.

It is expected that any external agents that are monitoring these messages will detect the absence of the Health Monitor. The producer will have to be restarted for health monitoring to be restored.

The following is an example of the HealthMonitor section.

"HealthMonitor" : 
   {
      "Heartbeat" : 10,
      "AdditionalFields" : [
          "ProducerStarted",
          "LastEventSent",
          "EventsSentToDeadLetter",
          "ErrorsInPeriod",
          "EventsInPeriod"
      ],
      "Format" : {
          "AzureMonitor" : true,
          "CamelCasedPropertyNames" : false
      },
      "RestPublisher" : {
          "Endpoint" : "https://monitor.company.co.nz/monitor",
          "RetryOptions":{
              "MaxRetries" : 5,
              "RetryDelay" : 1000,  
              "MaxRetryDelay" : 30,
              "MaxRetryDelay" : 30,
              "StatusCodes" : [408, 500, 502, 503, 504, 403]
           },
          "Authentication" : { "Type" : "None" },
          "HttpLogging" : false
     },
     "TopicPublisher": {
         "Topic" : "my-eventhub-healthevents"
     }
}   

2025.0.01 and higher