Datadog Getting Started: Account, API Keys, and First Request

Getting started overview

To begin collecting data with Datadog, the initial steps involve setting up an account, generating API and application keys, and then submitting your first data point, typically a metric or an event. This guide focuses on the programmatic approach using Datadog's API, rather than agent-based installations, to illustrate the core interaction principles. Once an account is active and keys are obtained, developers can integrate Datadog into their applications or infrastructure to send telemetry data.

The general workflow for a programmatic first interaction is as follows:

1. Account Creation: Register for a Datadog account.
2. API Key Generation: Obtain the necessary API Key and Application Key from the Datadog console.
3. First API Call: Use an SDK or a direct HTTP request to send a metric or event to Datadog.

This process lays the groundwork for more advanced configurations, such as integrating with cloud providers, deploying agents, or setting up custom dashboards and alerts. Datadog supports various programming languages through its official SDKs, simplifying the process of sending data from different environments.

Create an account and get keys

To begin, navigate to the Datadog website and sign up for an account. Datadog offers a free tier that includes monitoring for up to 5 hosts or 150GB of logs per month, which is sufficient for initial testing and evaluation.

Once your account is created and you have logged into the Datadog console, you will need to obtain your API and Application Keys. These keys are essential for authenticating your requests to the Datadog API.

1. Log In: Access your Datadog console.
2. Navigate to API Keys: In the left-hand navigation, go to Organization Settings, then select API Keys.
3. Locate Keys: You will see an existing API Key. If you need a new one, you can generate it. Below the API Keys, you will find Application Keys. You may need to create a new Application Key if one does not exist or if you prefer to use a specific key for your integration.

It is critical to treat your API and Application Keys as sensitive credentials. Do not embed them directly in client-side code, commit them to version control, or expose them publicly. Use environment variables or a secure secret management system to store and retrieve these keys in production environments. For example, AWS Secrets Manager or Google Secret Manager can be used for secure credential storage, as detailed in the AWS Secrets Manager documentation.

Your first request

This section demonstrates how to send a simple custom metric to Datadog using its API. We will use curl for a direct HTTP request, which illustrates the underlying API structure, and then provide examples using Python and Node.js SDKs for a more idiomatic approach.

Direct API Call with curl

The Datadog API for submitting metrics is located at api.datadoghq.com/api/v1/series. You will need your API Key and Application Key. Replace <YOUR_API_KEY> and <YOUR_APP_KEY> with your actual keys.

curl -X POST -H "Content-Type: application/json" \
     -H "DD-API-KEY: <YOUR_API_KEY>" \
     -H "DD-APPLICATION-KEY: <YOUR_APP_KEY>" \
     -d '{
           "series": [
             {
               "metric": "my.custom.metric",
               "points": [[$(date +%s), 123.45]],
               "type": "gauge",
               "tags": ["env:dev", "service:example"]
             }
           ]
         }' \
     "https://api.datadoghq.com/api/v1/series"

This command sends a single gauge metric named my.custom.metric with a value of 123.45 and two tags. The timestamp is automatically generated using $(date +%s), which provides the current Unix epoch time in seconds.

Python SDK Example

First, install the Datadog Python client library:

pip install datadog

Then, use the following Python code to send a metric:

from datadog import initialize, statsd
import os

# Initialize Datadog with your API and Application Keys
# It's recommended to use environment variables for keys
options = {
    'api_key': os.getenv('DD_API_KEY'),
    'app_key': os.getenv('DD_APPLICATION_KEY')
}

initialize(**options)

# Send a custom gauge metric
statsd.gauge('my.python.metric', 99.9, tags=['env:prod', 'source:python-sdk'])
print("Metric 'my.python.metric' sent successfully.")

Ensure you set the DD_API_KEY and DD_APPLICATION_KEY environment variables before running the script.

Node.js SDK Example

First, install the Datadog Node.js client library:

npm install @datadog/datadog-api-client

Then, use the following Node.js code to send an event:

const { client, v1 } = require("@datadog/datadog-api-client");

const configuration = client.createConfiguration({
  authMethods: {
    apiKeyAuth: process.env.DD_API_KEY,
    appKeyAuth: process.env.DD_APPLICATION_KEY,
  },
});

const apiInstance = new v1.EventsApi(configuration);

const body = {
  title: "First Node.js Event",
  text: "This is a test event from the Node.js SDK.",
  tags: ["env:staging", "source:nodejs-sdk"],
  priority: "normal",
  alertType: "info",
};

apiInstance.createEvent({ body })
  .then((data) => {
    console.log("Event sent successfully:", JSON.stringify(data, null, 2));
  })
  .catch((error) => console.error(error));

Set DD_API_KEY and DD_APPLICATION_KEY as environment variables before executing.

Common next steps

After successfully sending your first data point, consider these common next steps to expand your Datadog integration:

• Install the Datadog Agent: For comprehensive infrastructure monitoring, install the Datadog Agent on your hosts. The agent collects metrics, logs, and traces directly from your servers and applications.
• Integrate with Cloud Providers: Connect Datadog with your cloud environments (e.g., AWS, Azure, Google Cloud) to automatically collect metrics and logs from cloud services. Refer to the Datadog Integrations documentation for specific setup instructions.
• Explore Dashboards: Navigate to the Dashboards section in the Datadog console to visualize your collected metrics and events. Create custom dashboards to monitor the health and performance of your applications and infrastructure.
• Set Up Alerts and Monitors: Configure monitors to receive notifications when specific metrics exceed thresholds or when events of interest occur. The Datadog Monitor documentation provides guidance on creating various types of alerts.
• Send Logs and Traces: Expand your observability by sending application logs and distributed traces. Datadog's Log Management and APM Tracing features provide deep insights into application behavior.
• Utilize SDKs for Application-level Metrics: Beyond the initial test, integrate Datadog SDKs into your applications to send custom metrics, events, and traces, enabling detailed application performance monitoring. The client libraries page lists all available SDKs.

Troubleshooting the first call

If your first API call to Datadog does not work as expected, consider the following common issues and troubleshooting steps:

• Incorrect API/Application Keys: Double-check that you are using the correct API Key and Application Key. These are distinct and both are often required for authentication. Ensure there are no leading or trailing spaces.
• Network Connectivity: Verify that your machine has network connectivity to api.datadoghq.com. A simple ping api.datadoghq.com or curl -v https://api.datadoghq.com/api/v1/validate can help diagnose network issues.
• API Endpoint Region: Datadog has multiple regions (e.g., US1, EU, US3). Ensure your API calls are directed to the correct endpoint for your account. The default is US1 (api.datadoghq.com), but if your account is in another region, you'll need to use the corresponding endpoint (e.g., api.datadoghq.eu). Consult the Datadog site documentation for region-specific URLs.
• JSON Payload Formatting: If using curl or a custom HTTP client, ensure your JSON payload is correctly formatted and valid. Syntax errors in JSON can lead to API rejection. Tools like JSON Formatter & Validator can help.
• Rate Limits: While unlikely for a first call, Datadog APIs have rate limits. If you are making many calls in quick succession, you might encounter 429 Too Many Requests errors. The Datadog Metrics API documentation details rate limits.
• Permissions: Ensure the API Key and Application Key used have the necessary permissions to perform the requested action (e.g., submitting metrics or events). Permissions are managed in the Datadog console under Organization Settings > API Keys.
• Check Datadog Event Stream/Metrics Explorer: After making a call, grant a few moments for data ingestion. Then, check the Event Stream or Metrics Explorer in your Datadog console to see if the data has arrived. If it appears there, the API call was successful, and any issues might be related to visualization or querying.