Linux에서 Single Step APM Instrumentation 사용

개요

Linux 호스트 또는 VM에서 APM에 단일 단계 계측(SSI)을 사용하여 추가 구성을 거치지 않고 한 번에 Datadog Agent를 설치하고 애플리케이션을 계측하세요.

에이전트를 사용해 APM 설정하기

Install the dd-apm skill in your AI coding agent for guided APM setup.
npx skills add https://github.com/datadog-labs/agent-skills --skill dd-apm --full-depth -y

애플리케이션에서 APM 활성화

계속 진행하기 전에 SSI 호환성 가이드를 검토하여 환경이 호환되는지 확인하세요.

새 Agent 설치

Datadog Agent를 설치하지 않은 경우, 한 번에 Datadog Agent를 설치하고 SSI를 활성화합니다.

  1. Linux 호스트 또는 VM에서 다음 명령을 실행합니다.

    DD_API_KEY=<YOUR_DD_API_KEY> \
DD_SITE="" \
DD_APM_INSTRUMENTATION_ENABLED=host \
bash -c "$(curl -L https://install.datadoghq.com/scripts/install_script_agent7.sh)"

    Replace <YOUR_DD_API_KEY> with your Datadog API key. The command installs or updates the Agent and the SSI packages.

    By default, SSI installs the latest SDK versions. To pin specific versions, add the DD_APM_INSTRUMENTATION_LIBRARIES variable with comma-separated language:major pairs. Available versions are listed in the source repositories for each language: Java (java), Node.js (js), Python (python), .NET (dotnet), Ruby (ruby), PHP (php).

  2. Restart your applications.

SSI adds a small amount of startup time to instrumented applications. If this overhead is not acceptable for your use case, contact Datadog Support.

Generate the command from Datadog

To get a command pre-filled with your API key and site, go to the Install the Datadog Agent on Linux page and turn on Application Performance Monitoring under Core Observability.

Linux에 Datadog Agent 설치를 위한 인앱 지침의 'Agent 적용 범위 사용자 지정' 섹션

드롭다운에서 SDK 버전을 선택하려면 Customize Library Versions를 클릭하세요.

Linux에 Datadog Agent 설치를 위한 지침의 '라이브러리 버전 사용자 지정' 드롭다운

그런 다음 생성된 명령을 복사하여 실행하세요.

기존 Agent 설치

Datadog Agent를 이미 설치한 경우, 호스트에서 새 Agent 설치의 Agent 설치 명령을 다시 실행합니다. 이 명령을 실행하면 기존 Agent 업데이트와 SSI 활성화 작업이 이루어집니다.

또는 Fleet Automation을 사용하여 Datadog에서 SSI를 활성화합니다.

  1. Datadog에서 Fleet Automation > Configuration으로 이동합니다.

  2. Configure Agents를 클릭합니다.

  3. 필터를 적용하여 구성하려는 에이전트를 선택한 다음 Next를 클릭합니다.

    Fleet Automation의 에이전트 필터링 화면(환경, 운영 체제, 호스트 이름별로 범위를 지정하는 옵션 표시)

  4. Application Performance Monitoring (APM) 타일을 클릭한 다음 Next를 클릭합니다.

    Fleet Automation의 제품 선택 화면(Application Performance Monitoring(APM) 타일 표시)

  5. Configure SDKs Installation 화면에서 Yes을 클릭하여 SDK를 자동으로 설치합니다. Use latest version을 선택하거나 선택을 해제하여 개별 SDK 버전을 지정합니다.

    Fleet Automation의 SDK 설치 구성 화면(자동 SDK 설치를 활성화하고 버전을 선택할 수 있는 옵션 표시)

  6. Next를 클릭합니다.

  7. 구성을 검토하고 Deploy Configuration을 클릭합니다.

설치 검증

  1. Agent가 실행 중인지 확인합니다.

    sudo datadog-agent status

  2. 호스트에서 SSI 인젝션이 활성화 상태인지 확인합니다.

    cat /etc/ld.so.preload && ls /opt/datadog-packages/ | grep apm

    출력에는 /etc/ld.so.preload의 APM 인젝터 라이브러리와 하나 이상의 datadog-apm-* 패키지가 나열됩니다.

  3. 애플리케이션에서 트래픽을 수신한 후, APM 서비스 페이지에 서비스 정보가 나타나는지 확인합니다. 몇 분 내에 나타나지 않으면 SSI 문제 해결 가이드를 따르세요.

Unified Service Tags 구성

Unified Service Tags(UST)는 트레이스, 메트릭, 로그에 일관된 태그를 적용해 탐색 및 관측 가능성 데이터 상호 연계가 간편합니다. Linux 서비스의 UST 설정 방법을 알아보세요.

SDK 종속적 제품 및 기능 활성화

SSI가 애플리케이션에 Datadog SDK를 로드하고 분산 트레이싱을 활성화하고 나면 SDK에 의존하는 추가적인 제품을 구성할 수 있습니다.

ProductEnvironment variable
Runtime MetricsDD_RUNTIME_METRICS_ENABLED
Log InjectionDD_LOGS_INJECTION
Continuous ProfilerDD_PROFILING_ENABLED
Data Streams MonitoringDD_DATA_STREAMS_ENABLED
App and API ProtectionDD_APPSEC_ENABLED
Runtime Code Analysis (IAST)DD_IAST_ENABLED
Dynamic InstrumentationDD_DYNAMIC_INSTRUMENTATION_ENABLED
Data Jobs MonitoringDD_DATA_JOBS_ENABLED
Software Composition AnalysisDD_APPSEC_SCA_ENABLED

Note: All variables accept true or false. DD_PROFILING_ENABLED also accepts auto, which profiles only eligible processes and is recommended for SSI.

다음 설정 방법 중 한 가지를 사용하세요.

고급 옵션

SDK 버전 업데이트

Agent 설치 명령을 실행할 때는 SDK 버전이 고정됩니다.

SDK 버전을 업데이트하려면 다음 단계를 따르세요.

  1. Agent 설치 명령을 다시 실행합니다. 이 명령은 Agent도 최신 버전으로 업데이트합니다.
  2. 애플리케이션을 재시작하세요.

계측 규칙 정의

선택한 Datadog 사이트에서는 계측 규칙이 지원되지 않습니다().

계측 규칙(Agent v7.73 이상에서 사용 가능)을 정의하면 Linux 호스트에서 SSI에 의해 자동으로 계측되는 프로세스를 제어할 수 있습니다.

참고: Bits AI를 사용하여 자연어로 계측 규칙을 생성할 수 있습니다. 계측할 프로세스를 설명하면 Bits AI가 해당 규칙을 생성합니다.

계측 규칙을 구성하려면 다음 단계를 따르세요.

  1. Datadog에서 APM > Service Setup > Manage Instrumentation Rules로 이동합니다.

  2. Add or Edit Rules를 클릭합니다.

  3. 계측 규칙을 정의합니다.

    1. Add New Rule를 클릭한 다음 Allow Rule 또는 Block Rule을 선택하여 일치 프로세스를 계측할지 여부를 지정합니다.
    2. 규칙 이름을 지정합니다.
    3. 하나 이상의 조건을 추가합니다. 자세한 내용은 규칙 조건 정의를 참조하세요.
    규칙 정의를 위한 구성 옵션을 제시하는 계측 규칙 UI

  4. (필요시) 규칙을 드래그 앤 드롭하여 순서를 변경합니다.

    참고: 규칙은 순서대로 평가됩니다. 프로세스와 규칙이 일치하면 후속 규칙은 무시됩니다.

  5. 어떤 규칙과도 일치하지 않는 프로세스에 대해 기본 동작(허용 또는 차단)을 설정합니다.

  6. Next를 클릭하여 규칙을 미리 봅니다.

  7. Deploy Rules를 클릭합니다.

Remote Configuration이 활성화된 경우, 규칙이 모든 호스트에 배포되고 50초 이내에 SSI가 활성화된 호스트에 적용됩니다. 또는 Export를 클릭하여 구성 파일을 내보내고 호스트에 수동으로 적용합니다.

규칙 조건 정의

규칙은 각각 하나 이상의 조건으로 구성됩니다. 조건에는 다음 요소가 포함되어 있습니다.

  • Attribute: 규칙이 평가하는 프로세스 속성입니다.
  • Operator: 비교 로직(equals, not equals, prefix, contains)입니다.
  • Value: 프로세스 이름이나 명령줄 플래그 등 일치시켜야 할 텍스트 또는 패턴입니다.

지원되는 속성은 다음과 같습니다.

속성설명예시
운영 체제호스트의 OS입니다.linux
실행 파일프로세스의 실행 파일 이름입니다.python3.11
실행 파일 전체 경로실행 파일의 전체 경로입니다./usr/bin/python3.11
인수프로세스를 시작할 때 사용되는 명령줄 인수입니다.--env=production
작업 디렉터리프로세스의 작업 디렉터리입니다./app
언어프로세스에 대해 탐지된 프로그래밍 언어입니다.python
진입점 파일애플리케이션을 시작할 때 사용되는 특정 파일입니다.app.py, server.js

사용 사례

계측 규칙을 적용하는 방법을 보여주는 다음 예시를 확인하세요.

기본적으로 모든 프로세스를 계측합니다. 분석 cron 작업 및 Java 배치 프로세서 등 가치가 없는 노이즈만 유발하는 서비스를 제외하도록 차단 규칙을 추가합니다.
작업 디렉터리 및 진입점 파일 조건에 대한 두 가지 계측 차단 규칙(기본값으로 계측 허용 설정)
기본적으로 모든 계측을 차단합니다. 특정 프로세스를 APM 대상에 포함하도록 허용 규칙을 추가하세요. 이 접근 방식은 정밀한 제어가 가능하며 점진적인 롤아웃에 적합합니다. 예를 들어, 결제 서비스와 고객 포털만 계측하려면 Working Directory을 사용하여 허용 규칙을 생성한 다음, 기본 동작을 Block Instrumentation으로 설정하세요.
특정 작업 디렉터리의 서비스에 대한 두 가지 계측 허용 규칙(기본값으로 계측 차단 설정)

Agent에서 Single Step APM 계측 제거

인프라의 모든 서비스에서 트레이스 생성을 중지하려면 다음 단계를 따르세요.

  1. 다음을 실행합니다.
    dd-host-install --uninstall
  2. 호스트 또는 VM에서 서비스를 재시작합니다.

문제 해결

SSI를 사용한 APM 활성화와 관련한 문제가 발생하는 경우, SSI 문제 해결 가이드를 참조하세요.

추가 자료

추가적인 유용한 설명서, 링크 및 기사:

런타임 메트릭 활성화설명서 more more 단일 단계 계측 규칙을 사용하여 호스트 전반의 서비스 트레이싱을 관리하세요블로그 more more