Android SDK

OpenTelemetry 기반 Android SDK의 구성과 수집 범위, 문서를 읽는 순서를 안내합니다.

Sophonz Android SDK는 OpenTelemetry 위에 만들어졌습니다. 크래시와 ANR, 네트워크 요청, 화면 전환, 앱 시작 시간을 자동으로 수집하고, 같은 트레이스로 백엔드까지 이어 붙입니다. 앱 코드에서 하는 일은 SDK를 시작하는 한 줄이며, 나머지는 Gradle 플러그인이 빌드 시점에 처리합니다.

구성

설치하면 세 가지가 함께 동작합니다.

구성 요소역할
Gradle 플러그인SDK 의존성 추가, 바이트코드 계측 삽입, 설정 파일을 SDK에 새김
SDK텔레메트리 수집과 OTLP 전송
계측 모듈각 계측이 별도 모듈. 기본 포함되는 것과 직접 추가하는 것으로 나뉨

계측이 모듈로 나뉜 덕분에 필요 없는 것을 빼거나, 기본에 없는 것을 골라 넣을 수 있습니다. 어떤 모듈이 무엇을 수집하는지는 계측 항목에 정리했습니다.

수집 범위

자동으로 수집되는 것을 큰 갈래로 보면 다음과 같습니다.

  • 크래시 — JVM 예외와 네이티브 시그널, 그리고 프로세스가 죽은 뒤 다음 실행에서 읽는 종료 정보
  • 성능 — 앱 시작 트레이스, 화면 로드, ANR, 열 상태
  • 네트워크 — OkHttp와 HttpURLConnection 요청, 필요 시 본문
  • 사용자 경험 — 화면 전환, 탭, WebView 페이지 로드
  • 상태 — 세션 동안의 화면·네트워크·전원 상태 타임라인

각 항목의 기본 활성화 여부와 켜고 끄는 방법은 계측 항목에 있습니다.

백엔드와 연결

SDK는 요청에 W3C traceparent 헤더를 붙일 수 있습니다. 이 헤더가 있으면 앱에서 시작된 트레이스가 백엔드 스팬까지 하나로 이어져, 느린 화면의 원인이 앱인지 서버인지를 같은 화면에서 판단할 수 있습니다.

기본값은 꺼짐입니다. networking.enable_traceparent_injection으로 켜고, traceparent_only_allow_domains로 대상 도메인을 좁히세요. 통제 범위 밖의 서드파티 API까지 헤더를 보낼 이유는 없습니다.

데이터 형식

수집한 데이터는 OpenTelemetry 시맨틱 컨벤션을 따르며 OTLP로 전송됩니다. RUM 전용 포맷을 따로 정의하지 않았으므로, 다른 OTel 백엔드로 같은 데이터를 함께 보내거나 옮길 수 있습니다. 익스포터를 직접 추가하는 방법은 API 레퍼런스에 있습니다.

읽는 순서

  1. 설치 — 플러그인 적용, 저장소 인증, SDK 시작
  2. 설정 — 수집기 주소와 앱 키, 수집 항목 조정
  3. 계측 항목 — 무엇이 수집되고 어떻게 분류되는지
  4. API 레퍼런스 — 직접 기록을 남기거나 맥락을 덧붙일 때

NOTE — 이전 버전 문서

Nexus 저장소로 배포되던 v1.0 · v1.1 · Vanilla SDK 문서는 그대로 남겨 두었습니다. 이 문서가 설명하는 SDK와는 저장소와 API가 다르므로, 두 문서를 섞어 참고하지 마세요.