README

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.

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.

Origin detection in Kubernetes

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

Tag cardinality

The tags that can be added to metrics can be found here. The cardinality can be specified globally by setting the DD_CARDINALITY environment or by passing a 'cardinality' field to the constructor. Cardinality can also be specified per metric by passing the value in the $cardinality parameter. Valid values for this parameter are "none", "low", "orchestrator" or "high". If an invalid value is passed, an E_USER_WARNING error is raised. If this error is handled with set_error_handler the metric is sent without a cardinality field.

Origin detection is achieved in a number of ways:

CGroups

On Linux the container ID can be extracted from procfs entries related to cgroups. The client reads from /proc/self/cgroup or /proc/self/mountinfo to attempt to parse the container id.

In cgroup v2, the container ID can be inferred by resolving the cgroup path from /proc/self/cgroup, combining it with the cgroup mount point from /proc/self/mountinfo]. The resulting directory's inode is sent to the agent. Provided the agent is on the same node as the client, this can be used to identify the pod's UID.

Over UDP

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.

DD_EXTERNAL_ENV

If the pod is annotated with the label:

admission.datadoghq.com/enabled: "true"

The admissions controller injects an environment variable DD_EXTERNAL_ENV. The value of this is sent in a field with the metric which can be used by the agent to determine the metrics origin.

Tests

composer test

Lint

composer lint

Fix lint

composer fix-lint