에이전트 통합 로그 수집(Agent Integration Log Collection)

커스텀 에이전트 통합에서 send_log 메서드로 로그를 직접 제출하는 방법을 안내해 드려요.

출처: 문서

본문

개요

커스텀 에이전트 통합을 개발할 때 send_log 메서드를 사용해 로그를 Datadog의 로그 수집 백엔드로 직접 제출할 수 있어요. 이를 통해 커스텀 체크가 메트릭, 이벤트, 서비스 체크와 함께 로그를 발행할 수 있어요.

이 접근 방식은 모니터링되는 애플리케이션 또는 서비스에서 로그 데이터를 추출하는 것과 통합 체크 자체에서 생성된 로그를 캡처하는 것 모두에 유용해요.

사전 요구사항

• 커스텀 에이전트 통합 또는 체크. 셋업 지침은 에이전트 기반 통합 만들기를 참고하세요.
• 로그 수집이 활성화된 Datadog 에이전트 설치·실행.

구성

커스텀 에이전트 체크에서 로그 제출을 활성화하려면 통합의 구성 파일에서 로그 수집을 구성해야 해요.

1. 에이전트의 메인 구성 파일(datadog.yaml)에서 로그 수집이 전역적으로 활성화되어 있는지 확인하세요.

   logs_enabled: true
   

2. 통합의 구성 파일에 logs 섹션을 추가하세요(예: conf.d/my_integration.d/conf.yaml).

   init_config:
   
   instances:
     - <instance_configuration>
   
   logs:
     - type: integration
       source: <integration_name>
       service: <service_name>
   

여기서:

• type: 로그가 통합에 의해 수집됨을 나타내도록 integration으로 설정하세요.
• source: 로그의 소스(보통 통합 이름).
• service: 로그와 연결할 서비스 이름(다른 것이 적용되지 않는다면 통합 이름일 수도 있음).

1. 에이전트를 재시작해 구성 변경을 적용하세요.

구성된 후에는 통합이 send_log 메서드를 사용해 로그를 제출할 수 있어요. 이 로그는 구성에 지정된 source와 service로 태그가 지정돼요.

send_log 메서드 사용

send_log 메서드는 모든 AgentCheck 클래스에서 사용할 수 있으며 로그 항목을 Datadog에 제출할 수 있게 해 줘요.

메서드 시그니처

send_log(data, cursor=None, stream='default')

파라미터

데이터 사전의 특수 키

data 사전은 send_log 메서드가 자동으로 처리하는 다음 특수 키를 지원해요.

• timestamp: Unix epoch 이후의 초 수. 제공되지 않으면 현재 시간으로 기본 설정돼요.
• ddtags: 태그의 쉼표 구분 문자열. 제공되지 않으면 에이전트가 통합 인스턴스 구성의 태그를 자동으로 추가해요.

data 사전의 다른 모든 키는 로그 속성으로 전달돼요. 포함하면 좋은 일반 속성:

• message: 로그 메시지 내용.
• status: 로그 상태 레벨(info, error, warning, debug 등).
• service: 로그의 서비스 이름(체크 구성의 서비스 이름과 일치해야 함).
• source: 로그의 소스(보통 통합 이름; 구성된 소스 이름과도 일치해야 함).
• hostname: 로그와 연결된 호스트 이름.
• 통합과 관련된 모든 커스텀 필드.

사용 예제

기본 로그 제출

from datadog_checks.base import AgentCheck
import time

class MyCustomCheck(AgentCheck):
    def check(self, instance):
        # Submit a simple log message
        self.send_log({
            'message': 'Custom check executed successfully',
            'timestamp': time.time(),
            'status': 'info'
        })

메타데이터가 있는 구조화 로깅

from datadog_checks.base import AgentCheck
import time

class MyCustomCheck(AgentCheck):
    def check(self, instance):
        # Submit a structured log with additional fields
        self.send_log({
            'message': 'Database query completed',
            'timestamp': time.time(),
            'status': 'info',
            'service': 'my-custom-integration',
            'source': 'custom_check',
            'query_duration_ms': 145,
            'rows_returned': 1024
        })

상태 저장 로깅에 커서 사용

커서를 사용하면 체크 실행 간에 메타데이터를 유지할 수 있어서 진행 상황 추적이나 상태 유지에 유용해요.

from datadog_checks.base import AgentCheck
import time

class MyCustomCheck(AgentCheck):
    def check(self, instance):
        # Retrieve the last cursor for this stream
        last_cursor = self.get_log_cursor('my_stream')
        last_position = last_cursor.get('position', 0) if last_cursor else 0

        # Process logs from the last position
        new_logs = self.fetch_logs_since(last_position)

        for log in new_logs:
            # Submit each log with an updated cursor
            self.send_log(
                data={
                    'message': log['message'],
                    'timestamp': log['timestamp'],
                    'status': log['level']
                },
                cursor={'position': log['position']},
                stream='my_stream'
            )

오류 로깅

from datadog_checks.base import AgentCheck
import time

class MyCustomCheck(AgentCheck):
    def check(self, instance):
        try:
            # Your check logic here
            self.perform_check()
        except Exception as e:
            # Log the error
            self.send_log({
                'message': f'Check failed: {str(e)}',
                'timestamp': time.time(),
                'status': 'error',
                'error_type': type(e).__name__,
                'service': 'my-custom-integration'
            })
            raise

로그 보기

제출 후 커스텀 체크의 로그가 로그 탐색기에 나타나요. 할 수 있는 일:

• source, service 또는 커스텀 태그로 로그 필터링.
• 로그 처리 파이프라인으로 구조화 로그 데이터 파싱.
• 로그 콘텐츠 기반 모니터와 알림 생성.
• 동일한 통합의 로그를 메트릭 및 트레이스와 상관관계 만들기.

모범 사례

• 구조화 로깅 사용: 모든 정보를 메시지 문자열에 포함하지 말고 data 사전에 추가 필드를 포함하세요.
• 적절한 상태 레벨 설정: 필터링과 알림에 도움이 되도록 error, warning, info, debug를 사용하세요.
• 타임스탬프 포함: 특히 과거 데이터를 처리할 때 정확한 로그 순서를 위해 항상 timestamp를 제공하세요.
• 일관된 태깅: 통합의 로그, 메트릭, 이벤트 전반에 걸쳐 동일한 태깅 전략을 사용하세요.
• 상태 저장 처리를 위한 커서 사용: 로그 소스를 추적할 때 커서를 사용해 데이터 재처리를 피하세요.

트러블슈팅

로그가 Datadog에 나타나지 않는다면:

1. Datadog 에이전트 구성에서 로그 수집이 활성화되어 있는지 확인하세요.
2. 로그 제출과 관련된 오류가 있는지 에이전트 로그를 확인하세요.
3. data 사전에 최소한 message 키가 있는지 확인하세요.
4. 에이전트의 상태 명령을 실행해 체크가 오류 없이 실행되는지 확인하세요.

더 알아보기 (Learn more)

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

• 에이전트 기반 통합 만들기
• 로그를 처리하는 방법 알아보기
• 파싱에 대해 더 알아보기
• 로그를 탐색하는 방법 알아보기
• send_logs API 파라미터