Metrics

Eclipse Hono™’s components report several metrics which may be used to gain some insight into the running system. For instance, the HTTP adapter reports the number of successfully processed telemetry messages. Some of these metrics are considered part of Hono’s external interface. This section describes the semantics and format of the metrics, how they can be retrieved and how to interpret actual values.

Reported Metrics

Hono uses Micrometer for collecting metrics. Those metrics can be exported to different back ends. Please refer to Configuring Metrics for details.

The container images published on Docker Hub have been compiled with support for Prometheus as the metrics back end.

When deploying to Kubernetes/OpenShift, the metrics reported by Hono may contain environment specific tags (like the pod name) which are added by the Prometheus scraper. However, those tags are not part of the Hono metrics definition.

Hono applications may report other metrics in addition to the ones defined here. In particular, all components report metrics regarding the JVM’s internal state, e.g. memory consumption and garbage collection status. Those metrics are not considered part of Hono’s official metrics definition. However, all those metrics will still contain the common tags described below.

Common Metrics

Tags for common metrics are:

Tag	Value	Description
host	string	The name of the host that the component reporting the metric is running on
component-type	`adapter`, `service`	The type of component reporting the metric
component-name	string	The name of the component reporting the metric.

The names of Hono’s standard components are as follows:

Component	component-name
Auth Server	`hono-auth`
Device Registry	`hono-registry`
Command Router	`hono-command-router`
AMQP adapter	`hono-amqp`
CoAP adapter	`hono-coap`
HTTP adapter	`hono-http`
MQTT adapter	`hono-mqtt`
Lora adapter	`hono-lora`
Sigfox adapter	`hono-sigfox`

Protocol Adapter Metrics

Additional tags used for metrics reported by protocol adapters are:

Name	Value	Description
direction	`one-way`, `request`, `response`	The direction in which a Command & Control message is being sent: `one-way` indicates a command sent to a device for which the sending application doesn’t expect to receive a response. `request` indicates a command request message sent to a device. `response` indicates a command response received from a device.
qos	`0`, `1`, `unknown`	The quality of service used for a telemetry or event message. `0` indicates at most once, `1` indicates at least once and `none` indicates unknown delivery semantics.
status	`forwarded`, `unprocessable`, `undeliverable`	The processing status of a message. `forwarded` indicates that the message has been forwarded to a downstream consumer `unprocessable` indicates that the message has not been processed not forwarded, e.g. because the message was malformed `undeliverable` indicates that the message could not be forwarded, e.g. because there is no downstream consumer or due to an infrastructure problem
tenant	string	The identifier of the tenant that the metric is being reported for.
ttd	`command`, `expired`, `none`	A status indicating the outcome of processing a TTD value contained in a message received from a device. `command` indicates that a command for the device has been included in the response to the device’s request for uploading the message. `expired` indicates that a response without a command has been sent to the device. `none` indicates that either no TTD value has been specified by the device or that the protocol adapter does not support it.
type	`command_response`, `credentials`, `event`, `registration`, `telemetry`, `tenant`	The type of message that the metric is being reported for.

Additional tags for hono.connections.attempts:

Name	Value	Description
cipher-suite	string	The name of the cipher suite that is used for the device’s connection to the adapter. The specific value depends on the TLS implementation used by the protocol adapter. The value `UNKNOWN` is used if the connection does not use TLS or the cipher suite could not be determined, e.g. because the connection attempt failed before the cipher suite has been negotiated.
outcome	`adapter-disabled`, `connection-duration-exceeded`, `data-volume-exceeded`, `registration-assertion-failure`, `succeeded`, `tenant-connections-exceeded`, `unauthorized`, `unavailable`, `unknown`	The outcome of a device’s connection attempt. `adapter-connections-exceeded` indicates that the maximum number of connections that the adapter instance can handle are exceeded `adapter-disabled` indicates that the protocol adapter is not enabled for the device’s tenant `connection-duration-exceeded` indicates that the overall amount of time that a tenant’s devices may be connected to an adapter has exceeded `data-volume-exceeded` indicates that the overall amount of data that a tenant’s device may transfer per time period has exceeded `registration-assertion-failure` indicates that the device is either unknown or disabled `succeeded` indicates a successfully established connection `tenant-connections-exceeded` indicates that the maximum number of devices that may be connected simultaneously for a tenant has been exceeded `unauthorized` indicates that the device failed to authenticate `unavailable` indicates that some of Hono’s (required) services are not available `unknown` indicates an unknown reason.

Additional tags for hono.amqp.delivery.duration:

Name	Value	Description
outcome	`received`, `accepted`, `rejected`, `released`, `modified`, `declared`, `transactionalState`, and `aborted`	Any of the AMQP 1.0 disposition states, as well as `aborted`, in the case the connection/link was closed before the disposition could be read.

Metrics provided by the protocol adapters are:

Metric	Type	Tags	Description
hono.amqp.delivery.duration	Timer	host, component-type, component-name, tenant, type, outcome	The time it took to send an AMQP 1.0 message and receive the remote peers disposition.
hono.amqp.nocredit	Counter	host, component-type, component-name, tenant, type	The number of times an AMQP 1.0 message should be sent, but could not because the sender was out of credit.
hono.amqp.timeout	Counter	host, component-type, component-name, tenant, type	The number of times sending an AMQP 1.0 message timed out, meaning that no disposition was received in the appropriate amount of time.
hono.command.payload	DistributionSummary	host, component-type, component-name, tenant, type, status, direction	The number of bytes conveyed in the payload of a command message.
hono.command.processing.duration	Timer	host, component-type, component-name, tenant, type, status, direction	The time it took to process a message conveying a command or a response to a command.
hono.connections.authenticated	Gauge	host, component-type, component-name, tenant	Current number of connected, authenticated devices. NB This metric is only supported by protocol adapters that maintain connection state with authenticated devices. In particular, the HTTP adapter does not support this metric.
hono.connections.unauthenticated	Gauge	host, component-type, component-name	Current number of connected, unauthenticated devices. NB This metric is only supported by protocol adapters that maintain connection state with authenticated devices. In particular, the HTTP adapter does not support this metric.
hono.connections.authenticated.duration	Timer	host, component-type, component-name, tenant	The overall amount of time that authenticated devices have been connected to protocol adapters. NB This metric is only supported by protocol adapters that maintain connection state with authenticated devices. In particular, the HTTP adapter does not support this metric.
hono.connections.attempts	Counter	host, component-type, component-name, tenant, outcome, cipher-suite	The number of attempts made by devices to connect to a protocol adapter. The outcome tag’s value determines if the attempt was successful or not. In the latter case the outcome also indicates the reason for the failure to connect. NB This metric is only supported by protocol adapters that maintain connection state with authenticated devices. In particular, the HTTP adapter does not support this metric.
hono.telemetry.payload	DistributionSummary	host, component-type, component-name, tenant, type, status	The number of bytes conveyed in the payload of a telemetry or event message.
hono.telemetry.processing.duration	Timer	host, component-type, component-name, tenant, type, status, qos, ttd	The time it took to process a message conveying telemetry data or an event.

Minimum Message Size

If a minimum message size is configured for a tenant, then the payload size of the telemetry, event and command messages are calculated in accordance with the configured value and then reported to the metrics by the AMQP, HTTP and MQTT protocol adapters. If minimum message size is not configured for a tenant then the actual message payload size is reported.

Assume that the minimum message size for a tenant is configured as 4096 bytes (4KB). The payload size of an incoming message with size 1KB is calculated as 4KB by the protocol adapters and reported to the metrics system. For an incoming message of size 10KB, it is reported as 12KB.

Service Metrics

Authentication Server

Metric	Type	Tags	Description
hono.authentication.attempts	Counter	host, component-type, component-name, outcome, client-type	The number of attempts made by clients to authenticate to the server. The outcome tag’s value determines if the attempt was successful or not: `succeeded` indicates that the client has been authenticated successfully, `unauthorized` indicates that the client failed to authenticate, e.g. because of wrong credentials and `unavailable` indicates that some of the services required for verifying the client’s credentials are (temporarily) not available. The client-type tag indicates what type of client has attempted to authenticate: `auth-service` indicates that the client tried to use the server as an implementation of the Hono Authentication Service, `dispatch-router` indicates that the client tried to use the server as an implementation of the Qpid Dispatch Router AuthService. `unknown` indicates that the type of client is unknown.

Command Router

Command messages get first received by the Command Router component and then get forwarded to the matching protocol adapter instance, where the command will be reflected in the corresponding protocol adapter metrics with the hono.command prefix. If the command could not be forwarded to a protocol adapter, the Command Router will report the command in its metrics, as listed below.

Metric	Type	Tags	Description
hono.command.payload	DistributionSummary	host, component-type, component-name, tenant, type, status, direction	The number of bytes conveyed in the payload of a command message that could not be forwarded to a protocol adapter.
hono.command.processing.duration	Timer	host, component-type, component-name, tenant, type, status, direction	The time it took to process a message conveying a command that could not be forwarded to a protocol adapter.

Device Registry

Metric	Type	Tags	Description
hono.tenants.total	Gauge	host, component-type, component-name	The total number of tenants registered. All registry instances will report the same (total) number of tenants so no aggregation along the host dimension should be performed.