Network Performance Monitoring is now generally available! Network Monitoring is now available!


Library Library


Connect your PHP applications to Datadog to:

  • Visualize their performance
  • Correlate their performance with the rest of your applications
  • Monitor any relevant metric
  • Collect your PHP logs


The PHP integration enables you to monitor any custom metric by instrumenting a few lines of code. For example, setup a metric that returns the number of page views or the time of any function call. For additional information on submitting metrics, please refer to Datadog’s Metrics documentation.

Installation Options

Install the PHP Datadog StatsD Client with Composer or manually using the GitHub repository.


Add the following to your composer.json:

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

Note: The first version shipped in Composer is 0.0.3.


Clone the Git repository:

git clone

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

Log Collection

Available for Agent >6.0

Monitor your PHP log files with the Datadog Agent to forward your logs to Datadog. See the specific instructions to generate logs with your logging library:



Use the following to instantiate a DogStatsd object using composer:

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

use DataDog\DogStatsd;
use DataDog\BatchedDogStatsd;

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

The DogStatsd constructor, takes a configuration array. The configuration can take any of these optional values:

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


The tags argument can be an array or a string. The value can be set to null.

$statsd->increment('<METRIC.NAME>', 1, array('app' => 'php1', 'beta' => null));
$statsd->increment('<METRIC.NAME>', 1, "app:php1,beta");


To increment metrics:

$statsd->increment('<METRIC.NAME>', .5);
$statsd->increment('<METRIC.NAME>', 1, array('<TAG_KEY>' => '<VALUE>'));


To decrement metrics:



To time metrics:

$start_time = microtime(true);
$statsd->microtiming('<METRIC.NAME>', microtime(true) - $start_time);

$statsd->microtiming('<METRIC.NAME>', microtime(true) - $start_time, 1, array('<TAG_KEY>' => '<VALUE>'));


For documentation on event parameters, see the Datadog API Events page.

Submitting events via TCP vs UDP

  • TCP - High-confidence event submission. Logs errors on event submission error.
  • UDP - “Fire and forget” event submission. Does not log errors on event submission error. No acknowledgement of submitted event from Datadog.

The event function uses the same API for TCP and UDP transport.

UDP submission to local DogStatsD

Since the UDP method uses a local DogStatsD instance, you don’t need to setup any additional application/api access.

Items to note for UDP:

  • Default method
  • No configuration
  • Faster
  • Less reliable
  • No logging on communication errors with Datadog


$statsd = new DogStatsd();
        'text'       => '<SUCCESS_EVENT_TEXT>',
        'alert_type' => 'success'

TCP submission to Datadog API

To submit events via TCP, first configure the library with your Datadog credentials. The event function submits directly to Datadog instead of a local DogStatsD instance. Your API and app keys are available in Datadog on the APIs tab.

Items to note for TCP:

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

When sending events over TCP these options are available:

api_keyRequired to send event over TCP.
app_keyRequired to send event over TCP.
curl_ssl_verify_hostConfig pass-through for CURLOPT_SSL_VERIFYHOST default 2.
curl_ssl_verify_peerConfig pass-through for CURLOPT_SSL_VERIFYPEER default 1.
datadog_hostThe location to send events, defaults to


$statsd = new DogStatsd(
    array('api_key' => '<DD_API_KEY>',
          'app_key' => '<DD_APP_KEY>',

        'alert_type'      => 'error',
        'aggregation_key' => '<KEY>'
        'alert_type'      => 'success',
        'aggregation_key' => '<KEY>'

Data Collected


The PHP integration does not include any default metrics. Use the instructions above to send custom metrics.


The PHP integration does not include any default events. Use the instructions above to send custom events.

Service Checks

The PHP integration does not include any service checks.


Need help? Contact Datadog support.