계측 항목

Apple SDK의 캡처 서비스가 각각 무엇을 수집하고 어떤 spz.type을 붙이는지, 기본 설치 여부와 플랫폼 제약을 정리합니다.

계측은 캡처 서비스가 담당합니다. 각 서비스는 시스템 API 하나를 스위즐링하거나 알림 하나를 구독하고, 만들어낸 텔레메트리에 spz.type 속성을 붙입니다. 어떤 서비스가 어떤 타입을 쓰는지가 곧 대시보드의 분류 기준입니다.

타입 체계

spz.type은 타입.하위타입 형태이며 하위타입은 없을 수 있습니다.

타입	의미
`perf`	구간이 얼마나 걸렸는지
`ux`	사용자 행동 또는 화면에 보이는 사건
`sys`	사용자 행동과 무관한 시스템 사건

NOTE — Android와 다른 점

속성 키(spz.type)와 상위 타입 이름은 Android와 같지만, Apple에는 state 타입이 없습니다. Android가 화면·네트워크·전원을 세션 상태 타임라인으로 기록하는 반면, Apple은 같은 정보를 스팬이나 스팬 이벤트로 남깁니다. 두 플랫폼의 데이터를 한 쿼리로 묶을 때 이 차이를 고려해야 합니다.

sys.ios.crash처럼 플랫폼 접두사가 붙는 값도 있습니다. Android의 sys.android.crash에 대응합니다.

기본 설치되는 캡처 서비스

서비스	`spz.type`	수집 내용	플랫폼
`URLSessionCaptureService`	`perf.network_request`	네트워크 요청마다 스팬. 이름은 `<METHOD> <경로>`	전체
`ViewCaptureService`	`ux.view` · `perf.ui_load`	화면 노출 구간과 첫 렌더링까지의 트리	iOS · tvOS
`TapCaptureService`	`ux.tap`	화면 탭마다 스팬 이벤트	iOS · tvOS
`WebViewCaptureService`	`ux.webview`	WebView가 URL을 로드하거나 실패할 때 스팬 이벤트	watchOS 제외
`LowMemoryWarningCaptureService`	`sys.low_memory`	메모리 경고 알림	전체
`LowPowerModeCaptureService`	`sys.low_power`	저전력 모드가 켜져 있던 구간을 스팬으로	전체

이 외에 AppInfoCaptureService와 DeviceInfoCaptureService가 항상 설치됩니다. 두 서비스는 신호를 만들지 않고 리소스 속성만 채웁니다 — SDK 버전, 앱 버전, OS, 기기 모델, 로캘, 디스크 여유 공간 등입니다. 끌 수 없습니다.

watchOS에서는 탭·화면·WebView 서비스가 기본 목록에서 아예 빠집니다.

URLSessionCaptureService는 SDK 자신의 업로드를 기록하지 않습니다. 시작 시점에 수집기 주소가 내부 목록에 등록되고 캡처에서 제외됩니다 — 그렇지 않으면 업로드마다 스팬이 생기고 그 스팬이 다음 업로드에 실려 또 스팬을 만듭니다.

화면 이름

ViewCaptureService는 나타난 뷰 컨트롤러의 이름을 app.screen.name으로 붙입니다. SwiftUI 앱은 화면마다 sophonzScreen(_:)을 붙여야 의미 있는 이름이 남습니다 — API를 참고하세요.

기본으로 꺼져 있는 서비스

서비스	`spz.type`	켜는 방법
`HangCaptureService`	`perf.thread_blockage`	`hang: true`
`PushNotificationCaptureService`	`sys.push_notification`	서비스 추가

행 감지는 CADisplayLink로 프레임을 감시하다가 메인 스레드가 멈춘 구간을 스팬으로 만들고, 샘플링한 백트레이스를 스팬 이벤트로 붙입니다. iOS와 tvOS에서만 동작합니다.

CAUTION — 디버거가 붙어 있으면 행 감지가 멈춥니다

디버거로 정지시킨 시간을 행으로 기록하지 않기 위해, 디버거가 붙어 있으면 서비스가 스스로 비활성화됩니다. 디버깅 중에 동작을 확인하려면 환경 변수 SPZAllowWatchdogInDebugger=1을 설정하세요.

크래시

크래시 수집은 캡처 서비스가 아니라 별도 옵션입니다.

try Sophonz.start(options: .withCollector(
  url: "https://in.sophonz.ai",
  appKey: "sk_…",
  crashReporter: .sophonz
))

값	동작
`.sophonz`	내장 KSCrash 기반 리포터 (기본값)
`.crashlytics`	Firebase Crashlytics의 크래시 데이터를 가져옴
`.none`	크래시 리포터를 설치하지 않음

크래시는 sys.ios.crash 로그로 기록됩니다.

MetricKit

MetricKit 진단 페이로드를 텔레메트리로 옮기는 서비스가 셋 있습니다. 옵션이나 빌더로 선택할 수 없고, 크래시 리포터 설정과 원격 설정에 따라 런타임에 설치됩니다.

서비스	`spz.type`
`MetricKitCrashCaptureService`	`sys.ios.crash`
`MetricKitHangCaptureService`	`perf.thread_blockage`
`MetricKitMetricsCaptureService`	`sys.ios.metrickit-metrics`

캡처 서비스가 만들지 않는 타입

다음 값들은 세션 엔진, SDK 시작 코드, 또는 직접 호출하는 API가 만듭니다.

값	출처
`ux.session`	세션 엔진
`sys.startup`	SDK 시작
`sys.breadcrumb`	`addBreadcrumb`
`sys.log`	로그 API
`sys.exception`	예외 기록 API
`sys.network_capture`	URLSession 서비스의 본문 수집 (원격 설정으로만 활성화)
`sys.internal`	SDK 자체 진단

전체 목록

`spz.type`	신호	생성 주체
`perf.network_request`	스팬	URLSession
`perf.ui_load`	스팬	View
`perf.thread_blockage`	스팬 · 스팬 이벤트 · 로그	Hang, MetricKit Hang
`ux.view`	스팬	View
`ux.session`	스팬	세션 엔진
`ux.tap`	스팬 이벤트	Tap
`ux.webview`	스팬 이벤트	WebView
`sys.startup`	스팬	SDK 시작
`sys.low_power`	스팬	LowPowerMode
`sys.low_memory`	스팬 이벤트	LowMemoryWarning
`sys.push_notification`	스팬 이벤트	PushNotification
`sys.breadcrumb`	스팬 이벤트	직접 호출
`sys.log`	로그	직접 호출
`sys.exception`	로그	직접 호출
`sys.network_capture`	로그	URLSession 본문 수집
`sys.ios.crash`	로그	크래시 리포터, MetricKit
`sys.ios.metrickit-metrics`	로그	MetricKit Metrics
`sys.internal`	로그	SDK 자체 진단

서비스별 옵션은 설정에서 다룹니다.