Quick start#

Installation#

See the Installation overview.

Connect to the MQTT Broker and Otel Server#

The mapping between MQTT and OpenTelemetry is defined in a configuration file called Manifest.yaml.
Below is an example of a minimal configuration that connects to an MQTT broker at
http://mymqtt-broker.net:32007 and an OpenTelemetry collector at
http://my-otel-collector.net:32014:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

Version: 1.0

MqttConnections:
  - Name: "My broker"
    Endpoint:
      Port: 32007
      Address: "mymqtt-broker.net"
      EnableTls: false

OtelConnections:
  - Name: "My Otel server"
    ServiceName: "my-service"
    ServiceNamespace: "my-service-namespace"
    Endpoint:
      Protocol: "http"
      Port: 32014
      Address: "my-otel-collector.net"
      EnableTls: false

This example assumes that neither the MQTT broker nor the Otel collector requires authentication.
For additional configuration options, see Configure MQTT Broker and Configure Otel Server.

Breakdown of the configuration#

• MQTT Broker

  • Name: A unique identifier for the MQTT broker.
  • Endpoint: The broker’s address and port.

• Otel Connections

  • Name: A unique identifier for the Otel connection.
  • ServiceName: The name of the service.
  • ServiceNamespace: The namespace of the service.
  • Endpoint: The collector’s address and port.

Subscribe to a Topic and Generate a Metric#

After connecting to the MQTT broker and Otel server, you can subscribe to an MQTT topic and generate an Otel metric from incoming messages.

Assume the server publishes messages to the topic sensor/1234/data in the following JSON format:

1
2
3
4
5
6
7

{
   Data:
   {
      Temperature: 42,
      Angle: 32
   }
}

You can parse this payload using the processor below, which automatically creates metric signals based on the JSON structure:

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

Processors:
  - Name: "Processor Temperature"
    Description: "Automatically parses a Json payload."
    Mqtt: 
      Subscriptions:
        - Topic: "sensor/+/data"
    Otel:
      Metrics:
        - Instrument: Gauge
          ParseAs: 
             Type: Json

This configuration subscribes to the MQTT topic sensor/1234/data and generates two Otel Gauge metrics:
Data.Temperature and Data.Angle. The data types are detected automatically.

The syntax works as follows:

• Processors contains a list of processors. Each processor receives MQTT messages, processes them, and sends the results to the configured Otel endpoint.
• A processor consists of two parts:
  • Mqtt
    • A list of MQTT topic subscriptions, each with:
      • A name
      • The topic to subscribe to
  • Otel
    • ParseAs: Defines how the processor interprets the MQTT payload:
      • Type: The payload type, e.g., Json
      • NameOnly: If true, hierarchy is removed from the signal name.
        For example, instead of Data.Temperature, the metric becomes Temperature.
      • Separator: Defines the separator for hierarchy levels.
        For example, _ turns Data.Temperature into Data_Temperature.

Did you know?

Have you noticed the explorer icon on the upper right corner of the example code? If you click on it, you will be redirected to the mqtt2otel explorer, where you can play around with the examples and inspect the generated output.

You can further adjust names using NameFormatter, and you can convert values—for example, to a different unit.

Given the following payload:

1
2
3
4
5
6

{
   Processor:
   {
      Temperature: 212
   }
}

You can convert the value from °F to °C and format the metric name in camel case using this processor:

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

Processors:
  - Name: "Use name formatter and value converter"
    Description: "Renames the signal name be using camel case and converts the value from fahrenheit to celsius."
    Mqtt: 
      Subscriptions:
        - Topic: "sensor/temperature/+"
    Otel:
      Metrics:
        - Instrument: Gauge
          NameFormatter: "ToCamelCase([Name])"
          ValueConverter: "([Value] -32) * 5/9"
          ParseAs: 
             Type: Json

For more details, refer to the documentation.

Working with Expressions#

In the previous example, we used expressions to convert values and format names.
Expressions are a central and powerful concept in the application, allowing you to adjust generated signals in many ways.

Expressions support standard mathematical operations (+, -, *, /), functions such as SQRT, Sin, Cos, Tan, and constants like [Pi] or [e].

For more details, see the documentation.

If you need to adjust signals based on complex conditions, refer to conditional actions, which are beyond the scope of this quickstart.

Manually creating a metric#

If your payload cannot be parsed automatically, or if you need fine‑grained control over the generated signal, you can define metrics manually.

Assume the server publishes messages to the topic in this JSON format:

1
2
3
4
5
6
7

{
    "Processor": 
    {
        "Temperature": 42
    },
    "TempUnit": "C"
}

To extract the temperature, use the JSONPath expression $.Processor.Temperature.
The corresponding YAML looks like this:

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

Processors:
  - Name: "Processor Temperature"
    Description: "Provides the current processor temperature."
    Mqtt: 
      Subscriptions:
        - Topic: "sensor/+/data"
    Otel:
      Metrics:
        - Name: "Processor.Temperature"
          Description: "The current processor temperature."
          Instrument: Gauge
          SignalDataType: Double
          Unit: "C"
          Value: "JSONPATH('$.Processor.Temperature')"

This configuration subscribes to the MQTT topic and creates an Otel metric called Processor.Temperature with:

• a float signal data type is explicitly set, instead of the autodetected integer.
• a Gauge instrument
• a Unit of type C
• a value extracted from the JSON payload

Each time a message arrives on the topic, the temperature is parsed and sent to the Otel endpoint.

The syntax works as follows:

• Processors contains a list of processors.
• A processor consists of:
  • Mqtt
    • A list of topic subscriptions, each with:
      • A name
      • The topic
  • Otel
    • A list of metrics to generate from the payload, each with:
      • Name and description
      • Data type
      • Instrument
      • Value expression
      • Unit

Variables and Attributes#

Subscriptions can define variables that you can later use in rules.
Here is an example:

1
2
3
4
5
6
7
8
9

Processors:
    - Name: "Processor 1"
      Mqtt:
        Subscriptions:
          - Name: "Processor information"
            Topic: "metric/sensor_1234"
            Variables:
              - Key: "SensorName"
                Value: "ProcessorServerA"

Access variables in Otel rules by prefixing them with $. For example, $SensorName.

Otel rules can also include attributes, which are added to the generated signals for filtering or grouping. Variables can be used inside attributes as needed.

Example:

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

Processors:
      - Name: "Processor 1"
        Otel:
          Attributes:
            - Key: SensorName
              Value: $SensorName
            - Key: Location
              Value: "Main server room"
          Metrics:
            - Name: "Processor.Temperature"
              Description: "The current processor temperature."
              Attributes:
                - Key: MeasurementQuality
                  Value: 10
              Instrument: Gauge
              Value: "JSONPATH('$.Processor.Temperature')"

Attributes defined directly under Processor apply to all metrics inside the processor. Attributes defined under a specific metric apply only to that metric.

Resulting Signal Attributes:#

Attributes via message topic#

In addition to manual attributes and variable‑based attributes, you can extract attributes from the MQTT topic itself.

Given a topic like:

1

sensor/germany/1234/data

You can see that the location (germany) and device ID (1234) are encoded in the topic.
The following processor extracts them using the TopicAttributes property:

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

Processors:
  - Name: "Processor Temperature"
    Description: "Create attributes from the mqtt topic."
    Mqtt: 
      Subscriptions:
        - Topic: "sensor/+/+/data"
    Otel:
      Metrics:
        - Name: "Sensor.$(TopicPath('[2]')).Temperature"
          Description: "The current processor temperature."
          Instrument: Gauge
          TopicAttributes: "_/location/device.Id/_"
          Value: "PAYLOAD()"

This produces:

More information about topic parsing is available here.

Attributes via MQTT user properties#

MQTT user properties are automatically converted into OpenTelemetry attributes. To disable this behavior, set CreateAttributesFromUserProperties to false.

To use user properties inside expressions, access them via UserProperty(name). More information about available functions can be found here.

Log Messages and Transformation#

Log messages work similarly to metrics.
Assume you receive a log message payload in this format:

2026-02-26T10:28:34Z [Info] [ServerA] Temperature value read successfully.

Instead of forwarding the raw message to Otel, you can transform it into structured log data using an extended
DISSECT expression:

1

%{otel_timestamp:DateTime} [%{otel_loglevel}] [%{server_name}] %{otel_message}

This expression performs the following steps:

• Parse date and time → otel_timestamp
• Read a space and [ → discard
• Read everything until ] → otel_loglevel
• Read ] [ → discard
• Read everything until ] → server_name
• Read ] [ → discard
• Read the remaining message → otel_message

You can use this expression inside a Transform rule in the Logs section:

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

Processors:
  - Name: "Server logs"
    Description: "Collect all log messages from the server."
    Mqtt:
      Subscriptions:
        - Name: "Server logs"
          Topic: "message-log-topic"
    Otel:
      Attributes:
        - Key: Location
          Value: MainServerRoom
      Logs:
        - Name: "Logging"
          PayloadType: Json
          Transform: "DISSECT('%{otel_timestamp} [%{otel_loglevel}] [%{server_name}] %{otel_message}')"

Note that the Logs keyword is used to identify log messages.
The Transform expression converts the log into a JSON structure like:

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."
}

Since PayloadType: Json is specified, Otel interprets the top‑level keys as log attributes. Attributes starting with otel_ have special meaning and are interpreted as the message body, timestamp, and log level.

You can also explicitly set the timezone of the parsed log entry:

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

Processors:
  - Name: "Server logs"
    Description: "Collect all log messages from the server and interpret timestamp as timezone europe/berlin."
    Mqtt:
      Subscriptions:
        - Topic: "sensor/+/log"
    Otel:
      Attributes:
        - Key: Location
          Value: MainServerRoom
      Logs:
        - PayloadType: Json
          Transform: "DISSECT('%{otel_timestamp:DateTime[Europe/Berlin]} [%{otel_loglevel}] %{otel_message}')"

More information about transformations can be found here.

Where to continue#

If you want to learn more about more complex scenarios, please have a look at the documentation and the examples libraries.

Topics of special interest may be:

• Expressions and transformations
• How to organize complex manifest files
• Working with MQTT user properties
• Conditional metric actions

Complete example manifest#

Below is a complete minimal example manifest using logs and metrics:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

Version: 1.1

MqttConnections:
  - Name: "My broker"
    Endpoint:
      Port: 32007
      Address: "mymqtt-broker.net"
      EnableTls: false

OtelConnections:
  - Name: "My Otel server"
    ServiceName: "my-service"
    ServiceNamespace: "my-service-namespace"
    Endpoint:
      Protocol: "http"
      Port: 32014
      Address: "my-otel-collector.net"
      EnableTls: false

Processors:
  - Name: "Processor Temperature"
    Description: "Automatically parses a Json payload."
    Mqtt: 
      Subscriptions:
        - Topic: "sensor/+/data"
    Otel:
      Metrics:
        - Instrument: Gauge
          Attributes:
            - Key: Location
              Value: MainServerRoom
          ParseAs: 
             Type: Json

  - Name: "Server logs"
    Description: "Collect all log messages from the server."
    Mqtt:
      Subscriptions:
        - Topic: "message-log-topic"
    Otel:
      Attributes:
        - Key: Location
          Value: MainServerRoom
      Logs:
        - Name: "Logging"
          PayloadType: Json
          Transform: "DISSECT('%{otel_timestamp:DateTime} [%{otel_loglevel}] [{server_name}] %{otel_message}')"