파이프라인 (Pipelines)

원문 보기 위키 갱신 2026.10.05

Datadog는 JSON 형식 로그를 자동으로 파싱해요. 그다음 모든 로그(원시 및 JSON)를 처리 파이프라인에 통과시켜 가치를 더할 수 있어요. 파이프라인은 다양한 형식의 로그를 받아 Datadog의 공통 형식으로 변환해주죠. 로그 파이프라인과 처리 전략을 도입하면 조직에 속성 명명 규칙이 생겨서 좋아요.

출처: 문서

본문

참고: 이 문서에서 설명하는 파이프라인과 프로세서는 클라우드 기반 로깅 환경에 특화된 것이에요. 온프레미스 로그를 집계·처리·라우팅하려면 Observability Pipelines을 참고하세요.

개요

파이프라인을 사용하면 로그를 프로세서에 순차적으로 연결하면서 파싱하고 보강해요. 이 과정은 반구조화 텍스트에서 의미 있는 정보나 속성을 추출해 패싯으로 재사용하게 해주죠. 파이프라인을 통과하는 각 로그는 모든 파이프라인 필터에 대해 테스트돼요. 필터와 일치하면 모든 프로세서가 순차적으로 적용된 후 다음 파이프라인으로 이동해요.

파이프라인과 프로세서는 어떤 유형의 로그에도 적용할 수 있어요. 로깅 구성을 바꾸거나 서버 측 처리 규칙에 변경 사항을 배포할 필요가 없어요. 모든 것은 파이프라인 구성 페이지에서 설정할 수 있어요.

참고: Log Management 솔루션을 최적으로 사용하려면 Datadog는 파이프라인당 최대 20개 프로세서와 Grok 프로세서 내에서 파싱 규칙 10개를 사용할 것을 권장해요. Datadog는 서비스 성능에 영향을 줄 수 있는 성능이 낮은 파싱 규칙, 프로세서, 파이프라인을 비활성화할 권리를 보유해요.

파이프라인 권한

파이프라인은 Granular Access Control을 사용해 파이프라인·프로세서 구성을 편집할 수 있는 사람을 관리해요. 즉 권한을 역할(roles), 개별 사용자, 팀에 할당해 파이프라인 리소스를 정밀하게 제어할 수 있어요. 제한이 없는 파이프라인은 unrestricted로 간주되어 logs_write_pipelines 권한이 있는 모든 사용자가 해당 파이프라인과 프로세서를 수정할 수 있어요.

각 파이프라인에 대해 관리자는 다음 편집 범위를 선택할 수 있어요:

Editor (편집자): 지정된 사용자, 팀, 역할만 파이프라인 구성과 프로세서를 편집할 수 있어요.
Processor Editor (프로세서 편집자): 지정된 사용자, 팀, 역할만 프로세서(중첩 파이프라인 포함)를 편집할 수 있어요. 필터 쿼리나 전역 파이프라인 목록에서의 순서 같은 파이프라인 속성은 아무도 수정할 수 없어요.

경고: 사용자에게 파이프라인의 제한 목록 접근 권한을 부여한다고 해서 logs_write_pipelines나 logs_write_processors 권한이 자동으로 부여되지는 않아요. 관리자가 해당 권한을 별도로 부여해야 해요.

이 권한은 프로그래밍 방식으로 API와 Terraform을 통해 관리할 수 있어요.

전처리 (Preprocessing)

JSON 로그의 전처리는 로그가 파이프라인 처리를 시작하기 전에 발생해요. 전처리는 timestamp, status, host, service, message 같은 예약 속성을 기준으로 일련의 연산을 실행해요. JSON 로그에 다른 속성 이름이 있다면 전처리를 사용해 로그 속성 이름을 예약 속성 목록의 이름에 매핑할 수 있어요.

JSON 로그 전처리에는 표준 로그 포워더에서 작동하는 기본 구성이 함께 제공돼요. 이 구성을 사용자 지정 또는 특정 로그 전달 방식에 맞게 편집하려면:

Datadog의 Pipelines로 이동해 Preprocessing for JSON logs를 선택해요.

참고: JSON 로그를 전처리하는 것만이 로그 속성 중 하나를 로그의 host로 정의하는 유일한 방법이에요.

예약 속성을 기준으로 기본 매핑을 변경해요:

Source 속성

JSON 형식 로그 파일에 ddsource 속성이 포함되어 있으면 Datadog는 그 값을 로그의 소스로 해석해요. Datadog가 사용하는 것과 같은 소스 이름을 사용하려면 Integration Pipeline Library를 참고하세요.

참고: 컨테이너화된 환경에서 오는 로그는 기본 source와 service 값을 재정의하려면 환경 변수를 사용해야 해요.

Host 속성

Datadog Agent나 RFC5424 형식을 사용하면 로그의 host 값이 자동으로 설정돼요. 하지만 JSON 형식 로그 파일에 다음 속성이 포함되어 있으면 Datadog는 그 값을 로그의 host로 해석해요:

host
hostname
syslog.hostname

참고: Kubernetes에서 Datadog Agent가 수집한 JSON 로그에 host, hostname, syslog.hostname 키 속성이 포함되어 있으면 그 값이 해당 로그의 기본 Agent hostname을 재정의해요. 결과적으로 이 로그는 올바른 호스트의 호스트 레벨 태그(호스트 레벨에서 설정됨)를 상속받지 못해요. 이 경우 Datadog는 이 속성들을 지워 로그가 올바른 호스트에 귀속될 수 있도록 권장해요.

Date 속성

기본적으로 Datadog는 로그를 받으면 타임스탬프를 생성해 date 속성에 추가해요. 하지만 JSON 형식 로그 파일에 다음 속성 중 하나가 포함되어 있으면 Datadog는 그 값을 로그의 공식 날짜로 해석해요:

@timestamp
timestamp
_timestamp
Timestamp
eventTime
date
published_date
syslog.timestamp

log date remapper 프로세서를 설정해 로그 날짜의 소스로 사용할 대체 속성을 지정할 수 있어요.

참고: Datadog는 공식 날짜가 과거 18시간보다 오래된 로그 항목은 거부해요.

경고: 인식되는 날짜 형식은 ISO8601, UNIX (밀리초 EPOCH 형식), RFC3164예요.

Message 속성

기본적으로 Datadog는 message 값을 로그 항목의 본문으로 수집해요. 그 값은 Log Explorer에서 강조 표시되고 표시되며, 전체 텍스트 검색을 위해 인덱싱돼요. 하지만 JSON 형식 로그 파일에 다음 속성 중 하나가 포함되어 있으면 Datadog는 그 값을 로그의 공식 메시지로 해석해요:

message
msg
log

log message remapper 프로세서를 설정해 로그 메시지의 소스로 사용할 대체 속성을 지정할 수 있어요.

Status 속성

각 로그 항목은 Datadog 내에서 패싯 검색에 사용할 수 있는 상태 레벨을 지정할 수 있어요. 하지만 JSON 형식 로그 파일에 다음 속성 중 하나가 포함되어 있으면 Datadog는 그 값을 로그의 공식 상태로 해석해요:

status
severity
level
syslog.severity

log status remapper 프로세서를 설정해 로그 상태의 소스로 사용할 대체 속성을 지정할 수 있어요.

Service 속성

Datadog Agent나 RFC5424 형식을 사용하면 로그의 service 값이 자동으로 설정돼요. 하지만 JSON 형식 로그 파일에 다음 속성이 포함되어 있으면 Datadog는 그 값을 로그의 service로 해석해요:

service
syslog.appname
dd.service

log service remapper 프로세서를 설정해 로그 서비스의 소스로 사용할 대체 속성을 지정할 수 있어요.

Trace ID 속성

기본적으로 Datadog SDK는 로그에 trace 및 span ID를 자동으로 주입할 수 있어요. 하지만 JSON 형식 로그에 다음 속성이 포함되어 있으면 Datadog는 그 값을 로그의 trace_id로 해석해요:

dd.trace_id
contextMap.dd.trace_id
named_tags.dd.trace_id
trace_id

trace ID remapper 프로세서를 설정해 로그 trace ID의 소스로 사용할 대체 속성을 지정할 수 있어요.

Span ID 속성

기본적으로 Datadog SDK는 로그에 span ID를 자동으로 주입할 수 있어요. 하지만 JSON 형식 로그에 다음 속성이 포함되어 있으면 Datadog는 그 값을 로그의 span_id로 해석해요:

dd.span_id
contextMap.dd.span_id
named_tags.dd.span_id
span_id

파이프라인 만들기

Datadog의 Pipelines로 이동해요.
New Pipeline을 선택해요.
라이브 테일 미리보기에서 로그를 선택해 필터를 적용하거나 직접 필터를 만들어요. 드롭다운 메뉴에서 필터를 선택하거나 </> 아이콘을 선택해 직접 필터 쿼리를 만들 수 있어요. 필터는 파이프라인이 적용되는 로그 종류를 제한해요.

참고: 파이프라인 필터링은 파이프라인의 모든 프로세서 앞에 적용돼요. 따라서 파이프라인 자체에서 추출된 속성을 기준으로 필터링할 수 없어요.

파이프라인 이름을 지정해요.
(선택) 파이프라인에 설명과 태그를 추가해 용도와 소유권을 표시해요. 파이프라인 태그는 로그에 영향을 주지 않지만 Pipelines 페이지 내에서 필터링·검색하는 데 사용할 수 있어요.
Create를 눌러요.

통합 파이프라인

참고: 지원되는 통합 목록을 참고하세요.

통합 처리 파이프라인은 특정 소스를 로그 수집하도록 설정했을 때 사용할 수 있어요. 이 파이프라인은 **읽기 전용(read-only)**이며 특정 소스에 적합한 방식으로 로그를 파싱해요. 통합 로그의 경우 로그 파싱을 처리하고 Log Explorer에 해당 패싯을 추가하는 통합 파이프라인이 자동으로 설치돼요.

통합 파이프라인을 보려면 Pipelines 페이지로 이동해요. 통합 파이프라인을 편집하려면 복제(clone)한 다음 복제본을 편집해요:

참고: 통합 파이프라인은 삭제할 수 없고 비활성화만 할 수 있어요.

통합 파이프라인 라이브러리

Datadog가 제공하는 전체 통합 파이프라인 목록을 보려면 통합 파이프라인 라이브러리를 찾아보세요. 파이프라인 라이브러리는 Datadog가 다양한 로그 형식을 기본적으로 어떻게 처리하는지 보여줘요.

통합 파이프라인을 사용하려면 Datadog는 해당 로그 source를 구성해 통합을 설치할 것을 권장해요. Datadog가 이 source로 첫 로그를 받으면 설치가 자동으로 트리거되고 통합 파이프라인이 처리 파이프라인 목록에 추가돼요. 로그 소스를 구성하려면 해당 통합 문서를 참고하세요.

복제(clone) 버튼을 사용해 통합 파이프라인을 복사하는 것도 가능해요.

프로세서 또는 중첩 파이프라인 추가하기

Datadog의 Pipelines로 이동해요.
파이프라인 위에 커서를 올리고 옆에 있는 화살표를 클릭해 프로세서와 중첩 파이프라인을 펼쳐요.
Add Processor 또는 Add Nested Pipeline을 선택해요.

프로세서

프로세서는 파이프라인 안에서 실행되어 데이터 구조화 작업을 완료해요. Processors 문서에서 앱 또는 API로 프로세서 유형별로 추가·구성하는 방법을 알아보세요.

사용자 지정 날짜·시간 형식과 UTC가 아닌 타임스탬프에 필요한 timezone 파라미터에 대해서는 날짜 파싱을 참고하세요.

여러 프로세서가 일치할 때의 속성 우선순위

일치하는 파이프라인 안의 여러 프로세서가 같은 속성을 설정하면 결과는 프로세서 유형에 따라 달라져요. 세 가지 동작이 있어요:

Behavior	Description	Processors
Last write wins (마지막 쓰기가 승리)	나중 프로세서(더 아래 순서)가 설정한 값이 이전 값을 덮어써요.	Grok parser, Category processor, Arithmetic processor, String builder processor, Lookup processor, URL parser, User-Agent parser, GeoIP parser, Decoder processor
Depends on `override_on_conflict`	`override_on_conflict` 파라미터를 따르며, 기본값(`false`)에서는 대상 요소가 이미 설정되어 있으면 덮어쓰지 않아요.	Remapper, Array Map processor
First write wins (첫 쓰기가 승리)	첫 번째 프로세서만 적용돼요(마지막 프로세서를 사용하는 Log date remapper 제외). 단일 파이프라인 안에서는 첫 번째 프로세서의 값이 사용되고, 여러 파이프라인이 일치하면 먼저 만난 것이 적용돼요.	Log status remapper, Service remapper, Log message remapper, Trace remapper, Span remapper

각 프로세서에 대한 자세한 내용은 Processors를 참고하세요.

중첩 파이프라인

중첩 파이프라인은 파이프라인 안의 파이프라인이에요. 처리를 두 단계로 나누려면 중첩 파이프라인을 사용해요. 예를 들어 먼저 team 같은 상위 레벨 필터를 사용한 다음 통합, 서비스, 또는 다른 태그·속성을 기준으로 두 번째 레벨 필터링을 하죠.

파이프라인은 중첩 파이프라인과 프로세서를 포함할 수 있지만, 중첩 파이프라인은 프로세서만 포함할 수 있어요.

파이프라인을 중첩 파이프라인으로 만들려면 다른 파이프라인으로 이동시키면 돼요:

이동하려는 파이프라인 위에 커서를 올리고 Move to 아이콘을 클릭해요.
원래 파이프라인을 이동할 파이프라인을 선택해요. 참고: 중첩 파이프라인을 포함하는 파이프라인은 다른 최상위 위치로만 이동할 수 있어요. 다른 파이프라인 안으로는 이동할 수 없어요.
Move를 클릭해요.

파이프라인 변경 미리보기

파이프라인이나 그 프로세서를 만들거나 편집할 때, 적용하기 전에 변경 사항이 로그에 어떤 영향을 미치는지 미리 볼 수 있어요. 미리보기는 제안한 변경 사항으로 처리된 로그의 라이브 테일을 사용해요.

각 로그에 대해 before와 after 상태를 비교해요. 비교할 변경 사항을 선택하세요:

Your changes: 파이프라인의 현재 배포 버전과 변경 사항이 적용된 버전을 비교해요.
Entire pipeline: 파이프라인으로 들어오는 로그와 전체 파이프라인이 실행된 후의 로그를 비교해요.

로그 목록을 좁히려면 쿼리 필터를 사용하거나 영향을 기준으로 필터링해요:

All logs: 라이브 테일의 모든 로그.
Impacted logs: 이 세션에서 편집으로 변경된 로그만.
Not impacted logs: 편집으로 변경되지 않은 로그만.

파이프라인 관리하기

파이프라인의 수정 정보를 사용해 파이프라인·프로세서에 마지막으로 변경이 가해진 시기와 그 변경을 한 사용자를 식별할 수 있어요. 이 수정 정보와 함께 파이프라인이 활성화되어 있는지·읽기 전용인지 같은 다른 패싯 속성으로 파이프라인을 필터링해요.

슬라이딩 옵션 패널의 Move to 옵션으로 파이프라인을 정밀하게 재정렬해요. Move to 모달에서 이동할 파이프라인의 정확한 위치로 스크롤해 클릭해요. 파이프라인은 다른 읽기 전용 파이프라인으로 이동할 수 없어요. 중첩 파이프라인을 포함하는 파이프라인은 다른 최상위 위치로만 이동할 수 있고, 다른 파이프라인으로는 이동할 수 없어요.

파이프라인을 복제(clone)하면 처음부터 다시 시작하지 않고 기존 규칙과 프로세서를 재사용할 수 있어요. 파이프라인을 복제하면 Datadog가 복제한 원본 파이프라인을 자동으로 비활성화해요. 토글을 클릭해 활성화할 수 있어요.

예상 사용량 메트릭

각 파이프라인에 예상 사용량 메트릭이 표시돼요. 각 파이프라인이 수집·수정하는 로그의 볼륨과 개수를 보여주죠. 모든 파이프라인에는 기본 제공 Logs Estimated Usage Dashboard 링크가 포함돼 있어요. 이 대시보드는 파이프라인의 사용량 메트릭에 대한 상세 차트를 제공해요.

더 알아보기 (Learn more)

추가로 도움이 되는 문서, 링크, 아티클:

*Logging without Limits는 Datadog, Inc.의 상표예요.