Metric actions#

Metric processors support the concept of actions, that can interfere with how (and if) a signal is created. A transformation consists of two parts:

1. The condition (When) - Checks whether a generated metric signal matches certain conditions
2. The action (Then) - Executes an action when the condition is met.

Transformations will be executed after the signal is generated, but before a value converter or a name formatter is applied..

The condition#

A condition consists of an expression that must evaluate to true to pass the test. The expression gets the following variables set:

The action#

The transformation action, will set properties on the signal, when the condition returned true. It consists of the following properties, properties that are not set, will keep their original state:

Example#

Let’s have a look at the following example. We get a message that contains different information from different kind of sensors and additionaly a unit for the temperature measurement:

1
2
3
4
5
6
7
8
9

{
   data:
   {
      Temperature: 42,
      Temperature_B: 39,
      Pressure: 12,
      TemperatureUnit: "C"
   }
}

We want this to be automatically parsed using a ParseAs command, but we want all temperatures to be in °C. So we set the unit accordingly. In case the temperature unit is reported as °F we will convert the value to °C using a ValueConverter:

 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

Processors:
  - Name: "Action demo"
    Description: "Sets the unit to all temperature values and converts °F in °C if needed."
    Mqtt: 
      Subscriptions:
        - Topic: "#"
    Otel:
      Metrics:
        - Instrument: Gauge
          ParseAs: 
             Type: Json
             NameOnly: true
          Actions:
              - Name: "Skip TemperatureUnit field"
                When:
                    - "[Name] == 'TemperatureUnit' "
                Then:
                    Ignore: true
              -  Name: "Convert to Celsius if Fahrenheit is reported and name contains Temp."
                 When:
                    - "JsonPath('$.data.TemperatureUnit') == 'F' "
                    - " Contains([Name], 'Temp') "
                 Then:
                    ValueConverter: "([Value] -32) * 5.0/9.0"
              -  Name: "Set unit to Celsius for all signals with the term Temp in its name"
                 When:
                    - " Contains([Name], 'Temp') "
                 Then:
                    Unit: "C"

Processing pipeline#

To understand actions in detail it is important to understand how the processing pipeline works:

• First the received message is preprocessed by the processor, so a name, a unit, a description, the type and the value is created
• Then the actions are applied, if the When Condition is successful. If any action return Ignore: true, no further actions are applied.
• After all actions are applied the signal name is formatted using the NameFormatter.
• Then the signal value is converted using the ValueConverter.
• Then the metric is send.

---
config:
  flowchart:
    curve: stepAfter
---

flowchart TD
    received(Message received) --> PreProcessMessage

    subgraph PreProcessMessage[Pre process signal]
        direction TB
        evaluate(Evaluate expressions)
        evaluate --> name(Name)
        evaluate --> description(Description)
        evaluate --> unit(Unit)
        evaluate --> type(SignalDataType)
        evaluate --> value(Value)
        evaluate --> attributes(Attributes)

    end

    subgraph ApplyActions[Apply actions]
        direction TB
        evaluateConidition(Start evaluating action)
        evaluateConidition --> when{When condition met?}
        when -->|true| action(Apply Then action)
        when -->|false| next{Next action available AND NOT Then.Ignore?}
        next -->|true| evaluateConidition
        action --> next
    end

    PreProcessMessage --> ApplyActions
    ApplyActions --> nameFormatter(Apply NameFormatter)
    nameFormatter --> valueConverter(Apply ValueConverter)
    valueConverter --> createMetric(Create metric)

When changing the attributes of a pre processed signal the pipeline is as following:

---
config:
  flowchart:
    curve: stepAfter
---

flowchart TD
    clear(ClearAttributes) --> remove(RemoveAttributes) --> add(AddAttributes)

So attributes added via AddAttributesare never removed by either ClearAttributes or RemoveAttributes.