graze/dog-statsd

DataDog StatsD Client

1.0.0 2021-04-14 20:34 UTC

Requires

• php: ^7.1|^8.0

Requires (Dev)

• graze/standards: ^2
• johnkary/phpunit-speedtrap: ^2|^3
• phpunit/phpunit: ^7|^8|^9
• squizlabs/php_codesniffer: ^3.6

MIT

• Harry Bragg
• Graze Developers

• statsd
• DataDog
• graze
• dogstatsd
• dog-statsd

README

Client to talk to DataDogs StatsD Agent Forked from: League/StatsD

For more information on the metric, see: Datadogs metrics guide.

Install

Via Composer

$ composer require graze/dog-statsd

Usage

Configuring

$statsd = new Graze\DogStatsD\Client();
$statsd->configure([
    'host' => '127.0.0.1',
    'port' => 8125,
    'namespace' => 'example',
]);

OR

$statsd1 = DogStatsD\Client::instance('server1')->configure([...]);
$statsd2 = DogStatsD\Client::instance('server2')->configure([...]);

The StatsD client waits for ini_get('default_socket_timeout') seconds when opening the socket by default. To reduce this timeout, add 'timeout' => <int> to your config.

The StatsD client will either throw a ConnectionException, throw a warning or ignore all errors if it is unable to send data to the StatsD server. This can be configured using the onError property

    'onError' => 'error' // 'error', 'exception' or 'ignore'

By default this is set to 'error'

Core StatsD implementation

To use this with a core statsd implementation (without the extra features DataDog have added) include the following in your configuration:

'dataDog' => false

Methods

Counters

$statsd->increment('web.pageview');
$statsd->decrement('storage.remaining');
$statsd->increment([
    'first.metric',
    'second.metric'
], 2);
$statsd->increment('web.clicks', 1, 0.5);

Gauges

$statsd->gauge('api.logged_in_users', 123456);

Sets

$userID = 23;
$statsd->set('api.unique_logins', $userID);

Histogram

$result = $db->fetch();
$statsd->histogram('db.results', count($result), 0.5);

Timers

$statsd->timing('api.response_time', 256);

Timing Blocks

$statsd->time('api.dbcall', function () {
    // this code execution will be timed and recorded in ms
});

Tags

$statsd->increment('web.pageview', 1, ['page' => 'some/page']);
$statsd->guage('api.logged_in_users', 123456, ['environement' => 'live']);
$statsd->set('api.unique_logins', $userID, ['tag']);
$statsd->timing('api.response_time', 245, ['end-point' => 'page', 'env' => 'test']);

Tags Processors

You can add tag processors to inject tags at runtime for each metric.

$statsd->addTagProcessor(function (array $tags) {
    $tags['new-key'] = 'new-value';
    return $tags;
});

Events

$statsd->event(
    'build.success',
    'The build super_awesome_application_build_1 has completed',
    [
        'time'  => time(),
        'alert' => Client::ALERT_SUCCESS,
    ],
    [
        'environment' => 'live',
    ]
);

Service Check

$statsd->serviceCheck(
    'service.api.account',
    Client::STATUS_OK,
    [
        'host' => 'this.hostname.com',
        'time' => time(),
    ],
    [
        'environment' => 'staging',
    ]
);

Default Tags

Send the same base tags with every request

$client = new Client();
$client->configure([
    'tags' => [
        'env'     => 'live',
        'release' => 'app-2.3.1',
    ],
]);

Testing

$ make test

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email [e-mail] instead of using the issue tracker.

Credits

• Harry Bragg
• All Contributors

Forked from thephpleague/statsd:

• Marc Qualie
• League/StatsD Contributors

License

The MIT License (MIT). Please see License File for more information.