Manual Configuration

Configuration of the agent using the YAML file

After learning about the different types of scenarios, the available Expect Types and how to format your CSV data, it's time to jump into how to build a scenario using YAML.

The Agent YAML file can be found at

/etc/ardexa/ardexa.yaml

All properties are key/value pairs. Keys should be written as snake_case using all lowercase letters, however Values can use almost any combination of characters from the Unicode character set (UTF-8).

YAML overview

For the purposes of this guide, we will be using only basic types:

• Scalar values: Strings and Numbers

• Lists: sequential list of items

• Maps: group of key/value pairs

YAML uses indentation to indicate nesting.

Strings

Strings can use single or double quotes, or no quotes at all.

example 1
'example 2'
"example 3"

Lists

Each list item is denoted by a hyphen

- one
- 2
- "three"

Maps

Maps are a set of key/value pairs, starting with a key, followed by a colon and a space

key: value
one: 1
two: 2

Nesting

That all combines together when building scenarios

run:
  - table: example
    source: one
    expect: keyword
    command: "echo one"
    frequency: 30
  - table: example
    source: two
    expect: keyword
    command: "echo two"
    frequency: 30

General information

Scenarios are a List of Maps such as the Nesting example above. In this article, we will discuss the simplest Scenario types: RUN (execute a command and process the output) and CAPTURE (monitor a file and treat each new line as a separate record). First we will discuss the structure of a scenario and then discuss the specifics of each Scenario type.

Mandatory items

Table and Source

Table is used to specify which table in the cloud you would like the information to be stored in.

Source is used to identify the "thing" that generated the information stream, e.g. a solar inverter.

Table and Source combine to uniquely identify each scenario, usually presented as table.source. Therefore, full stop cannot be used in Table or Source.

An Agent configuration can have many sources logging to the same Table, or the same Source logging to different tables.

table: solar
source: inverter-01

Expect

Expect identifies the type of information you expect to arrive. The different types are listed here. Generally speaking, we strongly recommend the use of CSV as the primary expect type as it gives users the greatest amount of flexibility and helps to simplify data collection.

expect: csv

Fields (CSV)

The CSV expect type adds a new mandatory property, Fields. Fields is a List of Maps that describes what information will appear in each column. Each entry requires a Name and Expect property, along with Units for Number-based Expect types.

fields:
  - name: one
    expect: date
  - name: two
    expect: keyword 

Units (Numbers)

For Integer and Decimal types, Units are considered mandatory. If you do not want or need units, you still need to provide an entry, so simply use a hash or full stop to indicate that the value should be ignored. Units are nested inside the Meta property.

table: example
source: one
file: /tmp/power.txt
expect: integer
meta:
  units: "kW"

RUN specific properties

Command

This is the command to run. It is passed to a shell for execution, so pipes and redirects are supported

command: 'echo 1,2 >> /tmp/log.csv'

Frequency

An integer representing how often, in seconds, the target command should be executed

frequency: 30

CAPTURE specific properties

Capture is listed as "tail" in the configuration file in reference to the ubiquitous Unix tool of the same name. Like the tail command, Capture scenarios will monitor files for new lines being added to a given file.

File

The absolute path to the file to be monitored. If the file doesn't exist, the agent will wait for it to become available and then start monitoring. If the file is moved, removed, renamed or truncated, the agent will restart it's monitor, ensuring it is always targeting the correct file.

file: /path/to/log.csv

Example

Here is a complete example of a RUN scenario and a CAPTURE scenario working together

# Broker configuration
amqp:
  ...

# Run scenario
run:
  - table: test
    source: run5
    expect: keyword
    command: 'echo 1,2 >> /tmp/run.csv && echo success'
    frequency: 5
  - table: test
    source: run30
    expect: keyword
    command: 'echo 3,4 >> /tmp/run.csv && echo success'
    frequency: 30

# Capture scenario
tail:
  - table: test
    source: tail
    expect: csv
    file: /tmp/run.csv
    fields:
      - name: one
        expect: integer
        meta:
          units: '!'
      - name: two
        expect: integer
        meta:
          units: '@'