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:

Criar e gerenciar programaticamente dashboards, monitores e alertas
Enviar métricas personalizadas de qualquer aplicativo ou componente de infraestrutura
Automatizar fluxos de trabalho de gerenciamento de incidentes
Integrar-se a pipelines de CI/CD para monitoramento contínuo
Criar ferramentas e soluções personalizadas em torno dos seus dados de monitoramento

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:

Chave API: Esta identifica sua conta do Datadog e é necessária para todas as requisições à API.

Navegue até sua conta do Datadog: Configurações da Organização > Chaves da API
Clique em "Nova Chave" para criar uma nova chave da API
Dê um nome significativo que indique seu propósito e uso
Armazene a chave de forma segura, pois ela concede acesso à sua conta do Datadog

Chave de Aplicação: Necessária para muitos endpoints de gerenciamento, isso fornece autenticação adicional e especifica permissões de acesso.

Navegue até Configurações da Organização > Chaves de Aplicação
Clique em "Nova Chave" para gerar uma chave de aplicação
Nomeie-a apropriadamente com base em seu uso pretendido
Opcionalmente, restrinja seu acesso a aplicativos específicos do Datadog

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

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

Inclua sua chave API no cabeçalho usando DD-API-KEY: sua_chave_api_aqui
Para endpoints que requerem autenticação adicional, inclua DD-APPLICATION-KEY: sua_chave_de_aplicacao_aqui

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:

Gire as chaves regularmente, especialmente as chaves da API
Defina permissões apropriadas para as chaves de aplicação
Nunca codifique as chaves diretamente no código-fonte do seu aplicativo
Use variáveis de ambiente ou cofres seguros para armazenar chaves
Audite o uso da chave da API periodicamente
Revogue chaves não utilizadas ou potencialmente comprometidas imediatamente

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:

API de Métricas: Para enviar e consultar dados de métricas, permitindo que você envie métricas personalizadas ou recupere valores históricos de métricas. Esses endpoints são centrais para monitorar o desempenho de aplicativos e infraestrutura.
API de Eventos: Usada para postar e recuperar eventos do fluxo de eventos do Datadog. Os eventos podem representar implantações, alertas ou qualquer ocorrência significativa em seu ambiente.
API de Monitores: Permite a criação e gestão programática de alertas de monitoramento, incluindo a configuração de definições de notificação e agendamento de períodos de inatividade.
API de Dashboards: Para construir, modificar e recuperar dashboards de visualização, permitindo a criação automatizada de dashboards com base em modelos ou necessidades do aplicativo.
API de Logs: Fornece endpoints para enviar logs diretamente para o Datadog, configurando pipelines de processamento de logs e gerenciando arquivos de log.
API de Sintéticos: Para gerenciar testes sintéticos, recuperar resultados de testes e agendar execuções de testes.
API de Usuários e Organizações: Permite o gerenciamento de membros da equipe, permissões e configurações da organização.
API de Objetivos de Nível de Serviço (SLOs): Para criar e rastrear SLOs para medir a confiabilidade do serviço.

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:

Cria um payload com uma métrica personalizada chamada "custom.application.performance"
Define o timestamp atual e um valor de 100
Adiciona tags para melhor organização e filtragem
Envia os dados para o endpoint de métricas do Datadog
Imprime a resposta da API

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:

status: Indica o sucesso ou falha da requisição
errors: Contém mensagens de erro se a requisição falhou
data: Os dados reais do recurso retornado pela API

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:

Cria um monitor de alerta de métrica
Define limites para alerta (70%) e crítico (80%)
Inclui configurações de notificação com menções para Slack e email
Adiciona opções de configuração detalhadas, como atraso de avaliação e atraso para novos hosts

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:

Conecta-se à sua conta AWS usando um papel ou chaves de acesso
Configura filtragens para focar em recursos específicos
Aplica automaticamente tags aos hosts monitorados
Ativa namespaces de serviços AWS específicos
Exclui regiões que você não deseja monitorar

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:

Envia um log estruturado com metadados ricos
Inclui informações de origem, serviço e ambiente
Adiciona atributos personalizados para o contexto específico do negócio
Usa tags para melhor filtragem e correlação

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:

Operações de leitura geralmente têm limites mais altos do que operações de escrita
Alguns endpoints podem ter limites por organização, enquanto outros têm limites por chave
Chaves API compartilhadas entre vários aplicativos podem atingir limites mais rápido

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:

X-RateLimit-Limit: O número máximo de requisições permitidas na janela de limite de taxa
X-RateLimit-Remaining: O número de requisições restantes na janela atual de limite de taxa
X-RateLimit-Reset: O tempo em segundos até que o limite de taxa seja redefinido
X-RateLimit-Period: A duração da janela de limite de taxa em segundos

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:

Armazene as chaves em variáveis de ambiente ou cofres seguros, nunca em repositórios de código
Implemente políticas de rotação de chaves e atualize regularmente as chaves da API
Use chaves da API diferentes para aplicativos ou propósitos diferentes
Aplique o princípio do menor privilégio restringindo as permissões das chaves de aplicação
Use listas de permissões de IP sempre que possível para limitar o acesso a endereços IP conhecidos

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:

Projete uma taxonomia de tagging consistente antes de iniciar implementações da API
Inclua tags de ambiente, serviço e versão em todas as métricas e logs
Use tags hierárquicas (por exemplo, region:us-east, availability-zone:us-east-1a)
Mantenha as tags consistentes em todas as suas telemetrias (métricas, logs, traços)
Evite tags de alta cardinalidade em métricas (por exemplo, IDs de usuários únicos)

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:

Verifique os códigos de status HTTP e trate diferentes tipos de erro de forma apropriada
Analise os corpos de resposta de erro para obter informações detalhadas sobre o erro
Implemente lógica de repetição com recuo exponencial para erros temporários
Registre as chamadas à API que falharam com contexto suficiente para depuração
Defina timeouts razoáveis para evitar requisições pendentes

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:

Crie uma organização dedicada de desenvolvimento/estágio no Datadog
Use chaves da API separadas para testes e produção
Crie monitores de teste com notificações direcionadas apenas à equipe de desenvolvimento
Simule testes de carga para entender os impactos dos limites de taxa
Documente os padrões de uso da API para referência futura

Monitorando o Uso da API do Datadog

Rastreie seu uso da API para detectar problemas precocemente:

Crie dashboards para visualizar volumes de chamadas à API e taxas de erro
Configurar monitores para erros excessivos da API ou limites de taxa se aproximando
Implemente logs para todas as operações da API com detalhes apropriados
Audite o uso da chave da API periodicamente através dos logs de auditoria do Datadog
Rastreie o impacto de custo de métricas personalizadas enviadas através da API

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:

Geração de dashboards com base em modelos para novos serviços
Manutenção e ajuste automatizados de monitores
Integrações personalizadas com ferramentas e sistemas internos
Relatórios programados e fluxos de extração de dados
Monitoramento sintético para processos de negócios críticos

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