(Legacy) Detección y agregación automática multilínea

Este documento se aplica a las versiones del Agent anteriores a la v7.65.0, o cuando la detección automática multilínea legacy está explícitamente activada. Para versiones más recientes del Agent, consulta Detección y agregación automática multilínea.

Agregación automática global multilínea

Con el Agent 7.37+, puedes habilitar auto_multi_line_detection para que detecte automáticamente patrones multilínea comunes en todas las integraciones de log configuradas.

Activa auto_multi_line_detection globalmente en el archivo datadog.yaml:

logs_config:
  auto_multi_line_detection: true

Utiliza la variable de entorno DD_LOGS_CONFIG_AUTO_MULTI_LINE_DETECTION en el contenedor del Datadog Agent para configurar una regla global de agregación automática multilínea. Por ejemplo:

DD_LOGS_CONFIG_AUTO_MULTI_LINE_DETECTION=true

Operación

Utiliza el parámetro spec.override.nodeAgent.env en tu manifiesto del Datadog Operator para establecer la variable de entorno DD_LOGS_CONFIG_AUTO_MULTI_LINE_DETECTION para configurar una regla global de agregación automática multilínea. Por ejemplo:

spec:
  override:
    nodeAgent:
      env:
        - name: DD_LOGS_CONFIG_AUTO_MULTI_LINE_DETECTION
          value: "true"

Helm

Utiliza la opción Datadog.log.autoMultiLineDetection en el Helm chart para configurar una regla global de agregación automática multilínea. Por ejemplo:

datadog:
  logs:
    enabled: true
    autoMultiLineDetection: true
En las versiones del Agent 7.65+, puedes elegir el comportamiento legacy al configurar en true lo siguiente:
- logs_config.force_auto_multi_line_detection_v1 en tu archivo datadog.yaml
O
- LOGS_CONFIG_FORCE_AUTO_MULTI_LINE_DETECTION_V1 en tu variable de entorno.

Activar la agregación multilínea por integración

Alternativamente, puedes activar o desactivar la agregación multilínea para la recopilación de logs de una integración individual. Al cambiar la agregación multilínea para una integración se anula la configuración global.

En un entorno de host, habilita auto_multi_line_detection con el método Recopilación de logs personalizada. Por ejemplo:

logs:
  - type: file
    path: /my/test/file.log
    service: testApp
    source: java
    auto_multi_line_detection: true

En un entorno de Docker, utiliza la etiqueta com.datadoghq.ad.log en tu contenedor para especificar la configuración del log. Por ejemplo:

 labels:
    com.datadoghq.ad.logs: >-
      [{
        "source": "java",
        "service": "testApp",
        "auto_multi_line_detection": true
      }]

En un entorno de Kubernetes, utiliza la anotación ad.datadoghq.com/<CONTAINER_NAME>.log en tu pod para especificar la configuración del log. Por ejemplo:

apiVersion: apps/v1
metadata:
  name: testApp
spec:
  selector:
    matchLabels:
      app: testApp
  template:
    metadata:
      annotations:
        ad.datadoghq.com/<CONTAINER_NAME>.logs: >-
          [{
            "source": "java",
            "service": "testApp",
            "auto_multi_line_detection": true
          }]
      labels:
        app: testApp
      name: testApp
    spec:
      containers:
        - name: '<CONTAINER_NAME>'
          image: testApp:latest

Personalizar la configuración de la agregación multilínea

La detección automática multilínea utiliza una lista de expresiones regulares comunes para coincidir con los logs. Si la lista incorporada no es suficiente, también puedes añadir patrones y umbrales personalizados para la detección.

Patrones personalizados

En un archivo de configuración, añade auto_multi_line_extra_patterns a tu datadog.yaml:

logs_config:
  auto_multi_line_detection: true
  auto_multi_line_extra_patterns:
   - \d{4}\-(0?[1-9]|1[012])\-(0?[1-9]|[12][0-9]|3[01])
   - '[A-Za-z_]+ \d+, \d+ \d+:\d+:\d+ (AM|PM)'

Umbral personalizado

El parámetro auto_multi_line_default_match_threshold determina hasta qué punto los logs deben coincidir con los patrones para que funcione la agregación multilínea automática.

Si tus logs multilínea no se agregan como se espera, puedes cambiar la sensibilidad de la coincidencia configurando el parámetro auto_multi_line_default_match_threshold. Añade el parámetro auto_multi_line_default_match_threshold a tu archivo de configuración con un valor inferior (para aumentar las coincidencias) o superior (para reducirlas) al valor del umbral actual.

Reinicia el Datadog Agent para aplicar el nuevo valor de umbral a los logs recién ingeridos. Para conocer el valor de umbral actual, ejecuta el comando status del Agent.

logs_config:
  auto_multi_line_detection: true
  auto_multi_line_extra_patterns:
   - \d{4}\-(0?[1-9]|1[012])\-(0?[1-9]|[12][0-9]|3[01])
   - '[A-Za-z_]+ \d+, \d+ \d+:\d+:\d+ (AM|PM)'
  auto_multi_line_default_match_threshold: 0.1

En un Agent en contenedores, añade la variable de entorno DD_LOGS_CONFIG_AUTO_MULTI_LINE_EXTRA_PATTERNS:

    environment:
      - DD_LOGS_CONFIG_AUTO_MULTI_LINE_DETECTION=true
      - DD_LOGS_CONFIG_AUTO_MULTI_LINE_EXTRA_PATTERNS=\d{4}-(0?[1-9]|1[012])-(0?[1-9]|[12][0-9]|3[01]) [A-Za-z_]+\s\d+,\s\d+\s\d+:\d+:\d+\s(AM|PM)

Nota: El Datadog Agent interpreta los espacios en la variable de entorno DD_LOGS_CONFIG_AUTO_MULTI_LINE_EXTRA_PATTERNS como separadores entre varios patrones. En el siguiente ejemplo, los dos patrones de expresión regular están divididos por un espacio, y \s en el segundo patrón de expresión regular coincide con espacios.

Umbral personalizado

El parámetro auto_multi_line_default_match_threshold determina el grado de coincidencia de los logs con los patrones para que funcione la agregación multilínea automática.

Si tus logs multilínea no se agregan como se espera, puedes cambiar la sensibilidad de la coincidencia configurando el parámetro auto_multi_line_default_match_threshold.

Añade el parámetro auto_multi_line_default_match_threshold a tu archivo de configuración con un valor inferior (para aumentar las coincidencias) o superior (para disminuirlas) al valor del umbral actual.

Para conocer el valor umbral actual, ejecuta el comando status del Agent.

    environment:
      - DD_LOGS_CONFIG_AUTO_MULTI_LINE_DETECTION=true
      - DD_LOGS_CONFIG_AUTO_MULTI_LINE_EXTRA_PATTERNS=\d{4}-(0?[1-9]|1[012])-(0?[1-9]|[12][0-9]|3[01]) [A-Za-z_]+\s\d+,\s\d+\s\d+:\d+:\d+\s(AM|PM)
      - DD_LOGS_CONFIG_AUTO_MULTI_LINE_DEFAULT_MATCH_THRESHOLD=0.1

En Kubernetes, añade la variable de entorno DD_LOGS_CONFIG_AUTO_MULTI_LINE_EXTRA_PATTERNS:

Operación

spec:
  override:
    nodeAgent:
      env:
        - name: DD_LOGS_CONFIG_AUTO_MULTI_LINE_EXTRA_PATTERNS
          value: \d{4}-(0?[1-9]|1[012])-(0?[1-9]|[12][0-9]|3[01]) [A-Za-z_]+\s\d+,\s\d+\s\d+:\d+:\d+\s(AM|PM)

Helm

datadog:
  env:
    - name: DD_LOGS_CONFIG_AUTO_MULTI_LINE_EXTRA_PATTERNS
      value: \d{4}-(0?[1-9]|1[012])-(0?[1-9]|[12][0-9]|3[01]) [A-Za-z_]+\s\d+,\s\d+\s\d+:\d+:\d+\s(AM|PM)

Nota: El Datadog Agent interpreta los espacios en la variable de entorno DD_LOGS_CONFIG_AUTO_MULTI_LINE_EXTRA_PATTERNS como separadores entre varios patrones. En el siguiente ejemplo, los dos patrones de expresión regular están divididos por un espacio, y \s en el segundo patrón de expresión regular coincide con espacios.

Umbral personalizado

El parámetro auto_multi_line_default_match_threshold determina el grado de coincidencia de los logs con los patrones para que funcione la agregación multilínea automática.

Si tus logs multilínea no se agregan como se espera, puedes cambiar la sensibilidad de la coincidencia configurando el parámetro auto_multi_line_default_match_threshold. Añade el parámetro auto_multi_line_default_match_threshold a tu archivo de configuración con un valor inferior (para aumentar las coincidencias) o superior (para reducirlas) al valor del umbral actual. Para conocer el valor de umbral actual, ejecuta el comando status del Agent.

Operación

spec:
  override:
    nodeAgent:
      env:
        - name: DD_LOGS_CONFIG_AUTO_MULTI_LINE_EXTRA_PATTERNS
          value: \d{4}-(0?[1-9]|1[012])-(0?[1-9]|[12][0-9]|3[01]) [A-Za-z_]+\s\d+,\s\d+\s\d+:\d+:\d+\s(AM|PM)
        - name: DD_LOGS_CONFIG_AUTO_MULTI_LINE_DEFAULT_MATCH_THRESHOLD
          value: "0.1"

Helm

datadog:
  env:
    - name: DD_LOGS_CONFIG_AUTO_MULTI_LINE_EXTRA_PATTERNS
      value: \d{4}-(0?[1-9]|1[012])-(0?[1-9]|[12][0-9]|3[01]) [A-Za-z_]+\s\d+,\s\d+\s\d+:\d+:\d+\s(AM|PM)
    - name: DD_LOGS_CONFIG_AUTO_MULTI_LINE_DEFAULT_MATCH_THRESHOLD
      value: "0.1"

Proceso de detección

La detección automática multilínea detecta los logs que comienzan y cumplen los siguientes formatos de fecha/hora:

  • ANSIC
  • RFC822
  • RFC822Z
  • RFC850
  • RFC1123
  • RFC1123Z
  • RFC3339
  • RFC3339Nano
  • Formato de fecha Ruby
  • Formato de fecha Unix
  • Formato de fecha SimpleFormatter de logs Java por defecto

Con la agregación multilínea activada, el Agent intenta primero detectar un patrón en cada nuevo archivo de log. Este proceso de detección dura como máximo 30 segundos o los primeros 500 logs, lo que ocurra primero. Durante el proceso de detección inicial, los logs se envían como líneas individuales.

Una vez alcanzado el umbral de detección, todos los logs futuros de esa fuente se agregan con el patrón que mejor coincida, o como líneas únicas si no se encuentra ningún patrón.

Nota: Si puedes controlar el patrón de nombres del log rotado, asegúrate de que el archivo rotado sustituya al archivo activo anteriormente con ese mismo nombre. El Agent reutiliza un patrón detectado anteriormente en el archivo recién rotado para evitar tener que volver a ejecutar la detección.

Referencias adicionales