Blog

Como Usar a API do Datadog

@apidog

@apidog

2 abril 2025

Como Usar a API do Datadog
💡
Ao trabalhar com a API do Datadog ou qualquer outra API, ter uma plataforma poderosa de desenvolvimento e teste de API é crucial. O Apidog se destaca como uma excelente alternativa ao Postman, oferecendo um conjunto abrangente de ferramentas para o desenvolvimento de APIs.
botão

Introdução à API do Datadog

A API do Datadog fornece acesso programático às robustas capacidades de monitoramento e análise da plataforma. Esta API RESTful permite que os desenvolvedores enviem dados, criem visualizações e gerenciem suas contas do Datadog por meio de código. Se você está integrando aplicativos personalizados, automatizando fluxos de trabalho ou estendendo a funcionalidade do Datadog, entender como aproveitar a API é essencial para maximizar o potencial da plataforma.

A API do Datadog foi projetada com uma arquitetura orientada a recursos que utiliza códigos de resposta HTTP padrão, aceita e retorna JSON em todas as requisições e utiliza métodos HTTP padrão. Isso a torna intuitiva para desenvolvedores familiarizados com serviços web RESTful. A funcionalidade abrangente da API permite operações de leitura e escrita, permitindo que você não apenas recupere dados de monitoramento, mas também configure vários aspectos do seu ambiente Datadog.

Ao dominar a API do Datadog, você será capaz de:

Iniciando com a Autenticação da API do Datadog

Antes de fazer qualquer chamada à API, você precisará configurar a autenticação corretamente para garantir acesso seguro aos seus recursos do Datadog.

Obtendo Chaves da API do Datadog e Chaves de Aplicação

Para começar a usar a API do Datadog, você precisará de dois tipos de chaves:

  1. Chave API: Esta identifica sua conta do Datadog e é necessária para todas as requisições à API.
  1. Chave de Aplicação: Necessária para muitos endpoints de gerenciamento, isso fornece autenticação adicional e especifica permissões de acesso.

Configurando Cabeçalhos de Autenticação da API do Datadog

Ao fazer requisições à API, você precisará incluir essas chaves como cabeçalhos:

Aqui está um exemplo de uma requisição autenticada básica:

curl -X GET "<https://api.datadoghq.com/api/v1/dashboard>" \\\\
-H "Content-Type: application/json" \\\\
-H "DD-API-KEY: sua_chave_api_aqui" \\\\
-H "DD-APPLICATION-KEY: sua_chave_de_aplicacao_aqui"

Gerenciando a Segurança da Chave da API do Datadog

Dada a quantidade significativa de acesso que essas chaves fornecem, seguir as melhores práticas de segurança é crucial:

Conceitos Básicos da API do Datadog

Compreender os conceitos fundamentais da API do Datadog ajudará você a navegar suas extensas capacidades de forma mais eficaz.

Estrutura dos Endpoints da API do Datadog

A API do Datadog está logicamente organizada em áreas funcionais que refletem as capacidades da plataforma:

Fazendo sua Primeira Chamada à API do Datadog

Vamos começar com um caso de uso comum: enviar uma métrica personalizada. Este exemplo demonstra como enviar uma métrica de medição simples com tags:

import requests
import time
import json

api_key = "sua_chave_api_aqui"
current_time = int(time.time())

payload = {
    "series": [
        {
            "metric": "custom.application.performance",
            "points": [[current_time, 100]],
            "type": "gauge",
            "tags": ["environment:production", "application:web", "region:us-east"]
        }
    ]
}

headers = {
    "Content-Type": "application/json",
    "DD-API-KEY": api_key
}

response = requests.post("<https://api.datadoghq.com/api/v1/series>",
                        headers=headers,
                        data=json.dumps(payload))

print(f"Código de Status da Resposta: {response.status_code}")
print(f"Corpo da Resposta: {response.json()}")

Este trecho de código:

Entendendo o Formato de Resposta da API do Datadog

As respostas da API do Datadog geralmente seguem um formato JSON consistente:

{
  "status": "ok",
  "errors": [],
  "data": {
    "id": "abc-123-xyz",
    "name": "Recurso de Exemplo",
    "created_at": "2023-06-01T12:00:00.000Z",
    "modified_at": "2023-06-02T15:30:00.000Z",
    ...
  }
}

Os campos-chave incluem:

Casos de Uso Comuns da API do Datadog e Exemplos

Vamos explorar aplicações práticas da API do Datadog através de exemplos detalhados cobrindo funcionalidades-chave.

Recuperando Informações do Dashboard da API do Datadog

Dashboards são centrais para as capacidades de visualização do Datadog. Aqui está como recuperar detalhes sobre um dashboard específico:

curl -X GET "<https://api.datadoghq.com/api/v1/dashboard/dashboard_id>" \\\\
-H "Content-Type: application/json" \\\\
-H "DD-API-KEY: sua_chave_api_aqui" \\\\
-H "DD-APPLICATION-KEY: sua_chave_de_aplicacao_aqui"

Para criar um novo dashboard programaticamente:

import requests
import json

api_key = "sua_chave_api_aqui"
app_key = "sua_chave_de_aplicacao_aqui"

dashboard_payload = {
    "title": "Dashboard Gerado pela API",
    "description": "Criado via API do Datadog",
    "widgets": [
        {
            "definition": {
                "type": "timeseries",
                "requests": [
                    {
                        "q": "avg:system.cpu.user{*} by {host}",
                        "display_type": "line"
                    }
                ],
                "title": "Uso de CPU por Host"
            }
        }
    ],
    "layout_type": "ordered"
}

headers = {
    "Content-Type": "application/json",
    "DD-API-KEY": api_key,
    "DD-APPLICATION-KEY": app_key
}

response = requests.post("<https://api.datadoghq.com/api/v1/dashboard>",
                        headers=headers,
                        data=json.dumps(dashboard_payload))

print(f"Dashboard criado com ID: {response.json().get('id')}")

Criando um Monitor com a API do Datadog

Monitores são essenciais para alertas proativos. Aqui está como criar um monitor que alerta quando o uso da CPU excede um limite:

import requests
import json

api_key = "sua_chave_api_aqui"
app_key = "sua_chave_de_aplicacao_aqui"

monitor_payload = {
    "name": "Alerta de Alto Uso de CPU",
    "type": "metric alert",
    "query": "avg(last_5m):avg:system.cpu.user{*} > 80",
    "message": "O uso da CPU está acima de 80% nos últimos 5 minutos. @slack-alerts-channel @email.address@example.com",
    "tags": ["app:web", "env:production", "team:infrastructure"],
    "priority": 3,
    "options": {
        "notify_no_data": True,
        "no_data_timeframe": 10,
        "new_host_delay": 300,
        "evaluation_delay": 60,
        "thresholds": {
            "critical": 80,
            "warning": 70
        },
        "include_tags": True,
        "notify_audit": False,
        "require_full_window": False
    }
}

headers = {
    "Content-Type": "application/json",
    "DD-API-KEY": api_key,
    "DD-APPLICATION-KEY": app_key
}

response = requests.post("<https://api.datadoghq.com/api/v1/monitor>",
                        headers=headers,
                        data=json.dumps(monitor_payload))

print(f"Status da Resposta: {response.status_code}")
print(f"Monitor criado: {response.json()}")

Este exemplo:

Integrando com AWS usando a API do Datadog

Conectar o Datadog com serviços de nuvem estende suas capacidades de monitoramento. Aqui está como criar uma integração com a AWS:

curl -X POST "<https://api.datadoghq.com/api/v1/integration/aws>" \\\\
-H "Content-Type: application/json" \\\\
-H "DD-API-KEY: sua_chave_api_aqui" \\\\
-H "DD-APPLICATION-KEY: sua_chave_de_aplicacao_aqui" \\\\
-d '{
  "account_id": "seu_id_de_conta_aws",
  "role_name": "DatadogAWSIntegrationRole",
  "access_key_id": "sua_chave_de_acesso",
  "secret_access_key": "sua_chave_secreta",
  "filter_tags": ["env:production", "service:critical"],
  "host_tags": ["account:main", "region:us-east-1"],
  "account_specific_namespace_rules": {
    "auto_scaling": true,
    "opsworks": false,
    "elasticache": true
  },
  "excluded_regions": ["us-west-2", "ca-central-1"]
}'

Esta configuração de integração:

Enviando Logs pela API do Datadog

Logs fornecem informações contextuais críticas para solução de problemas. Aqui está como enviar logs diretamente para o Datadog:

import requests
import json
import datetime

api_key = "sua_chave_api_aqui"

logs_payload = [{
    "ddsource": "python",
    "ddtags": "env:production,service:payment-processor,version:1.2.3",
    "hostname": "payment-service-01",
    "message": "Transação de pagamento concluída com sucesso para o pedido #12345",
    "service": "payment-service",
    "status": "info",
    "timestamp": datetime.datetime.now().isoformat(),
    "attributes": {
        "transaction_id": "tx_789012345",
        "amount": 99.95,
        "currency": "USD",
        "customer_id": "cust_123456",
        "payment_method": "credit_card"
    }
}]

headers = {
    "Content-Type": "application/json",
    "DD-API-KEY": api_key
}

response = requests.post("<https://http-intake.logs.datadoghq.com/v1/input>",
                        headers=headers,
                        data=json.dumps(logs_payload))

print(f"Resposta de envio de log: {response.status_code}")

Este exemplo:

Trabalhando com os Limites de Taxação da API do Datadog

O Datadog impõe limites de taxa para garantir a estabilidade da plataforma e uso justo entre os clientes. Compreender e respeitar esses limites é crucial para uma integração confiável da API.

Entendendo a Limitação de Taxa da API do Datadog

Diferentes endpoints têm limites de taxa diferentes com base em sua intensidade de recurso e padrões de uso típicos:

Monitorando os Cabeçalhos de Limite de Taxa da API do Datadog

Ao fazer chamadas à API, verifique esses cabeçalhos de resposta para entender seu status atual de limite de taxa:

Implementando o Manuseio de Limite de Taxa nas Chamadas da API do Datadog

Aqui está uma implementação robusta para manuseio de limite de taxa com recuo exponencial:

import requests
import time
import random

def make_api_request_with_backoff(url, headers, payload=None, max_retries=5):
    retries = 0
    while retries < max_retries:
        response = requests.post(url, headers=headers, json=payload) if payload else requests.get(url, headers=headers)

        if response.status_code == 429:  # Muitas requisições
            # Extrair informações do limite de taxa
            limit = response.headers.get('X-RateLimit-Limit', 'Desconhecido')
            remaining = response.headers.get('X-RateLimit-Remaining', 'Desconhecido')
            reset = int(response.headers.get('X-RateLimit-Reset', 60))

            print(f"Limite de taxa atingido: {remaining}/{limit} requisições restantes. Reset em {reset} segundos.")

            # Calcular tempo de recuo com jitter
            backoff_time = min(2 ** retries + random.uniform(0, 1), reset)
            print(f"Recuperando por {backoff_time:.2f} segundos")
            time.sleep(backoff_time)
            retries += 1
        else:
            return response

    raise Exception(f"Falhou após {max_retries} tentativas devido a limitação de taxa")

Usando Bibliotecas Cliente da API do Datadog

Para conveniência, o Datadog oferece bibliotecas cliente oficiais em várias linguagens, simplificando a autenticação e a formatação de requisições.

Cliente da API do Datadog em Python

O cliente oficial em Python fornece uma interface limpa e idiomática para a API do Datadog:

pip install datadog-api-client

Aqui está um exemplo de envio de métricas usando o cliente:

from datadog_api_client import ApiClient, Configuration
from datadog_api_client.v1.api.metrics_api import MetricsApi
from datadog_api_client.v1.model.metrics_payload import MetricsPayload
from datadog_api_client.v1.model.metrics_series import MetricsSeries
from datadog_api_client.v1.model.point import Point
import time

configuration = Configuration()
configuration.api_key["apiKeyAuth"] = "sua_chave_api_aqui"
configuration.api_key["appKeyAuth"] = "sua_chave_de_aplicacao_aqui"

with ApiClient(configuration) as api_client:
    api_instance = MetricsApi(api_client)
    body = MetricsPayload(
        series=[
            MetricsSeries(
                metric="application.request.duration",
                points=[
                    Point([int(time.time()), 250.0])
                ],
                type="gauge",
                host="web-server-01",
                tags=["endpoint:login", "environment:staging"]
            )
        ]
    )
    response = api_instance.submit_metrics(body=body)
    print(f"Envio de métricas bem-sucedido: {response}")

Cliente da API do Datadog em Ruby

Para aplicativos Ruby, a biblioteca cliente oficial simplifica interações com a API:

gem install datadog_api_client -v 2.31.1

Exemplo de uso para criar um monitor:

require 'datadog_api_client'

DatadogAPIClient.configure do |config|
  config.api_key = 'sua_chave_api_aqui'
  config.application_key = 'sua_chave_de_aplicacao_aqui'
end

api_instance = DatadogAPIClient::V1::MonitorsAPI.new
body = {
  'name' => 'Monitor de teste da API',
  'type' => 'metric alert',
  'query' => 'avg(last_5m):avg:system.cpu.user{*} > 75',
  'message' => 'O uso da CPU está alto',
  'tags' => ['test:api', 'monitor:automated'],
  'options' => {
    'thresholds' => {
      'critical' => 75,
      'warning' => 65
    }
  }
}

begin
  result = api_instance.create_monitor(body)
  puts "Monitor criado com sucesso com ID: #{result['id']}"
rescue DatadogAPIClient::APIError => e
  puts "Erro ao criar monitor: #{e}"
end

Melhores Práticas para o Uso da API do Datadog

Seguir estas diretrizes ajudará você a construir integrações mais confiáveis, seguras e eficientes com a API do Datadog.

Protegendo suas Chaves da API do Datadog

A segurança de suas chaves da API é fundamental:

Usando Tags de Forma Efetiva nas Chamadas da API do Datadog

Tags são um mecanismo poderoso para organizar e filtrar seus dados do Datadog:

Implementando o Manuseio de Erros nas Requisições à API do Datadog

Um manuseio de erros robusto garante que suas integrações permaneçam confiáveis:

def send_to_datadog(endpoint, payload, headers):
    try:
        response = requests.post(endpoint,
                                json=payload,
                                headers=headers,
                                timeout=10)
        response.raise_for_status()
        return response.json()
    except requests.exceptions.Timeout:
        print("A requisição expirou - A API do Datadog pode estar enfrentando atrasos")
    except requests.exceptions.HTTPError as e:
        if e.response.status_code == 400:
            print(f"Requisição ruim: {e.response.json().get('errors', [])}")
        elif e.response.status_code == 403:
            print("Erro de autenticação - verifique suas chaves API e de aplicação")
        elif e.response.status_code == 429:
            print("Limite de taxa atingido - implemente recuo e repetição")
        else:
            print(f"Erro HTTP: {e.response.status_code}")
    except requests.exceptions.RequestException as e:
        print(f"Falha na requisição: {e}")

    return None

Testando em Ambientes Sandbox com a API do Datadog

Antes de implementar em produção:

Monitorando o Uso da API do Datadog

Rastreie seu uso da API para detectar problemas precocemente:

Conclusão: Dominando a API do Datadog

A API do Datadog fornece capacidades poderosas para estender e personalizar sua plataforma de monitoramento e análise. Ao entender o processo de autenticação, conceitos fundamentais e melhores práticas descritas neste guia, você estará bem preparado para integrar o Datadog em suas aplicações e automatizar seus fluxos de trabalho de forma eficaz.

Se você está enviando métricas personalizadas, criando monitores ou construindo dashboards complexos, a API oferece a flexibilidade para adaptar o Datadog às suas necessidades específicas. À medida que seu uso amadurece, considere implementar padrões mais avançados como:

As capacidades programáticas fornecidas pela API do Datadog permitem que você construa um ecossistema de monitoramento que escale com sua infraestrutura e se adapte às necessidades únicas da sua organização.

Lembre-se de verificar regularmente a documentação oficial da API do Datadog, pois novos endpoints e funcionalidades são frequentemente adicionados para expandir as capacidades da plataforma. Com o conhecimento adquirido neste guia, você está pronto para construir soluções de monitoramento sofisticadas e automatizadas que aproveitam todo o poder da plataforma de observabilidade do Datadog.

botão

Pratique o design de API no Apidog

Descubra uma forma mais fácil de construir e usar APIs

Cadastre-se gratuitamenteBaixar