공통 설정¶

이 페이지는 애플리케이션과 DataKit이 같은 호스트에 배포된 환경을 기준으로 Beacon 수신 측 설정을 설명합니다. 서로 다른 호스트나 컨테이너에 배포하는 경우 127.0.0.1을 애플리케이션에서 접근할 수 있는 DataKit 주소로 바꾸고 DataKit 수신 주소를 조정하세요.

DataKit 수집기 활성화¶

먼저 DataKit을 설치하고 대상 워크스페이스에 연결되어 있는지 확인하세요. 기본 설치 경로에서 OpenTelemetry 예제 설정을 복사합니다.

sudo cp /usr/local/datakit/conf.d/samples/opentelemetry.conf.sample \
  /usr/local/datakit/conf.d/opentelemetry.conf

파일을 편집해 아래 수신 설정을 유지하세요. 해당 설정이 이미 있으면 기존 설정을 수정하고 수집기를 중복 추가하지 마세요.

[[inputs.opentelemetry]]
  [inputs.opentelemetry.http]
    http_status_ok = 200
    trace_api = "/otel/v1/traces"
    metric_api = "/otel/v1/metrics"
    logs_api = "/otel/v1/logs"
  [inputs.opentelemetry.grpc]
    addr = "127.0.0.1:4317"

설정 후 DataKit을 재시작하세요. HTTP는 기본값이 9529인 DataKit HTTP 서비스 포트를 사용합니다. 다른 호스트에서 연결할 때는 HTTP 서비스 수신 주소와 gRPC addr도 조정하고 네트워크 정책으로 접근 범위를 제한하세요. Kubernetes 설정과 전체 파라미터는 OpenTelemetry 수집기를 참조하세요.

서비스 식별 및 OTLP 파라미터¶

DataKit으로 전송할 때는 우선 env와 version으로 환경과 버전을 식별하는 것이 좋습니다. 다른 사용자 정의 리소스 속성을 태그로 유지하려면 OpenTelemetry 수집기의 customer_tags 허용 목록에 추가하세요. 속성 이름의 .은 _로 변환됩니다.

export OTEL_SERVICE_NAME=order-service
export OTEL_RESOURCE_ATTRIBUTES=env=prod,version=1.0.0
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4317

export OTEL_SERVICE_NAME=order-service
export OTEL_RESOURCE_ATTRIBUTES=env=prod,version=1.0.0
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:9529/otel

공통 HTTP 주소에는 신호에 따라 /v1/traces, /v1/metrics 또는 /v1/logs가 추가됩니다. DataKit HTTP 주소에는 /otel 접두사를 유지하세요. DataKit OTLP/HTTP는 Protobuf만 지원하므로 http/protobuf를 사용하세요.

OTEL_EXPORTER_OTLP_TRACES_ENDPOINT와 같은 신호별 변수는 공통 주소보다 우선합니다. 신호별 HTTP 주소에는 http://127.0.0.1:9529/otel/v1/traces처럼 전체 경로를 입력해야 합니다. gRPC 주소에는 HTTP 경로를 추가하지 마세요.

이 설정은 실제 애플리케이션 프로세스에 주입해야 합니다. systemd, 컨테이너, PHP-FPM은 현재 터미널의 환경을 상속하지 않을 수 있습니다. 설정 후 애플리케이션을 재시작하세요. 인증 정보는 배포 플랫폼의 Secret으로 주입하고 코드 저장소에 기록하지 마세요.

Profile 및 Security¶

• Profile: 먼저 DataKit Profile 수집기를 활성화하세요. 업로드 주소는 http://127.0.0.1:9529/profiling/v1/input입니다. Java는 JFR을, Python과 Node.js는 pprof를 사용합니다. 자세한 설정은 각 언어의 연동 가이드를 참조하세요.
• Security: 기본적으로 비활성화되어 있습니다. 지원 언어는 기존 에이전트를 사용해 OTLP Logs로 전송합니다. Security에 따라 런타임 범위와 내보내기 파라미터를 설정한 뒤 로그에서 레코드를 확인하세요.

연동 확인¶

1. 애플리케이션 실행 환경에서 다음 명령을 실행해 DataKit HTTP 서비스에 접근할 수 있는지 확인하세요. 이 명령은 4317 포트나 수집기 활성화 여부를 검증하지 않습니다.

   curl -f http://127.0.0.1:9529/v1/ping
   

2. 해당 언어 가이드에 따라 애플리케이션을 시작하고 에이전트가 로드되었으며 OTLP 내보내기 오류가 없는지 확인하세요.

3. 지원되는 Web 프레임워크, HTTP 클라이언트 또는 데이터베이스를 거치는 애플리케이션 API에 접근해 실제 요청을 발생시키세요.
4. Guance의 APM > 트레이스에서 현재 시간 범위를 선택하고 service로 서비스 이름을 필터링하세요. 메트릭은 최소 한 번의 내보내기 주기가 지나야 표시될 수 있습니다.
5. Profile을 활성화했다면 수집 주기보다 오래 애플리케이션을 실행한 뒤 APM > Profiling에서 서비스 이름으로 확인하세요. Security를 활성화했다면 로그에서 해당 서비스의 레코드를 확인하세요.

데이터를 찾을 수 없으면 문제 해결을 참조하세요.