Custom OTLP 연결

전체 문서 PDF

Custom OTLP는 이미 OTLP를 사용 중인 SDK·Agent·Collector를 Monithub에 연결하거나, 여러 서비스의 OTLP 데이터를 하나의 Collector로 모아 전달할 때 사용합니다. 기존 송신기에서 데이터를 받아 Monithub로 전달하는 Collector를 실행하는 방식입니다.

수집되는 신호는 앞단 송신기가 실제로 보내는 데이터에 따라 달라집니다. 메트릭, 트레이스와 로그 중 하나만 보내고 있다면 해당 신호만 확인됩니다.

설정 생성

커스텀 OTLP를 선택합니다.
데이터를 받아 전달할 Collector의 실행 환경을 선택합니다. 기본 설정은 같은 호스트의 송신기 연결을 지원합니다.
목록에서 구분할 수집 대상 이름과 운영 환경을 입력하고 설정 생성을 누릅니다.

Collector 실행과 송신 주소 적용

Collector 실행

설치 · 설정 적용에서 선택한 OS·CPU에 맞는 Collector를 준비하고, 생성된 otelcol-monithub.yaml 전체를 저장합니다. Docker를 선택했다면 생성된 컨테이너 실행 명령을 사용합니다.

기존 Collector가 이미 4317·4318을 사용 중이면 호스트 실행 시 새 YAML의 수신 포트를 바꿉니다. Docker에서 호스트 포트만 충돌한다면 -p의 호스트 쪽 포트를 바꿉니다. 아래 송신 주소에도 해당 송신기가 접근하는 포트를 적용하세요.

otelcol-contrib --config ./otelcol-monithub.yaml

& .\otelcol-contrib.exe --config .\otelcol-monithub.yaml

Collector가 실행 중인 터미널은 유지하고, 다른 터미널이나 기존 서비스 설정에서 송신기 설정을 변경합니다. 상시 수집할 때는 기존 서비스 관리 방식으로 Collector를 계속 실행하세요.

송신 주소 선택

주소는 데이터를 보내는 SDK·Agent·Collector에서 접근할 수 있는 주소를 사용합니다.

송신기와 Collector의 위치	OTLP HTTP 주소	OTLP gRPC 주소
같은 호스트에서 직접 실행	`http://127.0.0.1:4318`	`127.0.0.1:4317`
송신기는 호스트에서 직접 실행, Collector는 해당 호스트의 Docker	`http://127.0.0.1:4318`	`127.0.0.1:4317`
같은 사용자 정의 Docker 네트워크의 별도 컨테이너	`http://monithub-collector:4318`	`monithub-collector:4317`

마지막 행의 monithub-collector는 Collector의 컨테이너 이름 또는 Compose 서비스 이름 예시입니다. 생성된 docker run에 --name monithub-collector를 추가하고 --network 옵션에 송신기와 같은 사용자 정의 네트워크 이름을 지정합니다. Compose에서는 두 서비스를 같은 네트워크에 연결하세요. 별도 컨테이너의 127.0.0.1은 그 컨테이너 자신을 가리킵니다.

기본 설정은 다른 서버의 송신기가 접속하는 구성을 포함하지 않습니다. 호스트 방식은 로컬 주소에서 수신하고, Docker 방식도 호스트 포트를 127.0.0.1에만 연결합니다. 여러 서비스 집계는 위와 같이 Collector에 접근할 수 있는 범위에서 사용합니다.

SDK·Agent에서 보내기

아래는 환경 변수로 OTLP 설정을 지원하는 SDK·Agent의 HTTP 예시입니다. 애플리케이션의 실행 환경에 적용하고 앱을 다시 시작합니다. SDK를 코드로 설정했다면 해당 코드의 exporter 설정을 변경하세요.

export OTEL_EXPORTER_OTLP_ENDPOINT="http://127.0.0.1:4318"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"

$env:OTEL_EXPORTER_OTLP_ENDPOINT="http://127.0.0.1:4318"
$env:OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"

앱이 Docker에서 실행된다면 두 변수를 앱 컨테이너의 환경 변수로 전달하고 재생성합니다. 주소는 위 표의 컨테이너용 주소로 바꿉니다. gRPC를 사용한다면 프로토콜은 grpc, SDK endpoint는 http://127.0.0.1:4317 또는 http://monithub-collector:4317을 사용합니다.

기존에 신호별 endpoint나 프로토콜을 지정했다면 해당 값도 변경합니다. 예를 들어 OTEL_EXPORTER_OTLP_TRACES_ENDPOINT를 사용하는 HTTP 송신기는 http://127.0.0.1:4318/v1/traces처럼 신호 경로까지 지정합니다. 서비스별 service.name은 유지해 Monithub에서 각 서비스를 구분합니다.

기존 Collector에서 보내기

기존 Collector가 송신기라면 위 SDK 환경 변수 대신 기존 Collector의 YAML을 수정합니다.

현재 Collector 설정을 백업합니다.
사용하는 OTLP exporter의 endpoint를 위 표의 주소로 변경합니다. HTTP exporter는 http://127.0.0.1:4318 형식, gRPC exporter는 127.0.0.1:4317 형식을 사용합니다. gRPC exporter에는 이 로컬 비암호화 연결에 맞게 tls 아래 insecure: true를 설정합니다.
해당 exporter가 보낼 신호의 service.pipelines에 포함되어 있는지 확인합니다. 기존 전송 대상도 유지해야 한다면 exporter를 별도 이름으로 추가하고 필요한 파이프라인에 함께 연결합니다.
기존 Collector의 실행 환경으로 설정을 검증하고 다시 시작합니다.

이 방식은 기존 Collector에서 새 Custom OTLP Collector로 데이터를 보내는 구성입니다. 카탈로그의 수집 설정을 기존 Collector에 직접 병합하는 경우는 기존 Collector에 적용을 참고하세요.

연결 후 확인

기존 송신기에서 실제 메트릭, 트레이스 또는 로그를 보낸 뒤 Connect의 데이터 수집 확인을 실행합니다. 필요한 신호가 모두 들어오는지는 각 데이터 조회에서도 확인하세요.

증상	확인할 내용
모든 신호가 없음	송신기에서 접근 가능한 주소인지, HTTP·gRPC 프로토콜과 포트가 맞는지, 변경한 설정으로 송신기를 다시 시작했는지 확인합니다.
일부 신호만 없음	앞단 송신기가 해당 신호를 실제로 생성하고 내보내는지 확인합니다.
Collector가 시작되지 않음	Connect에서 생성한 YAML 전체를 저장했는지와 수신 포트 충돌 여부를 확인합니다.
기존 Collector의 전송 실패	exporter가 파이프라인에 연결되어 있는지와 기존 Collector의 전송 오류 로그를 확인합니다.

상태의 의미와 확인 순서는 연결 및 수집 확인에서 안내합니다.