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

원문 보기 위키 갱신 2026.10.05

Datadog Agent가 여러 줄로 된 로그(멀티라인 로그)를 자동으로 감지하고 한 덩어리로 묶어주는 기능을 소개할게요. 예외 스택 트레이스처럼 여러 줄로 나뉘어 기록되는 로그를 정리하는 데 특히 유용해요.

출처: 문서

본문

⛔️ 이 기능은 Agent 버전 7.65.0 이상에서 사용할 수 있어요. 이전 Agent 버전을 사용하거나 레거시 구현을 명시적으로 활성화하려면 (Legacy) Automatic Multi-line Detection and Aggregation 문서를 참고하세요. Agent 버전 7.82.0보다 낮은 버전에서는 자동 멀티라인 감지가 기본적으로 비활성화되어 있어요.

개요 (Overview)

자동 멀티라인 감지는 Agent가 흔한 멀티라인 로그를 자동으로 감지하고 집계하도록 해 줍니다.

예를 들어, 애플리케이션이 아래와 같은 다섯 줄을 기록한다고 해볼게요. 자동 멀티라인 감지가 없으면 Agent는 각 줄을 각각 별도의 로그로 보내서, 예외를 그것을 유발한 메시지와 분리해 버립니다:

2024-08-13 17:15:17 ERROR Request handler failed              -> log 1
Exception in thread "main" java.lang.NullPointerException     -> log 2
    at com.example.MyClass.doSomething(MyClass.java:42)       -> log 3
    at com.example.MyClass.main(MyClass.java:20)              -> log 4
2024-08-13 17:15:18 INFO Request handler stopped              -> log 5

자동 멀티라인 감지를 활성화하면, 기본적으로 datetime으로 시작하는 줄만 새 로그를 시작해요. 예외와 그 스택 트레이스는 그 앞에 있는 로그에 집계되므로, 같은 다섯 줄이 두 개의 로그로 전송됩니다:

2024-08-13 17:15:17 ERROR Request handler failed           --+
Exception in thread "main" java.lang.NullPointerException    |
    at com.example.MyClass.doSomething(MyClass.java:42)      |-> log 1
    at com.example.MyClass.main(MyClass.java:20)           --+

2024-08-13 17:15:18 INFO Request handler stopped              -> log 2

시작하기 (Getting started)

자동 멀티라인 감지는 Agent 버전 7.82.0부터 기본적으로 활성화됩니다. Agent 구성에서 자동 멀티라인 기능을 비활성화하려면 설정 파일에서 auto_multi_line_detection을 false로 설정하거나, DD_LOGS_CONFIG_AUTO_MULTI_LINE_DETECTION=false 환경 변수를 설정하세요:

Configuration file

logs_config:
  auto_multi_line_detection: false

Environment Variable

DD_LOGS_CONFIG_AUTO_MULTI_LINE_DETECTION=false

기본 설정 (Default settings)

기본적으로 다음 기능이 활성화됩니다:

enable_datetime_detection: 자동 datetime 집계를 구성해요. datetime 형식으로 시작하는 로그를 집계에 사용합니다.
enable_json_detection: JSON 감지 및 거부를 구성해요. JSON 구조의 로그는 절대 집계되지 않습니다.

설정 파일이나 환경 변수에서 다음을 false로 설정하면 이 기능들을 비활성화할 수 있어요:

Configuration file

logs_config:
  auto_multi_line:
    enable_datetime_detection: false
    enable_json_detection: false

Environment Variables

DD_LOGS_CONFIG_AUTO_MULTI_LINE_ENABLE_DATETIME_DETECTION=false
DD_LOGS_CONFIG_AUTO_MULTI_LINE_ENABLE_JSON_DETECTION=false

통합별 멀티라인 집계 활성화 (Enable multi-line aggregation per integration)

특정 통합의 로그 수집에 대해 멀티라인 집계를 활성화하거나 비활성화할 수 있어요:

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

통합별 멀티라인 설정 (Per integration multi-line integration settings)

각 통합에 자동 멀티라인 설정을 개별적으로 지정할 수 있어요. 통합은 일반 datadog.yaml 파일과 동일한 설정을 받아들입니다:

logs:
  - type: file
    path: /my/test/file.log
    service: testApp
    source: java
    auto_multi_line_detection: true
    auto_multi_line_detection_custom_samples:
      - sample: "ERROR [DatabaseService]"
    auto_multi_line:
        enable_json_detection: true
        enable_datetime_detection: true
        tokenizer_max_input_bytes: 50

지원되는 datetime 형식 (Supported datetime formats)

자동 멀티라인 감지는 로그 줄의 첫 60바이트에서 나타나는 어떤 datetime 형식이든 감지하는 알고리즘을 사용해요. 오탐(false positive)을 막기 위해, 알고리즘은 datetime 형식을 매치로 간주할 만큼 충분한 컨텍스트를 요구합니다.

datetime 형식이 감지되려면 날짜(date) 와 시간(time) 구성 요소를 모두 포함해야 해요.

감지될 만큼 충분한 컨텍스트를 포함하는 유효한 형식의 예:

2021-03-28 13:45:30
2023-03-28T14:33:53.743350Z
Jun 14 15:16:01
2024/05/16 19:46:15

감지될 만큼 충분한 컨텍스트가 없는 형식의 예:

12:30:2017
12:30:20
2024/05/16

커스텀 패턴 구성 (Custom pattern configuration)

datetime 집계가 충분하지 않거나 형식이 너무 짧아 자동 감지가 안 된다면, 다음 두 가지 방법으로 기능을 커스터마이즈할 수 있어요:

커스텀 샘플(Custom Samples)
정규식 패턴(Regex Patterns)

커스텀 샘플 (Custom samples)

커스텀 샘플은 집계하고 싶은 로그의 샘플이에요. 예를 들어 스택 트레이스를 집계하려면 스택 트레이스의 첫 줄이 좋은 샘플이 됩니다. 커스텀 샘플은 정규식 패턴보다 로그를 집계하기 더 쉬운 방법이에요.

커스텀 샘플을 구성하려면 datadog.yaml 파일의 logs_config를 사용하거나 환경 변수를 설정하세요. 다음 예시에서 멀티라인 감지는 샘플 "SEVERE Main main Exception occurred"를 찾고 있어요:

Configuration file

logs_config:
  auto_multi_line_detection_custom_samples:
    - sample: "SEVERE Main main Exception occurred"

Environment Variables

DD_LOGS_CONFIG_AUTO_MULTI_LINE_DETECTION_CUSTOM_SAMPLES='[{"sample": "SEVERE Main main Exception occurred"}]'

이 설정은 "SEVERE Main main Exception occurred"가 첫 줄과 일치하는 로그를 집계합니다. 예를 들면:

SEVERE Main main Exception occurred
java.lang.Exception: Something bad happened!
    at Main.funcd(Main.java:50)
    at Main.funcc(Main.java:49)
    at Main.funcb(Main.java:48)
    at Main.funca(Main.java:47)
    at Main.main(Main.java:29)

커스텀 샘플 동작 방식 (How custom samples work)

커스텀 샘플은 로그 줄의 첫 60바이트를 토큰화하고, 제공된 샘플도 토큰화해요. 토큰에는 다음이 포함됩니다:

단어와 그 길이
공백(whitespace)
숫자와 그 길이
특수 문자
datetime 구성 요소

각 로그 토큰은 샘플의 각 토큰과 비교됩니다. 로그 토큰의 75%가 샘플과 일치하면 로그는 집계 대상으로 표시돼요. 로그 형식이 안정적이라면 샘플 기반 매칭을 사용하는 것을 Datadog은 추천합니다. 더 유연한 매칭이 필요하다면 정규식을 사용할 수 있어요.

정규식 패턴 (Regex patterns)

정규식 패턴은 multi_line 규칙과 비슷하게 동작해요. 정규식 패턴이 로그와 일치하면 그 로그를 집계에 사용합니다.

커스텀 정규식 패턴을 구성하려면 datadog.yaml 파일의 logs_config를 사용하거나 환경 변수를 설정하세요.

Configuration file

logs_config:
  auto_multi_line_detection_custom_samples:
    - regex: "\\[\\w+\\] Main main Exception occurred"

Environment Variables

DD_LOGS_CONFIG_AUTO_MULTI_LINE_DETECTION_CUSTOM_SAMPLES='[{"regex": "\\[\\w+\\] Main main Exception occurred"}]'

여러 로그 형식을 지원하기 위해 샘플과 정규식 패턴을 섞을 수도 있어요:

Configuration file

logs_config:
  auto_multi_line_detection_custom_samples:
    - sample: "CORE | INFO | (pkg/logs/"
    - regex: "\\d{4}dog.\\s\\w+"
    - sample: "[ERR] Exception"
      label: no_aggregate

Environment Variables

DD_LOGS_CONFIG_AUTO_MULTI_LINE_DETECTION_CUSTOM_SAMPLES='[
  {"sample": "CORE | INFO | (pkg/logs/"},
  {"regex": "\\d{4}dog.\\s\\w+"},
  {"sample": "[ERR] Exception", "label": "no_aggregate"}
]'

참고: 기존 auto_multi_line_extra_patterns 구성은 V1에서 마이그레이션할 때 자동으로 지원됩니다.

JSON 집계 (JSON aggregation)

Datadog Agent 버전 7.67 이상에서는 pretty-printed 또는 멀티라인 JSON이 자동으로 감지되어 한 줄로 집계됩니다.

예를 들어, 다음 로그는:

2024-08-13 17:15:17 INFO My log message 1
2024-08-13 17:15:17 INFO My log message 2
{
    "id": "565290f7-6ce0-4d3d-be7f-685905c27f04",
    "clusters": 6,
    "samples": 1301,
    "top_match": {
        "score": 1317,
        "weight": 1.108
    }
}
2024-08-13 17:15:17 INFO My log message 3
2024-08-13 17:15:17 INFO My log message 4

자동으로 다음과 같이 변환됩니다:

2024-08-13 17:15:17 INFO My log message 1
2024-08-13 17:15:17 INFO My log message 2
{"id":"565290f7-6ce0-4d3d-be7f-685905c27f04","clusters":6,"samples": 1301,"top_match":{"score":1317,"weight":1.108}}
2024-08-13 17:15:17 INFO My log message 3
2024-08-13 17:15:17 INFO My log message 4

이렇게 하면 Datadog이 JSON을 구조화된 로그로 식별하고, 그 속성을 자동으로 쿼리할 수 있게 됩니다.

⚠️ JSON 집계는 log_processing_rules가 평가되기 전에 실행됩니다. log_processing_rules 정규식 패턴이 콜론 뒤 공백(예: "key": "value")에 의존한다면 Agent 7.67 이상에서 매치되지 않을 수 있어요. 압축된 JSON("key":"value")을 처리하도록 패턴을 업데이트하거나, JSON 집계를 비활성화하세요.

JSON 집계는 다음으로 비활성화할 수 있어요:

Configuration file

logs_config:
  auto_multi_line:
    enable_json_aggregation: false

Environment Variable

DD_LOGS_CONFIG_AUTO_MULTI_LINE_ENABLE_JSON_AGGREGATION=false

스택 트레이스 집계 (Stack trace aggregation)

Datadog Agent 버전 7.81 이상에서는 멀티라인 Go 스택 트레이스가 자동으로 감지되어 단일 로그로 집계됩니다.

예를 들어, 자동 멀티라인 감지는 다음 스택 트레이스를 별도 줄로 나누는 대신 하나의 로그로 집계합니다:

panic: INVALID ADDRESS runtime error: invalid memory address or nil pointer dereference [iter=249]
[signal SIGSEGV: segmentation violation code=0x1 addr=0x0 pc=0x45e1f2]

goroutine 1 [running]:
main.doWork(0x0)
	/app/main.go:24 +0x1d
main.run(...)
	/app/main.go:18
main.main()
	/app/main.go:14 +0x2c

JSON 집계와 마찬가지로, 스택 트레이스 집계는 자동 멀티라인 감지가 활성화되면 자동으로 켜집니다.

stack_trace_parsers를 빈 목록으로 설정하면 스택 트레이스 집계를 비활성화할 수 있어요. 기본값은 ["go"]입니다:

Configuration file

logs_config:
  auto_multi_line:
    stack_trace_parsers: []

Environment Variable

DD_LOGS_CONFIG_AUTO_MULTI_LINE_STACK_TRACE_PARSERS='[]'

고급 커스터마이즈 (Advanced customization)

자동 멀티라인 감지는 라벨링된 집계 시스템으로 로그를 집계해요. 감지 단계가 각 로그에 라벨을 할당하고, 집계 단계가 그 라벨을 기준으로 로그를 집계합니다.

라벨 (Labels)

start_group : 멀티라인 로그의 시작을 정의합니다.

버퍼링된 멀티라인 로그가 있다면 플러시합니다.
새 멀티라인 로그를 시작합니다.
한 번에 하나의 멀티라인 로그만 버퍼링할 수 있어요.

aggregate : 기존 멀티라인 로그에 추가됩니다.

멀티라인 로그가 없다면 즉시 플러시합니다.
다른 무엇과도 일치하지 않을 때의 기본 라벨이에요.

no_aggregate : 집계에 절대 포함되지 않는 로그를 선언합니다.

버퍼링된 멀티라인 로그가 있다면 플러시합니다.
샘플을 즉시 플러시합니다.
JSON 로그에 사용됩니다.

라벨 구성 (Label configuration)

라벨 규칙에 따라 집계 동작을 바꾸기 위해 각 정규식이나 샘플에 커스텀 라벨을 제공할 수 있어요. 특정 로그 형식을 멀티라인 집계에 명시적으로 포함하거나 제외하고 싶을 때 유용합니다.

Configuration file

logs_config:
  auto_multi_line_detection_custom_samples:
    # Never aggregate these formats
    - sample: "some service we should not aggregate"
      label: no_aggregate
    - regex: \w*\s(data|dog)
      label: no_aggregate

Environment Variables

DD_LOGS_CONFIG_AUTO_MULTI_LINE_DETECTION_CUSTOM_SAMPLES='[
  {"sample": "some service we should not aggregate", "label": "no_aggregate"},
  {"regex": "\\w*\\s(data|dog)", "label": "no_aggregate"}
]'

모니터링과 디버깅 (Monitoring and debugging)

다음 설정을 활성화하면 멀티라인 로그나 잘린(truncated) 로그를 검색할 수 있어요:

logs_config:
  tag_multi_line_logs: true
  tag_truncated_logs: true

이 설정들은 로그에 다음 태그를 추가해서 Logs Explorer에서 검색할 수 있게 해 줍니다:

multiline: 집계 소스를 표시합니다(예: auto_multiline, multiline_regex).
truncated: 잘림 소스를 표시합니다(예: single_line, multi_line).

참고: Agent는 처리하기 너무 긴 로그를 자릅니다. 멀티라인 집계 전에 줄이 너무 길면 Agent는 그 로그에 single_line 태그를 할당해요. 잘못된 패턴 때문에 로그가 집계 버퍼를 넘치게 하면 Agent는 multi_line 태그를 적용합니다.

집계된 JSON 로그에도 태그를 지정할 수 있어요.

logs_config:
  auto_multi_line:
    tag_aggregated_json: true

Logs Explorer에서 aggregated_json:true를 쿼리하면 이 태그를 검색할 수 있어요.

구성 참조 (Configuration reference)

설정	타입	기본값	설명
`logs_config.auto_multi_line_detection_custom_samples`	Object	Empty	커스텀 샘플/정규식 패턴
`logs_config.auto_multi_line.enable_json_detection`	Bool	True	JSON 감지 및 거부 활성화
`logs_config.auto_multi_line.enable_datetime_detection`	Bool	True	datetime 감지 활성화
`logs_config.auto_multi_line.timestamp_detector_match_threshold`	Float	0.5	타임스탬프 매칭 임계값
`logs_config.auto_multi_line.tokenizer_max_input_bytes`	Int	60	토큰화할 바이트 수
`logs_config.auto_multi_line.stack_trace_parsers`	List	`["go"]`	집계에 사용할 스택 트레이스 파서. `[]`로 설정하면 비활성화.

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

본문

개요 (Overview)

시작하기 (Getting started)

기본 설정 (Default settings)

통합별 멀티라인 집계 활성화 (Enable multi-line aggregation per integration)

통합별 멀티라인 설정 (Per integration multi-line integration settings)

지원되는 datetime 형식 (Supported datetime formats)

커스텀 패턴 구성 (Custom pattern configuration)

커스텀 샘플 (Custom samples)

커스텀 샘플 동작 방식 (How custom samples work)

정규식 패턴 (Regex patterns)

JSON 집계 (JSON aggregation)

스택 트레이스 집계 (Stack trace aggregation)

고급 커스터마이즈 (Advanced customization)

라벨 (Labels)

라벨 구성 (Label configuration)

모니터링과 디버깅 (Monitoring and debugging)

구성 참조 (Configuration reference)

더 알아보기 (Learn more)