Mqtt subscriptions and subscription groups#

Configure subscriptions#

To subscribe to a mqtt topic you can use a Subscription section inside a manifst file. It consists of a name and the topic you want to subscribe to.

Example:

1      Subscriptions:
2        - Name: "My subscription name"
3          Topic: "message-topic"
4          Variables:
5            - Key: "SensorName"
6              Value: "MySensor"

It consists of the following parameters:

Subscription Groups#

To avoid repetition and reuse the same subscriptions across different metrics or logs, you can group them into Subscription Groups and refer to them later. This is useful when you have e.g. multiple devices or sensors sending data under the same topic structure but need to handle them differently in your rules.

Example Scenario#

Let’s say you have a device that sends both power consumption metrics (like current, power, voltage) and status information (like the microcontroller core temperature) in the same MQTT message. The message payload is structured as follows:

 1{
 2  "Time": "2026-04-12T09:07:04",
 3  "ENERGY": {
 4    "Power": 0.000,
 5    "Voltage": 227,
 6    "Current": 0.000
 7  },
 8  "ESP32": {
 9    "Temperature": 37.4
10  }
11}

You want to treat power metrics separately from the microcontroller status. To achieve this, you can group the subscriptions into a SubscriptionGroup for reuse:

Defining a Subscription Group#

Example:

 1SubscriptionGroups:
 2  - Name: "Power sensors"
 3    Subscriptions:
 4      - Name: "Power Sensor washing machine"
 5        Topic: "1234"
 6        Variables:
 7          - Key: "SensorName"
 8            Value: "WashingMachine"
 9      - Name: "Power Sensor dryer"
10        Topic: "sensor_9876"
11        Variables:
12          - Key: "SensorName"
13            Value: "Dryer"

A subscription group has the following parameters:

Here, we define a Subscription Group called Power sensors, which includes two subscriptions: one for a washing machine and another for a dryer. Both subscriptions have associated variables that can be used later in the metrics or logs.

Defining Subscription Groups with ParentPath and SubPath#

Sometimes, devices may use different MQTT topics but contain the same identifier. For example, you might have multiple topics for each sensor:

To manage these different topics, you can group them under a common Subscription Group and then specify ParentPath and SubPath to correctly target the topics.

Example:

 1SubscriptionGroups:
 2  - Name: "Power sensors"
 3    Subscriptions:
 4      - Name: "Power Sensor 1"
 5        Topic: "1234"
 6      - Name: "Power Sensor 2"
 7        Topic: "9876"
 8
 9Processors:
10  - Name: "Power Metrics"
11    Description: "Provides power information from a power sensor."
12    Mqtt: 
13      SubscriptionGroups:
14        - Name: "Power sensors"
15          ParentPath: "tele"
16          SubPath: "sensor"
17    Otel:
18      Metrics:
19        - Name: "Energy_Power_W"
20          Description: "The current power consumption at the time of measurement in Watt."
21          SignalDataType: Float
22          Instrument: Gauge
23          Value: "JSONPATH('$.ENERGY.Power')"
24        - ...
25
26  - Name: "Sensor Logs"
27    Description: "Collect all log messages from the sensors."
28    Mqtt:
29      SubscriptionGroups:
30        - Name: "Power sensors"
31          ParentPath: "stat"
32          SubPath: "logs"
33    Otel:
34      Logs:
35        - Name: "Logging"
36          PayloadType: Json
37          Transform: "GROK('%{TIME:otel_timestamp} %{WORD:category}: %{GREEDYDATA:otel_message}')"

Explanation:#

• ParentPath: This specifies the top-level directory or prefix of the topic. For example, tele for telemetry data or stat for status/log data.
• SubPath: This specifies the specific subtopic or suffix that targets a specific part of the topic.

Result:#

• The Power Metrics rule will subscribe to topics like tele_1234_sensor and tele_9876_sensor using the ParentPath tele and SubPath sensor.
• The Sensor Logs rule will subscribe to topics like stat_1234_logs and stat_9876_logs using the ParentPath stat and SubPath logs.