개요

이 페이지에서는 Technology Partners가 Datadog Agent 통합을 생성하는 방법에 대해 알아봅니다. 이 통합은 Integrations 페이지에서 기본 제공 항목으로 공개하거나 Marketplace 페이지에서 유료로 공개할 수 있습니다.

Agent 기반 통합은 Datadog Agent를 사용하여 개발자가 작성한 사용자 지정 점검을 통해 데이터를 제출합니다. 이러한 점검은 메트릭, 이벤트, 서비스 점검을 고객의 Datadog 계정으로 전송할 수 있습니다. Agent 자체도 로그를 제출할 수 있지만, 이는 점검 외부에서 구성됩니다.

Agent 기반 통합은 언제 사용하나요?

Agent 통합은 다음을 실행하는 시스템이나 애플리케이션에서 데이터를 수집하는 데 가장 적합합니다.

• 근거리 통신망(LAN)
• 가상 프라이빗 클라우드(VPC) Agent 기반 통합은 Python wheel(.whl)로 게시하고 배포해야 합니다.

개발 프로세스

Agent 기반 통합을 만드는 프로세스는 다음과 같습니다.

1. Datadog Partner Network에 가입하기
   • Datadog Partner Network에 지원하세요. 지원이 승인되면 Datadog Technology Partner 팀 담당자와의 오리엔테이션 콜 일정이 예약됩니다.
2. 개발 환경 설정
   • Datadog Partner Network 포털을 통해 Datadog 샌드박스 계정을 요청합니다.
   • 필수 개발 도구를 설치합니다.
3. 통합 생성
   • Datadog 샌드박스에서 Developer Platform > add a new listing으로 이동합니다.
   • 통합을 설명하는 세부 정보를 입력합니다.
4. Agent 점검 구축 및 통합 테스트
   • Agent 점검을 [단계]((#write-an-agent-check)를 따라 생성합니다.
5. 리뷰를 위해 제출
   • Developer Platform을 통해 통합 콘텐츠를 제출합니다.
   • 해당 코드를 사용하여 Agent 점검에 대한 GitHub 풀 요청을 엽니다.
   • Datadog 팀에서 통합 리뷰를 위해 최종 데모 일정을 예약합니다.

사전 필수 조건

필수 Datadog 에이전트 통합 개발 도구에는 다음이 포함됩니다:

• Python v3.12, pipx, Agent Integration Developer Tool(ddev). 설치 지침은 Datadog Agent Integration Developer Tool 설치에서 확인하세요.
• 도커를 통해 전체 테스트 스위트를 실행합니다.
• git 명령줄 또는 GitHub 데스크톱 클라이언트.

mkdir $HOME/dd && cd $HOME/dd

통합 생성

Docker를 다운로드하고, 적절한 버전의 Python을 설치하고, 개발 환경을 준비하면 Agent 기반 통합을 만들 수 있습니다.

다음 지침에서는 Awesome이라는 통합 예제를 사용합니다. Awesome의 코드를 사용하거나, Awesome을 직접 작성한 코드로 바꾸고 명령 내에서 통합 이름을 입력하세요. 예를 들어 ddev create Awesome 대신 ddev create <your-integration-name>을 사용합니다.

통합을 위한 스캐폴딩 만들기

ddev create 명령은 에이전트 기반 통합에 필요한 기본 파일 및 경로 구조 (또는 “스캐폴딩”)를 만드는 대화형 도구를 실행합니다.

1. 첫 번째 통합 디렉토리를 만들기 전에 디스크에 아무것도 쓰지 않는 -n/--dry-run 플래그를 사용하여 드라이 런을 시도해 보세요:

   ddev create -n Awesome
   

   이 명령은 파일이 작성되었을 경로와 구조를 표시합니다. 출력 첫 줄의 경로가 리포지토리 위치와 일치하는지 확인하세요.

2. -n 플래그 없이 명령을 실행합니다. 도구에서 이메일과 이름을 입력하면 통합을 시작하는 데 필요한 파일을 생성합니다.

   Datadog 마켓플레이스용 통합을 만드는 경우, 디렉토리가 {파트너 이름}_{통합 이름}의 패턴을 따르는지 확인하세요.

   ddev create Awesome
   

에이전트 검사 작성

모든 Agent 기반 통합의 핵심은 주기적으로 정보를 수집하고 Datadog에 전송하는 Agent Check입니다.

검사는 AgentCheck 기본 클래스에서 로직을 이어 받고, 다음과 같은 요구 사항을 갖습니다:

• Datadog 에이전트 v7 이상에서 실행되는 통합은 Python 3과 호환되어야 하지만, 에이전트 v5 및 v6에서 실행되는 통합은 여전히 Python 2.7을 사용합니다.
• 검사는 반드시 AgentCheck에서 파생되어야 합니다.
• 검사는 서명 check(self, instance)이 포함된 방식을 제공해야 합니다.
• 검사는 datadog_checks 네임스페이스 아래의 일반 Python 패키지에 구성됩니다. 예를 들어, Awesome의 코드는 awesome/datadog_checks/awesome/ 디렉토리에 있습니다.
• 패키지 이름은 검사 이름과 동일해야 합니다.
• 해당 패키지 내의 Python 모듈 이름이나 검사를 구현하는 클래스 이름에는 제한이 없습니다.

검사 로직 구현

Awesome의 경우 Agent Check는 awesome.search라는 서비스 점검으로 구성되며, 이 점검은 웹 페이지에서 문자열을 검색합니다. 문자열이 존재하면 OK, 페이지에 접근할 수 있지만 문자열을 찾을 수 없다면 WARNING, 페이지에 접근할 수 없다면 CRITICAL을 표시합니다.

에이전트 검사로 메트릭을 제출하는 방법을 알아보려면 커스텀 에이전트 검사를 참조하세요.

awesome/datadog_checks/awesome/check.py 안에 포함된 코드는 다음과 같습니다:

import requests

from datadog_checks.base import AgentCheck, ConfigurationError


class AwesomeCheck(AgentCheck):
    """AwesomeCheck derives from AgentCheck, and provides the required check method."""

    def check(self, instance):
        url = instance.get('url')
        search_string = instance.get('search_string')

        # It's a very good idea to do some basic sanity checking.
        # Try to be as specific as possible with the exceptions.
        if not url or not search_string:
            raise ConfigurationError('Configuration error, please fix awesome.yaml')

        try:
            response = requests.get(url)
            response.raise_for_status()
        # Something went horribly wrong
        except Exception as e:
            # Ideally we'd use a more specific message...
            self.service_check('awesome.search', self.CRITICAL, message=str(e))
        # Page is accessible
        else:
            # search_string is present
            if search_string in response.text:
                self.service_check('awesome.search', self.OK)
            # search_string was not found
            else:
                self.service_check('awesome.search', self.WARNING)

기본 Python 클래스에 대해 자세히 알아보려면 Python 검사의 구조를 참조하세요.

유효성 테스트 작성

테스트에는 두 가지 유형이 있습니다:

• 특정 기능에 대한 단위 테스트입니다.
• check 방식을 실행하고 적절한 메트릭 수집을 확인하는 통합 테스트입니다.

pytest 및 hatch는 테스트를 실행하는 데 사용됩니다. 통합을 게시하려면 테스트가 필요합니다.

단위 테스트 작성

Awesome용 check 메서드의 첫 번째 부분은 구성 파일에서 두 요소를 검색하고 검증합니다. 이는 단위 테스트를 작성하기에 적합한 대상입니다.

awesome/tests/test_awesome.py에서 파일을 열고 내용을 다음으로 바꿉니다:

import pytest

    # Don't forget to import your integration

from datadog_checks.awesome import AwesomeCheck
from datadog_checks.base import ConfigurationError


@pytest.mark.unit
def test_config():
    instance = {}
    c = AwesomeCheck('awesome', {}, [instance])

    # empty instance
    with pytest.raises(ConfigurationError):
        c.check(instance)

    # only the url
    with pytest.raises(ConfigurationError):
        c.check({'url': 'http://foobar'})

    # only the search string
    with pytest.raises(ConfigurationError):
        c.check({'search_string': 'foo'})

    # this should not fail
    c.check({'url': 'http://foobar', 'search_string': 'foo'})

pytest에는 테스트를 카테고리로 그룹화하는 데 사용할 수 있는 마커라는 개념이 있습니다. test_config이 unit 테스트로 표시된 것을 주목하세요.

awesome/tests에 있는 모든 테스트를 실행하도록 스캐폴딩이 설정되어 있습니다. 테스트를 실행하려면 다음 명령을 실행하세요:

ddev test awesome

통합 테스트 작성

위의 단위 테스트는 수집 로직을 확인하지 않습니다. 로직을 테스트하려면 통합 테스트를 위한 환경을 생성하고 통합 테스트를 작성해야 합니다.

통합 테스트를 위한 환경 만들기

툴킷은 NGINX 컨테이너를 스핀업하는 데 docker를 사용하며 검사가 시작 페이지를 검색할 수 있도록 합니다.

통합 테스트를 위한 환경을 만들려면 다음 내용으로 awesome/tests/docker-compose.yml에서 docker-compose 파일을 생성합니다:

version: "3"

services:
  nginx:
    image: nginx:stable-alpine
    ports:
      - "8000:80"

그런 다음 awesome/tests/conftest.py에서 파일을 열고 내용을 다음으로 바꿉니다:

import os

import pytest

from datadog_checks.dev import docker_run, get_docker_hostname, get_here

URL = 'http://{}:8000'.format(get_docker_hostname())
SEARCH_STRING = 'Thank you for using nginx.'
INSTANCE = {'url': URL, 'search_string': SEARCH_STRING}


@pytest.fixture(scope='session')
def dd_environment():
    compose_file = os.path.join(get_here(), 'docker-compose.yml')

    # 이렇게 하면 세 가지 작업이 수행됩니다:
    #
    # 1. compose 파일에 정의된 서비스를 스핀업
    # 2. 테스트를 실행하기 전에 URL을 사용할 수 있을 때까지 대기
    # 3. 테스트가 완료되면 서비스 중단
    with docker_run(compose_file, endpoints=[URL]):
        yield INSTANCE


@pytest.fixture
def instance():
    return INSTANCE.copy()

통합 테스트 추가

통합 테스트를 위한 환경을 설정한 후 awesome/tests/test_awesome.py 파일에 통합 테스트를 추가합니다:

@pytest.mark.integration
@pytest.mark.usefixtures('dd_environment')
def test_service_check(aggregator, instance):
    c = AwesomeCheck('awesome', {}, [instance])

    # the check should send OK
    c.check(instance)
    aggregator.assert_service_check('awesome.search', AwesomeCheck.OK)

    # the check should send WARNING
    instance['search_string'] = 'Apache'
    c.check(instance)
    aggregator.assert_service_check('awesome.search', AwesomeCheck.WARNING)

개발 속도를 높이려면 -m/--marker 옵션을 사용하여 통합 테스트만 실행하세요:

ddev test -m integration awesome

통합이 거의 완료되었습니다. 샌드박스의 Developer Platform으로 돌아가서 제출을 완료하세요.

휠 구축하기

pyproject.toml 파일은 휠을 패키징하고 구축하는 데 사용되는 메타데이터를 제공합니다. 휠에는 통합 기능에 필요한 파일이 포함되어 있으며, 여기에는 에이전트 검사, 설정 예제 파일 및 휠 빌드 중에 생성된 아티팩트가 포함됩니다.

메타데이터 파일 등 모든 추가 요소는 wheel 내에 포함되지 않으며, Datadog 플랫폼과 에코시스템의 다른 곳에서 사용됩니다.

Python 패키징에 대해 자세히 알아보려면 Python 프로젝트 패키징을 참조하세요.

pyproject.toml 준비가 완료되면 다음 옵션 중 하나를 사용하여 휠을 만듭니다:

• (권장) ddev 툴링 사용 시: ddev release build <INTEGRATION_NAME>.
• ddev 툴링 미사용 시: cd <INTEGRATION_DIR> && pip wheel . --no-deps --wheel-dir dist.

휠 설치하기

휠은 에이전트 v6.10.0 이상에서 사용할 수 있는 에이전트 integration 명령을 사용하여 설치됩니다. 환경에 따라 특정 사용자 또는 특정 권한으로 이 명령을 실행해야 할 수도 있습니다:

Linux (dd-agent로 표시):

sudo -u dd-agent datadog-agent integration install -w /path/to/wheel.whl

OSX (어드민으로 표시):

sudo datadog-agent integration install -w /path/to/wheel.whl

Windows PowerShell(셸 세션에 administrator 권한이 있는지 확인하세요):

& "C:\Program Files\Datadog\Datadog Agent\embedded\agent.exe" integration install -w /path/to/wheel.whl

& "C:\Program Files\Datadog\Datadog Agent\bin\agent.exe" integration install -w /path/to/wheel.whl

Kubernetes 환경에서 테스트 목적으로 wheel을 설치하려면 다음 단계를 따르세요.

1. .whl 파일을 initContainer에 마운트합니다.
2. initContainer에서 wheel 설치를 실행합니다.
3. Agent 컨테이너가 실행되는 동안 initContainer를 마운트합니다.

호스트 및 컨테이너 환경에 대한 고객 설치 명령은 Community 및 Marketplace 통합 문서를 참고하세요.

리뷰를 위해 코드를 제출합니다.

Developer Platform에 안내된 단계를 따라 GitHub에서 리뷰할 수 있도록 Agent 점검 코드를 제출합니다. 승인되면 통합과 함께 풀 리퀘스트가 공개됩니다.

통합 업그레이드

• 새로운 통합 코드를 편집하거나 추가하려면 버전 업그레이드가 필요합니다.

• README 콘텐츠, 매니페스트 정보, 자산(대시보드 및 모니터 템플릿)을 편집하거나 추가하는 경우 버전을 올릴 필요가 없습니다.

통합 버전 올리기

통합 버전을 변경할 때는 코드 변경 외에도 다음 사항이 필요합니다.

1. 새 버전 번호를 반영하도록 __about__.py를 업데이트합니다. 이 파일은 /datadog_checks/<your_check_name>/__about__.py의 통합 디렉터리에서 찾을 수 있습니다.
2. Developer Platform의 *Release Notes**에 다음 형식을 따르는 항목을 추가합니다.

   ## Version Number / Date in YYYY-MM-DD
   
   ***Added***:
   
   * New feature
   * New feature
   
   ***Fixed***:
   
   * Bug fix
   * Bug fix
   
   ***Changed***:
   
   * Feature update
   * Feature update
   
   ***Removed***:
   
   * Feature removal
   * Feature removal
   

3. 설치 지침과 다른 모든 곳에서 언급된 버전 번호를 모두 업데이트하세요. 설치 지침에는 보통 버전 번호가 포함되어 있으므로, 해당 번호를 업데이트해야 합니다.

참고 자료

추가 유용한 문서, 링크 및 기사:

통합 생성하기설명서 에이전트 기반 통합 개발을 위한 Python설명서 Datadog 플랫폼에서 개발하는 방법에 대해 알아보세요.설명서