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:

1
2
3
4
5
6
7

Processors:
  - Name: "Example processor"
    Description: "Provides sensor info from power sensors."
    Mqtt: 
      ...
    Otel:
      ...

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
 2
 3
 4
 5
 6
 7
 8
 9
10

    Mqtt: 
      Name: "My mqtt configuration"
      Variables:
        - Key: "MyVariable"
          Value: "42"
      Subscriptions:
        - Name: "My subscription"
          Topic: "sub-topic"
      SubscriptionGroups:
        - 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
 2
 3
 4
 5
 6
 7
 8
 9
10
11

    Otel:
      Name: "My otel section"
      Attributes:
        - Key: SensorName
          Value: $SensorName
        - Key: DeviceName
          Value: $DeviceName
      Metrics:
        ...
      Logs:
        ...

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:#

Given the following payload:

1
2
3
4
5
6

{
   Processor:
   {
      Temperature: 42
   }
}

We can process this via the following processor:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

Processors:
  - Name: "Read Json payload"
    Description: "Read a single metric from a json payload."
    Mqtt: 
      Subscriptions:
        - Topic: "sensor/+/data"
    Otel:
      Metrics:
        - Name: "Processor.Temperature"
          Description: "The current processor temperature."
          Instrument: Gauge
          Value: "JSONPATH('$.Processor.Temperature')"

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

ParseAs#

The ParseAs property tells the metrics processor to interpret the payload as the provided type and tries to automatically parse it.

It consists of:

• Type: The payload type. Can be either Json or Xml.
• Separator: The separator for hierarchical names. Optional. “.” will be used if no other value is set.
• NameOnly: The created name will usually reflect the full hierarchy (e.g. data.Temperature). If this is not wanted and only the name of the property (e.g. Temperature) should be used, then this value must be set to true.

Be careful#

When the ParseAs property is used, the Name value of the signal will be overridden, even if it is explicitly set. The SignalDataType will be detected automatically. However, if a data type is explicitly defined in the Otel section, that explicit data type will be used for all signals.

When a signal has the signal data type string, it will be ignored, silently!

When using a json type to parse the following payload:

1
2
3
4
5
6
7

{
   MachineA:
   {
      Temperature: 42,
      Pressure: 10
   }
}

Two metrics will be created:

• MachineA.Temperature: 42 (or Temperature: 42 if NameOnly is true)
• MachineA.Pressure: 10 (or Pressure: 10 if NameOnly is true)

Interacting with the created names and values#

You can interact with the ParseAsresults by convert the values using a ValueConverter and formatting the signal name using a NameFormatter.

Histogram bucket boundaries#

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

Example:

1
2
3
4
5

          HistogramBucketBoundaries:
            - 0
            - 0.5
            - 0.8
            - 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
 2
 3
 4
 5
 6
 7
 8
 9
10
11

Processors:
  - Name: "Server logs"
    Description: "Collect all log messages from the server."
    Mqtt:
      Subscriptions:
        - Topic: "sensor/+/log"
    Otel:
       Logs:
         - PayloadType: Json
           Transform: "DISSECT('%{otel_timestamp} [%{otel_loglevel}] [%{server_name}] %{otel_message}')"

PayloadType Json#

When 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
3
4
5
6

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

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.