This pack interfaces with the InfluxDB REST API. Actions are available to both query for and write data to an InfluxDB instance. This pack utilizes InfluxDB terminology, for more information we suggest reviewing the key concepts and the glossery of terms.
Copy the example configuration in influxdb.yaml.example
to /opt/stackstorm/configs/influxdb.yaml
and edit as required.
server
- The hostname/IP of the default InfluxDB server.port
- Port number to connect to InfluxDB on (default: 8086)ssl
- Use SSL/HTTPSverify_ssl
- Verify remote host SSL certificatescredentials
- Mapping of name to an object containing credential informationusername
- User to authenticate aspassword
- Password to authenticate with.
Note : All actions allow you to specify a credentials
parameter that will
reference the credentials
information in the config. Alternatively
all actions allow you to override these credential parameters so a
config isn't required.
Note : When modifying the configuration in /opt/stackstorm/configs/
please
remember to tell StackStorm to load these new values by running
st2ctl reload --register-configs
Most options in the config are simply key/value pairs, with the exception of credentials
.
In order to make working with the InfluxDB pack easier, we've provided a mechanism to
store credentials in the pack's config. Credentials are stored as a dictionary, sometimes
called a hash, where the key is the name of the credential and the values are
the credential information (username, password, etc).
Below is an example of a simple config with a single credential named dev
:
credentials:
dev:
username: 'test_user'
password: 'myPassword'
Multiple credentials can also be specified:
credentials:
dev:
username: 'test_user'
password: 'myPassword'
qa:
username: 'qa_user'
password: 'xxxYYYzzz!!!'
prod:
username: 'prod_user'
password: 'lkdjfldsfjO#U)R$'
These credentials can then be referenced by name when executing a influxdb
pack action
using the credentials
parameter available on every action. Example:
# use login information from the "dev" credential stored in the config
st2 run influxdb.query query="select * from my_measurement" server="influxdb.domain.tld" credentials="dev"
If a credential parameter is not specified, then we will attempt to lookup a credential
with the name of default
. This allows end users to specify a default set of credentials
to be used via the config.
Example config:
credentials:
default:
username: 'default_user'
password: 'abc123'
Example command using default credentials
# use login information from the "default" credential stored in the config because
# the credentials parameter was not pass in
st2 run influxdb.query query="select * from my_measurement" server="influxdb.domain.tld"
The configuration below is an example of what a end-user config might look like.
One of the most common config options will most likely be the modulepath
, that will
direct bolt
at the place where they've installed their Puppet modules.
---
server: influxdb.domain.tld
port: 443
ssl: true
verify_ssl: true
credentials:
default:
username: 'myuser'
password: 'secretSauce!'
ping
- Use this endpoint to check the status of your InfluxDB instance and your version of InfluxDB. /pingquery
- Query data and manage databases,retention policies and users. /querywrite
- Use this endpoint to write data to a pre-existing database. /write
Ping a InfluxDB instance and check its status and version.
$ st2 run influxdb.ping server=influxdb.domain.tld
.
id: 5bc7dfb69387ef0673b72741
status: succeeded
parameters:
server: influxdb.domain.tld
result:
exit_code: 0
result: 1.6.4
stderr: ''
stdout: ''
Run an arbitrary query using the InfluxQL syntax.
$ st2 run influxdb.query query="show databases" server=influxdb.domain.tld
id: 5bc7eb9f9387ef0673b72754
status: succeeded
parameters:
query: show databases
server: influxdb.domain.tld
result:
exit_code: 0
result:
- series:
- columns:
- name
name: databases
values:
- - _internal
- - exampledb
statement_id: 0
stderr: ''
stdout: ''
Writes data into an InfluxDB database measurement
.
The data can be passed in one of two ways:
- Using navive arrays and object in the
points
paramter - Using a raw string where data is in the Line Protocol Format in the
points_raw
parameter.
When writing data into InfluxDB from StackStorm, the logical way to do this is using
native arrays and objects within StackStorm. To do this pass an array of objects
to the points
parameter. This array of objects should have the following schema:
points:
type: array
items:
type: object
paramters:
measurement:
type: string
description:
Name of the measurement
tags:
type: object
description:
Object containing tags where the key is the tag name and the value
is the tag value.
time:
type: string OR integer
description:
Can either be the timestamp string (ISO format) or an integer
containing the epoch time.
fields:
type: object
description:
Object containing field values where the field name is the key
and the value is the data.
Example points array (YAML):
- measurement: "meas"
tags:
tag1: "t1"
time: 1234
fields:
value: 43
Example points array (JSON):
[
{
"measurement": "meas",
"tags":
{
"tag1": "t1"
},
"time": 1234,
"fields":
{
"value": 43
}
}
]
Example of using the points
parameter:
$ st2 run influxdb.write points='[{"measurement": "meas", "tags": {"tag1": "t1"}, "time": 1234, "fields": {"value": 43}}]' database=exampledb server=influxdb.domain.tld
.
id: 5bc7e67a9387ef0673b7274e
status: succeeded
parameters:
database: exampledb
points:
- fields:
value: 43
measurement: meas
tags:
tag1: t1
time: 1234
server: influxdb.domain.tld
result:
exit_code: 0
result: true
stderr: ''
stdout: ''
Alternatively you can create a string with raw data points, encoded in the InfluxDB
Line Protocol Format.
To utilize this raw format, pass your string into the in the points_raw
parameter.
Example Line Protocol Format points:
meas,tag1=t1 value=43i 1234
Example writing points using the raw Line Protocol Format:
$ st2 run influxdb.write points_raw="meas,tag1=t1 value=43i 1234" database=exampledb server=influxdb.domain.tld
.
id: 5bc7f2069387ef0673b72784
status: succeeded
parameters:
database: exampledb
points_raw: meas,tag1=t1 value=43i 1235
server: influxdb.domain.tld
result:
exit_code: 0
result: true
stderr: ''
stdout: ''