설치

공식 OpenTelemetry Erlang/Elixir 패키지를 추가하고 OTLP 익스포터를 설정한 뒤, 환경 변수로 Phoenix 또는 순수 Elixir 앱에서 Sophonz로 트레이스를 전송하세요.

빠른 시작

아래에서 수집기 URL, 프로젝트, 앱, 버전, 앱 키를 입력하면 그 값으로 스니펫이 생성됩니다. 탭은 따로 없습니다. 고급 옵션은 "고급 옵션" 토글 뒤에 있습니다.

# mix.exs — deps에 추가합니다
{:opentelemetry, "~> 1.7"},
{:opentelemetry_api, "~> 1.5"},
{:opentelemetry_exporter, "~> 1.10"},
{:opentelemetry_phoenix, "~> 2.0"},
{:opentelemetry_bandit, "~> 0.3"}, # Phoenix 1.7+ 기본 어댑터
# {:opentelemetry_cowboy, "~> 1.0"}, # 아직 Cowboy를 쓴다면 이쪽을 대신 사용하세요
{:opentelemetry_ecto, "~> 1.2"}

# config/runtime.exs
config :opentelemetry,
  span_processor: :batch,
  traces_exporter: :otlp,
  resource: %{
    service: %{
      name: "next-sample",
      namespace: "sophonz",
      version: "1.0.0",
      key: "sk_tYtJUa4WweXXedj6lxjSqoPW5O0DnbXz"
    },
    deployment: %{environment: %{name: "production"}}
  }

config :opentelemetry_exporter,
  otlp_endpoint: "https://in.sophonz.ai",
  otlp_headers: [{"authorization", "sk_tYtJUa4WweXXedj6lxjSqoPW5O0DnbXz"}],
  otlp_protocol: :http_protobuf

# lib/my_app/application.ex — start/2에서, 슈퍼비전 트리가 시작되기 전에
OpentelemetryPhoenix.setup(adapter: :bandit)
OpentelemetryEcto.setup([:my_app, :repo])

사전 요구 사항

• Elixir 1.15+ / OTP 25+.
• Sophonz 콘솔에 등록한 서비스와 그 서비스에 발급된 sk_... API 키.

의존성 추가

# mix.exs
def deps do
  [
    {:opentelemetry, "~> 1.7"},
    {:opentelemetry_api, "~> 1.5"},
    {:opentelemetry_exporter, "~> 1.10"},
 
    # Phoenix 앱: 스택에 맞는 계측 패키지를 선택하세요
    {:opentelemetry_phoenix, "~> 2.0"},
    {:opentelemetry_bandit, "~> 0.3"}, # Phoenix 1.7+ 기본 어댑터
    # {:opentelemetry_cowboy, "~> 1.0"}, # 아직 Cowboy를 쓴다면 이걸 대신 사용
    {:opentelemetry_ecto, "~> 1.2"}
  ]
end

OTLP 익스포터 설정

config/runtime.exs에서 (릴리스를 사용하지 않는다면 config/config.exs에서) 배치 OTLP 파이프라인을 선택합니다.

# config/runtime.exs
config :opentelemetry,
  span_processor: :batch,
  traces_exporter: :otlp

opentelemetry_exporter 자체는 추가 설정이 필요 없습니다 — OS 환경에서 OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_PROTOCOL, OTEL_EXPORTER_OTLP_HEADERS를 자동으로 읽습니다. 배포 시점에 이 값들(그리고 OTEL_RESOURCE_ATTRIBUTES)을 설정하세요 — 아래를 참고하세요.

계측 연결

Application.start/2에서, 슈퍼바이저 트리가 시작되기 전에(리포지토리가 먼저 존재해야 하는 Ecto는 시작 직후에) 연결합니다.

# lib/my_app/application.ex
def start(_type, _args) do
  OpentelemetryPhoenix.setup(adapter: :bandit) # 또는 :cowboy2
  OpentelemetryEcto.setup([:my_app, :repo])
 
  children = [
    # ... 기존 children
  ]
 
  Supervisor.start_link(children, strategy: :one_for_one, name: MyApp.Supervisor)
end

OpentelemetryPhoenix.setup/1과 OpentelemetryEcto.setup/1은 Phoenix와 Ecto가 이미 발생시키는 :telemetry 핸들러에 연결됩니다 — 별도로 작성해야 할 스팬 생성 코드는 없습니다.

환경 변수 구성

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.name=my-elixir-service,service.key=sk_your_api_key,service.namespace=my-project,deployment.environment.name=production

Phoenix와 Ecto 참고 사항

• 어댑터가 중요합니다: Phoenix 앱이 Bandit을 사용한다면(Phoenix 1.7부터 기본값) OpentelemetryPhoenix.setup/1에 adapter: :bandit을 전달하고, 아직 Cowboy라면 adapter: :cowboy2를 전달하세요. 그에 맞춰 opentelemetry_bandit 또는 opentelemetry_cowboy 의존성을 추가합니다.
• Ecto: OpentelemetryEcto.setup([:my_app, :repo])는 리포지토리의 telemetry 프리픽스를 받습니다 — :telemetry.attach에 전달하는 것과 같은 원자 목록으로, 보통 Ecto.Repo의 :telemetry_prefix 설정 값입니다(MyApp.Repo라는 이름의 리포지토리라면 기본값은 [:my_app, :repo]).
• LiveView: opentelemetry_phoenix는 컨트롤러 액션뿐 아니라 LiveView의 mount/handle_event telemetry 이벤트도 계측하므로 별도 패키지가 필요 없습니다.

확인

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

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.name=my-elixir-service,service.key=sk_your_api_key,service.namespace=my-project,deployment.environment.name=production \
mix phx.server

전송 실패는 앱을 크래시시키지 않고 OTLP 익스포터가 :error 레벨로 로깅하므로, 정상적으로 부팅됐다고 해서 텔레메트리가 도착했다는 보장은 없습니다 — service.key가 잘못되었거나 없어도 정상 동작할 때와 똑같이 부팅되며, 다만 아무것도 보이지 않을 뿐입니다. 요청을 조금 발생시킨 뒤 Sophonz 콘솔에서 등록한 서비스를 확인하세요.