iOS/tvOS/macOS 애플리케이션 데이터 수집
애플리케이션 데이터가 Guance에 수집되면 Guance 콘솔에서 사용자 정의 시나리오를 구성하고 이상 탐지 이벤트를 설정할 수 있습니다.
데이터 유형
Guance의 실제 사용자 모니터링(RUM)은 여섯 가지 데이터 유형을 포함합니다.
iOS SDK가 직접 보고하는 RUM 데이터 유형은 view, resource, error, long_task, action이며, session은 세션 차원 데이터로 SDK가 보고한 RUM 데이터를 기반으로 집계되어 생성됩니다.
| 유형 |
설명 |
| session |
사용자 세션 정보 기록으로, 현재 세션에서는 세션 차원의 사용자 페이지, 리소스, 작업, 오류, 긴 작업 관련 방문 데이터를 기반으로 합니다. |
| view |
사용자가 모바일 애플리케이션의 페이지를 방문할 때마다 view 기록이 생성됩니다. 사용자가 동일한 페이지에 머무르는 동안 리소스, 긴 작업, 오류 및 작업 기록은 view_id 속성을 통해 관련 RUM view에 연결됩니다. |
| resource |
사용자가 페이지를 방문할 때 로드되는 리소스 정보 기록입니다. |
| error |
모바일 애플리케이션에서 발생한 예외 또는 크래시입니다. |
| long_task |
애플리케이션에서 메인 스레드를 지정된 기간 임계값 이상 차단하는 모든 작업에 대해 긴 작업 이벤트가 생성됩니다. |
| action |
모바일 애플리케이션의 사용자 활동(애플리케이션 시작, 클릭, 스와이프, 뒤로 가기 등)을 기록합니다. 각 작업에는 고유한 action_id가 첨부됩니다. |
전역 속성
RUM의 시나리오 구성과 이벤트 알림은 모두 아래 전역 속성을 통해 조회할 수 있습니다.
SDK 속성
| 필드 |
유형 |
설명 |
sdk_name |
string |
수집기 이름, 고정 이름:
df_macos_rum_sdk
df_ios_rum_sdk
df_tvos_rum_sdk
df_android_rum_sdk |
sdk_version |
string |
수집기 버전 정보 |
sdk_pkg_info |
object |
SDK 패키지 정보 |
애플리케이션 속성
| 필드 |
유형 |
설명 |
app_id |
string |
필수, 사용자 방문 애플리케이션 고유 ID 식별자이며, Guance 콘솔에서 모니터링을 생성할 때 자동으로 생성됩니다. |
application_uuid |
string |
애플리케이션 UUID, iOS SDK는 기본 Mach-O UUID에서 가져옵니다. |
env |
string |
필수, 환경 필드입니다. 속성 값: prod/gray/pre/common/local. 그중: prod: 프로덕션 환경 gray: 그레이 환경 pre: 사전 출시 환경 common: 일상 환경 local: 로컬 환경 |
version |
string |
필수, 버전 번호입니다. |
service |
string |
선택 사항, 소속 비즈니스 또는 서비스 이름입니다. 고정 이름:
df_rum_ios
df_rum_tvos
df_rum_android
df_rum_windows
df_rum_linux |
사용자 및 세션 속성
| 필드 |
유형 |
설명 |
userid |
string |
로그인하지 않은 사용자는 임의 UUID를 userid로 사용하고, 로그인한 사용자는 애플리케이션 백엔드에서 생성된 사용자 ID를 사용합니다. |
user_name |
string |
선택 사항, 사용자 이름입니다. |
user_email |
string |
선택 사항, 사용자 이메일입니다. |
session_id |
string |
세션 ID이며, 15분 이상 작업이 없으면 새 session_id가 생성됩니다. |
session_type |
string |
세션 유형입니다. 참조 값: user & synthetics user: RUM 기능에서 생성된 데이터, synthetics: headless 신서틱 테스트에서 생성된 데이터. |
session_start_reason |
string |
SDK 1.6.8+: RUM 이벤트에서 세션이 시작되거나 갱신된 이유입니다. sdk_init: SDK 초기화, inactivity_timeout: 세션 무작업 제한 시간 초과, max_duration: 세션 최대 지속 시간 도달, sampling_changed: 샘플링 설정 변경, unknown: 원인 알 수 없음. 이 필드는 세션 컨텍스트에 속하며, SDK가 Session 데이터를 별도로 보고함을 의미하지 않습니다. |
is_signin |
boolean |
등록 사용자인지 여부, 속성 값: T & F. |
session_has_replay |
boolean |
현재 세션이 Session Replay 데이터와 연결되어 있는지 여부입니다. Session Replay 관련 기능을 활성화하면 View, Resource, Error, Long Task, Action에 이 필드를 기록할 수 있습니다. |
visitor_id |
string |
SDK 1.6.8+: 유효 방문자 식별자(Visitor ID) 설정을 활성화한 후 연결되는 SDK 관리 익명 식별자이며, 로그인 사용자 ID와 다릅니다. 방문자 식별자 Visitor ID를 참조하세요. |
custom_keys |
string |
RUM 사용자 정의 속성 키 목록 |
기기 및 해상도 속성
| 필드 |
유형 |
설명 |
device |
string |
모바일 기기 제조사 |
model |
string |
모바일 기기 모델 |
device_uuid |
string |
모바일 기기 고유 ID이며, UIDevice.identifierForVendor를 사용하여 생성합니다. |
os |
string |
운영 체제 정보 |
os_version |
string |
운영 체제 버전 |
os_version_major |
string |
운영 체제 주 버전 |
screen_size |
string |
화면 해상도 |
arch |
string |
CPU 아키텍처(예: arm64, arm64e, x86_64) |
지리 및 네트워크 속성
| 필드 |
유형 |
설명 |
ip |
string |
사용자 방문 IP 주소 |
isp |
string |
통신사 |
network_type |
string |
네트워크 연결 유형, 속성 값 참조: wifi & 2g & 3g & 4g & 5g & unknown(알 수 없는 네트워크) & unreachable(네트워크 사용 불가) |
country |
string |
국가 |
country_iso_code |
string |
국가 iso_code |
province |
string |
도 |
city |
string |
도시 |
사용자 정의 속성
전역 속성 외에도 사용자 정의 속성(SDK는 사용자가 사용자 정의 tag 데이터를 추가하는 것을 지원합니다)을 통해 시나리오를 구성하고 이벤트 알림을 설정할 수 있습니다. 사용자 정의 속성은 전역 속성이 아니며, 이를 통해 사용자가 애플리케이션을 방문하는 전체 과정을 추적하고, 사용자에게 영향을 준 방문 상황을 파악 및 발견하며, 사용자 방문 성능을 모니터링할 수 있습니다.
기타 데이터 유형 속성
Session
Session은 세션 차원 데이터로, 일반적으로 서버 측에서 SDK가 보고한 RUM 데이터를 기반으로 생성하거나 집계하며, iOS SDK가 단독으로 직접 보고하는 measurement가 아닙니다.
속성
| 필드 |
유형 |
설명 |
session_id |
string |
세션 ID |
session_type |
string |
세션 유형입니다. 참조 값: user & synthetics user: RUM 기능에서 생성된 데이터, synthetics: headless 신서틱 테스트에서 생성된 데이터. |
session_referrer |
string |
세션 소스입니다. 일반적으로 소스를 기록한 페이지 주소입니다. |
session_first_view_id |
string |
현재 세션의 첫 번째 페이지 view_id |
session_first_view_name |
string |
현재 세션의 첫 번째 페이지 URL |
session_last_view_id |
string |
현재 세션에서 마지막으로 방문한 페이지의 view_id |
session_last_view_name |
string |
현재 세션에서 마지막으로 방문한 페이지의 URL |
통계 메트릭
| 필드 |
유형 |
설명 |
time_spent |
number(ns) |
현재 세션 지속 시간 |
session_view_count |
number |
현재 세션과 연결된 view_id 개수 |
session_error_count |
number |
현재 세션에서 발생한 오류 개수 |
session_resource_count |
number |
현재 세션에서 로드한 리소스 개수 |
session_action_count |
number |
현재 세션의 사용자 작업 횟수 |
session_long_task_count |
number |
현재 세션에서 발생한 긴 작업 횟수 |
View
속성
| 필드 |
유형 |
설명 |
view_id |
string |
페이지를 방문할 때마다 생성되는 고유 ID |
view_referrer |
string |
페이지 소스, 페이지의 상위 |
view_name |
string |
페이지 이름 |
session_has_replay |
boolean |
현재 View가 속한 세션이 Session Replay 데이터와 연결되어 있는지 여부 |
app_state |
string |
SDK 1.6.8+: 로딩 시작 지점(제공되지 않으면 View 시작으로 대체)부터 현재 스냅샷 이벤트 시간까지의 포그라운드/백그라운드 이력을 기반으로 애플리케이션 상태를 계산합니다. 값: foreground(포그라운드만), background(백그라운드만), foreground_and_background(포그라운드와 백그라운드를 모두 거침), unknown(이력 누락 또는 구간 유효하지 않음) |
메트릭
| 필드 |
유형 |
설명 |
loading_time |
number(ns) |
페이지 로딩 시간 |
interaction_to_next_view_time |
number(ns) |
SDK 1.6.8+: 현재 View 시작 시간에서 동일 Session의 바로 이전 View 내에서 가장 최근의 적격 Action 시작 시간을 뺀 값입니다. 기본적으로 click을 매칭하며 간격은 [0,3초]입니다. 적격 Action이 없거나 데이터가 필터링되었거나 폴백 View에 속한 경우에는 나타나지 않으며, Session을 넘어 연결하지 않습니다. 누락은 0과 같지 않으며, 유효한 0 소요 시간은 보고할 수 있습니다. 매칭 규칙 및 예시를 참조하세요. |
network_settled_time |
number(ns) |
SDK 1.6.8+: 초기 요청의 가장 늦은 유효 종료 시간에서 View 시작 시간을 뺀 값입니다(로딩 시작 지점이 아님). 기본적으로 View 시작 후 [0,100ms] 내에 시작된 요청을 대상으로 하며, 네트워크가 100ms 동안 유휴 상태가 되기를 기다리는 것이 아닙니다. 완료된 배치에서는 결과를 생성하고 갱신할 수 있으며, 이후 View 스냅샷에 현재 값이 포함됩니다. 유효한 요청 구간이 없거나, 데이터가 필터링되었거나, 구간이 백그라운드를 가로지르거나, 상태 이력이 없거나, 폴백 View에 속한 경우에는 나타나지 않습니다. 누락은 0과 같지 않으며, 유효한 0 소요 시간은 보고할 수 있습니다. 매칭 규칙 및 예시를 참조하세요. |
time_spent |
number(ns) |
페이지 체류 시간 |
is_active |
boolean |
사용자가 아직 활성 상태인지 여부, 참조 값: true & false |
session_sample_rate |
number |
RUM Session 샘플링 비율 |
session_on_error_sample_rate |
number |
RUM Session 샘플링에 선정되지 않았을 때 오류 발생 후 추가 샘플링하는 비율 |
session_replay_sample_rate |
number |
Session Replay 샘플링 비율이며, Session Replay 관련 기능을 활성화한 후 나타납니다. |
session_replay_on_error_sample_rate |
number |
오류 발생 후 Session Replay를 추가 샘플링하는 비율이며, Session Replay 관련 기능을 활성화한 후 나타납니다. |
sampled_for_error_session |
boolean |
현재 Session이 오류 샘플링 정책으로 샘플링되었는지 여부 |
sampled_for_error_replay |
boolean |
현재 Session Replay가 오류 샘플링 정책으로 샘플링되었는지 여부 |
session_error_timestamp |
number(ns) |
오류 샘플링이 적중했을 때의 오류 발생 시간 |
session_replay_stats |
object |
현재 View와 연결된 Session Replay 통계 정보 |
통계 메트릭
| 필드 |
유형 |
설명 |
view_error_count |
number |
페이지를 로드할 때마다 발생한 오류 횟수 |
view_resource_count |
number |
페이지를 로드할 때마다 요청한 리소스 개수 |
view_long_task_count |
number |
페이지를 로드할 때마다 발생한 긴 작업 개수 |
view_action_count |
number |
페이지 조회 과정에서의 작업 횟수 |
view_update_time |
number |
View 업데이트 횟수 |
view_long_task_rate |
number |
View 기간 동안 긴 작업 소요 시간 비율 |
모니터링 메트릭
| 필드 |
유형 |
설명 |
cpu_tick_count |
number |
선택 사항, 해당 페이지의 CPU 틱 횟수 |
cpu_tick_count_per_second |
number |
선택 사항, 초당 평균 CPU 틱 횟수 |
fps_avg |
number |
선택 사항, 페이지의 평균 초당 프레임 수 |
fps_mini |
number |
선택 사항, 페이지의 최소 초당 프레임 수 |
memory_avg |
number |
선택 사항, 페이지 메모리 사용량 평균값 |
memory_max |
number |
선택 사항, 페이지 메모리 최대값 |
Resource
View 속성
| 필드 |
유형 |
설명 |
view_id |
string |
페이지를 방문할 때마다 생성되는 고유 ID |
view_referrer |
string |
페이지 소스, 페이지의 상위 |
view_name |
string |
페이지 이름 |
Action 속성
| 필드 |
유형 |
설명 |
action_id |
string |
사용자가 페이지를 조작할 때 생성되는 고유 ID |
action_name |
string |
작업 이름 |
action_type |
string |
작업 유형(콜드/핫 시작, click 클릭 등 작업) |
Resource 속성
| 필드 |
유형 |
설명 |
resource_url |
string |
리소스 URL |
resource_url_host |
string |
리소스 URL의 도메인 부분 |
resource_url_path |
string |
리소스 URL의 path 부분 |
resource_url_query |
string |
리소스 URL의 query 부분 |
resource_url_path_group |
string |
리소스 URL의 path 그룹 |
resource_type |
string |
리소스 카테고리 |
resource_method |
string |
리소스 요청 방식 |
resource_status |
string |
리소스 요청이 반환한 상태 값 |
resource_status_group |
string |
리소스 요청이 반환한 상태 그룹 값 |
resource_host_ip |
string |
리소스 URL 액세스 대상 IP |
resource_id |
string |
리소스 요청 고유 ID |
response_connection |
string |
응답 헤더 Connection 값 |
response_content_type |
string |
응답 헤더 Content-Type 값 |
response_content_encoding |
string |
응답 헤더 Content-Encoding 값 |
span_id |
string |
트레이스와 연결된 span id |
trace_id |
string |
트레이스와 연결된 trace id |
session_has_replay |
boolean |
현재 Resource가 속한 세션이 Session Replay 데이터와 연결되어 있는지 여부 |
app_state |
string |
SDK 1.6.8+: 수집 측에서 정규화한 요청 시작부터 종료까지의 구간 내 포그라운드/백그라운드 이력을 기반으로 애플리케이션 상태를 계산합니다. 값: foreground(포그라운드만), background(백그라운드만), foreground_and_background(포그라운드와 백그라운드를 모두 거침), unknown(이력 누락 또는 구간 유효하지 않음) |
메트릭
| 필드 |
유형 |
설명 |
resource_size |
number |
리소스 크기, 기본 단위: byte |
resource_request_size |
number |
리소스 요청 크기, 기본 단위: byte |
resource_dns |
number(ns) |
리소스 로딩 DNS 조회 시간 계산 방식: domainLookupEnd - domainLookupStart |
resource_tcp |
number(ns) |
리소스 로딩 TCP 연결 시간 계산 방식: connectEnd - connectStart |
resource_ssl |
number(ns) |
리소스 로딩 SSL 연결 시간 계산 방식: connectEnd - secureConnectStart |
resource_ttfb |
number(ns) |
리소스 로딩 요청 응답 시간 계산 방식: responseStart - requestStart |
resource_trans |
number(ns) |
리소스 로딩 콘텐츠 전송 시간 계산 방식: responseEnd - responseStart |
resource_first_byte |
number(ns) |
리소스 로딩 첫 패킷 시간 계산 방식: responseStart - domainLookupStart |
duration |
number(ns) |
리소스 로딩 시간 계산 방식: duration(responseEnd-startTime) |
resource_dns_time |
object |
DNS 단계 소요 시간, 구조는 {start, duration} |
resource_connect_time |
object |
TCP 연결 단계 소요 시간, 구조는 {start, duration} |
resource_first_byte_time |
object |
첫 패킷 단계 소요 시간, 구조는 {start, duration} |
resource_ssl_time |
object |
SSL 단계 소요 시간, 구조는 {start, duration} |
resource_download_time |
object |
다운로드 단계 소요 시간, 구조는 {start, duration} |
resource_redirect_time |
object |
리다이렉트 단계 소요 시간, 구조는 {start, duration} |
resource_http_protocol |
string |
리소스 요청에 사용된 네트워크 프로토콜 |
resource_connection_reuse |
boolean |
리소스 요청이 연결을 재사용했는지 여부 |
request_header |
string |
리소스 요청 헤더 |
response_header |
string |
리소스 응답 헤더 |
네트워크 스냅샷
| 필드 |
유형 |
설명 |
network_available |
boolean |
Resource 시작 시 네트워크 사용 가능 여부 |
network_signal_strength |
number |
SDK 1.6.9부터 지원합니다. Resource 수집 시작 시의 시스템 링크 품질이며, 다음과 같이 매핑됩니다: 0 = unknown(알 수 없음), 1 = minimal(낮음), 2 = moderate(보통), 3 = good(양호). |
network_signal_strength는 iOS 26.0, tvOS 26.0, macOS 26.0 이상 시스템에서만 지원됩니다. 지원되지 않거나 아직 네트워크 상태를 얻지 못한 경우에는 이 필드를 보고하지 않습니다. 해당 값은 링크 품질 등급을 나타내며, RSSI, dBm 또는 시스템 신호 막대 수를 의미하지 않습니다.
Error
View 속성
| 필드 |
유형 |
설명 |
view_id |
string |
페이지를 방문할 때마다 생성되는 고유 ID |
view_referrer |
string |
페이지 소스, 페이지의 상위 |
view_name |
string |
페이지 이름 |
Action 속성
| 필드 |
유형 |
설명 |
action_id |
string |
사용자가 페이지를 조작할 때 생성되는 고유 ID |
action_name |
string |
작업 이름 |
Error 속성
| 필드 |
유형 |
설명 |
error_source |
string |
오류 소스, 참조 값: logger & network |
error_type |
string |
오류 유형 logger error type: anr_error | ios_crash network error type: network_error |
error_situation |
string |
오류 발생 시의 애플리케이션 상태, 참조 값: startup(시작 시), run(실행 중), background(백그라운드), unknown(알 수 없음). SDK 1.6.9부터 자동 수집된 ANR은 보고 시점의 상태가 아니라 지연이 시작된 시점의 상태를 유지합니다. |
session_has_replay |
boolean |
현재 Error가 속한 세션이 Session Replay 데이터와 연결되어 있는지 여부 |
type=network인 경우 다음 Network Error 속성이 추가됩니다.
| 필드 |
유형 |
설명 |
resource_id |
string |
리소스 요청 고유 ID |
resource_status |
string |
리소스 요청이 반환한 상태 값 |
resource_url |
string |
리소스 URL |
resource_url_host |
string |
리소스 URL의 도메인 부분 |
resource_url_path |
string |
리소스 URL의 path 부분 |
resource_url_path_group |
string |
리소스 URL의 path 그룹 |
resource_status_group |
string |
리소스 요청이 반환한 상태 그룹 값 |
resource_method |
string |
리소스 요청 방식 |
Error 모니터링 속성
| 필드 |
유형 |
설명 |
memory_total |
string |
선택 사항, 총 메모리 |
memory_use |
number |
선택 사항, 메모리 사용률 |
cpu_use |
number |
선택 사항, CPU 사용률 |
battery_use |
number |
선택 사항, 현재 휴대폰 배터리 잔량(tvOS 미지원) |
carrier |
string |
선택 사항, 통신사 정보(iOS 지원) |
locale |
string |
현재 시스템 언어 |
메트릭
| 필드 |
유형 |
설명 |
error_message |
string |
오류 메시지 |
error_stack |
string |
오류 스택 |
foreground_crash_free_duration |
number(ns) |
Crash 발생 전 애플리케이션이 포그라운드에 있었던 무크래시 지속 시간 |
background_crash_free_duration |
number(ns) |
Crash 발생 전 애플리케이션이 백그라운드에 있었던 무크래시 지속 시간 |
crash_extra |
object |
Crash 추가 정보, 예: 레지스터 정보 |
Long Task
View 속성
| 필드 |
유형 |
설명 |
view_id |
string |
페이지를 방문할 때마다 생성되는 고유 ID |
view_referrer |
string |
페이지 소스, 페이지의 상위 |
view_name |
string |
페이지 이름 |
Action 속성
| 필드 |
유형 |
설명 |
action_id |
string |
사용자가 페이지를 조작할 때 생성되는 고유 ID |
action_name |
string |
작업 이름 |
메트릭
| 필드 |
유형 |
설명 |
duration |
number(ns) |
버벅임 지속 시간 |
long_task_stack |
string |
버벅임 스택 |
session_has_replay |
boolean |
현재 Long Task가 속한 세션이 Session Replay 데이터와 연결되어 있는지 여부 |
app_state |
string |
SDK 1.6.8+: 이벤트 시작 시간 및 지속 시간에 따라 구간을 결정한 후, 해당 구간 내의 포그라운드/백그라운드 이력을 기반으로 애플리케이션 상태를 계산합니다. 값: foreground(포그라운드만), background(백그라운드만), foreground_and_background(포그라운드와 백그라운드를 모두 거침), unknown(이력 누락 또는 구간 유효하지 않음) |
Action
View 속성
| 필드 |
유형 |
설명 |
view_id |
string |
페이지를 방문할 때마다 생성되는 고유 ID |
view_referrer |
string |
페이지 소스, 페이지의 상위 |
view_name |
string |
페이지 이름 |
Action 속성
| 필드 |
유형 |
설명 |
action_id |
string |
사용자가 페이지를 조작할 때 생성되는 고유 ID |
action_name |
string |
작업 이름, 기본 시작 Action에는 app_hot_start, app_cold_start, app_warm_start가 포함됩니다. |
action_type |
string |
작업 유형, 참조 값은 click, launch_hot, launch_cold, launch_warm입니다. |
session_has_replay |
boolean |
현재 Action이 속한 세션이 Session Replay 데이터와 연결되어 있는지 여부 |
메트릭
| 필드 |
유형 |
설명 |
duration |
number(ns) |
페이지 작업에 소요된 시간 |
app_pre_runtime_init_time |
object |
시작 단계 메트릭, 런타임 초기화 전 소요 시간, 구조는 {start, duration} |
app_runtime_init_time |
object |
시작 단계 메트릭, 런타임 초기화 소요 시간, 구조는 {start, duration} |
app_uikit_init_time |
object |
시작 단계 메트릭, UIKit 초기화 소요 시간, 구조는 {start, duration} |
app_application_init_time |
object |
시작 단계 메트릭, Application 초기화 소요 시간, 구조는 {start, duration} |
app_first_frame_init_time |
object |
시작 단계 메트릭, 첫 프레임 렌더링 소요 시간, 구조는 {start, duration} |
app_launch_type |
string |
콜드 시작 유형이며, action_type=launch_cold인 경우에만 보고됩니다. foreground: 포그라운드 시작, background: 백그라운드 시작, SDK 1.6.9부터 foreground_and_background 지원: 포그라운드 시작 과정에서 백그라운드로 전환되어 중단됨 |
통계 메트릭
| 필드 |
유형 |
설명 |
action_long_task_count |
number |
작업과 연결된 긴 작업 횟수 |
action_resource_count |
number |
작업과 연결된 리소스 요청 횟수 |
action_error_count |
number |
작업과 연결된 오류 횟수 |
WebView 연결
WebView JSBridge 데이터를 RUM에 연동할 때 SDK는 해당 데이터에 is_web_view=true를 추가하여 해당 데이터가 WebView에서 왔음을 식별합니다. WebView 데이터 필드는 주로 Web SDK가 보고하는 필드를 따르며, 네이티브 iOS 필드 표에는 이 연결 설명만 유지합니다.