본문 바로가기
WIKI 기술 지식 베이스

(레거시) 자동 멀티라인 감지 및 집계 ((Legacy) Automatic Multi-line Detection and Aggregation)

원문 보기 위키 갱신

(레거시) Datadog Agent가 여러 줄로 된 로그(멀티라인 로그)를 자동으로 감지하고 집계하는 방법을 알려드릴게요. 이 문서는 Agent v7.65.0 이전 버전이나 레거시 자동 멀티라인 감지를 명시적으로 활성화한 경우에 적용돼요.

출처: 문서

본문

이 문서는 Agent v7.65.0 이전 버전 또는 레거시 자동 멀티라인 감지를 명시적으로 활성화한 경우에 적용돼요. 더 새로운 Agent 버전은 자동 멀티라인 감지 및 집계를 참고하세요.

전역 자동 멀티라인 집계 (Global automatic multi-line aggregation)

Agent 7.37+에서는 auto_multi_line_detection을 활성화해 구성된 모든 로그 통합에서 공통 멀티라인 패턴을 자동으로 감지할 수 있어요.

구성 파일 — datadog.yaml 파일에서 auto_multi_line_detection을 전역으로 활성화하세요:

logs_config:
  auto_multi_line_detection: true

Docker — Datadog Agent 컨테이너에서 DD_LOGS_CONFIG_AUTO_MULTI_LINE_DETECTION 환경 변수를 사용해 전역 자동 멀티라인 집계 규칙을 구성하세요. 예:

DD_LOGS_CONFIG_AUTO_MULTI_LINE_DETECTION=true

Kubernetes

Operator

Datadog Operator 매니페스트에서 spec.override.nodeAgent.env 파라미터를 사용해 DD_LOGS_CONFIG_AUTO_MULTI_LINE_DETECTION 환경 변수를 설정해 전역 자동 멀티라인 집계 규칙을 구성하세요. 예:

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

Helm

Helm 차트에서 datadog.logs.autoMultiLineDetection 옵션을 사용해 전역 자동 멀티라인 집계 규칙을 구성하세요. 예:

datadog:
  logs:
    enabled: true
    autoMultiLineDetection: true

Agent 7.65+ 버전에서는 다음 중 하나를 true로 설정해 레거시 동작을 옵트인할 수 있어요: - datadog.yaml 파일의 logs_config.force_auto_multi_line_detection_v1 또는 - 환경 변수의 LOGS_CONFIG_FORCE_AUTO_MULTI_LINE_DETECTION_V1.

통합별 멀티라인 집계 활성화

또는 개별 통합의 로그 수집에 대해 멀티라인 집계를 활성화하거나 비활성화할 수 있어요. 통합에 대한 멀티라인 집계를 변경하면 전역 구성을 덮어써요.

구성 파일 — 호스트 환경에서 커스텀 로그 수집 방식으로 auto_multi_line_detection을 활성화하세요. 예:

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

Docker — Docker 환경에서 컨테이너의 com.datadoghq.ad.logs 라벨을 사용해 로그 구성을 지정하세요. 예:

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

Kubernetes — Kubernetes 환경에서 pod의 ad.datadoghq.com/<CONTAINER_NAME>.logs 어노테이션을 사용해 로그 구성을 지정하세요. 예:

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

멀티라인 집계 구성 커스터마이즈

자동 멀티라인 감지는 공통 정규식 목록을 사용해 로그를 매칭해요. 내장 목록으로 부족하다면 감지를 위한 커스텀 패턴과 임계값도 추가할 수 있어요.

커스텀 패턴 (Custom Patterns)

구성 파일 — 구성 파일에서 auto_multi_line_extra_patterns를 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)'

커스텀 임계값 (Custom threshold)

auto_multi_line_default_match_threshold 파라미터는 자동 멀티라인 집계가 동작하기 위해 로그가 패턴과 얼마나 밀접하게 일치해야 하는지를 결정해요.

멀티라인 로그가 기대대로 집계되지 않는다면 auto_multi_line_default_match_threshold 파라미터를 설정해 매칭 감도를 변경할 수 있어요. 현재 임계값보다 낮은 값(매치 증가) 또는 높은 값(매치 감소)으로 구성 파일에 auto_multi_line_default_match_threshold 파라미터를 추가하세요.

새로 수집되는 로그에 새 임계값을 적용하려면 Datadog Agent를 재시작하세요. 현재 임계값을 찾으려면 Agent status 명령어를 실행하세요.

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

Docker — 컨테이너화된 Agent에서 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)

참고: Datadog Agent는 DD_LOGS_CONFIG_AUTO_MULTI_LINE_EXTRA_PATTERNS 환경 변수의 공백을 여러 패턴 사이의 구분자로 해석해요. 다음 예시에서 두 정규식 패턴은 공백으로 나뉘며, 두 번째 정규식의 \s는 공백과 일치해요.

커스텀 임계값 (Custom threshold)

auto_multi_line_default_match_threshold 파라미터는 자동 멀티라인 집계가 동작하기 위해 로그가 패턴과 얼마나 밀접하게 일치해야 하는지를 결정해요.

멀티라인 로그가 기대대로 집계되지 않는다면 auto_multi_line_default_match_threshold 파라미터를 설정해 매칭 감도를 변경할 수 있어요.

현재 임계값보다 낮은 값(매치 증가) 또는 높은 값(매치 감소)으로 구성 파일에 auto_multi_line_default_match_threshold 파라미터를 추가하세요.

현재 임계값을 찾으려면 Agent status 명령어를 실행하세요.

    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

Kubernetes — Kubernetes에서 DD_LOGS_CONFIG_AUTO_MULTI_LINE_EXTRA_PATTERNS 환경 변수를 추가하세요:

Operator

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)

참고: Datadog Agent는 DD_LOGS_CONFIG_AUTO_MULTI_LINE_EXTRA_PATTERNS 환경 변수의 공백을 여러 패턴 사이의 구분자로 해석해요. 다음 예시에서 두 정규식 패턴은 공백으로 나뉘며, 두 번째 정규식의 \s는 공백과 일치해요.

커스텀 임계값 (Custom threshold)

auto_multi_line_default_match_threshold 파라미터는 자동 멀티라인 집계가 동작하기 위해 로그가 패턴과 얼마나 밀접하게 일치해야 하는지를 결정해요.

멀티라인 로그가 기대대로 집계되지 않는다면 auto_multi_line_default_match_threshold 파라미터를 설정해 매칭 감도를 변경할 수 있어요. 현재 임계값보다 낮은 값(매치 증가) 또는 높은 값(매치 감소)으로 구성 파일에 auto_multi_line_default_match_threshold 파라미터를 추가하세요. 현재 임계값을 찾으려면 Agent status 명령어를 실행하세요.

Operator

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"

감지 과정 (Detection process)

자동 멀티라인 감지는 다음 날짜/시간 형식으로 시작하고 그에 부합하는 로그를 감지해요:

  • ANSIC
  • RFC822
  • RFC822Z
  • RFC850
  • RFC1123
  • RFC1123Z
  • RFC3339
  • RFC3339Nano
  • Ruby Date Format
  • Unix Date Format
  • Default Java logging SimpleFormatter date format

멀티라인 집계가 활성화되면 Agent는 먼저 각 새 로그 파일에서 패턴을 감지하려고 해요. 이 감지 과정은 최대 30초 또는 처음 500개 로그 중 먼저 도달하는 것까지 걸려요. 초기 감지 과정 동안 로그는 한 줄씩 전송돼요.

감지 임계값을 충족한 뒤에는 해당 소스의 이후 모든 로그가 가장 잘 맞는 패턴으로 집계되거나, 패턴이 없으면 한 줄씩 집계돼요.

참고: 로테이션된 로그의 이름 패턴을 제어할 수 있다면, 로테이션된 파일이 이전 활성 파일을 같은 이름으로 교체하도록 하세요. Agent는 새로 로테이션된 파일에 이전에 감지된 패턴을 재사용해 감지 재실행을 피해요.

더 알아보기 (Learn more)

도움이 되는 추가 문서, 링크, 글: