Ruby on Rails

공식 opentelemetry-ruby 젬을 사용해 별도의 Sophonz 패키지 없이 모든 Ruby·Rails 앱에서 트레이스를 Sophonz로 전송하세요.

sophonz 젬은 존재하지 않으며, 필요하지도 않습니다. Sophonz 컬렉터는 표준 OTLP를 사용하므로, 모든 Ruby·Rails 앱은 공식 opentelemetry-ruby 젬과 초기화 파일 하나, 그리고 환경 변수만으로 트레이스를 전송할 수 있습니다.

제공되는 것

  • 공식 Ruby SDK — opentelemetry-sdk + opentelemetry-exporter-otlp. 익스포터 젬이 로드되면 표준 OTEL_EXPORTER_OTLP_* 환경 변수를 자동으로 읽습니다.
  • 애플리케이션 전체에 대한 자동 계측 — opentelemetry-instrumentation-all을 통해 c.use_all 호출 한 번으로 현재 설치된 모든 계측 젬이 활성화됩니다: Rails 자체의 컨트롤러/뷰 스팬, Rack, ActiveRecord/pg/mysql2, Faraday/Net::HTTP를 통한 외부 호출, Sidekiq, Redis 등.
  • 직접 작성할 몽키패치가 없음 — 계측은 Rails가 이미 사용하는 ActiveSupport::Notifications 이벤트와 Rack 미들웨어를 그대로 이용합니다.

동작 방식

  1. Gemfile에 SDK, OTLP 익스포터, 계측 젬을 추가합니다.
  2. OpenTelemetry::SDK.configure { |c| c.use_all }을 호출하는 초기화 파일 하나를 만듭니다.
  3. 컬렉터 엔드포인트, 프로토콜, 헤더, 서비스 신원을 위한 환경 변수를 설정합니다.

Rails는 부팅 시(Bundler.require) Gemfile의 모든 젬을 자동으로 require하므로, 초기화 파일이 실행될 때는 이미 OTLP 익스포터가 로드된 상태입니다 — OpenTelemetry::SDK.configure는 별도 설정 없이 이를 기본 트레이스 익스포터로 인식합니다.

CAUTION — 유효한 service.key가 없으면 텔레메트리는 조용히 버려집니다

Sophonz 컬렉터는 강제 모드(enforce mode)로 동작합니다. 즉, OTLP 페이로드는 네트워크상으로 정상 수신되더라도 해석 가능한 service.key 리소스 속성이 없으면 조용히 폐기됩니다. 애플리케이션에 오류가 발생하지도, 요청이 거부되지도 않습니다 — 그저 콘솔이 비어 있을 뿐입니다. 다른 문제라고 넘겨짚기 전에 OTEL_RESOURCE_ATTRIBUTES(그리고 OTEL_EXPORTER_OTLP_HEADERS)부터 다시 확인하세요.

TIP — 다음 단계

정확한 Gemfile 항목, 초기화 코드, 환경 변수 표, Rails 관련 참고 사항은 설치 문서를 확인하세요.