Send metrics to InfluxDB and query for any data.
This project support InfluxDB API >= 0.9
- For InfluxDB v0.8 checkout branch 0.3
Supported adapters:
- HTTP
- UDP/IP
Just use composer
{
"require": {
// ...
"corley/influxdb-sdk": ">=0.4"
}
}
Add new points:
$client->mark("app-search", [
"key" => "this is my search"
]);
Or use InfluxDB direct messages
$client->mark([
"tags" => [
"dc" => "eu-west-1",
],
"points" => [
[
"measurement" => "instance",
"fields" => [
"cpu" => 18.12,
"free" => 712423,
],
],
]
]);
Retrieve existing points:
$results = $client->query('select * from "app-search"');
Actually we supports two network adapters
- UDP/IP - in order to send data via UDP/IP (datagram)
- HTTP JSON - in order to send/retrieve using HTTP messages (connection oriented)
In order to use the UDP/IP adapter your must have PHP compiled with the sockets
extension.
Usage
$options = new Options();
$adapter = new UdpAdapter($options);
$client = new Client($adapter);
Actually Guzzle is used as HTTP client library
<?php
$http = new \GuzzleHttp\Client();
$options = new Options();
$adapter = new GuzzleAdapter($http, $options);
$client = new Client($adapter);
Effectively the client creation is not so simple, for that reason you can you the factory method provided with the library.
$options = [
"adapter" => [
"name" => "InfluxDB\\Adapter\\GuzzleAdapter",
"options" => [
// guzzle options
],
],
"options" => [
"host" => "my.influx.domain.tld",
"db" => "mydb",
"retention_policy" => "myPolicy",
"tags" => [
"env" => "prod",
"app" => "myApp",
],
]
];
$client = \InfluxDB\ClientFactory::create($options);
Of course you can always use a DiC (eg symfony/dependency-injection
) or your service manager in order to create
a valid client instance.
You can query the time series database using the query method.
$influx->query('select * from "mine"');
You can query the database only if the adapter is queryable (implements
QueryableInterface
), actually GuzzleAdapter
.
The adapter returns the json decoded body of the InfluxDB response, something like:
array(1) {
'results' =>
array(1) {
[0] =>
array(1) {
'series' =>
array(1) {
...
}
}
}
}
As you know InfluxDB support UDP/IP with a "line protocol", that is a string line, like:
cpu,region=us-west,env=prod,zone=1c cpu=18.12,free=712432 1257894000
In order to simplify the SDK usage, you will use a single method signature for both adapters, UDP/IP and HTTP:
Concise Format
$client->mark("serie-name", [
"power" => 124.21,
"voltage" => 12.4,
]);
Extended Format
$client->mark([
"tags" => [
"region" => "us-west",
"host" => "serverA",
"env" => "prod",
"target" => "servers",
"zone" => "1c",
],
"time" => "2009-11-10T23:00:00Z",
"points" => [
[
"measurement" => "cpu",
"fields" => [
"cpu" => 18.12,
"free" => 712432,
],
],
],
]);
If you want to use the inline protocol directly you have to use the UDP/IP adapter directly
$udp = new UdpAdapter($options);
$udp->write("cpu,region=us-west,host=serverA,env=prod,target=servers,zone=1c cpu=18.12,free=712432 1257894000");
You can create, list or destroy databases using dedicated methods
$client->getDatabases(); // list all databases
$client->createDatabase("my.name"); // create a new database with name "my.name"
$client->deleteDatabase("my.name"); // delete an existing database with name "my.name"
Actually only queryable adapters can handle databases (implements the
QueryableInterface
)
You can set a set of default tags, that the SDK will add to your metrics:
$options = new Options();
$options->setTags([
"env" => "prod",
"region" => "eu-west-1",
]);
The SDK mark all point adding those tags.
You can set a default retentionPolicy using
$options->setRetentionPolicy("myPolicy");
In that way the SDK use that policy instead of default
policy.
Simple benchmarks executed on a Sony Vaio T13 (SVT1311C5E)
The impact using UDP/IP or HTTP adapters
Corley\Benchmarks\InfluxDB\AdapterEvent
Method Name Iterations Average Time Ops/second
------------------------ ------------ -------------- -------------
sendDataUsingHttpAdapter: [1,000 ] [0.0167509446144] [59.69813]
sendDataUsingUdpAdapter : [1,000 ] [0.0000905156136] [11,047.81773]
As you know the SDK will provide a single interface in order to send data to InfluxDB (concise or expanded).
The impact of message to inline protocol conversion is:
Corley\Benchmarks\InfluxDB\MessageToInlineProtocolEvent
Method Name Iterations Average Time Ops/second
---------------------------------------------------- ------------ -------------- -------------
convertMessageToInlineProtocolWithNoTags : [10,000 ] [0.0000237422466] [42,119.01324]
convertMessageToInlineProtocolWithGlobalTags : [10,000 ] [0.0000306700468] [32,605.10185]
convertMessageToInlineProtocolWithDifferentTagLevels: [10,000 ] [0.0000343942404] [29,074.63543]
To verify if you have the sockets
extension just issue a:
php -m | grep sockets
If you don't have the sockets
extension, you can proceed in two ways:
- Recompile your PHP whith the
--enable-sockets
flag - Or just compile the
sockets
extension extracting it from the PHP source.
- Download the source relative to the PHP version that you on from here
- Enter in the
ext/sockets
directory - Issue a
phpize && ./configure && make -j && sudo make install
- Add
extension=sockets.so
to your php.ini