계측 항목

Android SDK가 내장한 자동 계측이 각각 무엇을 수집하고 어떤 spz.type을 붙이는지, 기본 활성화 여부와 켜고 끄는 방법을 정리합니다.

Android SDK는 계측을 모듈 단위로 나눠 담고 있습니다. 각 계측은 안드로이드 API 하나 또는 프레임워크 하나를 감싸고, 생성한 텔레메트리에 spz.type 속성을 붙입니다. 대시보드와 세션 타임라인이 이 값으로 데이터를 분류하므로, 어떤 계측이 어떤 타입을 사용하는지가 곧 쿼리 기준이 됩니다.

타입 체계

spz.type은 타입.하위타입 형태입니다. 상위 타입은 넷입니다.

타입	의미	적용 대상
`perf`	구간이 얼마나 걸렸는지	스팬
`ux`	사용자 행동 또는 화면에 보이는 사건	스팬 · 로그 · 스팬 이벤트
`sys`	사용자 행동과 무관한 시스템 사건	스팬 · 로그 · 스팬 이벤트
`state`	세션 동안 값이 바뀌는 상태 타임라인	상태

성능

계측	`spz.type`	기본값	활성화 조건	추가 요건
앱 시작 트레이스	`perf`	켜짐	—	—
화면 로드	`perf.ui_load`	켜짐	`automatic_data_capture.ui_load_tracing_disabled`	—
ANR (스레드 블로킹)	`perf.thread_blockage`	켜짐	`automatic_data_capture.anr_info`	—
열 상태	`perf.thermal_state`	켜짐	원격 설정	API 29 이상
프레임 부드러움	`perf.smoothness`	꺼짐	원격 설정	API 24 이상
화면 로드 상세	`perf.screen_load`	꺼짐	원격 설정	API 24 이상
OkHttp	`perf.network_request`	켜짐	바이트코드 `okhttpEnabled`	OkHttp
HttpURLConnection (경량)	`perf.network_request`	켜짐	`networking.enable_huc_lite_instrumentation`	—
HttpURLConnection (전체)	`perf.network_request`	꺼짐	`networking.enable_native_monitoring`	아티팩트 별도 추가

앱 시작 트레이스는 process-init, sophonz-init, activity-init, app-ready로 이어지는 트리를 만듭니다. 하위 스팬과 속성은 addStartupTraceChildSpan, addStartupTraceAttribute로 직접 추가할 수 있습니다.

두 HttpURLConnection 계측은 동시에 동작하지 않습니다. 전체 계측을 켜면 경량 계측이 물러납니다.

사용자 경험

계측	`spz.type`	기본값	활성화 조건	추가 요건
화면 (Activity)	`ux.view`	켜짐	`view_config.enable_automatic_activity_capture`	—
탭 (View)	`ux.tap`	켜짐	바이트코드 `onClickEnabled` · `onLongClickEnabled`	—
탭 (Compose)	`ux.tap`	꺼짐	`compose.capture_compose_onclick`	Compose, 아티팩트 별도 추가
WebView	`ux.webview`	켜짐	`webview.enable` + 바이트코드 `webviewOnPageStartedEnabled`	—

탭 좌표 수집은 taps.capture_coordinates로 켜며 기본값은 꺼짐입니다. Compose 탭은 테스트 태그로 요소를 식별하므로, 태그가 없는 요소는 이름 없이 기록됩니다.

WebView는 onPageStarted 시점의 URL을 남깁니다. 쿼리 파라미터는 webview.capture_query_params로, 프래그먼트는 webview.fragment_capture(keep · redact · remove)로 조정합니다.

시스템

계측	`spz.type`	기본값	활성화 조건	추가 요건
JVM 크래시	`sys.android.crash`	켜짐	`crash_handler.enabled`	—
네이티브 크래시	`sys.android.native_crash`	켜짐	`ndk_enabled`	NDK
앱 종료 정보	`sys.exit`	켜짐	`app_exit_info.aei_enabled`	API 30 이상
푸시 알림 (FCM)	`sys.push_notification`	꺼짐	바이트코드 `firebasePushNotificationsEnabled`	Firebase Messaging
절전 모드	`sys.low_power`	켜짐	`automatic_data_capture.power_save_mode_info`	—
네트워크 연결 변화	`sys.network_status`	켜짐	`automatic_data_capture.network_connectivity_info`	—
요청·응답 본문	`sys.network_capture`	원격 규칙에 따름	—	—

앱 종료 정보는 안드로이드의 ApplicationExitInfo 기록을 그대로 옮깁니다. 종료 사유, 중요도, 메모리 사용량과 함께 ANR·네이티브 트레이스가 포함됩니다. 프로세스가 이미 죽은 뒤 다음 실행에서 읽어오는 방식이므로, 크래시 계측이 놓친 종료를 메웁니다.

FCM은 모듈이 기본 포함되어 있으나 바이트코드 계측을 켜지 않으면 아무것도 수집하지 않습니다. 제목과 본문 같은 개인정보는 capture_fcm_pii_data를 켠 경우에만 담깁니다.

본문 수집은 원격 규칙과 일치하는 요청에만 적용됩니다. 로컬 설정만으로는 켜지지 않습니다.

상태 타임라인

세션이 진행되는 동안 값이 바뀌는 항목입니다. 스팬이 아니라 구간으로 기록되어, 세션 타임라인에서 다른 텔레메트리와 겹쳐 볼 수 있습니다.

상태	값	기본값
화면	현재 화면 이름	켜짐
네트워크	`wifi` · `wan` · `not_reachable` 등	켜짐
전원	절전 모드 여부	켜짐

화면 상태는 Activity 전환만으로도 기록되지만, Jetpack Navigation을 쓰는 앱은 androidx-navigation 연동을 붙여야 목적지 단위로 정확해집니다.

텔레메트리를 만들지 않는 계측

메모리 누수 탐지는 스팬이나 로그를 만들지 않습니다. 회수되지 않은 Activity·Fragment 인스턴스 목록을 세션 속성으로 남깁니다. 기본값은 꺼짐이며 원격 설정으로만 켭니다. API 23 이상이 필요하고, Fragment까지 보려면 androidx.fragment가 있어야 합니다.

추가 계측

다음은 SDK에 기본 포함되지 않습니다. 필요한 경우 아티팩트를 직접 추가합니다.

아티팩트	역할
`sophonz-android-instrumentation-androidx-navigation`	Jetpack Navigation의 목적지 변화를 화면 상태에 반영
`sophonz-android-instrumentation-compose-tap`	Compose 요소의 탭 수집
`sophonz-android-instrumentation-huc`	HttpURLConnection 전체 계측

androidx-navigation은 화면마다 rememberObservedNavController 또는 rememberObservedBackStack으로 연결합니다. 자동으로 적용되지 않습니다.

NOTE — 원격 설정으로 결정되는 항목

표에서 활성화 조건이 "원격 설정"인 항목은 sophonz-config.json으로 켤 수 없습니다. 서버에서 내려주는 설정이 결정하며, 표의 기본값은 원격 설정이 없을 때 적용되는 값입니다.

전부 끄기

바이트코드 계측 전체를 한 번에 끕니다.

sophonz {
  bytecodeInstrumentation {
    enabled.set(false)
  }
}

특정 패키지만 제외하려면 classIgnorePatterns를 사용합니다. 설정 방법은 설정에서 다룹니다.