A easy to use library for using InfluxDB with PHP.
The influxdb-php library was created to have php port of the python influxdb client. This way there will be a common abstraction library between different programming languages.
Installation can be done with composer:
composer require influxdb/influxdb-php:dev-master
If you use either PHP 5.3 and PHP 5.4, the 0.1.x release is still supported (bug fixes and new release fixes). The 0.1.x branch will work on PHP 5.3 and PHP 5.4 but doesn't contain all the features that the 1.0.0 release has such as UDP support.
Initialize a new client object:
$client = new InfluxDB\Client($host, $port);
This will create a new client object which you can use to read and write points to InfluxDB.
It's also possible to create a client from a DSN (Data Source Name):
// directly get the database object
$database = InfluxDB\Client::fromDSN(sprintf('influxdb://user:pass@%s:%s/%s', $host, $port, $dbname));
// get the client to retrieve other databases
$client = $database->getClient();
To fetch records from InfluxDB you can do a query directly on a database:
// fetch the database
$database = $client->selectDB('influx_test_db');
// executing a query will yield a resultset object
$result = $database->query('select * from test_metric LIMIT 5');
// get the points from the resultset yields an array
$points = $result->getPoints();
It's also possible to use the QueryBuilder object. This is a class that simplifies the process of building queries.
// retrieve points with the query builder
$result = $database->getQueryBuilder()
->select('cpucount')
->from('test_metric')
->limit(2)
->getResultSet()
->getPoints();
// get the query from the QueryBuilder
$query = $database->getQueryBuilder()
->select('cpucount')
->from('test_metric')
->getQuery();
Writing data is done by providing an array of points to the writePoints method on a database:
// create an array of points
$points = array(
new Point(
'test_metric', // name of the measurement
0.64, // the measurement value
['host' => 'server01', 'region' => 'us-west'], // optional tags
['cpucount' => 10], // optional additional fields
1435255849 // Time precision has to be set to seconds!
),
new Point(
'test_metric', // name of the measurement
0.84, // the measurement value
['host' => 'server01', 'region' => 'us-west'], // optional tags
['cpucount' => 10], // optional additional fields
1435255849 // Time precision has to be set to seconds!
)
);
// we are writing unix timestamps, which have a second precision
$result = $database->writePoints($points, Database::PRECISION_SECONDS);
It's possible to add multiple fields when writing measurements to InfluxDB. The point class allows one to easily write data in batches to influxDB.
The name of a measurement and the value are mandatory. Additional fields, tags and a timestamp are optional. InfluxDB takes the current time as the default timestamp.
You can also write multiple fields to a measurement without specifying a value:
$points = [
new Point(
'instance', // the name of the measurement
null, // measurement value
['host' => 'server01', 'region' => 'us-west'], // measurement tags
['cpucount' => 10, 'free' => 1], // measurement fields
exec('date +%s%N') // timestamp in nanoseconds
),
new Point(
'instance', // the name of the measurement
null, // measurement value
['host' => 'server01', 'region' => 'us-west'], // measurement tags
['cpucount' => 10, 'free' => 2], // measurement fields
exec('date +%s%N') // timestamp in nanoseconds
)
];First, set your InfluxDB host to support incoming UDP sockets:
[udp]
enabled = true
bind-address = ":4444"
database = "test_db" Then, configure the UDP driver in the client:
// set the UDP driver in the client
$client->setDriver(new \InfluxDB\Driver\UDP($client->getHost(), 4444));
$points = [
new Point(
'test_metric',
0.84,
['host' => 'server01', 'region' => 'us-west'],
['cpucount' => 10],
exec('date +%s%N') // this will produce a nanosecond timestamp in Linux operating systems
)
];
// now just write your points like you normally would
$result = $database->writePoints($points);Or simply use a DSN (Data Source Name) to send metrics using UDP:
// get a database object using a DSN (Data Source Name)
$database = \InfluxDB\Client::fromDSN('udp+influxdb://username:pass@localhost:4444/test123');
// write your points
$result = $database->writePoints($points); Note: It is import to note that precision will be ignored when you use UDP. You should always use nanosecond precision when writing data to InfluxDB using UDP.
It's important to provide the correct precision when adding a timestamp to a Point object. This is because if you specify a timestamp in seconds and the default (nanosecond) precision is set; the entered timestamp will be invalid.
// Points will require a nanosecond precision (this is default as per influxdb standard)
$newPoints = $database->writePoints($points);
// Points will require second precision
$newPoints = $database->writePoints($points, Database::PRECISION_SECONDS);
// Points will require microsecond precision
$newPoints = $database->writePoints($points, Database::PRECISION_MICROSECONDS);When creating a database a default retention policy is added. This retention policy does not have a duration so the data will be flushed with the memory.
This library makes it easy to provide a retention policy when creating a database:
// create the client
$client = new \InfluxDB\Client($host, $port, '', '');
// select the database
$database = $client->selectDB('influx_test_db');
// create the database with a retention policy
$result = $database->create(new RetentionPolicy('test', '5d', 1, true));
// check if a database exists then create it if it doesn't
$database = $client->selectDB('test_db');
if (!$database->exists()) {
$database->create(new RetentionPolicy('test', '1d', 2, true));
}
You can also alter retention policies:
$database->alterRetentionPolicy(new RetentionPolicy('test', '2d', 5, true));and list them:
$result = $database->listRetentionPolicies();You can add more retention policies to a database:
$result = $database->createRetentionPolicy(new RetentionPolicy('test2', '30d', 1, true));Some functions are too general for a database. So these are available in the client:
// list users
$result = $client->listUsers();
// list databases
$result = $client->listDatabases();- Add more admin features
- More unit tests
- Increase documentation (wiki?)
- Add more features to the query builder
- Add validation to RetentionPolicy
####1.0.0
- -BREAKING CHANGE- Dropped support for PHP 5.3 and PHP 5.4
- Allowing for custom drivers
- UDP support
####0.1.2
- Added exists method to Database class
- Added time precision to database class
####0.1.1
- Merged repository to influxdb/influxdb-php
- Added unit test for createRetentionPolicy
- -BREAKING CHANGE- changed $client->db to $client->selectDB