WebService::DataDog - Interface to DataDog's REST API.


Version 0.9.0


This module allows you to interact with DataDog, a service that will "Capture metrics and events, then graph, filter, and search to see what's happening and how systems interact." This module encapsulates all the communications with the REST API provided by DataDog to offer a Perl interface to metrics, dashboards, events, alerts, etc.

Requests that write data require reporting access and require an API key. Requests that read data require full access and additionally require an application key.

        use WebService::DataDog;

        # Create an object to communicate with DataDog
        my $datadog = WebService::DataDog->new(
                api_key         => 'your_api_key_here',
                application_key => 'your_application_key',

        # For metrics functions, first build a metrics object
        my $metric = $datadog->build('Metric');

        # To post metrics (past or present)
        # NOTE: only use 'value' OR 'data_points', but not both.
                name        => $metric_name,
                type        => $metric_type,  # Optional - gauge|counter. Default=gauge.
                value       => $metric_value, # For posting a single data point, time 'now'
                data_points => $data_points,  # 1+ data points, with timestamps
                host        => $hostname,     # Optional - host that produced the metric
                tags        => $tag_list,     # Optional - tags associated with the metric

        # For dashboard functions, first build a dashboard object
        my $dashboard = $datadog->build('Dashboard');

        # Create a new dashboard
        my $dashboard_id = $dashboard->create(
                title       => $dash_title,
                description => $dash_description,
                graphs      => $graphs,

        # Delete a user-created dashboard that you don't need anymore
        $dashboard->delete( id => $dash_id );

        # To make any changes to an existing user-created dashboard:
        # Specify dash_id and any combination of title, description, graphs
                id          => $dash_id,
                title       => $dash_title,
                description => $dash_description,
                graphs      => $graphs,

        # For event functions, first build an event object
        my $event = $datadog->build('Event');

        # To search the event stream
        my $event_list = $event->search(
                start     => $start_time,
                end       => $end_time, # Optional - default 'now'
                priority  => $priority, # Optional - low|normal
                sources   => $sources,  # Optional - list of sources. Ex: Datadog, Github, Pingdom, Webmetrics
                tags      => $tag_list, # Optional - list of tags associated with the event

        # Find all events in the last 48 hours.
        my $event_list = $event->search(
                start => time() - ( 48 * 60 * 60 ),

        # To get all details of a specific event
        my $event_data = $event->retrieve( id => $event_id );

        # To post a new event to the event stream
                title            => $event_title,
                text             => $event_text,  # Body/Description of the event.
                date_happened    => $timestamp,   # Optional, default "now"
                priority         => $priority,    # Optional. normal|low
                related_event_id => $event_id,    # Optional, id of aggregate event
                tags             => $tag_list,    # Optional - tags to apply to event (easy to search by)
                alert_type       => $alert_type,  # Optional. error|warning|info|success
                aggregation_key  => $agg_key,     # Optional. Arbitrary string to use for aggregation.
                source_type_name => $source_type, # Optional. nagios|hudson|jenkins|user|my apps|feed|chef|puppet|git|bitbucket|fabric|capistrano

        # Submit a user event, with timestamp of `now`.
                title            => 'Test event',
                text             => 'Testing posting to event stream',
                source_type_name => 'user',

        # For alert functions, first build an alert object
        my $alert = $datadog->build('Alert');

        # Get list, with details, of all alerts
        my $alert_list = $alert->retrieve_all();

        # Create a new alert
        my $alert_id = $alert->create(
                query    => $query,      # Metric query to alert on
                name     => $alert_name, # Optional. default=dynamic, based on query
                message  => $message,    # Optional. default=None
                silenced => $boolean,    # Optional. default=0

        # Retrieve details on a specific alert
        my $alert_data = $alert->retrieve( id => $alert_id );

        # Update an existing alert
                id       => $alert_id,   # ID of alert to modify
                query    => $query,      # Metric query to alert on
                name     => $alert_name, # Optional.
                message  => $message,    # Optional.
                silenced => $boolean,    # Optional.

        # Mute all alerts at once. Example usage: system maintenance.

        # Unmute all alerts at once. Example usage: completed system maintenance.

        # For tag functions, first build a tag object
        my $tag = $datadog->build('Tag');

        # Retrieve a mapping of tags to hosts.
        my $tag_host_list = $tag->retrieve_all();

        # Return a list of tags for the specified host.
        my $tag_list = $tag->retrieve( host => $host_name_or_id );

        # Update tags for specified host.
                host => $host,  # name/ID of host to modify
                tags => $tag_list, # Updated full list of tags to apply to host

        # Add tags to specified host.
                host => $host,  # name/ID of host to modify
                tags => $tag_list, # Updated full list of tags to apply to host

        # Delete all tags from the specified host.
        $tag->delete( host => $host );

        # For search, first build a search object
        my $search = $datadog->build('Search');

        my $search_results = $search->retrieve(
                term  => $search_term,
                facet => [ 'hosts', 'metrics' ] #optional



Create a new DataDog object that will be used as the interface with DataDog's API

        use WebService::DataDog;

        # Create an object to communicate with DataDog
        my $datadog = WebService::DataDog->new(
                api_key         => 'your_api_key_here',
                application_key => 'your_application_key',
                verbose         => 1,

Creates a new object to communicate with DataDog.



Create a WebService::DataDog::* object with the correct connection parameters.

                # Use the factory to get a WebService::DataDog::* object with
                # the correct DataDog connection parameters.
                my $metric = $datadog->build( 'Metric' );


  • The submodule name, such as Metric for WebService::DataDog::Metric.


Get or set the 'verbose' property.

        my $verbose = $self->verbose();
        $self->verbose( 1 );


By default, only basic tests that do not require a connection to DataDog's platform are run in t/.

To run the developer tests, you will need to do the following:

You can now create a file named in your own directory, with the following content:

        package DataDogConfig;

        sub new
                        api_key         => 'your_api_key',
                        application_key => 'your_application_key',
                        verbose         => 0, # Enable this for debugging output


You will then be able to run all the tests included in this distribution, after adding the path to to your library paths.




Jennifer Pinkham, <jpinkham at>.


Please report any bugs or feature requests to bug-WebService-DataDog at, or through the web interface at I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.


You can find documentation for this module with the perldoc command.

        perldoc WebService::DataDog

You can also look for information at:


Thanks to ThinkGeek (<>) and its corporate overlords at Geeknet (<>), for footing the bill while I write code for them!

Special thanks for architecture advice, and code contributions, from fellow ThinkGeek CPAN author Guillaume Aubert as well as architecture advice from fellow ThinkGeek CPAN author Kate Kirby


Copyright 2013 Jennifer Pinkham.

This program is free software; you can redistribute it and/or modify it under the terms of the Artistic License.

See for more information.