호스트 Agent 로그 수집

원문 보기 위키 갱신 2026.10.05

Datadog Agent를 이용해 로그를 수집하고 Datadog로 보내는 방법을 설명해 드릴게요. 로그 수집은 기본적으로 꺼져 있기 때문에 직접 활성화하고, 어디서 로그를 가져올지(파일, 네트워크, journald, Windows 채널 등) 구성해야 해요.

출처: 문서

본문

로그 수집에는 Datadog Agent v6.0 이상이 필요해요. 이전 버전의 Agent에는 log collection 인터페이스가 포함되어 있지 않아요. 아직 Agent를 사용하지 않는다면 Agent 설치 지침을 따르세요.

다른 벤더의 컬렉터나 포워더로 로그를 보내고 싶거나, 전송 전에 로그 데이터를 환경 내에서 전처리하고 싶다면 Observability Pipelines를 참고하세요.

로그 수집 활성화

로그 수집은 Datadog Agent에서 기본적으로 활성화되어 있지 않아요. Kubernetes나 Docker 환경에서 Agent를 실행한다면 전용 Kubernetes Log Collection 또는 Docker Log Collection 문서를 참고하세요.

호스트에서 실행되는 Agent의 로그 수집을 활성화하려면 Agent의 메인 구성 파일(datadog.yaml)에서 logs_enabled: false를 logs_enabled: true로 바꾸세요.

datadog.yaml 파일에서:

logs_enabled: true
logs_config:
    auto_multi_line_detection: true
    force_use_http: true

사용 가능한 모든 구성 옵션은 운영 체제에 맞는 예제 Agent 구성 파일을 참고하세요.

참고: Agent v6.19+/v7.19+부터 HTTPS 전송이 기본 전송 방식이에요. 자세한 내용은 Agent transport를 참고하세요.

환경 변수로 로그를 보내려면 다음과 같이 설정하세요:

DD_LOGS_ENABLED=true

로그 수집을 활성화하면 Agent는 로그를 Datadog로 전달할 준비가 됩니다. 이제 Agent가 어디에서 로그를 수집할지 구성하세요.

커스텀 로그 수집

Datadog Agent v6은 파일, 네트워크(TCP 또는 UDP), journald, Windows 채널에서 로그를 수집해 Datadog로 전달할 수 있어요.

Agent 구성 디렉터리 루트의 conf.d/ 디렉터리에 Datadog 사용자가 접근할 수 있는 새 <CUSTOM_LOG_SOURCE>.d/ 폴더를 만드세요.
이 새 폴더에 새 conf.yaml 파일을 만드세요.
아래 파라미터로 커스텀 로그 수집 구성 그룹을 추가하세요.
이 새 구성을 반영하려면 Agent를 재시작하세요.
Agent의 status 하위 명령을 실행하고 Checks 섹션에서 <CUSTOM_LOG_SOURCE>를 찾아보세요.

권한 오류가 있다면 로그 파일 테일링 중 권한 문제를 참고해 문제를 해결하세요.

각 호스트에서 파일을 편집하지 않고 여러 Agent에 커스텀 로그 수집 구성을 한 번에 배포하려면 Fleet Automation으로 Configure Custom Logs를 참고하세요.

커스텀 로그 수집 설정 예시는 다음과 같아요.

파일 테일링

<PATH_LOG_FILE>/<LOG_FILE_NAME>.log에 저장된 <APP_NAME> 애플리케이션의 로그를 수집하려면 Agent 구성 디렉터리 루트에 다음 내용의 <APP_NAME>.d/conf.yaml 파일을 만드세요:

logs:
  - type: file
    path: "<PATH_LOG_FILE>/<LOG_FILE_NAME>.log"
    service: "<APP_NAME>"
    source: "<SOURCE>"

Windows에서는 <DRIVE_LETTER>:\\<PATH_LOG_FILE>\\<LOG_FILE_NAME>.log 경로를 사용하고, ddagentuser 사용자가 로그 파일에 읽기 권한을 갖고 있는지 확인하세요.

참고: 로그 줄은 줄바꿈 문자 \n 또는 \r\n으로 끝나야 해요. 그렇지 않으면 Agent가 무한정 기다리며 로그 줄을 보내지 않아요.

TCP/UDP

보내는 쪽 IP 주소를 캡처해 로그 메시지 페이로드에 포함하려면 datadoghq.yaml 파일에 다음 구성을 추가하세요:

 logs_config:
   use_sourcehost_tag: true

TCP 포트 10518로 로그를 전달하는 <APP_NAME> 애플리케이션의 로그를 수집하려면 Agent 구성 디렉터리 루트에 다음 내용의 <APP_NAME>.d/conf.yaml 파일을 만드세요:

logs:
  - type: tcp
    port: 10518
    service: "<APP_NAME>"
    source: "<CUSTOM_SOURCE>"

Serilog를 사용한다면 UDP 연결에는 Serilog.Sinks.Network가 옵션이 될 수 있어요.

Agent 7.31.0+ 버전에서는 TCP 연결이 유휴 상태여도 무한정 유지돼요.

참고:

Agent는 raw string, JSON, Syslog 형식의 로그를 지원해요. 로그를 배치로 보낸다면 줄바꿈 문자로 로그를 구분하세요.
로그 줄은 줄바꿈 문자 \n 또는 \r\n으로 끝나야 해요. 그렇지 않으면 Agent가 무한정 기다리며 로그 줄을 보내지 않아요.

journald

journald에서 로그를 수집하려면 Agent 구성 디렉터리 루트에 다음 내용의 journald.d/conf.yaml 파일을 만드세요:

logs:
  - type: journald
    path: /var/log/journal/

컨테이너화 환경과 유닛 필터링 설정에 대한 자세한 내용은 journald 통합 문서를 참고하세요.

Windows 이벤트

Windows 이벤트를 로그로 Datadog에 보내려면 conf.d/win32_event_log.d/conf.yaml에 채널을 수동으로 추가하거나 Datadog Agent Manager를 사용하세요.

채널 목록을 보려면 PowerShell에서 다음 명령을 실행하세요:

Get-WinEvent -ListLog *

가장 활발한 채널을 보려면 PowerShell에서 다음 명령을 실행하세요:

Get-WinEvent -ListLog * | sort RecordCount -Descending

그런 다음 win32_event_log.d/conf.yaml 구성 파일에 채널을 추가하세요:

logs:
  - type: windows_event
    channel_path: "<CHANNEL_1>"
    source: "<CHANNEL_1>"
    service: "<SERVICE>"
    sourcecategory: windowsevent

  - type: windows_event
    channel_path: "<CHANNEL_2>"
    source: "<CHANNEL_2>"
    service: "<SERVICE>"
    sourcecategory: windowsevent

<CHANNEL_X> 파라미터를 이벤트를 수집할 Windows 채널 이름으로 편집하세요. 통합 자동 처리 파이프라인 설정을 활용하려면 해당 source 파라미터를 같은 채널 이름으로 설정하세요.

마지막으로 Agent를 재시작하세요.

Windows 프라이빗 로케이션

다음 섹션의 단계를 따라 Windows 프라이빗 로케이션 로그를 Datadog에 보내세요.

Agent 구성하기

Agent 구성 파일에서 logs_enabled: true로 설정해 Agent 로그 수집을 활성화하세요.
C:\ProgramData\Datadog\conf.d로 이동해 synthetics_worker.d 폴더를 만드세요.
synthetics_worker.d 폴더 안에 다음 예시를 템플릿으로 사용한 conf.yaml 파일을 만드세요:

logs:
  - type: file
    path: "C:\\Program Files\\Datadog-Synthetics\\Synthetics\\private-location-service.out.log"
    service: <YOUR_SERVICE>
    source: synthetics
    tags: # Defined per user preference
      - env:<YOUR_ENV>
      - private_location:<YOUR_PRIVATE_LOCATION>

Agent를 실행하는 사용자 확인하기

프라이빗 로케이션 설치 폴더는 관리자 접근으로 제한되어 있으므로, Datadog Agent가 로그 파일에 접근할 권한이 필요해요. Datadog Agent를 실행하는 사용자를 확인하려면 다음 단계를 따르세요:

Windows 키와 R을 눌러 Run을 검색하세요.
Datadog Agent를 찾아 우클릭하고 Properties를 선택하세요.
Log On 탭에서 계정(기본값은 ddagentuser)을 확인하세요.
창을 닫으세요.

Agent를 실행하는 사용자에게 권한 부여하기

C:\Program Files로 이동해 synthetics_worker.d 폴더를 찾으세요.
synthetics_worker.d 폴더를 우클릭하고 Properties를 선택하세요.
Security 탭으로 이동하세요.
Edit를 클릭하고 ddagentuser를 추가하세요.
필요한 권한을 부여하세요.
Services 화면이나 명령줄을 통해 Datadog Agent를 재시작해 변경 사항을 적용하고 Datadog로 로그 전송을 시작하세요.

로그 수집에 사용 가능한 모든 파라미터:

파라미터	필수	설명
`type`	예	로그 입력 소스의 유형이에요. 유효한 값은 `tcp`, `udp`, `file`, `windows_event`, `docker`, `journald`예요.
`port`	예	`type`이 tcp 또는 udp라면 로그를 수신할 포트를 설정하세요.
`path`	예	`type`이 file 또는 journald라면 로그 수집 파일 경로를 설정하세요.
`channel_path`	예	`type`이 windows_event라면 로그 수집을 위한 Windows 이벤트 채널을 나열하세요.
`service`	예	로그를 소유하는 서비스의 이름이에요. 서비스를 Datadog APM으로 계측했다면 이 값은 같은 서비스 이름이어야 해요. 여러 데이터 유형에 걸쳐 `service`를 구성할 때는 unified service tagging 지침을 확인하세요.
`source`	예	어떤 통합이 로그를 보내는지 정의하는 속성이에요. 기존 통합에서 오는 로그가 아니라면 이 필드에 커스텀 소스 이름을 넣을 수 있어요. 다만 수집 중인 관련 커스텀 메트릭의 네임스페이스와 이 값을 일치시키는 것이 권장돼요. 예: `myapp.request.count`에서 `myapp`.
`include_units`	아니요	`type`이 journald라면 포함할 특정 journald 유닛 목록을 설정하세요.
`exclude_paths`	아니요	`type`이 file이고 `path`에 와일드카드 문자가 있다면 로그 수집에서 제외할 일치 파일을 설정하세요. Agent 6.18 이상에서 사용 가능해요.
`exclude_units`	아니요	`type`이 journald라면 제외할 특정 journald 유닛 목록을 설정하세요.
`sourcecategory`	아니요	source 속성이 속한 범주를 정의하는 속성이에요. 예: `source:postgres, sourcecategory:database` 또는 `source: apache, sourcecategory: http_web_access`.
`start_position`	아니요	자세한 내용은 Start position을 참고하세요.
`encoding`	아니요	`type`이 file이라면 Agent가 파일을 읽을 인코딩을 설정하세요. UTF-16 리틀엔디안은 `utf-16-le`, UTF-16 빅엔디안은 `utf-16-be`, Shift JIS는 `shift-jis`로 설정하세요. 다른 값으로 설정하면 Agent는 파일을 UTF-8로 읽어요. `utf-16-le`과 `utf-16be`는 Agent v6.23/v7.23, `shift-jis`는 Agent v6.34/v7.34에 추가됨
`tags`	아니요	수집된 각 로그에 추가되는 태그 목록이에요 (태깅에 대해 더 알아보기).

시작 위치

start_position 파라미터는 file과 journald 테일러 유형에서 지원돼요. 컨테이너를 테일링할 때 start_position은 항상 beginning이에요.

지원:

File: Agent 6.19+/7.19+
Journald: Agent 6.38+/7.38+

type이 file이라면:

Agent가 파일 읽기를 시작할 위치를 설정하세요.
유효한 값은 beginning, end, forceBeginning, forceEnd예요(기본값: end).
beginning 위치는 와일드카드가 있는 경로를 지원하지 않아요.

type이 journald라면:

Agent가 저널 읽기를 시작할 위치를 설정하세요.
유효한 값은 beginning, end, forceBeginning, forceEnd예요(기본값: end).

우선순위

file과 journald 테일러 유형 모두에서 end 또는 beginning 위치를 지정했지만 저장된 오프셋이 있다면, 오프셋이 우선해요. forceBeginning이나 forceEnd를 사용하면 저장된 오프셋이 있어도 Agent가 지정된 값을 강제로 사용해요.