PHP

Library

Overview

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

Setup

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.

Composer

Add the following to your composer.json:

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

Note: The first version shipped in Composer is 0.0.3.

Manually

Clone the Git repository:

git clone git@github.com:DataDog/php-datadogstatsd.git

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:

• Monolog
• Symfony
• Zend-Log

Usage

Instantiate

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:

Tags

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");

Increment

To increment metrics:

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

Decrement

To decrement metrics:

$statsd->decrement('<METRIC.NAME>');

Timing

To time metrics:

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

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

Events

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

Example:

$statsd = new DogStatsd();
$statsd->event('<SUCCESS_EVENT_NAME>',
    array(
        '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:

Examples:

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

$statsd->event('<ERROR_EVENT_NAME>',
    array(
        'alert_type'      => 'error',
        'aggregation_key' => '<KEY>'
    )
);
$statsd->event('<SUCCESS_EVENT_NAME>',
    array(
        'alert_type'      => 'success',
        'aggregation_key' => '<KEY>'
    )
);

Data Collected

Metrics

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

Events

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.

Troubleshooting

Need help? Contact Datadog support.