Accede mediante programación a los datos de log con la API de Búsqueda de logs
Utiliza la API de Búsqueda de logs para acceder mediante programación a los datos del log y ejecutar consultas.
En esta guía se tratan los siguientes ejemplos:
Requisitos previos
El uso de la API de Búsqueda de logs requiere una clave de API y una clave de aplicación. El usuario que ha creado la clave de aplicación debe tener los permisos adecuados para acceder a los datos. Para utilizar los ejemplos siguientes, sustituye <DATADOG_API_KEY> y <DATADOG_APP_KEY> por tu clave de API de Datadog y tu clave de aplicación de Datadog, respectivamente.
Esta guía incluye ejemplos de curl. Instala curl si no lo tienes instalado, o consulta ejemplos de lenguaje adicionales para este endpoint de la API en la API de logs.
Ejemplos
Búsqueda básica
Para recuperar todos los eventos de log dentro de un periodo específico, utiliza la siguiente Sintaxis de búsqueda para completar la llamada a la API.
from indica start time y to indica end time para los datos del log. query indica la consulta de búsqueda que debe ejecutarse.
Llamada a la API:
curl -L -X POST "https://api.
Respuesta:
El conjunto de datos resultante está compuesto por el objeto data, como se muestra en el siguiente ejemplo de respuesta.
{
"meta": {
"page": {
"after": "eyJhZnRlciI6IkFRQUFBWFVBWFJZVkpHeHZEUUFBQUFCQldGVkJXRkpaVm1kMlpsa3RiVWRVWmpSQlFRIn0"
}
},
"data": [
{
"attributes": {
"status": "info",
"service": "pageViewService",
"tags": [
"source:postman",
"project:test"
],
"timestamp": "2020-10-07T00:02:33.461Z",
"host": "my.sample.host",
"attributes": {
"hostname": "my.sample.host",
"pageViews": "450",
"user": "chris",
"service": "pageViewService"
},
"message": "Sample message"
},
"type": "log",
"id": "AQAAAXUAXd91M9wyTgAAAABBWFVBWGQ5MVZrQmFzdEZ2TG9BQQ"
},
{
"attributes": {
"status": "info",
"service": "pageViewService",
"tags": [
"source:postman",
"project:test"
],
"timestamp": "2020-10-07T00:01:57.586Z",
"host": "my.sample.host",
"attributes": {
"hostname": "my.sample.host",
"pageViews": "500",
"user": "bob",
"service": "pageViewService"
},
"message": "Sample message"
},
"type": "log",
"id": "AQAAAXUAXVNSvuMvWwAAAABBWFVBWFZOU2I2ZWcxX3c2LVVBQQ"
},
{
"attributes": {
"status": "info",
"service": "pageViewService",
"tags": [
"source:postman",
"project:test"
],
"timestamp": "2020-10-07T00:01:41.909Z",
"host": "my.sample.host",
"attributes": {
"hostname": "my.sample.host",
"pageViews": "700",
"user": "steve",
"service": "pageViewService"
},
"message": "Sample message"
},
"type": "log",
"id": "AQAAAXUAXRYVJGxvDQAAAABBWFVBWFJZVmd2ZlktbUdUZjRBQQ"
}
],
"links": {
"next": "https://api.datadoghq.com/api/v2/logs/events?filter%5Bquery%5D=%2A&page%5Bcursor%5D=eyJhZnRlciI6IkFRQUFBWFVBWFJZVkpHeHZEUUFBQUFCQldGVkJXRkpaVm1kMlpsa3RiVWRVWmpSQlFRIn0&page%5Blimit%5D=3&filter%5Bfrom%5D=2020-10-07T00%3A00%3A00%2B00%3A00&filter%5Bto%5D=2020-10-07T00%3A15%3A00%2B00%3A00"
}
}
Ordenar por faceta o marca temporal
Faceta
Con la siguiente llamada a la API, ordena los eventos de log recuperados por una faceta como pageViews en orden ascendente. Incluye @ para la faceta. Utiliza - hyphen in front of the facet name such as -@pageViews para ordenar de forma descendente. El orden por defecto es descendente por marcas temporales.
Llamada a la API:
curl -L -X POST "https://api.
Respuesta:
Los eventos de log se recuperan en orden ascendente de los valores de la faceta pageViews, como se muestra en la siguiente respuesta. El usuario chris tiene 450, bob tiene 500 y steve tiene 700 vistas de páginas.
{
"meta": {
"page": {
"after": "eyJhZnRlciI6IkFRQUFBWFVBWFJZVkpHeHZEUUFBQUFCQldGVkJXRkpaVm1kMlpsa3RiVWRVWmpSQlFRIiwidmFsdWVzIjpbIjcwMCJdfQ"
}
},
"data": [
{
"attributes": {
"status": "info",
"service": "pageViewService",
"tags": [
"source:postman",
"project:test"
],
"timestamp": "2020-10-07T00:02:33.461Z",
"host": "my.sample.host",
"attributes": {
"hostname": "my.sample.host",
"pageViews": "450",
"user": "chris",
"service": "pageViewService"
},
"message": "Sample message"
},
"type": "log",
"id": "AQAAAXUAXd91M9wyTgAAAABBWFVBWGQ5MVZrQmFzdEZ2TG9BQQ"
},
{
"attributes": {
"status": "info",
"service": "pageViewService",
"tags": [
"source:postman",
"project:test"
],
"timestamp": "2020-10-07T00:01:57.586Z",
"host": "my.sample.host",
"attributes": {
"hostname": "my.sample.host",
"pageViews": "500",
"user": "bob",
"service": "pageViewService"
},
"message": "Sample message"
},
"type": "log",
"id": "AQAAAXUAXVNSvuMvWwAAAABBWFVBWFZOU2I2ZWcxX3c2LVVBQQ"
},
{
"attributes": {
"status": "info",
"service": "pageViewService",
"tags": [
"source:postman",
"project:test"
],
"timestamp": "2020-10-07T00:01:41.909Z",
"host": "my.sample.host",
"attributes": {
"hostname": "my.sample.host",
"pageViews": "700",
"user": "steve",
"service": "pageViewService"
},
"message": "Sample message"
},
"type": "log",
"id": "AQAAAXUAXRYVJGxvDQAAAABBWFVBWFJZVmd2ZlktbUdUZjRBQQ"
}
],
"links": {
"next": "https://api.datadoghq.com/api/v2/logs/events?sort=%40pageViews&filter%5Bquery%5D=%2A&page%5Bcursor%5D=eyJhZnRlciI6IkFRQUFBWFVBWFJZVkpHeHZEUUFBQUFCQldGVkJXRkpaVm1kMlpsa3RiVWRVWmpSQlFRIiwidmFsdWVzIjpbIjcwMCJdfQ&filter%5Bfrom%5D=2020-10-07T00%3A00%3A00%2B00%3A00&filter%5Bto%5D=2020-10-07T00%3A15%3A00%2B00%3A00"
}
}
Marca temporal
Con la siguiente llamada a la API, los eventos de log recuperados se ordenan por timestamp en orden ascendente. Por defecto, el orden es descendente.
Llamada a la API:
curl -L -X POST "https://api.
Respuesta:
Los eventos de log se recuperan en orden ascendente en función de sus valores de timestamp, como se muestra en la siguiente respuesta.
{
"meta": {
"page": {
"after": "eyJhZnRlciI6IkFRQUFBWFVBWGQ5MU05d3lUZ0FBQUFCQldGVkJXR1E1TVZaclFtRnpkRVoyVEc5QlFRIn0"
}
},
"data": [
{
"attributes": {
"status": "info",
"service": "pageViewService",
"tags": [
"source:postman",
"project:test"
],
"timestamp": "2020-10-07T00:01:41.909Z",
"host": "my.sample.host",
"attributes": {
"hostname": "my.sample.host",
"pageViews": "700",
"user": "steve",
"service": "pageViewService"
},
"message": "Sample message"
},
"type": "log",
"id": "AQAAAXUAXRYVJGxvDQAAAABBWFVBWFJZVmd2ZlktbUdUZjRBQQ"
},
{
"attributes": {
"status": "info",
"service": "pageViewService",
"tags": [
"source:postman",
"project:test"
],
"timestamp": "2020-10-07T00:01:57.586Z",
"host": "my.sample.host",
"attributes": {
"hostname": "my.sample.host",
"pageViews": "500",
"user": "bob",
"service": "pageViewService"
},
"message": "Sample message"
},
"type": "log",
"id": "AQAAAXUAXVNSvuMvWwAAAABBWFVBWFZOU2I2ZWcxX3c2LVVBQQ"
},
{
"attributes": {
"status": "info",
"service": "pageViewService",
"tags": [
"source:postman",
"project:test"
],
"timestamp": "2020-10-07T00:02:33.461Z",
"host": "my.sample.host",
"attributes": {
"hostname": "my.sample.host",
"pageViews": "450",
"user": "chris",
"service": "pageViewService"
},
"message": "Sample message"
},
"type": "log",
"id": "AQAAAXUAXd91M9wyTgAAAABBWFVBWGQ5MVZrQmFzdEZ2TG9BQQ"
}
],
"links": {
"next": "https://api.datadoghq.com/api/v2/logs/events?sort=timestamp&filter%5Bquery%5D=%2A&page%5Bcursor%5D=eyJhZnRlciI6IkFRQUFBWFVBWGQ5MU05d3lUZ0FBQUFCQldGVkJXR1E1TVZaclFtRnpkRVoyVEc5QlFRIn0&filter%5Bfrom%5D=2020-10-07T00%3A00%3A00%2B00%3A00&filter%5Bto%5D=2020-10-07T00%3A15%3A00%2B00%3A00"
}
}
Limitar el número de resultados recuperados
Con la siguiente llamada a la API, limita el número de eventos de log recuperados. El limit indica el número máximo de eventos de log devueltos en la respuesta. El límite máximo es 1000.
curl -L -X POST "https://api.
Respuesta:
{
"meta": {
"page": {
"after": "eyJhZnRlciI6IkFRQUFBWFVBWFZOU3Z1TXZXd0FBQUFCQldGVkJXRlpPVTJJMlpXY3hYM2MyTFZWQlFRIiwidmFsdWVzIjpbIjUwMCJdfQ"
}
},
"data": [
{
"attributes": {
"status": "info",
"service": "pageViewService",
"tags": [
"source:postman",
"project:test"
],
"timestamp": "2020-10-07T00:01:41.909Z",
"host": "my.sample.host",
"attributes": {
"hostname": "my.sample.host",
"pageViews": "700",
"user": "steve",
"service": "pageViewService"
},
"message": "Sample message"
},
"type": "log",
"id": "AQAAAXUAXRYVJGxvDQAAAABBWFVBWFJZVmd2ZlktbUdUZjRBQQ"
},
{
"attributes": {
"status": "info",
"service": "pageViewService",
"tags": [
"source:postman",
"project:test"
],
"timestamp": "2020-10-07T00:01:57.586Z",
"host": "my.sample.host",
"attributes": {
"hostname": "my.sample.host",
"pageViews": "500",
"user": "bob",
"service": "pageViewService"
},
"message": "Sample message"
},
"type": "log",
"id": "AQAAAXUAXVNSvuMvWwAAAABBWFVBWFZOU2I2ZWcxX3c2LVVBQQ"
}
],
"links": {
"next": "https://api.datadoghq.com/api/v2/logs/events?sort=-%40pageViews&filter%5Bto%5D=2020-10-07T00%3A15%3A00%2B00%3A00&page%5Bcursor%5D=eyJhZnRlciI6IkFRQUFBWFVBWFZOU3Z1TXZXd0FBQUFCQldGVkJXRlpPVTJJMlpXY3hYM2MyTFZWQlFRIiwidmFsdWVzIjpbIjUwMCJdfQ&filter%5Bfrom%5D=2020-10-07T00%3A00%3A00%2B00%3A00&filter%5Bquery%5D=%2A&page%5Blimit%5D=2"
}
}
Ajustes de hora
Los parámetros from y to pueden ser:
- una cadena ISO-8601
- una marca temporal unix (número que representa los milisegundos transcurridos desde epoch)
- una cadena matemática de fecha como
+1h para añadir una hora, -2d to subtract two days, etc. The full list includes s for seconds, m for minutes, h for hours, and d for days. Optionally, use now (ahora) para indicar la hora actual.
{
"filter": {
"from": "now-1h",
"to": "now"
}
}
La zona horaria puede especificarse como un desfase (por ejemplo, “UTC+03:00”) o como una zona regional (por ejemplo, “Europa/París”). Si se indican a la vez el desfase y la zona horaria, prevalece el desfase. El desfase debe indicarse en segundos.
{
"options": {
"timeOffset": -1000,
"timezone": "Europe/Paris"
}
}
Paginación
Para recuperar una lista de log más larga que el límite de logs 1000, utiliza la función de paginación.
El parámetro data es una matriz de objetos de logs y como máximo contiene tantos logs como se definan con el parámetro limit en tu consulta. Este parámetro es 50 por defecto, pero puede configurarse hasta 1000.
Para ver la página siguiente de tus logs, vuelve a enviar la consulta con el parámetro cursor que toma el valor after de la llamada anterior.
A partir del ejemplo JSON anterior, utiliza el valor after eyJhZnRlciI6IkFRQUFBWFVBWFZOU3Z1TXZXd0FBQUFCQldGVkJXRlpPVTJJMlpXY3hYM2MyTFZWQlFRIiwidmFsdWVzIjpbIjUwMCJdfQ para obtener los dos resultados siguientes.
curl -L -X POST "https://api.
Respuesta:
En la respuesta, se recuperan los dos resultados siguientes, joe con 500 pageviews y chris con 450 pageviews. Cuando veas que data devuelve null, habrás devuelto todas las páginas de logs asociadas a tu consulta.
{
"meta": {
"page": {
"after": "eyJhZnRlciI6IkFRQUFBWFVBWGQ5MU05d3lUZ0FBQUFCQldGVkJXR1E1TVZaclFtRnpkRVoyVEc5QlFRIiwidmFsdWVzIjpbIjQ1MCJdfQ"
}
},
"data": [
{
"attributes": {
"status": "info",
"service": "pageViewService",
"tags": [
"source:postman",
"project:test"
],
"timestamp": "2020-10-07T00:00:59.733Z",
"host": "my.sample.host",
"attributes": {
"hostname": "my.sample.host",
"pageViews": "500",
"user": "joe",
"service": "pageViewService"
},
"message": "Sample message"
},
"type": "log",
"id": "AQAAAXUAXHFV1KuyTgAAAABBWFVBWEhGVlZrQmFzdEZ2X2dBQQ"
},
{
"attributes": {
"status": "info",
"service": "pageViewService",
"tags": [
"source:postman",
"project:test"
],
"timestamp": "2020-10-07T00:02:33.461Z",
"host": "my.sample.host",
"attributes": {
"hostname": "my.sample.host",
"pageViews": "450",
"user": "chris",
"service": "pageViewService"
},
"message": "Sample message"
},
"type": "log",
"id": "AQAAAXUAXd91M9wyTgAAAABBWFVBWGQ5MVZrQmFzdEZ2TG9BQQ"
}
],
"links": {
"next": "https://api.datadoghq.com/api/v2/logs/events?sort=-%40pageViews&filter%5Bto%5D=2020-10-07T00%3A15%3A00%2B00%3A00&page%5Bcursor%5D=eyJhZnRlciI6IkFRQUFBWFVBWGQ5MU05d3lUZ0FBQUFCQldGVkJXR1E1TVZaclFtRnpkRVoyVEc5QlFRIiwidmFsdWVzIjpbIjQ1MCJdfQ&filter%5Bfrom%5D=2020-10-07T00%3A00%3A00%2B00%3A00&filter%5Bquery%5D=%2A&page%5Blimit%5D=2"
}
}
Nota: Evita el uso de intervalos de tiempo relativos cuando utilices la paginación, ya que puede hacer que se pierdan resultados de búsqueda.
Referencias adicionales
Más enlaces, artículos y documentación útiles:
