설치

공식 opentelemetry-ruby 젬을 추가하고 Rails 초기화 파일을 설정한 뒤, 환경 변수로 Sophonz에 트레이스를 전송하세요.

이 문서는 Sophonz 패키지가 아니라 업스트림 opentelemetry-ruby 젬을 연결합니다. 텔레메트리가 어디로 가고 누구에게 속하는지는 모두 환경 변수가 처리하며, 초기화 파일은 계측을 켜는 역할만 합니다.

빠른 시작

아래에서 수집기 URL, 프로젝트, 앱 이름, 버전, 앱 키를 입력하고 탭(Rails · Plain Ruby)을 선택하면 그 값으로 초기화 코드가 생성됩니다. 고급 옵션은 "고급 옵션" 토글 뒤에 있습니다.

# config/initializers/opentelemetry.rb
require "opentelemetry/sdk"
require "opentelemetry/exporter/otlp"
require "opentelemetry/instrumentation/all"

ENV["OTEL_SERVICE_NAME"] ||= "next-sample"
ENV["OTEL_EXPORTER_OTLP_ENDPOINT"] ||= "https://in.sophonz.ai"
ENV["OTEL_EXPORTER_OTLP_PROTOCOL"] ||= "http/protobuf"
ENV["OTEL_EXPORTER_OTLP_HEADERS"] ||= "authorization=sk_tYtJUa4WweXXedj6lxjSqoPW5O0DnbXz"
ENV["OTEL_RESOURCE_ATTRIBUTES"] ||= "service.key=sk_tYtJUa4WweXXedj6lxjSqoPW5O0DnbXz,service.namespace=sophonz,service.version=1.0.0"

OpenTelemetry::SDK.configure do |c|
  c.service_name = ENV.fetch("OTEL_SERVICE_NAME", "my-rails-app")
  c.use_all
end

사전 요구 사항

  • Ruby 3.0+ 및 Rails 6.1+ (Rails 없이 순수 Ruby 앱에서도 동작합니다 — 아래 참고 사항 확인).
  • Sophonz 콘솔에 등록한 서비스와 그 서비스에 발급된 sk_... API 키.

젬 설치

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

TIP — API 키 발급

Sophonz 콘솔에 로그인해 서비스를 등록하고 발급된 sk_... 키를 복사하세요. 이 키는 테넌트 신원을 나타냅니다 — 아래 service.key 참고.

초기화 파일 추가

# config/initializers/opentelemetry.rb
require "opentelemetry/sdk"
require "opentelemetry/exporter/otlp"
require "opentelemetry/instrumentation/all"
 
OpenTelemetry::SDK.configure do |c|
  c.service_name = ENV.fetch("OTEL_SERVICE_NAME", "my-rails-app")
  c.use_all
end

c.use_all은 설치되어 있고 사용 가능한 모든 OpenTelemetry 계측 젬을 활성화합니다 — Gemfile에 opentelemetry-instrumentation-all이 있으면 Rails, Rack, ActiveRecord와, 이미 사용 중인 HTTP 클라이언트·백그라운드 잡·캐시 젬까지 하나하나 나열하지 않아도 모두 계측됩니다.

NOTE — 명시적 require는 의도된 것입니다

Rails는 Bundler.require로 Gemfile의 모든 항목을 자동으로 require하므로, 실제 Rails 앱에서는 위 require 줄이 없어도 초기화 파일이 동작합니다. 그럼에도 포함해 둔 이유는 (그리고 순수 Ruby 스크립트에서, 또는 이 젬들에 require: false를 설정한 경우에는 실제로 필요합니다) 앱이 어떻게 부팅되든 OpenTelemetry::SDK.configure가 OTLP 익스포터와 계측 클래스를 찾을 수 있도록 하기 위해서입니다.

환경 변수 구성

OTEL_SERVICE_NAME=my-rails-app
OTEL_EXPORTER_OTLP_ENDPOINT=https://in.sophonz.ai
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_HEADERS=authorization=sk_your_api_key
OTEL_RESOURCE_ATTRIBUTES=service.key=sk_your_api_key,service.namespace=my-project,deployment.environment.name=production
변수값설명
OTEL_SERVICE_NAME서비스 이름위 초기화 파일에서 ENV.fetch로도 직접 읽습니다. 콘솔에 등록한 서비스 이름과 일치해야 합니다 — 포털은 (project, service.name) 조합으로 텔레메트리를 등록된 서비스에 연결합니다.
OTEL_EXPORTER_OTLP_ENDPOINThttps://in.sophonz.ai기본 OTLP 엔드포인트. OTLP 익스포터가 여기서 /v1/traces를 파생시킵니다.
OTEL_EXPORTER_OTLP_PROTOCOLhttp/protobufopentelemetry-exporter-otlp가 로드되면 자동으로 읽습니다.
OTEL_EXPORTER_OTLP_HEADERSauthorization=sk_your_api_key모든 전송 요청에 HTTP 헤더로 포함됩니다.
OTEL_RESOURCE_ATTRIBUTESservice.key=sk_your_api_key,service.namespace=...,deployment.environment.name=...service.key는 컬렉터가 검사하는 테넌트 신원으로 필수입니다. service.namespace는 서비스들을 프로젝트로 묶고, deployment.environment.name은 환경을 표시합니다.

CAUTION — service.key는 필수입니다

컬렉터는 강제 모드로 동작합니다. 해석 가능한 service.key 리소스 속성이 없는 텔레메트리는 조용히 폐기됩니다. 애플리케이션은 계속 실행되고 예외도 발생하지 않지만, Sophonz에는 아무것도 나타나지 않습니다. 항상 OTEL_RESOURCE_ATTRIBUTES에 service.key를 포함하고, OTEL_EXPORTER_OTLP_HEADERS를 통해 같은 키를 authorization 헤더로도 전송하세요.

Rails 참고 사항

  • 컨트롤러와 뷰 스팬은 Rails가 이미 발생시키는 ActiveSupport::Notifications 이벤트를 기반으로 Rails 자체 계측이 만들어 줍니다 — 별도로 추가할 미들웨어가 없습니다.
  • ActiveRecord 쿼리 스팬은 c.use_all이 실행되면 pg, mysql2, sqlite3에서 바로 동작합니다.
  • Rails 밖에서: 순수 Ruby 스크립트나 서비스(Sinatra, 워커 프로세스, Rake 태스크)라면 부팅 시퀀스에서 가능한 한 일찍 동일한 OpenTelemetry::SDK.configure 블록을 호출하세요 — Rails 전용 요구 사항은 없으며 use_all도 동일하게 동작합니다.
  • 백그라운드 잡: Sidekiq이나 Resque를 사용한다면 (opentelemetry-instrumentation-all에 포함된) 해당 계측 젬이 같은 c.use_all 호출로 활성화되어 별도 설정 없이 잡 스팬이 나타납니다.

확인

환경 변수를 설정한 뒤 앱을 시작하세요.

OTEL_SERVICE_NAME=my-rails-app \
OTEL_EXPORTER_OTLP_ENDPOINT=https://in.sophonz.ai \
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
OTEL_EXPORTER_OTLP_HEADERS=authorization=sk_your_api_key \
OTEL_RESOURCE_ATTRIBUTES=service.key=sk_your_api_key,service.namespace=my-project,deployment.environment.name=production \
bin/rails server

OTLP 익스포터 젬이 로드되지 않았다면 SDK가 부팅 시 WARN -- : The otlp exporter cannot be configured - please add opentelemetry-exporter-otlp to your Gemfile를 로깅합니다 — Gemfile/require 설정에 문제가 있다는 유용한 신호입니다. 그 경고만 없다면 전송 실패는 조용히 일어납니다 — 경고 없이 정상 부팅됐다고 해서 텔레메트리가 도착했다는 보장은 없습니다. service.key가 잘못되었거나 없어도 정상 동작할 때와 똑같이 부팅되기 때문입니다. 요청을 조금 발생시킨 뒤 Sophonz 콘솔에서 등록한 서비스를 확인하세요.

TIP — 이제 시작입니다

이제 앱을 배포하세요. Sophonz가 실사용자가 겪는 문제를 포착하고, 당신의 앱은 스스로 진화합니다.