OpenTelemetry 통합

OpenTelemetry를 통해 애플리케이션의 추적(Trace)과 로그(Log) 데이터를 Observability로 전송하는 방법을 안내합니다.

개요

OpenTelemetry는 벤더 중립적인 오픈소스 프로젝트로, 텔레메트리 데이터를 수집하고 내보내기 위한 API, SDK, 도구를 제공합니다. Observability는 OpenTelemetry 백엔드로서 트레이스(Trace)와 로그(Log) 데이터를 수신할 수 있습니다. 텔레메트리 데이터는 OpenTelemetry Collector를 통해 전달하거나, 애플리케이션에서 직접 전송할 수 있습니다.

분산추적 데이터와 로그는 커널 수준 자동 추적으로 코드 수정 없이도 수집됩니다. OpenTelemetry 연동은 필수가 아니지만, 추가로 연동하면 다음과 같은 이점이 있습니다.

분산추적: HTTP 헤더 등 상세 속성이 스팬에 추가되고, 서비스 간 호출 관계가 스팬의 부모-자식 관계로 정확히 연결되어 마이크로서비스 호출 체인을 추적할 수 있습니다.
로그: 로그에 추적 ID(Trace ID), 스팬 ID(Span ID) 등의 컨텍스트가 자동으로 포함되어 분산추적과 로그를 연결하여 분석할 수 있고, 구조화된 속성을 로그에 추가하여 더 정밀한 필터링이 가능합니다.

시스템 설정 탭 또는 분산추적, 로그 뷰어 화면에서 OpenTelemetry 통합 버튼을 클릭하면 연동 안내 다이얼로그가 표시됩니다.

연동 설정

OpenTelemetry 연동 다이얼로그 상단에서 다음 항목을 설정합니다.

항목	설명
Observability URL	Observability 서버의 URL (예: `http://openmaru-server:8080`)
API Key	프로젝트의 API 키. 시스템 설정에서 생성한 키 중 하나를 선택합니다.
Service name	SDK 직접 연동 시 사용할 서비스 이름 (Collector 방식에서는 표시되지 않음)

참고: API 키는 Admin 역할의 사용자만 선택할 수 있습니다. API 키가 없는 경우 project settings 링크를 클릭하여 시스템 설정 탭에서 키를 생성하세요.

OpenTelemetry Collector 방식

기존에 OpenTelemetry Collector를 사용하고 있는 경우, Collector 설정 파일에 Observability를 내보내기 대상으로 추가하면 됩니다.

Collector 설정 예시 (otel-collector-config.yaml):

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

processors:
  batch:

exporters:
  otlphttp/openmaru:
    endpoint: "<Observability URL>"
    encoding: proto
    headers:
      "x-api-key": "<API Key>"

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp/openmaru]
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp/openmaru]

설정 항목 설명:

receivers: OTLP 수신기를 활성화합니다. gRPC(4317 포트)와 HTTP(4318 포트) 프로토콜을 모두 지원합니다.
processors: batch 프로세서를 사용하여 데이터를 일괄 전송합니다.
exporters: otlphttp/openmaru 내보내기를 추가합니다. endpoint에 Observability 서버 URL을, headers에 API 키를 설정합니다.
service.pipelines: traces와 logs 파이프라인에 내보내기를 추가합니다.

참고: Kubernetes 환경에서는 Collector 서비스 주소를 http://openmaru-observ-server.openmaru-observ.svc:8080 형식으로 지정할 수 있습니다.

SDK 직접 연동 방식

OpenTelemetry SDK를 사용하여 애플리케이션에서 Observability 서버로 트레이스와 로그를 직접 전송할 수 있습니다.

1단계: OpenTelemetry SDK 설치

사용하는 프로그래밍 언어에 맞는 OpenTelemetry SDK를 설치합니다. 지원되는 언어:

Go, Java, Python, C++, .NET, JavaScript, PHP, Ruby, Rust

각 언어별 설치 방법은 OpenTelemetry 공식 문서를 참조하세요.

2단계: 환경 변수 설정

다음 환경 변수를 설정하여 SDK가 Observability 서버로 데이터를 전송하도록 구성합니다.

OTEL_SERVICE_NAME="<서비스 이름>" \
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="<Observability URL>/v1/traces" \
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT="<Observability URL>/v1/logs" \
OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf" \
OTEL_METRICS_EXPORTER="none" \
OTEL_EXPORTER_OTLP_HEADERS="x-api-key=<API Key>"

환경 변수 설명:

환경 변수	설명
`OTEL_SERVICE_NAME`	애플리케이션의 서비스 이름
`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`	트레이스 데이터 전송 엔드포인트
`OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`	로그 데이터 전송 엔드포인트
`OTEL_EXPORTER_OTLP_PROTOCOL`	전송 프로토콜 (`http/protobuf` 사용)
`OTEL_METRICS_EXPORTER`	메트릭 내보내기 비활성화 (`none` 설정)
`OTEL_EXPORTER_OTLP_HEADERS`	API 키를 포함하는 HTTP 헤더

참고: OTEL_METRICS_EXPORTER를 none으로 설정하는 이유는 Observability가 메트릭 수집에는 Prometheus를 사용하기 때문입니다. OpenTelemetry를 통한 메트릭 수집은 지원하지 않습니다.

OpenTelemetry 통합

개요​

연동 설정​

OpenTelemetry Collector 방식​

SDK 직접 연동 방식​

개요

연동 설정

OpenTelemetry Collector 방식

SDK 직접 연동 방식