Comment on page
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).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 can use single or double quotes, or no quotes at all.
example 1
'example 2'
"example 3"
Each list item is denoted by a hyphen
- one
- 2
- "three"
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
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
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.
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 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
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
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"
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'
An integer representing how often, in seconds, the target command should be executed
frequency: 30
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.
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
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: '@'
Last modified 4yr ago