
Introducción a la API de Datadog
La API de Datadog proporciona acceso programático a las sólidas capacidades de monitorización y análisis de la plataforma. Esta API RESTful permite a los desarrolladores enviar datos, crear visualizaciones y gestionar sus cuentas de Datadog a través de código. Ya sea que esté integrando aplicaciones personalizadas, automatizando flujos de trabajo o extendiendo la funcionalidad de Datadog, comprender cómo aprovechar la API es esencial para maximizar el potencial de la plataforma.
La API de Datadog está diseñada con una arquitectura orientada a recursos que utiliza códigos de respuesta HTTP estándar, acepta y devuelve JSON en todas las solicitudes y utiliza métodos HTTP estándar. Esto la hace intuitiva para los desarrolladores familiarizados con los servicios web RESTful. La funcionalidad integral de la API permite tanto operaciones de lectura como de escritura, lo que le permite no solo recuperar datos de monitorización, sino también configurar varios aspectos de su entorno de Datadog.
Al dominar la API de Datadog, podrá:
- Crear y gestionar programáticamente paneles, monitores y alertas
- Enviar métricas personalizadas desde cualquier aplicación o componente de infraestructura
- Automatizar los flujos de trabajo de gestión de incidentes
- Integrar con pipelines de CI/CD para una monitorización continua
- Crear herramientas y soluciones personalizadas en torno a sus datos de monitorización
Primeros pasos con la autenticación de la API de Datadog
Antes de realizar cualquier llamada a la API, deberá configurar correctamente la autenticación para garantizar un acceso seguro a sus recursos de Datadog.
Obtención de claves de API y de aplicación de Datadog
Para empezar a utilizar la API de Datadog, necesitará dos tipos de claves:
- Clave de API: Esta identifica su cuenta de Datadog y es necesaria para todas las solicitudes de la API.
- Navegue a su cuenta de Datadog: Organization Settings > API Keys
- Haga clic en "New Key" para crear una nueva clave de API
- Asigne un nombre significativo que indique su propósito y uso
- Guarde la clave de forma segura, ya que otorga acceso a su cuenta de Datadog
- Clave de aplicación: Necesaria para muchos endpoints de gestión, proporciona autenticación adicional y especifica los permisos de acceso.
- Navegue a Organization Settings > Application Keys
- Haga clic en "New Key" para generar una clave de aplicación
- Nómbrela apropiadamente según su uso previsto
- Opcionalmente, restrinja su acceso a aplicaciones específicas de Datadog
Configuración de los encabezados de autenticación de la API de Datadog
Al realizar solicitudes a la API, deberá incluir estas claves como encabezados:
- Incluya su clave de API en el encabezado utilizando
DD-API-KEY: your_api_key_here
- Para los endpoints que requieren autenticación adicional, incluya
DD-APPLICATION-KEY: your_application_key_here
Aquí tiene un ejemplo de una solicitud autenticada básica:
curl -X GET "<https://api.datadoghq.com/api/v1/dashboard>" \\\\
-H "Content-Type: application/json" \\\\
-H "DD-API-KEY: your_api_key_here" \\\\
-H "DD-APPLICATION-KEY: your_app_key_here"
Gestión de la seguridad de la clave de API de Datadog
Dado el importante acceso que proporcionan estas claves, es crucial seguir las mejores prácticas de seguridad:
- Rote las claves regularmente, especialmente las claves de API
- Establezca permisos apropiados para las claves de aplicación
- Nunca codifique las claves en el código fuente de su aplicación
- Utilice variables de entorno o bóvedas seguras para almacenar las claves
- Audite periódicamente el uso de la clave de API
- Revoque inmediatamente las claves no utilizadas o potencialmente comprometidas
Conceptos básicos de la API de Datadog
Comprender los conceptos fundamentales de la API de Datadog le ayudará a navegar por sus amplias capacidades de forma más eficaz.
Estructura de los endpoints de la API de Datadog
La API de Datadog está organizada lógicamente en áreas funcionales que reflejan las capacidades de la plataforma:
- API de métricas: Para enviar y consultar datos de métricas, lo que le permite enviar métricas personalizadas o recuperar valores de métricas históricos. Estos endpoints son fundamentales para monitorizar el rendimiento de la aplicación y la infraestructura.
- API de eventos: Se utiliza para publicar y recuperar eventos del flujo de eventos de Datadog. Los eventos pueden representar implementaciones, alertas o cualquier ocurrencia significativa en su entorno.
- API de monitores: Permite la creación y gestión programática de alertas de monitorización, incluida la configuración de los ajustes de notificación y la programación del tiempo de inactividad.
- API de paneles: Para crear, modificar y recuperar paneles de visualización, lo que permite la creación automatizada de paneles basados en plantillas o necesidades de la aplicación.
- API de registros: Proporciona endpoints para enviar registros directamente a Datadog, configurar pipelines de procesamiento de registros y gestionar archivos de registros.
- API de sintéticos: Para gestionar pruebas sintéticas, recuperar resultados de pruebas y programar ejecuciones de pruebas.
- API de usuarios y organizaciones: Permite la gestión de los miembros del equipo, los permisos y la configuración de la organización.
- API de objetivos de nivel de servicio (SLO): Para crear y rastrear SLOs para medir la fiabilidad del servicio.
Realización de su primera llamada a la API de Datadog
Comencemos con un caso de uso común: el envío de una métrica personalizada. Este ejemplo demuestra cómo enviar una métrica de tipo gauge simple con etiquetas:
import requests
import time
import json
api_key = "your_api_key_here"
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"Response Status Code: {response.status_code}")
print(f"Response Body: {response.json()}")
Este fragmento de código:
- Crea una carga útil con una métrica personalizada llamada "custom.application.performance"
- Establece la marca de tiempo actual y un valor de 100
- Añade etiquetas para una mejor organización y filtrado
- Envía los datos al endpoint de métricas de Datadog
- Imprime la respuesta de la API
Comprensión del formato de respuesta de la API de Datadog
Las respuestas de la API de Datadog suelen seguir un formato JSON coherente:
{
"status": "ok",
"errors": [],
"data": {
"id": "abc-123-xyz",
"name": "Example Resource",
"created_at": "2023-06-01T12:00:00.000Z",
"modified_at": "2023-06-02T15:30:00.000Z",
...
}
}
Los campos clave incluyen:
status
: Indica el éxito o el fracaso de la solicituderrors
: Contiene mensajes de error si la solicitud fallódata
: Los datos de recursos reales devueltos por la API
Casos de uso y ejemplos comunes de la API de Datadog
Exploremos las aplicaciones prácticas de la API de Datadog a través de ejemplos detallados que cubren la funcionalidad clave.
Recuperación de información del panel de la API de Datadog
Los paneles son fundamentales para las capacidades de visualización de Datadog. Aquí se explica cómo recuperar detalles sobre un panel específico:
curl -X GET "<https://api.datadoghq.com/api/v1/dashboard/dashboard_id>" \\\\
-H "Content-Type: application/json" \\\\
-H "DD-API-KEY: your_api_key_here" \\\\
-H "DD-APPLICATION-KEY: your_app_key_here"
Para crear un nuevo panel de forma programática:
import requests
import json
api_key = "your_api_key_here"
app_key = "your_app_key_here"
dashboard_payload = {
"title": "API Generated Dashboard",
"description": "Created via the Datadog API",
"widgets": [
{
"definition": {
"type": "timeseries",
"requests": [
{
"q": "avg:system.cpu.user{*} by {host}",
"display_type": "line"
}
],
"title": "CPU Usage by 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 created with ID: {response.json().get('id')}")
Creación de un monitor con la API de Datadog
Los monitores son esenciales para las alertas proactivas. Aquí se explica cómo crear un monitor que avise cuando el uso de la CPU supere un umbral:
import requests
import json
api_key = "your_api_key_here"
app_key = "your_app_key_here"
monitor_payload = {
"name": "High CPU Usage Alert",
"type": "metric alert",
"query": "avg(last_5m):avg:system.cpu.user{*} > 80",
"message": "CPU usage is above 80% for the last 5 minutes. @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"Response Status: {response.status_code}")
print(f"Monitor created: {response.json()}")
Este ejemplo:
- Crea un monitor de alerta de métricas
- Establece umbrales para advertencia (70%) y crítico (80%)
- Incluye ajustes de notificación con menciones para Slack y correo electrónico
- Añade opciones de configuración detalladas como el retardo de evaluación y el retardo de nuevo host
Integración con AWS mediante la API de Datadog
Conectar Datadog con los servicios en la nube amplía sus capacidades de monitorización. Aquí se explica cómo crear una integración de AWS:
curl -X POST "<https://api.datadoghq.com/api/v1/integration/aws>" \\\\
-H "Content-Type: application/json" \\\\
-H "DD-API-KEY: your_api_key_here" \\\\
-H "DD-APPLICATION-KEY: your_app_key_here" \\\\
-d '{
"account_id": "your_aws_account_id",
"role_name": "DatadogAWSIntegrationRole",
"access_key_id": "your_access_key",
"secret_access_key": "your_secret_key",
"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 configuración de integración:
- Se conecta a su cuenta de AWS utilizando un rol o claves de acceso
- Configura el filtrado para centrarse en recursos específicos
- Aplica automáticamente etiquetas a los hosts monitorizados
- Habilita espacios de nombres de servicios de AWS específicos
- Excluye las regiones que no desea monitorizar
Envío de registros a través de la API de Datadog
Los registros proporcionan información contextual crítica para la resolución de problemas. Aquí se explica cómo enviar registros directamente a Datadog:
import requests
import json
import datetime
api_key = "your_api_key_here"
logs_payload = [{
"ddsource": "python",
"ddtags": "env:production,service:payment-processor,version:1.2.3",
"hostname": "payment-service-01",
"message": "Payment transaction completed successfully for order #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"Log submission response: {response.status_code}")
Este ejemplo:
- Envía un registro estructurado con metadatos enriquecidos
- Incluye información de origen, servicio y entorno
- Añade atributos personalizados para el contexto empresarial específico
- Utiliza etiquetas para una mejor filtrado y correlación
Trabajo con los límites de velocidad de la API de Datadog
Datadog aplica límites de velocidad para garantizar la estabilidad de la plataforma y el uso justo entre los clientes. Comprender y respetar estos límites es crucial para una integración fiable de la API.
Comprensión de la limitación de velocidad de la API de Datadog
Los diferentes endpoints tienen diferentes límites de velocidad en función de la intensidad de sus recursos y los patrones de uso típicos:
- Las operaciones de lectura generalmente tienen límites más altos que las operaciones de escritura
- Algunos endpoints pueden tener límites por organización, mientras que otros tienen límites por clave
- Las claves de API compartidas entre varias aplicaciones pueden alcanzar los límites más rápido
Monitorización de los encabezados de límite de velocidad de la API de Datadog
Al realizar solicitudes a la API, compruebe estos encabezados de respuesta para comprender el estado actual de su límite de velocidad:
X-RateLimit-Limit
: El número máximo de solicitudes permitidas en la ventana de límite de velocidadX-RateLimit-Remaining
: El número de solicitudes restantes en la ventana de límite de velocidad actualX-RateLimit-Reset
: El tiempo en segundos hasta que se restablece el límite de velocidadX-RateLimit-Period
: La duración de la ventana de límite de velocidad en segundos
Implementación del manejo del límite de velocidad en las llamadas a la API de Datadog
Aquí tiene una implementación robusta para manejar los límites de velocidad con retroceso 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: # Too Many Requests
# Extract rate limit information
limit = response.headers.get('X-RateLimit-Limit', 'Unknown')
remaining = response.headers.get('X-RateLimit-Remaining', 'Unknown')
reset = int(response.headers.get('X-RateLimit-Reset', 60))
print(f"Rate limit hit: {remaining}/{limit} requests remaining. Reset in {reset} seconds.")
# Calculate backoff time with jitter
backoff_time = min(2 ** retries + random.uniform(0, 1), reset)
print(f"Backing off for {backoff_time:.2f} seconds")
time.sleep(backoff_time)
retries += 1
else:
return response
raise Exception(f"Failed after {max_retries} retries due to rate limiting")
Uso de las bibliotecas de cliente de la API de Datadog
Para mayor comodidad, Datadog ofrece bibliotecas de cliente oficiales en varios idiomas, lo que simplifica la autenticación y el formato de las solicitudes.
Cliente de la API de Python Datadog
El cliente oficial de Python proporciona una interfaz limpia e idiomática para la API de Datadog:
pip install datadog-api-client
Aquí tiene un ejemplo de envío de métricas utilizando el 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"] = "your_api_key_here"
configuration.api_key["appKeyAuth"] = "your_app_key_here"
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"Metrics submission successful: {response}")
Cliente de la API de Ruby Datadog
Para las aplicaciones de Ruby, la biblioteca de cliente oficial agiliza las interacciones de la API:
gem install datadog_api_client -v 2.31.1
Ejemplo de uso para crear un monitor:
require 'datadog_api_client'
DatadogAPIClient.configure do |config|
config.api_key = 'your_api_key_here'
config.application_key = 'your_app_key_here'
end
api_instance = DatadogAPIClient::V1::MonitorsAPI.new
body = {
'name' => 'API test monitor',
'type' => 'metric alert',
'query' => 'avg(last_5m):avg:system.cpu.user{*} > 75',
'message' => 'CPU usage is high',
'tags' => ['test:api', 'monitor:automated'],
'options' => {
'thresholds' => {
'critical' => 75,
'warning' => 65
}
}
}
begin
result = api_instance.create_monitor(body)
puts "Monitor created successfully with ID: #{result['id']}"
rescue DatadogAPIClient::APIError => e
puts "Error creating monitor: #{e}"
end
Mejores prácticas para el uso de la API de Datadog
Seguir estas directrices le ayudará a crear integraciones más fiables, seguras y eficientes con la API de Datadog.
Protección de sus claves de API de Datadog
La seguridad de sus claves de API es primordial:
- Almacene las claves en variables de entorno o bóvedas seguras, nunca en repositorios de código
- Implemente políticas de rotación de claves y actualice regularmente las claves de API
- Utilice diferentes claves de API para diferentes aplicaciones o propósitos
- Aplique el principio del mínimo privilegio restringiendo los permisos de la clave de aplicación
- Utilice listas blancas de IP siempre que sea posible para limitar el acceso a direcciones IP conocidas
Uso eficaz de las etiquetas en las llamadas a la API de Datadog
Las etiquetas son un mecanismo potente para organizar y filtrar sus datos de Datadog:
- Diseñe una taxonomía de etiquetado coherente antes de comenzar las implementaciones de la API
- Incluya etiquetas de entorno, servicio y versión en todas las métricas y registros
- Utilice etiquetas jerárquicas (por ejemplo,
region:us-east
,availability-zone:us-east-1a
) - Haga que las etiquetas sean coherentes en toda su telemetría (métricas, registros, trazas)
- Evite las etiquetas de alta cardinalidad en las métricas (por ejemplo, los ID de usuario únicos)
Implementación del manejo de errores para las solicitudes de la API de Datadog
Un manejo robusto de errores garantiza que sus integraciones sigan siendo fiables:
- Compruebe los códigos de estado HTTP y maneje los diferentes tipos de errores de forma adecuada
- Analice los cuerpos de respuesta de error para obtener información detallada sobre el error
- Implemente la lógica de reintento con retroceso exponencial para errores transitorios
- Registre las llamadas a la API fallidas con suficiente contexto para la depuración
- Establezca tiempos de espera razonables para evitar solicitudes colgadas
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("Request timed out - Datadog API may be experiencing delays")
except requests.exceptions.HTTPError as e:
if e.response.status_code == 400:
print(f"Bad request: {e.response.json().get('errors', [])}")
elif e.response.status_code == 403:
print("Authentication error - check your API and application keys")
elif e.response.status_code == 429:
print("Rate limit reached - implement backoff and retry")
else:
print(f"HTTP error: {e.response.status_code}")
except requests.exceptions.RequestException as e:
print(f"Request failed: {e}")
return None
Pruebas en entornos sandbox con la API de Datadog
Antes de implementar en producción:
- Cree una organización de desarrollo/staging dedicada en Datadog
- Utilice claves de API separadas para pruebas y producción
- Cree monitores de prueba con notificaciones dirigidas solo al equipo de desarrollo
- Simule pruebas de carga para comprender los impactos del límite de velocidad
- Documente los patrones de uso de la API para futuras referencias
Monitorización del uso de la API de Datadog
Realice un seguimiento del uso de su API para detectar problemas de forma temprana:
- Cree paneles para visualizar los volúmenes de llamadas a la API y las tasas de error
- Configure monitores para errores excesivos de la API o para acercarse a los límites de velocidad
- Implemente el registro para todas las operaciones de la API con el detalle apropiado
- Audite periódicamente el uso de la clave de API a través de los registros de auditoría de Datadog
- Realice un seguimiento del impacto en el coste de las métricas personalizadas enviadas a través de la API
Conclusión: Dominio de la API de Datadog
La API de Datadog proporciona potentes capacidades para extender y personalizar su plataforma de monitorización y análisis. Al comprender el proceso de autenticación, los conceptos básicos y las mejores prácticas descritas en esta guía, estará bien equipado para integrar Datadog en sus aplicaciones y automatizar sus flujos de trabajo de forma eficaz.
Ya sea que esté enviando métricas personalizadas, creando monitores o construyendo paneles complejos, la API ofrece la flexibilidad de adaptar Datadog a sus necesidades específicas. A medida que su uso madure, considere la posibilidad de implementar patrones más avanzados como:
- Generación de paneles basada en plantillas para nuevos servicios
- Mantenimiento y ajuste automatizados del monitor
- Integraciones personalizadas con herramientas y sistemas internos
- Flujos de trabajo de informes programados y extracción de datos
- Monitorización sintética para procesos empresariales críticos
Las capacidades programáticas proporcionadas por la API de Datadog le permiten construir un ecosistema de monitorización que se escala con su infraestructura y se adapta a los requisitos únicos de su organización.
Recuerde consultar regularmente la documentación oficial de la API de Datadog, ya que con frecuencia se añaden nuevos endpoints y características para ampliar las capacidades de la plataforma. Con el conocimiento adquirido en esta guía, está listo para construir soluciones de monitorización sofisticadas y automatizadas que aprovechen toda la potencia de la plataforma de observabilidad de Datadog.