Ruby 소스 통합¶

Beacon Ruby는 OpenTelemetry Ruby Contrib 기반의 계측 소스 프로젝트입니다. 애플리케이션에서 필요한 계측 gem을 소스로 참조하고 OpenTelemetry SDK를 명시적으로 초기화하여 OTLP HTTP/protobuf로 트레이스를 내보냅니다.

Beacon Ruby는 업스트림 gem 식별자를 유지하며 소스 아카이브로 배포됩니다. 별도의 beacon-ruby gem, Agent 실행 파일 또는 제로 코드 사전 로드 기능은 제공하지 않습니다. 환경 변수 설정만으로 수집이 활성화되지는 않습니다.

사전 요구 사항¶

프로젝트가 지원하는 Ruby 툴체인과 Bundler를 설치하고 GitHub 및 RubyGems에 접근할 수 있어야 합니다. 실행 환경 요구 사항은 소스 설치 가이드를 참조하세요.
로컬 트레이스 검증에는 Linux, Python, Docker가 필요합니다. 소스 아카이브의 검증 안내에 따라 검증 스크립트에서 사용하는 Collector 이미지를 미리 다운로드합니다.

다운로드 및 설치¶

Beacon Ruby 릴리스 페이지에서 소스 배포판을 선택하고 소스 아카이브, SOURCE.txt, SHA256SUMS를 같은 새 디렉터리에 다운로드합니다.
다운로드 디렉터리에서 파일을 검증합니다.
```
sha256sum -c SHA256SUMS
```
검증에 성공한 후 소스 아카이브의 압축을 해제하고 소스 루트 디렉터리로 이동합니다. SOURCE.txt는 소스 커밋과 업스트림 기준을 기록합니다. 아카이브에는 라이선스가 포함되며 의존성은 별도로 설치해야 합니다.

애플리케이션 통합은 소스 아카이브의 Gemfile을 참조하세요. 같은 Beacon 소스에서 opentelemetry-instrumentation-base와 opentelemetry-instrumentation-net_http를 참조하고 선택한 배포 소스에 맞는 opentelemetry-sdk, opentelemetry-exporter-otlp 의존성을 사용합니다. 소스 경로를 애플리케이션의 실제 배포 위치에 맞추고 애플리케이션의 Gemfile과 Gemfile.lock을 커밋합니다.

RubyGems에서 같은 이름의 계측 gem을 직접 설치하면 업스트림 패키지가 선택됩니다. Bundler 의존성 출처를 확인하여 선택한 Beacon 소스가 로드되는지 검증합니다.

SDK 초기화¶

애플리케이션 시작 단계에서 필요한 라이브러리를 로드한 후 SDK를 초기화하고 Net::HTTP 계측을 활성화합니다.

require 'bundler/setup'
require 'net/http'
require 'opentelemetry-sdk'
require 'opentelemetry-exporter-otlp'
require 'opentelemetry-instrumentation-net_http'

OpenTelemetry::SDK.configure do |config|
  config.service_name = 'my-ruby-service'
  config.use 'OpenTelemetry::Instrumentation::Net::HTTP'
end

이 설정을 기존 초기화 로직에 통합하여 SDK가 중복 초기화되지 않도록 합니다. 계측 라이브러리는 지원되는 라이브러리를 통한 호출에만 Span을 생성하며 임의의 비즈니스 메서드를 자동으로 계측하지 않습니다. 루트 Span, 요청 및 종료 전 플러시는 소스 아카이브의 Ruby 예제를 참조하세요.

Net::HTTP 트레이스 검증¶

먼저 소스에 포함된 검증 스크립트로 의존성과 계측 경로를 확인합니다. 소스 루트 디렉터리에서 실행합니다.

cd beacon/validation
BUNDLE_FROZEN=true bundle install
BUNDLE_FROZEN=true python3 collector_smoke.py

스크립트는 잠긴 의존성과 Collector 이미지를 사용하여 임시 HTTP 서버와 로컬 OpenTelemetry Collector를 시작한 뒤 계측된 Ruby HTTP 요청을 실행합니다. 서비스 이름 beacon-ruby-import-smoke, 루트 Span 1개, HTTP 클라이언트 Span 1개, 동일한 Trace ID 및 부모·자식 관계를 확인합니다. 성공하면 다음을 출력합니다.

Collector received the service identity and correlated root/client spans.

스크립트 종료 시 임시 서버, 컨테이너 및 트레이스 출력을 정리합니다. 이 절차는 합성 요청이 로컬 Collector에 도달하는지 검증하며 프로덕션 백엔드 저장을 증명하지는 않습니다.

수신기 및 기능 범위¶

공개된 검증 기록은 공통 계측 기반, Net::HTTP 시맨틱 모드 및 OTLP HTTP/protobuf를 통한 로컬 Collector로의 Trace 내보내기를 포함합니다. Rails, 다른 통합, DataKit, Metric, Log, Profile, Security는 아직 검증 범위에 포함되지 않습니다.

Guance에 트레이스를 전송하려면 공통 설정에 따라 DataKit OpenTelemetry HTTP 수신기를 활성화하고 OpenTelemetry Ruby SDK에 따라 HTTP/protobuf 내보내기 주소를 설정합니다. SDK 초기화는 계속 필요합니다. DataKit 통합은 실제 애플리케이션 환경에서 별도로 검증해야 하며 로컬 Collector 검증 결과를 DataKit 저장 증거로 간주해서는 안 됩니다.

실제 Net::HTTP 요청을 생성한 뒤 Guance의 APM > 트레이스에서 설정한 서비스 이름으로 필터링합니다. Trace, Span 및 부모·자식 관계를 확인합니다.

업그레이드 및 롤백¶

각 소스 배포판은 별도 디렉터리에 보관합니다. 검증된 아카이브, 체크섬 파일, SOURCE.txt, 애플리케이션 Gemfile, 잠금 파일 및 SDK 초기화 설정을 유지합니다. 업그레이드 전에 릴리스 노트를 읽고 필요한 계측 경로를 검증합니다.

롤백 시 이전 소스 참조, 의존성 및 초기화 설정을 복원하고 애플리케이션을 다시 시작한 후 텔레메트리를 재검증합니다. 자세한 내용은 소스 설치 가이드를 참조하세요.