datadog / php-datadogstatsd

A PHP client for DogStatsd

PHP DataDog StatsD Client

This is an extremely simple PHP DogStatsD client.

Requires PHP >= 5.6.0.

See CHANGELOG.md for changes.

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

Installation

Add the following to your composer.json:

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

The first version shipped in composer is 0.0.3

Or manually clone this repository and set it up with require './src/DogStatsd.php'.

Once installed, turn on the socket extension to PHP which must be enabled at compile time by giving the --enable-sockets option to configure.

Configuration

To instantiate a DogStatsd object using composer:

<?php

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

use DataDog\DogStatsd;

$statsd = new DogStatsd(
    array('host' => '127.0.0.1',
          'port' => 8125,
     )
  );

DogStatsd constructor, takes a configuration array. See the full list of available DogStatsD Client instantiation parameters.

Origin detection over UDP in Kubernetes

Origin detection is a method to detect which pod DogStatsD packets are coming from in order to add the pod's tags to the tag list.

To enable origin detection over UDP, add the following lines to your application manifest

env:
  - name: DD_ENTITY_ID
    valueFrom:
      fieldRef:
        fieldPath: metadata.uid

The DogStatsD client attaches an internal tag, entity_id. The value of this tag is the content of the DD_ENTITY_ID environment variable, which is the pod’s UID. The agent uses this tag to infer packets' origin, and tag their metrics accordingly.

Usage

In order to use DogStatsD metrics, events, and Service Checks the Agent must be running and available.

Metrics

After the client is created, you can start sending custom metrics to Datadog. See the dedicated Metric Submission: DogStatsD documentation to see how to submit all supported metric types to Datadog with working code examples:

• Submit a COUNT metric.
• Submit a GAUGE metric.
• Submit a SET metric
• Submit a HISTOGRAM metric
• Submit a TIMER metric
• Submit a DISTRIBUTION metric

Some options are suppported when submitting metrics, like applying a Sample Rate to your metrics or tagging your metrics with your custom tags.

Events

After the client is created, you can start sending events to your Datadog Event Stream. See the dedicated Event Submission: DogStatsD documentation to see how to submit an event to your Datadog Event Stream.

Service Checks

After the client is created, you can start sending Service Checks to Datadog. See the dedicated Service Check Submission: DogStatsD documentation to see how to submit a Service Check to Datadog.

Roadmap

• Write unit tests
• Document service check functionality

Tests

composer test

Lint

composer lint

Fix lint

composer fix-lint

php-datadogstatsd's Issues

No COUNT method?

Hello,

There doesn't seem to be any COUNT method available on this API, as opposed to in the Ruby API for example.

I'm currently just using increment with a supplied value instead, not sure if that's the best approach, but it would be nice if we could either add a COUNT method or alternatively update the documentation on the website to inform people it doesn't exist and what is their best alternative approach.

If it is just a case of wrapping the increment, I'd be happy to submit a PR which achieves this

Incompatible with IPv6

I just deployed Dogstatsd to a AWS EKS cluster which is IPv6 native and the library killed everything the moment any metrics were sent.

Specifically the error is:

ErrorException: Thrown ErrorException (500): socket_sendto(): Host lookup failed [-10000]: Unknown error -10000 in /var/www/html/vendor/datadog/php-datadogstatsd/src/DogStatsd.php:478

DD_AGENT_HOST is valid and is working for APM, and is set to something along the lines of:

DD_AGENT_HOST=xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:f992:d7c9

I believe the issue is with this line:

        $socket = is_null($this->socketPath) ? socket_create(AF_INET, SOCK_DGRAM, SOL_UDP)
            : socket_create(AF_UNIX, SOCK_DGRAM, 0);

For that to work with IPv6 it needs to select AF_INET6 if it's given a IPv6 IP. I will verify this and test tomorrow.

Push to statsd happens in UDP which is leading to metrics being missed to reach StatsD

Is TCP an option to send data to StatsD? Can we push at some intervals only but push in TCP protocol?

It is possible to send empty events via UDP

https://github.com/DataDog/php-datadogstatsd/pull/70/files#diff-9370933975e4185eb4190af53b5b95deR655

The above link to my PR to add tests indicates that it is possible to send empty event data via UDP. Once test coverage is in place, I recommend DogStatsd::eventUdp be updated to return early if there isn't any data to send.

Bools Tag values

Noticed a behavior with passing in a bool as a tag value.
For example: ['is_bot' => false] and ['is_bot' => true]
The tag gets evaluated to is_bot: whereas if it's true it's evaluated to is_bot:1

If you concat a string with a bool, this is the same behavior observed in php.

php > echo 'foo' . true;
foo1
php > echo 'foo' . false;
foo

Which is effectively what the function serializeTags() is doing, concatting a string to an unknown type, which with our case it was a bool.

php-datadogstatsd/src/DogStatsd.php

Line 327 in bec0a07

$tag_strings[] = $tag . ':' . $value;

Really this only affects booleans as values, would make sense to just convert true/false to "true"/"false" rather than having them evaluate to 1/null.

Gauge

Gauge should allow string for tag as well - but it is typed and will not allow a string value.

Constructor guards

Due to a mis-configuration at work, our agent host was in some cases not being set.

This led to (luckily dev/qa time) discovering a PHP warning is thrown at runtime if the class is constructed with an incorrect value.

Like a lot of 12-factor apps, we get our value from ENV, which in our case resulted in no errors and a booting app. But warnings silently output.

I think the constructor of DogStatsTimer should throw if the host configuration is not a valid hostname or IP address. In our case it was false 😂

I Know people SHOULD NOT have warnings output in QA or production environments. But separate to that issue, I would be interesting in contributing this change if the authors are amenable.

unexpected [ array bracket fix on PHP = 5.3.0

When executing against PHP 5.3.0, the array declaration using the brackets syntax [] provoke the error :

Parse error: syntax error, unexpected '[' in (...)

Replacing [] by array() in /src/DogStatsd.phpline 63 will resolve the issue.

PSR1, 2 and 4 compliance

This project has a combination of different styles. I suggest using PSR-1: basic coding standard, PSR-2: coding style guide, and PSR-4: autoloading standard.

See the this fork for a sample of how this code would look like.

also check out The PHP Coding Standards Fixer

Regards,

Incompatible with upcoming PHP 8.2 release

Due to its heavy use of dynamically-declared properties, DogStatsd is largely incompatible with PHP 8.2 and will throw quite a few deprecation notices. Now might be a good opportunity to give this library some much-needed love.

Bring up to date with lsjroberts/datadog-statsd fork.

There's been a bunch of updates in this fork (https://github.com/lsjroberts/datadog-statsd) that would be nice to get into our version, including a bunch of cleanup and refactoring.

@clutchski Can you take a look at the fork when you get a chance and see if it's worth merging back into ours?

Unable to set gauge to 0

Oct  1 14:10:34 ip-172-30-102-247 agent[14320]: 2020-10-01 10:10:34 EDT | CORE | ERROR | (pkg/dogstatsd/server.go:421 in errLog) | Dogstatsd: error parsing metric message '"name:|g|#tag:tag-value"': invalid name and value: "name:"

When setting a gauge to 0, the value is completely elided. This was caused by #100. There was a code review comment to replace some string manipulation with

return rtrim(rtrim(number_format($value, 5, '.', ''), "0"), ".");

is was instead replaced with

return rtrim(trim(number_format($value, 5, '.', ''), "0"), ".");

which transforms a zero to an empty string

No Route to Host

I tried your library but there is an error in line 260 states "No Route to Host". I have put my own app key and api key. Do you know what causes the problem? Thanks before :'D

blocking on socket_sendto

My application has started to barf in the following line:

socket_sendto($socket, $udp_message, strlen($udp_message), 0, static::$__server, static::$__serverPort);

This is the error:

Maximum execution time of 300 seconds exceeded
in: /var/www/site/libraries/php-datadogstatsd/libraries/datadogstatsd.php
line: 228
Error type: 1
IP: REMOVED

I was running an old version of the code and just updated to the latest and greatest.

push to dogstatsd in openmetrics format

We are using php with swooole - which automatically exposes swoole metrics in php array, json and openmetrics format.

https://openswoole.com/article/openswoole-4.9.0-released

I know there is an openmetrics integration for datatadog agent. The drawback - in that case I would have to add separate datadog agent container into ecs fargate task and configure it with openmetrics config - so custom container build is gonna be needed - which is why I would rather not go this route.
https://docs.datadoghq.com/integrations/openmetrics/

I would rather push metrics to datadogstatsd - however this client doesn't understand openmentrics format as a source... so one way out would be to write custom "api bulder" script (openmetrics -> builder).

so that's my feature request i supposed - kindly support openmetrics as a source.

Travis CI integration

I think that first step to writing unit tests and make the library more stable is integration with Travis CI.

Also errors like #52 could be prevented by linting code in CI.

Who can make integration? I'll write .travis.yml soon.

This doesn't appear to work in an nginx php-fpm setup.

*725 FastCGI sent in stderr: "PHP message: PHP Fatal error: Class 'DataDogStatsD' not found in XXXXXXXX on line XXX"

This despite the inclusion of the file require_once(...)

Might it have something to do with socket?

->event call's return varies based on whether UDP mode is being used

If UDP is not being used, ->event returns true or false based on success. If UDP is used, ->event returns null. This can probably be fixed by seeing if ->packets_sent == 1 after the call to ->eventUdp, as that indicates success (and yes, I know UDP is send-and-pray).

Regression: `set()` no longer supports strings

PR #100 (released in version 1.5.1) broke the ability to use string values in the set() method. This was likely due to the docblock suggesting that only float values could be used, even though the Python, C# and Java libraries all explicitly support strings, and string values previously worked with this library in 1.5.0 and earlier versions.

I'd be happy to submit a fix for this :)

Depending on `error_log` may result in unseen errors

php-datadogstatsd/src/DogStatsd.php

Line 397 in 5b89937

error_log($e->getMessage());

I've worked on PHP applications where error_log either wasn't properly configured, or the application used a completely separate logging infrastructure to log errors, exceptions, etc. It is probably a good idea to avoid letting exceptions be raised from DogStatsd::event, but I suspect it's less good to rely on error_log alone, as the client using the library may lose the error message, and/or lose the opportunity to do anything about the fact that the curl call failed.

One alternative could be to allow the client to inject an optional PSR-3 logger interface in the constructor, and then log to that on calls to DogStatsd::event. This is a very common strategy that provides the user of library code to make their own decisions about how to deal with errors, etc. Monolog, for example, provides a way to log to error_log, among a plethora of other things.

Tagged 1.5.6 as 0.5.6

Hey,

Ran into an issue in an old project whilst updating packages. It looks like you tagged a new version as 0.5.6 instead of 1.5.6, which packagist has picked up, and composer update picked it up as an update from 0.5, but the code is very different to that version, and so isn't a minor version. (I realise the better solution would be to update to the latest 1.* version, but I don't have the time at the moment)

Thanks,

DNS support for UDP transport

Currently, the code does not resolve domain names for UDP transport:

php-datadogstatsd/src/DogStatsd.php

Lines 295 to 302 in def70c3

	public function flush($udp_message)
	{
	// Non - Blocking UDP I/O - Use IP Addresses!
	$socket = socket_create(AF_INET, SOCK_DGRAM, SOL_UDP);
	socket_set_nonblock($socket);
	socket_sendto($socket, $udp_message, strlen($udp_message), 0, $this->host, $this->port);
	socket_close($socket);
	}

I understand the need (keep this entirely non-blocking), but was wondering what would be the right approach for this to be added (willing to file a PR, but want to make sure it can be merged before I go ahead).

/cc @jitendra-1217

submit to packagist.org

Hello,

I noticed you have a composer.json in your repo, but the package has not been submitted to packagist.org.

It would be great if you can submit it, then it can be easily used as a composer package.
http://packagist.org/packages/submit

Or perhaps I am missing something?

Thanks.

add license

Events should be set over UDP to the DD agent

The current implementation of the event method uses the API to send events over HTTP, this can take a toll in the overall performance of an application that sends large number of events to DataDog. API events should be separated from their dogstatsd counterpart or removed.

The implementation of this method should send events to the DataDog agent over UDP.

Maintained?

This library seems to be lagging a few significant PR's.
Is it still being maintained or is it abandoned?

typo in readme

$statsd = new DogStatsd();
...
$statd->increment('your.data.point');

sometimes it's $statsd sometimes it's $statd

¯(°_o)/¯

Link to Laravel Wrapper

Hello there,

I was wondering if you would be interested in adding my library to the bottom of the README here. It's a wrapper around this library, but made specifically for the Laravel framework. I have already included a couple links to this library, and I think it would be cool if it was cyclical. It has been stable for several months and is definitely ready for production use.

https://github.com/chaseconey/laravel-datadog-helper

Please let me know what other information you might need.

Thanks!

new release

Hi, could we cut a new release with the latest changes? Thanks.

tags should be separated by comma only

the implementation of tags in the client is inconsistent (and probably broken)

the official dogstatsd states this:

metric.name:value|type|@sample_rate|#tag1:value,tag2

so tags are attached via # and separated via ,

this implementation can be found in the ruby client for example.

it looks like this is also implemented correctly for service-checks.

but it looks like it's wrong in the metrics implementation as it will separate by ,#!

/cc @Bonko @fungusakafungus

Please look at the pull requests and merge or reject them.

At least the pwillcode one which fixes the composer package psr-0 autoloading. I am using that fork in production now specifically because of the autoloading.

Thanks.

Possible incompatibility with Datadog agent ( version 6 )

Hi. I'm using this client and it's working fine with Datadog agent ( v5.22 ) but when I upgrade to Datadog v6, the timing metrics doesnt work.

More details:
PHP: 7.0
OS: Ubuntu 16

Thanks in advance!

BatchedDogStatsd static variables

Because the BatchedDogStatsd class uses static variables instead it is essentially a singleton.

It is not possible to have multiple instances which target different daemons or have different buffer sizes.

All variables in this class should be non-static.

Integration with Laravel 5.1

I was looking for an easy way to integrate it with Laravel 5.1 but couldn't find facade or service provider shipped with it. Is there any plans to add those in the futur ?

Datadog increment/decrement not working

is this function still working? Because I trying to use increment from example or by my self is not working. But the event function is working nicely.

I try to use increment, but nothing happen to my metric

Sample rate is affected by the locale

We recently noticed that we were seeing this error in our agent logs:

2022-05-19 19:07:59 UTC | CORE | ERROR | (pkg/dogstatsd/server.go:592 in errLog) | Dogstatsd: error parsing metric message '"global_method:********@0,5|#env:prod': could not parse dogstatsd sample rate "@0,5"

We traced this back to the fact that these dogstatsd metrics were being emitted from an application using the de_DE local. This can be reproduced with the following snippet:

setlocale(LC_ALL, 'de_DE');
$statsd = new \DataDog\DogStatsd(
    array('host' => '127.0.0.1',
          'port' => 8125,
     )
  );
$statsd->gauge('with.locale', 200, 0.1);

The metric emitted by this script will be:
with.locale:200|g|@0,1
Where the decimal place is replaced with a comma. The agent is unable to process this number. This appears to be similar to the problem described in #100, but with the sample rate instead of the metric itself.