OpenTelemetry Filelog Receiver: 로그 파일을 수집하는 가이드

Source: Dev.to

Filelog 수신기가 작동하는 방식

구성 세부 사항에 들어가기 전에, 수신기가 로그 파일을 전체 수명 주기 동안 어떻게 처리하는지 상상해 보세요. 수신기는 간단한 4단계 반복 루프를 수행합니다:

• Discover(발견): include와 exclude 패턴을 사용해 파일 시스템을 정기적으로 스캔하고, 모니터링할 로그 파일을 결정합니다.
• Read(읽기): 선택된 각 파일을 열고 새 라인이 기록될 때마다 따라갑니다. start_at 설정에 따라 beginning(시작부터) 또는 end(끝에서부터) 중 어디서부터 읽을지 결정합니다.
• Parse(파싱): 각 라인(또는 멀티라인 파싱을 사용할 경우 라인 블록)이 일련의 Stanza 연산자 (구성된 경우)를 통과합니다. 연산자는 원시 텍스트를 파싱하고, 핵심 속성을 추출하며, 타임스탬프와 심각도 수준을 할당하고, 로그 데이터를 구조화합니다.
• Emit(전송): 구조화된 로그 레코드는 Collector 파이프라인으로 전달되어, 필터링되거나 추가 변환을 거친 뒤 백엔드로 내보낼 수 있습니다.

Discover → Read → Parse → Emit 루프는 수신기가 수행하는 모든 작업의 기반을 이룹니다.

빠른 시작: 로그 파일 tailing

일반적인 사용 사례는 애플리케이션이 이미 JSON 형식으로 로그를 파일에 기록하는 경우입니다. 예: /var/log/myapp/app.log:

{"time":"2025-09-28 20:15:12","level":"INFO","message":"User logged in successfully","user_id":"u-123","source_ip":"192.168.1.100"}
{"time":"2025-09-28 20:15:45","level":"WARN","message":"Password nearing expiration","user_id":"u-123"}

최소한의 filelog 수신기 구성

# otelcol.yaml
receivers:
  filelog:
    # 1. /var/log/myapp/ 아래의 모든 .log 파일을 DISCOVER
    include: [/var/log/myapp/*.log]
    # 2. 새 파일을 시작부터 READ
    start_at: beginning
    # 3. json_parser 연산자를 사용해 PARSE
    operators:
      - type: json_parser
        timestamp:
          parse_from: attributes.time
          layout: "%Y-%m-%d %H:%M:%S"
        severity:
          parse_from: attributes.level

exporters:
  debug:
    verbosity: detailed

service:
  pipelines:
    logs:
      receivers: [filelog]
      exporters: [debug]

구성 상세 설명

• include: /var/log/myapp/ 아래의 모든 .log 파일을 수신기에게 지정합니다.
• start_at: beginning: 파일을 처음 발견했을 때 전체 내용을 처리합니다. 기본값(end)은 Collector가 시작된 이후에 추가된 라인만 캡처합니다.
• operators: 여기서는 단일 json_parser를 사용해 각 라인을 JSON으로 해석하고, 선택된 필드를 로그 레코드의 핵심 메타데이터로 승격시킵니다.
• timestamp와 severity: JSON의 time과 level 필드를 추출해 OpenTelemetry의 최상위 Timestamp와 Severity* 필드에 매핑합니다.

debug exporter를 사용하면 파싱되고 구조화된 출력이 표시됩니다:

LogRecord #0
ObservedTimestamp: 2025-09-28 20:48:36.728437503 +0000 UTC
Timestamp: 2025-09-28 20:15:12 +0000 UTC
SeverityText: INFO
SeverityNumber: Info(9)
Body: Str({"time":"2025-09-28 20:15:12","level":"INFO","message":"User logged in successfully","user_id":"u-123","source_ip":"192.168.1.100"})
Attributes:
     -> user_id: Str(u-123)
     -> source_ip: Str(192.168.1.100)
     -> log.file.name: Str(myapp.log)
     -> time: Str(2025-09-28 20:15:12)
     -> level: Str(INFO)
     -> message: Str(User logged in successfully)
Trace ID:
Span ID:
Flags: 0

원시 JSON 로그가 이제 OpenTelemetry의 통합 로그 데이터 형식으로 변환되어, 시스템 간 관측성을 위한 일관된 기반을 제공합니다.

전체 파일 경로 추가하기

수신기는 자동으로 log.file.name 속성을 추가합니다. 전체 경로도 캡처하려면 include_file_path를 활성화하세요:

# otelcol.yaml (excerpt)
receivers:
  filelog:
    include: [/var/log/myapp/*.log]
    include_file_path: true

결과 속성:

Attributes:
     -> log.file.path: Str(/var/log/myapp/app.log)
     -> log.file.name: Str(app.log)

추가적인 풍부화 옵션은 공식 OpenTelemetry Filelog 수신기 문서를 참고하세요.

로그 파일 필터링 및 관리

filelog 수신기를 구성할 때 가장 기본적인 단계는 include와 exclude glob 패턴을 사용해 모니터링할 파일을 지정하는 것입니다. 수신기는 먼저 include를 사용해 목록을 만든 뒤, exclude 패턴에 일치하는 항목을 그 목록에서 제거합니다.

# otelcol.yaml
receivers:
  filelog:
    include: [/var/log/apps/**/*.log]
    exclude:
      - /var/log/apps/**/debug.log
      - /var/log/apps/**/*.tmp

위 예시에서는 /var/log/apps/ 하위(서브디렉터리 포함)의 모든 .log 파일을 수집하지만, debug.log 파일과 .tmp 확장자를 가진 파일은 제외합니다.

수정 연령에 따라 파일 제외하기

읽고 있는 로그 디렉터리에 기존 로그 파일이 많이 존재한다면, 수신기가 특정 연령 이하의 파일을 무시하도록 지시할 수 있습니다. (이후 내용은 원문을 참고하세요.)