OpenTelemetry Ruby SDK¶

이 문서는 SDK 계측 방식을 사용합니다. 애플리케이션 코드에서 OpenTelemetry Ruby SDK를 초기화하고 프레임워크 계측 라이브러리를 활성화하여 Rails, Rack, Sinatra 및 지원되는 HTTP, 데이터베이스 등 컴포넌트 호출을 수집합니다. 프레임워크 계측 라이브러리가 Span을 자동 생성할 수는 있지만 SDK 연동은 명시적으로 해야 합니다. Gem을 설치하거나 환경 변수를 설정하는 것만으로는 자동으로 수집이 시작되지 않습니다.

Ruby 공식 문서에 따르면 현재 Trace는 안정화되었고 Metric과 Log는 아직 개발 중입니다. 이 문서에서는 Trace만 구성하며 OTLP/HTTP + Protobuf를 통해 DataKit으로 전송한 뒤 DataKit이 Guance에 보고합니다.

Ruby + OpenTelemetry Ruby SDK -> OTLP/HTTP -> DataKit -> Guance

전제 조건¶

• CRuby 3.1 이상과 Bundler. 구체적인 Gem 및 프레임워크 버전 제약은 해당 릴리스 노트와 Gemfile.lock을 따릅니다.
• 정상적으로 실행되는 Ruby 애플리케이션이 있어야 하며, 아래에서는 Rails를 예로 듭니다.
• DataKit을 설치하고 대상 워크스페이스의 설치 명령으로 데이터 보고 주소와 Token을 구성했어야 합니다.
• 애플리케이션은 DataKit의 HTTP 포트 9529에 접근할 수 있어야 합니다. 이 문서는 Kubernetes를 다루지 않습니다.

1. OpenTelemetry 수집기 활성화¶

DataKit 구성 디렉터리로 이동합니다. opentelemetry.conf가 없는 경우에만 예시 파일을 복사하고, 이미 구성이 있다면 기존 파일에서 조정합니다.

cd /usr/local/datakit/conf.d/opentelemetry
sudo cp -n opentelemetry.conf.sample opentelemetry.conf

opentelemetry.conf에 다음 구성이 포함되어 있는지 확인합니다. customer_tags는 사용자 정의 리소스 태그를 유지하는 데 사용됩니다.

[[inputs.opentelemetry]]
  customer_tags = ["team"]

  [inputs.opentelemetry.http]
    http_status_ok = 200
    trace_api = "/otel/v1/traces"
    metric_api = "/otel/v1/metrics"
    logs_api = "/otel/v1/logs"

애플리케이션과 DataKit이 같은 호스트에 있으면 127.0.0.1:9529를 사용할 수 있습니다. 분리하여 배포하는 경우 DataKit 기본 구성 datakit.conf의 [http_api].listen을 애플리케이션에서 접근 가능한 수신 주소로 변경하고 네트워크 접근 제어를 구성해야 합니다. HTTP 수신 주소는 opentelemetry.conf에서 설정하지 않습니다.

DataKit을 재시작하고 확인합니다.

sudo datakit service restart
curl http://127.0.0.1:9529/v1/ping

/v1/ping은 DataKit HTTP 서비스에 접근 가능한지만 확인하며, 분산 추적 데이터가 저장되었는지 증명하지는 않습니다. 전체 구성은 OpenTelemetry 수집기와 DataKit 기본 구성을 참고하세요.

2. 애플리케이션에 OpenTelemetry 연동¶

의존성 설치¶

애플리케이션 루트 디렉터리에서 실행하면 의존성이 Gemfile에 기록됩니다. 업데이트된 Gemfile과 Gemfile.lock을 커밋하고 배포하여 프로덕션 환경에도 이러한 Gem이 설치되도록 하세요.

bundle add opentelemetry-sdk opentelemetry-exporter-otlp opentelemetry-instrumentation-all

SDK 및 프레임워크 계측 초기화¶

config/initializers/opentelemetry.rb 파일을 추가합니다.

require 'opentelemetry/sdk'
require 'opentelemetry/exporter/otlp'
require 'opentelemetry/instrumentation/all'

OpenTelemetry::SDK.configure do |c|
  c.use_all
end

c.use_all은 설치되어 있고 애플리케이션 의존성과 호환되는 계측을 활성화합니다. 예제에서는 환경 변수로 서비스 이름을 설정하므로 c.service_name을 추가로 작성할 필요가 없습니다. 기존 SDK 초기화 로직이 있다면 같은 위치에 병합하여 중복 초기화를 피하세요.

Rails가 아닌 애플리케이션은 시작 단계에서 위 구성을 가능한 한 일찍 로드하고 해당 프레임워크 계측 라이브러리의 로드 순서를 따라야 합니다. opentelemetry-instrumentation-all은 지원되지 않는 라이브러리나 임의의 비즈니스 메서드에 대해 자동으로 Span을 생성하지 않습니다. 지원 범위는 Ruby 계측 라이브러리를 참고하세요.

애플리케이션 구성 및 시작¶

애플리케이션을 시작하는 동일한 터미널에서 다음 환경 변수를 설정합니다. 별도 호스트에 배포하는 경우 127.0.0.1을 애플리케이션에서 접근 가능한 DataKit 주소로 바꿉니다.

export OTEL_SERVICE_NAME="order-service"
export OTEL_RESOURCE_ATTRIBUTES="deployment.environment.name=prod,service.version=1.0.0,team=backend"
export OTEL_TRACES_EXPORTER="otlp"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="http://127.0.0.1:9529/otel/v1/traces"
export OTEL_PROPAGATORS="tracecontext,baggage"
export OTEL_TRACES_SAMPLER="parentbased_always_on"

bundle exec rails server -b 127.0.0.1 -p 3000

예제에서는 Rails 개발 서버로 연동을 검증합니다. 프로덕션 환경에서는 환경 변수를 실제 systemd, 프로세스 매니저 또는 배포 구성에 설정하고 모든 애플리케이션 프로세스를 재시작하세요. 대화형 터미널에만 설정하지 마세요.

이 문서에서 사용하는 opentelemetry-exporter-otlp는 HTTP/Protobuf Exporter입니다. 프로토콜을 grpc로 변경하고 4317 포트를 사용해도 gRPC로 전환할 수 없습니다.

3. 데이터 보고 파라미터¶

프로덕션 환경에서는 비율 샘플링으로 변경할 수 있습니다.

export OTEL_TRACES_SAMPLER="parentbased_traceidratio"
export OTEL_TRACES_SAMPLER_ARG="0.1"

0.1은 루트 분산 추적의 약 10%가 샘플링됨을 의미하며, 하위 Span은 여전히 부모의 샘플링 결정을 따릅니다. 환경 변수는 SDK 초기화 전에 적용되어야 합니다.

이 문서에서는 Log, Metric 내보내기 파이프라인을 설치하거나 구성하지 않으며, 다른 언어에서 신호 스위치를 설정한다고 해서 해당 기능이 활성화된다고 보장하지 않습니다. 애플리케이션 로그는 별도로 DataKit 로그 파일 수집을 사용할 수 있습니다. 분산 추적과 연결해야 한다면 로그에 현재 Span의 Trace ID를 기록하고 Pipeline에서 trace_id로 파싱해야 합니다.

검증 및 문제 해결¶

1. 애플리케이션에 실제로 존재하는 비즈니스 엔드포인트에 접근하여 지원되는 Web, HTTP, 데이터베이스 호출을 트리거합니다. 프로세스만 시작한다고 Span이 생성되지는 않습니다.
2. 배치 내보내기를 기다린 후 Guance 애플리케이션 성능 모니터링(APM)에서 서비스 이름 order-service로 분산 추적을 조회합니다.
3. 데이터가 없으면 먼저 OTEL_TRACES_EXPORTER=console로 애플리케이션을 재시작하고 다시 요청합니다. Span이 출력되면 계측이 적용된 것이므로 문제를 확인한 후 otlp로 복원합니다.
4. Span은 생성되지만 보고가 실패하는 경우 DataKit 수집기가 활성화되어 있는지, HTTP 주소에 /otel/v1/traces가 포함되어 있는지, 애플리케이션 프로세스가 환경 변수를 상속하는지, 그리고 애플리케이션과 DataKit의 오류 로그를 확인합니다.
5. 수명이 짧은 스크립트는 종료 전에 OpenTelemetry.tracer_provider.shutdown을 호출하여 버퍼링된 데이터가 내보내질 때까지 기다려야 합니다. 프로세스를 강제 종료하면 아직 전송되지 않은 Span이 유실될 수 있습니다.

참고 문서¶

• OpenTelemetry Ruby
• Ruby 시작하기
• Ruby 계측 라이브러리
• Ruby Exporter