Prueba el análisis Grok en el Centro de Aprendizaje

Aprende a construir y modificar canalizaciones de registros, gestionarlas con el Escáner de Canalizaciones y estandarizar los nombres de atributos en los registros procesados para mantener la consistencia.

INSCRÍBETE AHORA

Resumen

Datadog analiza automáticamente los registros en formato JSON. Para otros formatos, Datadog te permite enriquecer tus registros con la ayuda del Analizador Grok. La sintaxis Grok proporciona una forma más fácil de analizar registros que las expresiones regulares puras. El Analizador Grok te permite extraer atributos de mensajes de texto semiestructurados.

Grok viene con patrones reutilizables para analizar enteros, direcciones IP, nombres de host, etc. Estos valores deben enviarse al analizador grok como cadenas.

Puedes escribir reglas de análisis con la sintaxis %{MATCHER:EXTRACT:FILTER}:

• Matcher: Una regla (posiblemente una referencia a otra regla de token) que describe qué esperar (número, palabra, noEspacio, etc.).

• Extract (opcional): Un identificador que representa el destino de captura para el fragmento de texto coincidente con el Matcher.

• Filter (opcional): Un post-procesador de la coincidencia para transformarla.

Ejemplo de un registro no estructurado clásico:

john connected on 11/08/2017

Con la siguiente regla de análisis:

MyParsingRule %{word:user} connected on %{date("MM/dd/yyyy"):date}

Después de procesar, se genera el siguiente registro estructurado:

{
  "user": "john",
  "date": 1575590400000
}

Nota:

• Si tienes múltiples reglas de análisis en un solo analizador Grok:
  • Solo una puede coincidir con cualquier registro dado. La primera que coincida, de arriba hacia abajo, es la que realiza el análisis.
  • Cada regla puede hacer referencia a reglas de análisis definidas por encima de sí misma en la lista.
• Debes tener nombres de regla únicos dentro del mismo analizador Grok.
• El nombre de la regla debe contener solo: caracteres alfanuméricos, _, y .. Debe comenzar con un carácter alfanumérico.
• Las propiedades con valores nulos o vacíos no se muestran.
• Debes definir tu regla de análisis para que coincida con toda la entrada del registro, ya que cada regla se aplica desde el principio hasta el final del registro.
• Ciertos registros pueden producir grandes espacios en blanco. Utiliza \n y \s+ para contabilizar saltos de línea y espacios en blanco.

Matcher y filtro

Aquí hay una lista de todos los matchers y filtros implementados nativamente por Datadog:

Configuraciones avanzadas

Utiliza la sección de Configuraciones Avanzadas al final de tu procesador Grok para analizar un atributo específico en lugar del atributo message por defecto, o para definir reglas auxiliares que reutilicen patrones comunes en múltiples reglas de parseo.

Parseo de un atributo de texto específico

Utiliza el campo de Extraer de para aplicar tu procesador Grok en un atributo de texto dado en lugar del atributo message por defecto.

Por ejemplo, considera un registro que contiene un atributo command.line que debe ser parseado como un par clave-valor. Extrae de command.line para analizar su contenido y crear atributos estructurados a partir de los datos del comando.

Uso de reglas auxiliares para reutilizar patrones comunes

Utiliza el campo de Reglas Auxiliares para definir tokens para tus reglas de parseo. Las reglas auxiliares te permiten reutilizar patrones comunes de Grok en tus reglas de análisis. Esto es útil cuando tienes varias reglas en el mismo procesador Grok que utilizan los mismos tokens.

Ejemplo de un registro no estructurado clásico:

john id:12345 connected on 11/08/2017 on server XYZ in production

Utiliza la siguiente regla de parseo:

MyParsingRule %{user} %{connection} %{server}

Con los siguientes auxiliares:

user %{word:user.name} id:%{integer:user.id}
connection connected on %{date("MM/dd/yyyy"):connect_date}
server on server %{notSpace:server.name} in %{notSpace:server.env}

Ejemplos

Algunos ejemplos que demuestran cómo usar analizadores:

• Clave-valor o logfmt
• Parseo de fechas
• Patrones alternos
• Atributo opcional
• JSON anidado
• Expresiones regulares
• Lista y arrays
• Formato Glog
• XML
• CSV

Clave-valor o logfmt

Este es el filtro central de clave-valor: keyvalue([separatorStr[, characterAllowList[, quotingStr[, delimiter]]]]) donde:

• separatorStr: define el separador entre clave y valores. Por defecto es =.
• characterAllowList: define caracteres de valor adicionales no escapados además del valor por defecto \\w.\\-_@. Se usa solo para valores no entrecomillados (por ejemplo, key=@valueStr).
• quotingStr: define comillas, reemplazando la detección de comillas por defecto: <>, "", ''.
• delimiter: define el separador entre los diferentes pares de clave-valor (por ejemplo, | es el delimitador en key1=value1|key2=value2). Por defecto es (espacio normal), , y ;.

Usa filtros como keyvalue para mapear más fácilmente cadenas a atributos para formatos de clave-valor o logfmt:

Registro:

user=john connect_date=11/08/2017 id=123 action=click

Regla:

rule %{data::keyvalue}

No es necesario especificar el nombre de tus parámetros ya que ya están contenidos en el registro. Si agregas un atributo extractmy_attribute en tu patrón de regla, verás:

{
  "my_attribute": {
    "user": "john",
    "id": 123,
    "action": "click"
  }
}

Si = no es el separador predeterminado entre tu clave y valores, agrega un parámetro en tu regla de parseo con un separador.

Registro:

user: john connect_date: 11/08/2017 id: 123 action: click

Regla:

rule %{data::keyvalue(": ")}

Si los registros contienen caracteres especiales en un valor de atributo, como / en una URL, agrégalo a la lista de permitidos en la regla de parseo:

Registro:

url=https://app.datadoghq.com/event/stream user=john

Regla:

rule %{data::keyvalue("=","/:")}

Otros ejemplos:

Ejemplo de cadena con múltiples comillas: Cuando se definen múltiples cadenas entre comillas, el comportamiento predeterminado se reemplaza por un carácter de comillas definido. La clave-valor siempre coincide con las entradas sin ningún carácter de comillas, independientemente de lo que se especifique en quotingStr. Cuando se utilizan caracteres de comillas, se ignora el characterAllowList ya que todo lo que está entre los caracteres de comillas se extrae.

Registro:

key1:=valueStr key2:=</valueStr2> key3:="valueStr3"

Regla:

rule %{data::keyvalue(":=","","<>")}

Resultado:

{"key1": "valueStr", "key2": "/valueStr2"}

Nota:

• Los valores vacíos (key=) o los valores null (key=null) no se muestran en el JSON de salida.
• Si defines un filtro de keyvalue en un data objeto, y este filtro no coincide, entonces se devuelve un JSON vacío {} (por ejemplo, entrada: key:=valueStr, regla de parseo: rule_test %{data::keyvalue("=")}, salida: {}).
• Definir "" como quotingStr mantiene la configuración predeterminada para las comillas.

Parseo de fechas

El comparador de fechas transforma tu marca de tiempo en el formato EPOCH (unidad de medida milisegundo).

¹ Utiliza el timezone parámetro si realizas tus propias localizaciones y tus marcas de tiempo no están en UTC. El formato soportado para zonas horarias es:

• GMT, UTC, UT o Z
• +hh:mm, -hh:mm, +hhmm, -hhmm. El rango máximo soportado es de +18:00 a -18:00 inclusive.
• Zonas horarias que comienzan con UTC+, UTC-, GMT+, GMT-, UT+ o UT-. El rango máximo soportado es de +18:00 a -18:00 inclusive.
• IDs de zona horaria extraídos de la base de datos TZ. Para más información, consulte nombres de la base de datos TZ.

Nota: El parseo de una fecha no establece su valor como la fecha oficial del registro. Para esto, utiliza el Remapeador de Fecha de Registro en un procesador posterior.

Patrón alternante

Si tiene registros con dos formatos posibles que difieren en solo un atributo, establezca una única regla utilizando alternancia con (<REGEX_1>|<REGEX_2>). Esta regla es equivalente a un operador booleano OR.

Registro:

john connected on 11/08/2017
12345 connected on 11/08/2017

Regla: Tenga en cuenta que “id” es un entero y no una cadena.

MyParsingRule (%{integer:user.id}|%{word:user.firstname}) connected on %{date("MM/dd/yyyy"):connect_date}

Resultados:
%{integer:user.id}

{
  "user": {
    "id": 12345
  },
  "connect_date": 1510099200000
}

%{word:user.firstname}

{
  "user": {
    "firstname": "john"
  },
  "connect_date": 1510099200000
}

Atributo opcional

Algunos registros contienen valores que solo aparecen parte del tiempo. En este caso, haga que la extracción de atributos sea opcional con ()?.

Registro:

john 1234 connected on 11/08/2017
john connected on 11/08/2017

Regla:

MyParsingRule %{word:user.firstname} (%{integer:user.id} )?connected on %{date("MM/dd/yyyy"):connect_date}

Nota: Una regla no coincidirá si incluye un espacio después de la primera palabra en la sección opcional.

Resultado:
(%{integer:user.id} )?

{
  "user": {
    "firstname": "john",
    "id": 1234
  },
  "connect_date": 1510099200000
}

%{word:user.firstname} (%{integer:user.id} )?

{
  "user": {
    "firstname": "john",
  },
  "connect_date": 1510099200000
}

JSON anidado

Utilice el filtro json para analizar un objeto JSON anidado después de un prefijo de texto sin procesar:

Registro:

Sep 06 09:13:38 vagrant program[123]: server.1 {"method":"GET", "status_code":200, "url":"https://app.datadoghq.com/logs/pipelines", "duration":123456}

Regla:

parsing_rule %{date("MMM dd HH:mm:ss"):timestamp} %{word:vm} %{word:app}\[%{number:logger.thread_id}\]: %{notSpace:server} %{data::json}

Resultado:

{
  "timestamp": 1567761218000,
  "vm": "vagrant",
  "app": "program",
  "logger": {
    "thread_id": 123
  }
}

Regex

Registro:

john_1a2b3c4 connected on 11/08/2017

Regla:

MyParsingRule %{regex("[a-z]*"):user.firstname}_%{regex("[a-zA-Z0-9]*"):user.id} .*

Resultado:

{
  "user": {
    "firstname": "john",
    "id": "1a2b3c4"
  }
}

Lista a array

Utilice el filtro array([[openCloseStr, ] separator][, subRuleOrFilter) para extraer una lista en un array en un solo atributo. El subRuleOrFilter es opcional y acepta estos filtros.

Registro:

Users [John, Oliver, Marc, Tom] have been added to the database

Regla:

myParsingRule Users %{data:users:array("[]",",")} have been added to the database

Resultado:

{
  "users": [
    "John",
    " Oliver",
    " Marc",
    " Tom"
  ]
}

Registro:

Users {John-Oliver-Marc-Tom} have been added to the database

Regla:

myParsingRule Users %{data:users:array("{}","-")} have been added to the database

Regla usando subRuleOrFilter:

myParsingRule Users %{data:users:array("{}","-", uppercase)} have been added to the database

Formato Glog

Los componentes de Kubernetes a veces registran en el formato glog; este ejemplo es del elemento Kube Scheduler en la Biblioteca de canalización.

Línea de registro de ejemplo:

W0424 11:47:41.605188       1 authorization.go:47] Authorization is disabled

Regla de parseo:

kube_scheduler %{regex("\\w"):level}%{date("MMdd HH:mm:ss.SSSSSS"):timestamp}\s+%{number:logger.thread_id} %{notSpace:logger.name}:%{number:logger.lineno}\] %{data:msg}

Y JSON extraído:

{
  "level": "W",
  "timestamp": 1587728861605,
  "logger": {
    "thread_id": 1,
    "name": "authorization.go"
  },
  "lineno": 47,
  "msg": "Authorization is disabled"
}

Parseo XML

El analizador XML transforma mensajes en formato XML a JSON.

Registro:

<book category="CHILDREN">
  <title lang="en">Harry Potter</title>
  <author>J K. Rowling</author>
  <year>2005</year>
</book>

Regla:

rule %{data::xml}

Resultado:

{
"book": {
  "year": "2005",
  "author": "J K. Rowling",
  "category": "CHILDREN",
  "title": {
    "lang": "en",
    "value": "Harry Potter"
  }
}
}

Notas:

• Si el XML contiene etiquetas que tienen tanto un atributo como un valor de cadena entre las dos etiquetas, se genera un atributo value. Por ejemplo: <title lang="en">Harry Potter</title> se convierte en {"title": {"lang": "en", "value": "Harry Potter" } }
• Las etiquetas repetidas se convierten automáticamente en arrays. Por ejemplo: <bookstore><book>Harry Potter</book><book>Everyday Italian</book></bookstore> se convierte en { "bookstore": { "book": [ "Harry Potter", "Everyday Italian" ] } }

Parseo CSV

Utilice el filtro CSV para mapear más fácilmente cadenas a atributos cuando están separadas por un carácter dado (, por defecto).

El filtro CSV se define como csv(headers[, separator[, quotingcharacter]]) donde:

• headers: Define los nombres de las claves separados por ,. Los nombres de las claves deben comenzar con un carácter alfabético y pueden contener cualquier carácter alfanumérico además de _.
• separator: Define los separadores utilizados para separar los diferentes valores. Solo se acepta un carácter. Predeterminado: ,. Nota: Utilice tab para el separator para representar el carácter de tabulación para TSVs.
• quotingcharacter: Define el carácter de comillas. Solo se acepta un carácter. Predeterminado: "

Nota:

• Los valores que contienen un carácter separador deben estar entre comillas.
• Los valores entre comillas que contienen un carácter de comillas deben ser escapados con caracteres de comillas. Por ejemplo, "" dentro de un valor entre comillas representa ".
• Si el registro no contiene el mismo número de valores que el número de claves en el encabezado, el analizador CSV emparejará los primeros.
• Los enteros y dobles se convierten automáticamente si es posible.

Registro:

John,Doe,120,Jefferson St.,Riverside

Regla:

myParsingRule %{data:user:csv("first_name,name,st_nb,st_name,city")}

Resultado:

{
  "user": {
    "first_name": "John",
    "name": "Doe",
    "st_nb": 120,
    "st_name": "Jefferson St.",
    "city": "Riverside"
  }
}

Otros ejemplos:

Utilice el comparador de datos para descartar texto innecesario

Si tiene un registro donde, después de haber parseado lo necesario, y sabiendo que el texto posterior es seguro para descartar, puede usar el comparador de datos para ello. Para el siguiente ejemplo de registro, puede usar el data comparador para descartar el % al final.

Registro:

Usage: 24.3%

Regla:

MyParsingRule Usage\:\s+%{number:usage}%{data:ignore}

Resultado:

{
  "usage": 24.3,
  "ignore": "%"
}

Caracteres de control ASCII

Si sus registros contienen caracteres de control ASCII, se serializan al ser ingeridos. Estos pueden ser manejados escapando explícitamente el valor serializado dentro de su analizador grok.

Lectura adicional

Más enlaces, artículos y documentación útiles:

Aprende a construir y modificar canalizaciones de registrosCENTRO DE APRENDIZAJE Aprende a procesar tus registrosDOCUMENTACIÓN Consejos y Trucos de Datadog: Usa el análisis Grok para extraer campos de los registrosVIDEO ¿Cómo investigar un problema de análisis de registros?PREGUNTAS FRECUENTES Análisis de Registros - Mejores PrácticasPREGUNTAS FRECUENTES Controla el volumen de registros indexados por DatadogDOCUMENTACIÓN Depuración de canalizaciones de registrosCENTRO DE APRENDIZAJE