PHP DataDog StatsD Client

This is an extremely simple PHP datadogstatsd client. Requires PHP >= 5.3.0.

For a Laravel-specific implementation that wraps this library, check out laravel-datadog-helper.

Installation

Composer

Add the following to your composer.json:

"datadog/php-datadogstatsd": "1.3.*"

Note: The first version shipped in composer is 0.0.3

Or manually

Clone repository at github.com/DataDog/php-datadogstatsd

Setup: require './src/DogStatsd.php';

Usage

instantiation

To instantiate a DogStatsd object using composer:

require __DIR__ . '/vendor/autoload.php';

use DataDog\DogStatsd;
use DataDog\BatchedDogStatsd;

$statsd = new DogStatsd();
$statsd = new BatchedDogStatsd();

DogStatsd constructor, takes a configuration array. The configuration can take any of the following values (all optional):

host: the host of your DogStatsd server, default to localhost
port: the port of your DogStatsd server. default to 8125
socket_path: the path to the DogStatsd UNIX socket (overrides host and port, only supported with datadog-agent >= 6). default to null
global_tags: tags to apply to all metrics sent

When sending events over TCP the following options can be set (see Events section):

api_key: needed to send event over TCP
app_key: needed to send event over TCP
curl_ssl_verify_host: Config pass-through for CURLOPT_SSL_VERIFYHOST defaults 2
curl_ssl_verify_peer: Config pass-through for CURLOPT_SSL_VERIFYPEER default 1
datadog_host: where to send events default https://app.datadoghq.com

Increment

To increment things:

$statsd->increment('your.data.point');
$statsd->increment('your.data.point', .5);
$statsd->increment('your.data.point', 1, array('tagname' => 'value'));

Decrement

To decrement things:

$statsd->decrement('your.data.point');

Timing

To time things:

$start_time = microtime(true);
run_function();
$statsd->microtiming('your.data.point', microtime(true) - $start_time);

$statsd->microtiming('your.data.point', microtime(true) - $start_time, 1, array('tagname' => 'value'));

Submitting events

For documentation on the values of events, see http://docs.datadoghq.com/api/#events.

Submitting events via TCP vs UDP

TCP - High-confidence event submission. Will log errors on event submission error.
UDP - "Fire and forget" event submission. Will not log errors on event submission error. No acknowledgement of submitted event from Datadog.

No matter wich transport is used the event function has the same API.

Differences between TCP/UDP

UDP Submission to local dogstatsd

Since the UDP method uses the a local dogstatsd instance we don't need to setup any additional application/api access.

$statsd = new DogStatsd();
$statsd->event('Fire and forget!',
    array(
        'text'       => 'Sending errors via UDP is faster but less reliable!',
        'alert_type' => 'success'
    )
);

Default method
No configuration
Faster
Less reliable
No logging on communication errors with Datadog (fire and forget)

TCP Submission to Datadog API

To submit events via TCP, you'll need to first configure the library with your Datadog credentials, since the event function submits directly to Datadog instead of sending to a local dogstatsd instance.

You can find your api and app keys in the API tab.

$statsd = new DogStatsd(
    array('api_key' => 'myApiKey',
          'app_key' => 'myAppKey',
     )
  );

$statsd->event('A thing broke!',
    array(
        'alert_type'      => 'error',
        'aggregation_key' => 'test_aggr'
    )
);
$statsd->event('Now it is fixed.',
    array(
        'alert_type'      => 'success',
        'aggregation_key' => 'test_aggr'
    )
);

Slower
More reliable
Logging on communication errors with Datadog (uses cURL for API request)
Logs via error_log and try/catch block to not throw warnings/errors on communication issues with API

Roadmap

Add a configurable timeout for event submission via TCP
Write unit tests
Document service check functionality

Contributing

Tests

composer test

derek9gag/php-datadogstatsd