Dogshell

You can use the Datadog API on the command line using a wrapper called Dogshell.

Install Dogshell

Dogshell comes with the officially supported datadogpy Python library, which is often used to send data to Datadog with DogStatsD. To install the library with PIP, run the following command:

pip install datadog

Depending on your environment, you might have to add the library to your PATH. See the datadogpy GitHub repo for alternative installation instructions.

Configure Dogshell

Dogshell uses a configuration file called .dogrc to store your API key, application key, and Datadog site.

To configure Dogshell:

  1. Create a .dogrc file in your home directory:

    touch ~/.dogrc

  2. Add the following content to the file, replacing MY_API_KEY and MY_APP_KEY with your API key and application key respectively:

    [Connection]
    apikey = MY_API_KEY
    appkey = MY_APP_KEY
    api_host = https://
    
    You can create multiple configuration files if you need to run commands against different environments. Use the --config flag to specify the path to an alternative configuration file.
  3. Test the dogshell command by posting a test metric:

    dog metric post test_metric 1

Dogshell commands

Use the -h flag for a full list of the available Dogshell commands:

dog -h

You can append the -h option to the following commands to get more information on specific Dogshell usage:

  • dog metric
  • dog event
  • dog service_check
  • dog monitor
  • dog downtime
  • dog timeboard
  • dog screenboard
  • dog dashboard
  • dog host
  • dog tag
  • dog search
  • dog comment

For additional information, see the Dogshell code.

Dogshell example

The following syntax posts a metric to your Datadog account:

dog metric post MY_METRIC_NAME METRIC_VALUE --tags "TAG_KEY_1:TAG_VALUE_1,TAG_KEY_2:TAG_VALUE_2"

For example, the following command sends a metric named test_dogshell_metric to your account with a value of 1.0 and the tags test:one and example:one:

dog metric post test_dogshell_metric 1.0 --tags "test:one,example:one"

After you run the command, search for test_dogshell_metric using the Metrics Explorer.

Observing test_dogshell_metric from the Metrics explorer