Processors#

A processor is responsible for

• parsing a mqtt message payload
• enriching and transforming the data
• translating the data to metrics or logs
• sending the data to an otel endpoint.

The basic structure#

A simple processor will look like this:

1Processors:
2  - Name: "Example processor"
3    Description: "Provides sensor info from power sensors."
4    Mqtt: 
5      ...
6    Otel:
7      ...

The Processor consists of the following parameters:

The Mqtt section#

The Mqttsection defines the payloads that should be processed by the processor. It subscribes to mqtt topics can add variables to the subscriptions and can apply transformation expressions to the payload, before it reaches the otel processor.

A simple example for the mqtt would look like this:

 1    Mqtt: 
 2      Name: "My mqtt configuration"
 3      Variables:
 4        - Key: "MyVariable"
 5          Value: "42"
 6      Subscriptions:
 7        - Name: "My subscription"
 8          Topic: "sub-topic"
 9      SubscriptionGroups:
10        - Name: "Tasmota Plugs"

It consists of the following parameters:

The processor will subscribe to all subscriptions (and subscription groups) in the Mqtt section. When a message for one of the subscriptions is received the message is transformed (if Transform is set) and afterwards the Otel section will be executed.

The Otel section#

Basics#

The Otelsection defines how the payloads will be processed, enriched and then send as logs or metrics to an open telemetry endpoint.

A simple example for the Otel would look like this:

 1    Otel:
 2      Name: "My otel section"
 3      Attributes:
 4        - Key: SensorName
 5          Value: $SensorName
 6        - Key: DeviceName
 7          Value: $DeviceName
 8      Metrics:
 9        ...
10      Logs:
11        ...

It consists of the following parameters:

The Otel metrics section#

When a mqtt message payload is received and a Metric section exists it will create an open telemetry metric for the given payload.

It consists of the following parameters:

Example:#

1      Metrics:
2        - Name: "Energy_Power_W"
3          Description: "The current power consumption at the time of measurement in Watt."
4          SignalDataType: Float
5          Instrument: Gauge
6          Unit: "W"
7          Value: "JSONPATH('$.ENERGY.Power')"

Otel instruments#

Most instruments support a synchronous and an asynchronous mode. Synchronous instruments will be send directly to the otel endpoint, while asynchronous instruments will be collected by the endpoint at the configured sample rate.

The following open telemetry instruments are supported:

Otel data types#

The otel processor supports the following metric data types:

• Float
• Int
• Double
• Long
• Decimal
• String

Histogram bucket boundaries#

When using a histogram instrument you can explicitly set the bucket boundaries for the instrument.

Example:

1          HistogramBucketBoundaries:
2            - 0
3            - 0.5
4            - 0.8
5            - 1

The Otel logs section#

Basics#

When a mqtt message payload is received and a Logs section exists it will create an open telemetry log entry for the given payload.

It consists of the following parameters:

Example:#

1      Logs:
2        - Name: "Logging"
3          PayloadType: Json
4          Transform: "GROK('%{TIME:otel_timestamp} %{WORD:category}: %{GREEDYDATA:otel_message}')"

PayloadType Json#

Whe using the payload type Json the created json parameters will be interpreted as attributes, that are added to the log message. Some parameters (starting with otel_) have a special meaning and are not treated as attributes:

The following json message:

1{
2  "otel_timestamp": "2026-02-26T10:28:34Z",
3  "otel_loglevel": "Info",
4  "server_name": "ServerA",
5  "otel_message": "Temperature value read successfully."
6}

will be send as a log message send with timestamp 2026-02-26T10:28:34Z, loglevel Info and message body Temperature value read successfully. The attribute server_name with the value ServerA will be added to the message.