본문으로 건너뛰기

모바일 로그 수집 API

개요​

모바일 로그 수집 API는 iOS 및 Android 애플리케이션에서 발생하는 에러 로그와 정보 로그를 수집하고 분석하는 기능을 제공합니다. 수집된 로그는 Google Cloud Pub/Sub를 통해 BigQuery에 저장되며, 앱의 안정성 모니터링과 문제 해결을 위한 기반 데이터로 활용됩니다.

로그 유형​

로그는 타입에 따라 다음과 같이 구분됩니다:

  • ERROR: 애플리케이션 에러 및 예외 상황

    • 필수 항목: severity (에러 심각도)
    • 선택 항목: jira (JIRA 이슈 생성 여부)
    • Slack 알림 자동 발송 (심각도별 채널 분리)

  • INFO: 일반 정보 및 이벤트 로그

    • 앱 라이프사이클 이벤트
    • 사용자 액션 추적
    • 성능 모니터링 데이터

자동 처리 기능​

시스템은 로그 수집 시 다음 기능을 자동으로 수행합니다:

  • Slack 알림: 환경(dev/stage/prod), OS, 런타임, 심각도에 따라 적절한 채널로 자동 발송
  • BigQuery 저장: 환경별로 분리된 테이블에 저장
  • 데이터 보관: 환경별 차등 보관 기간 적용

제약사항​

  • Timestamp 형식: milliseconds 단위 (13자리), 서버에서 microseconds로 자동 변환
  • 데이터 크기: 로그 메시지는 10,000자 이내
  • 라벨 개수: 최대 20개까지 허용
  • 파티션 제한: 현재 시점 기준 과거 3650일, 미래 366일 이내의 timestamp만 허용

모바일 로그 생성​

모바일 애플리케이션의 로그를 수집하고 처리합니다.

  • HTTP Method: POST
  • Path: /v1/logs/mobile
  • 인증: 불필요

Headers​

HeaderTypeDescriptionRequired
Content-Typeapplication/json요청 본문 형식을 지정합니다.Yes

Request Body​

에러 로그 예시:

{
  "type": "error",
  "timestamp": 1736756471000,
  "labels": ["NetworkManager", "API", "Error"],
  "log": "[ERROR] Network connection failed during API call",
  "os": "iOS",
  "runtimeEnv": "release",
  "version": "1.0.0",
  "severity": "critical",
  "userId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "userCycleId": "cycle-uuid-12345",
  "jira": false
}

정보 로그 예시:

{
  "type": "info",
  "timestamp": 1736756471000,
  "labels": ["AppLifecycle", "Launch"],
  "log": "[INFO] App launched successfully",
  "os": "Android",
  "runtimeEnv": "debug",
  "version": "1.0.0",
  "userId": "f1e2d3c4-b5a6-9078-1234-56789abcdef0",
  "userCycleId": "cycle-info-67890"
}
필드타입설명필수 여부
typestring로그 타입 (error 또는 info)필수
timestampnumberUnix timestamp (milliseconds, 13자리)필수
labelsstring[]로그 라벨 배열 (최대 20개)필수
logstring로그 메시지 (최대 10,000자)필수
osstring운영체제 (iOS 또는 Android)필수
runtimeEnvstring런타임 환경 (debug 또는 release)필수
versionstring앱 버전필수
severitystring에러 심각도 (critical, major, minor) - error 타입일 때 필수조건부
userIdstring사용자 UUID (optional)선택
userCycleIdstring사용자 사이클 ID (optional)선택
jirabooleanJIRA 이슈 생성 여부 (optional, error 타입일 때만)선택

Responses​

HTTP Status Code설명Error Code(s)
200 OK성공-
400 Bad Request잘못된 요청 (유효하지 않은 로그 타입)11021
500 Internal Server Error서버 내부 오류11000
200 OK - 성공

로그 수집 성공:

{
  "success": true,
  "messageId": "15484639870287320"
}
필드타입설명
successboolean처리 성공 여부
messageIdstringPub/Sub 메시지 ID
400 Bad Request - 잘못된 요청

예시: 유효하지 않은 로그 타입 (INVALID_LOG_TYPE - 11021)

{
  "code": 11021,
  "message": "INVALID_LOG_TYPE",
  "detail": "Unsupported log type: debug",
  "metadata": {
    "logType": "debug"
  }
}
500 Internal Server Error - 서버 내부 오류

예시: 로그 처리 실패 (SERVER_ERROR - 11000)

{
  "code": 11000,
  "message": "SERVER_ERROR",
  "detail": "Failed to process mobile log"
}

데이터 저장 및 활용​

BigQuery 테이블 구조​

로그 데이터는 다음 테이블에 저장됩니다:

  • 에러 로그: {project}.log.mobile_error_logs
  • 정보 로그: {project}.log.mobile_info_logs

참고: API에서 milliseconds로 받은 timestamp는 서버에서 자동으로 microseconds로 변환되어 BigQuery에 저장됩니다.

에러 로그 테이블 스키마​

컬럼명타입설명
timestampTIMESTAMP로그 생성 시간
user_idSTRING사용자 ID (UUID)
user_cycle_idSTRING사용자 사이클 ID
severitySTRING에러 심각도 (critical/major/minor)
runtime_envSTRING런타임 환경 (debug/release)
deploy_envSTRING배포 환경 (dev/stage/prod)
labelsSTRING REPEATED에러 라벨 배열
osSTRING운영체제 (iOS/Android)
app_versionSTRING앱 버전
error_messageSTRING에러 메시지
slack_webhookSTRING슬랙 웹훅 URL (nullable)
jira_enabledBOOLEANJIRA 이슈 생성 활성화 여부

정보 로그 테이블 스키마​

컬럼명타입설명
timestampTIMESTAMP로그 생성 시간
user_idSTRING사용자 ID (UUID)
user_cycle_idSTRING사용자 사이클 ID
runtime_envSTRING런타임 환경 (debug/release)
deploy_envSTRING배포 환경 (dev/stage/prod)
labelsSTRING REPEATED로그 라벨 배열
osSTRING운영체제 (iOS/Android)
app_versionSTRING앱 버전
log_messageSTRING로그 메시지
slack_webhookSTRING슬랙 웹훅 URL (nullable)

데이터 보관 기간​

환경에러 로그정보 로그
Dev90일30일
Stage180일90일
Prod2년1년

BigQuery 쿼리 예시​

-- 최근 24시간 Critical 에러 조회
SELECT 
  timestamp,
  user_id,
  user_cycle_id,
  os,
  app_version,
  error_message,
  labels
FROM 
  `dta-cloud-de-prod.log.mobile_error_logs`
WHERE 
  timestamp >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 24 HOUR)
  AND severity = 'critical'
  AND deploy_env = 'prod'
ORDER BY 
  timestamp DESC
LIMIT 100;

-- 특정 사용자의 에러 발생 추이
SELECT 
  DATE(timestamp) as error_date,
  COUNT(*) as error_count,
  ARRAY_AGG(DISTINCT error_message LIMIT 5) as sample_errors
FROM 
  `dta-cloud-de-prod.log.mobile_error_logs`
WHERE 
  user_id = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'
  AND timestamp >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 7 DAY)
GROUP BY 
  error_date
ORDER BY 
  error_date DESC;

-- OS별, 버전별 에러 통계
SELECT 
  os,
  app_version,
  severity,
  COUNT(*) as error_count
FROM 
  `dta-cloud-de-prod.log.mobile_error_logs`
WHERE 
  timestamp >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 24 HOUR)
  AND deploy_env = 'prod'
GROUP BY 
  os, app_version, severity
ORDER BY 
  error_count DESC;

-- 특정 라벨을 포함하는 에러 조회
SELECT 
  timestamp,
  user_id,
  error_message,
  labels
FROM 
  `dta-cloud-de-prod.log.mobile_error_logs`
WHERE 
  'NetworkManager' IN UNNEST(labels)
  AND severity = 'critical'
  AND timestamp >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 HOUR)
ORDER BY 
  timestamp DESC;

-- 런타임 환경별 에러 비율
SELECT 
  runtime_env,
  severity,
  COUNT(*) as error_count,
  ROUND(COUNT(*) * 100.0 / SUM(COUNT(*)) OVER(), 2) as percentage
FROM 
  `dta-cloud-de-prod.log.mobile_error_logs`
WHERE 
  timestamp >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 7 DAY)
  AND deploy_env = 'prod'
GROUP BY 
  runtime_env, severity
ORDER BY 
  runtime_env, severity;

로그 값 설명​

로그 심각도 (severity)​

값설명Slack 알림
critical치명적 오류즉시 발송
major주요 오류즉시 발송
minor경미한 오류배치 발송

런타임 환경 (runtimeEnv)​

값설명
debug디버그 빌드
release릴리스 빌드

설명​

  • 이 API는 모바일 애플리케이션의 안정성과 품질을 모니터링하기 위한 핵심 기능입니다.
  • 수집된 로그는 실시간 알림, 트렌드 분석, 문제 해결에 활용됩니다.
  • 데이터 활용:
    • 에러 발생률 모니터링 및 알림
    • 사용자별 문제 추적 및 지원
    • 앱 버전별 안정성 분석
    • 런타임 환경별 이슈 패턴 파악