Using the CLI¶
The command line interface allows you to interact with the database in a number of ways.
Location of the CLI Script¶
The CLI script is located in the bin/
directory and is called bin/pattoo_cli.py
.
Running the CLI script without any parameters will display the usage options as seen below.
$ bin/pattoo_cli.py
usage: pattoo_cli.py [-h] {show,create,set,import,assign} ...
This program is the CLI interface to configuring pattoo
positional arguments:
{show,create,set,import,assign}
show Show contents of pattoo DB.
create Create entries in pattoo DB.
set Show contents of pattoo DB.
import Import data into the pattoo DB.
assign Assign contents of pattoo DB.
optional arguments:
-h, --help show this help message and exit
Language¶
pattoo
is meant to support multiple languages. The default language is English with a language code of en
. Agents do not post language specific data, but the keys used to define the data will need to be translated to descriptions that are meaningful to the end user.
Language translation files should be provided with any pattoo agent you install. You may have to create your own translation files for agents that poll data from non-standard data sources.
Viewing Languages¶
To view languages configured in the pattoo
database use the bin/pattoo_cli.py show language
command.
$ bin/pattoo_cli.py show language
idx_language code name
1 en English
Upadating Language Names¶
You can update the name of a language using the bin/pattoo_cli.py set language
command. You must specify the language code and provide a name using the --name
qualifier
$ bin/pattoo_cli.py set language --code 'en' --name 'English (Jamaican)'
In this example we have changed the name to ‘English (Jamaican)’
Creating Languages¶
To create a new language use the bin/pattoo_cli.py create language
command.
$ bin/pattoo_cli.py create language --code 'es' --name 'Spanish'
In this case we create a new language with the name “Spanish” and identifying code “es”
Agents¶
As stated before, pattoo agents
report data to the central pattoo
server.
Viewing Agents¶
To view the agents posting data to the pattoo
server use the bin/pattoo_cli.py show agent
command.
$ bin/pattoo_cli.py show agent
idx_agent agent_program agent_target enabled
1 pattoo_agent_snmp_ifmibd localhost 1
2 pattoo_agent_snmpd localhost 1
3 pattoo_agent_os_autonomousd nada 1
4 pattoo_agent_os_spoked nada 1
Assigning Agents to Key-Pair Translations Groups¶
There are some important things to know first.
1. Each agent has an idx_agent
number that can be seen in the first column of the bin/pattoo_cli.py show agent
command.
1. Each agent group has an idx_pair_xlate_group
number that can be seen in the first column of the bin/pattoo_cli.py show key_translation
command.
To assign an agent
to an agent group
use the bin/pattoo_cli.py assign agent
command.
$ bin/pattoo_cli.py assign agent --idx_agent 2 --idx_pair_xlate_group 4
In this case we have assigned agent with an idx_agent
agent number of 2
to the idx_pair_xlate_group
group number 4
Key-Pair Translations¶
Agents only post key-value pairs to the pattoo
server. Translations are short descriptions of what each key means. The aim is for you to see these descriptions instead of the keys when you look at pattoo
data with the pattoo-web
UI.
When a translation for a key reported by an agent
is installed, the translation is seen in pattoo-web
instead of the key itself. This makes pattoo
data more meaningful.
You don’t have to install translations for every agent
that reports data. You just have to assign agents
to agent groups
, then you assign a single set of translations to the agent group
.
Viewing Agent Group Key-Pair Translation Assignments¶
You can view these agent group
to translation group
assignments using the bin/pattoo_cli.py show key_translation_group
command.
$ bin/pattoo_cli.py show key_translation_group
idx_pair_xlate_group translation_group_name enabled
1 Pattoo Default 1
2 IfMIB Agents 1
3 OS Agents 1
Creating Translation Groups¶
To create a new translation group use the bin/pattoo_cli.py create key_translation
command.
$ bin/pattoo_cli.py create key_translation --name "Stock Market Symbol Translations"
In this case we create a new translation group with the name “Stock Market Symbol Translations”
Upadating Translation Group Names¶
You can update the name of a translation group using the bin/pattoo_cli.py set key_translation_group
command. You must specify the group’s idx_pair_xlate_group
value and a name.
$ bin/pattoo_cli.py set key_translation_group --idx_pair_xlate_group 20 --name 'New Translation Group Name'
In this example we have changed the name to ‘New Translation Group Name’ for idx_pair_xlate_group
20.
Viewing Agent Key-Pair Translation Groups¶
To view translation groups use the bin/pattoo_cli.py show key_translation
command.
$ bin/pattoo_cli.py show key_translation
idx_pair_xlate_group name language key translation units enabled
1 Pattoo Default 1
2 IfMIB Agents en pattoo_agent_snmp_ifmibd_ifalias Interface Alias 1
en pattoo_agent_snmp_ifmibd_ifdescr Interface Description
en pattoo_agent_snmp_ifmibd_ifhcinbroadcastpkts Interface Broadcast Packets (HC inbound) Packets / Second
en pattoo_agent_snmp_ifmibd_ifhcinmulticastpkts Interface Multicast Packets (HC inbound) Packets / Second
...
...
...
3 OS Agents en pattoo_agent_os_autonomousd_cpu_frequency CPU Frequency Frequency 1
en pattoo_agent_os_autonomousd_cpu_stats_ctx_switches CPU (Context Switches) Events / Second
en pattoo_agent_os_autonomousd_cpu_stats_interrupts CPU (Context Switches) Events / Second
en pattoo_agent_os_autonomousd_cpu_stats_soft_interrupts CPU (Soft Interrupts) Events / Second
en pattoo_agent_os_autonomousd_cpu_stats_syscalls CPU (System Calls) Events / Second
Creating Agent Key-Pair Translation Group CSV Files¶
Creating a CSV key-pair translation file is easy. Follow these steps.
Make sure the first row has the following headings separated by commas.
language,key,translation,units
Each subsequent row must have values that correspond to the headings. Each value must be separated by a comma.
1. The
language
must correspond to the language configured in yourpattoo.yaml
configuration file.pattoo-web
will only evaluate translation entries that match to the configured language. 1. Thekey
value must correspond to any expected keys from key-value pairs reported by an agent. 1. Thetranslation
must correspond to the brief text you want to use to describe thekey
1. Theunits
value is used to let users know the unit of measure to be used for the data being tracked by thekey
language,key,translation,units en,pattoo_agent_os_spoked_disk_io_write_bytes,Disk I/O (Bytes Written),Bytes / Second en,pattoo_agent_os_spoked_disk_io_write_count,Disk I/O (Write Count),Writes / Second en,pattoo_agent_os_spoked_disk_io_write_merged_count,Disk I/O (Write Merged Count),Writes / Second en,pattoo_agent_os_spoked_disk_io_write_time,Disk I/O (Write Time), en,pattoo_agent_os_spoked_disk_partition,Disk Partition, en,pattoo_agent_os_spoked_disk_partition_device,Disk Partition,
Not all key-value pairs will need
units
. For example,agent
metadata won’t have them. In this case don’t put a value forunits
and end the line with a comma (,
). The previous example shows three lines of translations includingunits
followed by three withoutunits
.
Importing Agent Key-Pair Translation Group Files¶
There are some important things to know first.
1. Each translation group
has an idx_pair_xlate_group
number that can be seen in the first column of the bin/pattoo_cli.py show key_translation_group
command.
1. The translations for the translation group
must be in a CSV file formatted according to the guidelines mentioned previously.
To import a translation file’s data and assign it to a translation group
use the bin/pattoo_cli.py import key_translation
command.
$ bin/pattoo_cli.py import key_translation --idx_pair_xlate_group 7 --filename agent_name_1_english.csv
In this case we have imported translations from a file named agent_name_1_english.csv
and assigned it to a translation group
with an idx_pair_xlate_group
number of 7
.
You only need to import translations for the key-pairs you require. Any previously existing translation for an key-pair configured in the file will be updated. key-pairs not in the file will not be updated.
Agent Translations¶
Not only do an agent’s key-pairs need translations, but the agents themselves need translations too. This is because an agent
only reports its name when posting which, through translations, allows pattoo
to be more flexible in supporting many different spoken languages.
Without translations, all references to a pattoo
agent will just be by its name, which could be confusing.
Viewing Agent Translations¶
To view agent translations use the bin/pattoo_cli.py show agent_translation
command.
$ bin/pattoo_cli.py show agent_translation
language agent_program translation enabled
en pattoo_agent_os_autonomousd Pattoo Standard OS Autonomous Agent 1
pattoo_agent_os_spoked Pattoo Standard OS Spoked Agent
pattoo_agent_snmpd Pattoo Standard SNMP Agent
pattoo_agent_snmp_ifmibd Pattoo Standard IfMIB SNMP Agent
pattoo_agent_modbustcpd Pattoo Standard Modbus TCP Agent
pattoo_agent_bacnetipd Pattoo Standard BACnet IP Agent
Creating Agent Translation CSV Files¶
Creating a CSV agent translation file is easy. Follow these steps.
Make sure the first row has the following headings separated by commas.
language,key,translation
Each subsequent row must have values that correspond to the headings. Each value must be separated by a comma.
1. The
language
must correspond to the language configured in yourpattoo.yaml
configuration file.pattoo-web
will only evaluate translation entries that match to the configured language. 1. Thekey
value must correspond to the name of an agent. 1. Thetranslation
must correspond to the brief text you want to use to describe thekey
language,key,translation
en,pattoo_agent_os_autonomousd,Pattoo Standard OS Autonomous Agent
en,pattoo_agent_os_spoked,Pattoo Standard OS Spoked Agent
en,pattoo_agent_snmpd,Pattoo Standard SNMP Agent
en,pattoo_agent_snmp_ifmibd,Pattoo Standard IfMIB SNMP Agent
en,pattoo_agent_modbustcpd,Pattoo Standard Modbus TCP Agent
en,pattoo_agent_bacnetipd,Pattoo Standard BACnet IP Agent
Importing Agent Translation Files¶
To import an agent translation file’s data use the bin/pattoo_cli.py import agent_translation
command.
$ bin/pattoo_cli.py import agent_translation --filename agent_name_translation_english.csv
In this case we have imported translations from a file named agent_name_translation_english.csv
.
You only need to import translations for the agents
you require. Any previously existing translation for an agent
configured in the file will be updated. agents
not in the file will not be updated.