문서
Sophonz를 효과적으로 사용하기 위한 가이드와 레퍼런스입니다.
가이드
시작하기
프로덕션
프론트엔드 SDK
웹
설치
Sophonz Browser SDK를 CDN 또는 NPM으로 웹 프론트엔드 프로젝트에 설치하는 방법을 안내합니다.
설정
Sophonz Browser SDK의 초기화 옵션 전체 레퍼런스와, 서버에서 계측을 활성화·비활성화하는 원격 설정을 설명합니다.
계측
Browser SDK가 내장한 14개 계측이 각각 무엇을 수집하고 어떤 스팬을 만드는지, Web Vitals가 내보내는 속성, 그리고 활성화·비활성화 방법을 정리합니다.
API 레퍼런스
Sophonz Browser SDK가 공개하는 모든 API의 레퍼런스입니다.
민감정보 처리
URL 편집은 기본으로 적용되고 속성 편집은 선택 사항입니다. 기본으로 무엇을 URL에서 제거하는지, sanitizeUrl로 어떻게 확장하는지, attributeScrubbers로 속성 값을 어떻게 편집하는지 설명합니다.
WebView 연동
Sophonz Browser SDK를 모바일 네이티브 앱의 WebView와 연동해, 네이티브가 만든 세션을 웹 화면이 그대로 이어받게 하는 방법입니다.
소스맵 업로드
빌드한 소스맵을 웹 버전별로 Sophonz에 올려, 프로덕션 에러의 스택 트레이스를 원본 파일과 줄 번호로 되돌립니다.
예제 프로그램
Browser SDK가 실제로 무엇을 보내는지 브라우저에서 바로 확인할 수 있는 단일 HTML 예제입니다.
지원 사양
Sophonz Browser SDK가 지원하는 브라우저, WebView 환경, 프레임워크, 패키지 매니저 요구사항을 정리합니다.
Next.js
Next.js
Sophonz Next.js SDK는 App Router 앱의 브라우저·서버 모니터링을 하나의 설정으로 구성합니다. 클라이언트의 SophonzProvider와 서버의 register()가 하나의 trace를 공유합니다.
설치
@sophonz/nextjs 설치, instrumentation.ts에 register() 연결하기, App Router 루트 레이아웃에 SophonzProvider 마운트하기.
설정
@sophonz/nextjs 설정 전체 레퍼런스. 공유 SophonzNextConfig 옵션, 환경 변수, 패키지가 지정하는 기본값, 하위 브라우저·Node.js SDK 옵션에 접근하는 방법.
예제
App Router 프로젝트에 @sophonz/nextjs를 붙인 완전한 예제 — 최소 구성, Route Handler와 Server Action의 속성 추가, 데이터베이스 쿼리 트레이싱.
안드로이드
Android SDK
OpenTelemetry 기반 Android SDK의 구성과 수집 범위, 문서를 읽는 순서를 안내합니다.
설치
Gradle 플러그인 적용, 저장소 인증, SDK 시작까지 Android SDK를 앱에 붙이는 과정을 설명합니다.
설정
sophonz-config.json의 전체 항목과 Gradle sophonz 확장 블록의 옵션, 수집기 주소와 앱 키를 지정하는 방법을 정리합니다.
계측 항목
Android SDK가 내장한 자동 계측이 각각 무엇을 수집하고 어떤 spz.type을 붙이는지, 기본 활성화 여부와 켜고 끄는 방법을 정리합니다.
API 레퍼런스
Sophonz 오브젝트가 제공하는 공개 API — 세션과 사용자, 로그와 예외, 스팬, 트레이스 보강, OpenTelemetry 확장.
매핑 파일 업로드
R8/ProGuard mapping.txt를 올려 난독화된 스택 트레이스를 원래 클래스, 메서드, 줄 번호로 복원합니다.
레거시 — v1.0
Sophonz Android SDK v1.0 설치 및 설정 방법을 안내합니다.
레거시 — v1.1 Extension
Sophonz Android SDK v1.1 Extension 설치 및 설정 방법을 안내합니다.
레거시 — Vanilla
Sophonz Android Vanilla SDK v1.1 설치 및 설정 방법을 안내합니다.
iOS
iOS SDK
OpenTelemetry 기반 Apple SDK의 구성과 수집 범위, 현재 개발 상태, 문서를 읽는 순서를 안내합니다.
설치
Swift Package Manager 또는 CocoaPods로 Apple SDK를 추가하고 앱에서 시작하는 방법을 설명합니다.
설정
Sophonz.Options의 전체 항목과 캡처 서비스 빌더, 서비스별 옵션, 그리고 전송 경로의 현재 상태를 정리합니다.
계측 항목
Apple SDK의 캡처 서비스가 각각 무엇을 수집하고 어떤 spz.type을 붙이는지, 기본 설치 여부와 플랫폼 제약을 정리합니다.
API 레퍼런스
Sophonz 클래스의 공개 API — 수명 주기, 사용자와 세션, 로그와 크래시, 스팬, 브레드크럼, 푸시 알림, 실험과 기능 플래그, SwiftUI.
예제
앱에 Apple SDK를 붙인 완성된 예제 — 최소 구성, 자체 익스포터, 캡처 서비스 조정, 화면과 스팬, SwiftUI, 크래시 맥락.
dSYM 업로드
빌드의 dSYM을 올려 크래시와 에러 스택 트레이스를 함수 이름, 파일, 줄 번호로 복원하고 Xcode처럼 스레드별로 확인합니다.
레거시 — 설치 (구버전)
Sophonz iOS SDK를 XCFramework, CocoaPods, Swift Package Manager로 설치하는 방법을 안내합니다.
레거시 — API 및 설정 (구버전)
Sophonz iOS SDK의 Options 클래스, 주요 API, 그리고 초기화 예제를 설명합니다.
레거시 — 웹뷰 연동 (구버전)
Sophonz iOS SDK의 WebView 세션 연결, Objective-C 프로젝트 통합, 권장 사항 및 지원 안내입니다.
Flutter
Flutter
Sophonz Flutter SDK가 무엇을 수집하는지, Android·Apple SDK 위에서 어떻게 동작하는지, 어떤 패키지로 배포되는지, 이 가이드를 어떤 순서로 읽으면 되는지 정리합니다.
설치
새 Flutter 앱에 SDK를 붙이는 전체 과정 — Git 의존성, Android Gradle과 iOS CocoaPods·SwiftPM 연결, 네이티브 시작 호출, Dart 시작 순서를 단계별로 설명합니다.
설정
Flutter 앱이 플랫폼마다 갖춰야 하는 네이티브 설정(sophonz-config.json, Sophonz-Info.plist), 서비스 식별 방식, Dart에서 지정할 수 있는 모든 옵션을 정리합니다.
계측
코드를 더 쓰지 않아도 Flutter 앱이 보고하는 것 — Flutter 계층의 Dart 오류, 프레임, 아이솔레이트 멈춤, 시작과 수명 주기, 네이티브 SDK의 크래시, ANR, 세션 — 과 Android·iOS의 차이를 정리합니다.
내비게이션
SophonzNavigationObserver와 sophonz_go_router로 Flutter 라우트를 뷰와 화면 로드 스팬으로 기록하는 방법 — StatefulShellRoute, 라우트 이름, 라우트가 아닌 화면까지 — 을 설명합니다.
네트워크
SophonzHttpClient, sophonz_dio 인터셉터, recordNetworkRequest로 Dart의 HTTP 요청을 기록하고, W3C traceparent 헤더를 전파해 백엔드 트레이스를 앱의 요청에 잇는 방법을 설명합니다.
API 레퍼런스
Sophonz Flutter SDK의 모든 공개 Dart API — 수명 주기, 오류, 로그, 스팬, 네트워크 요청, 뷰, 사용자, 세션, 익스포터, OpenTelemetry API — 를 시그니처와 Android·iOS 지원 여부와 함께 정리합니다.
릴리스 빌드
Flutter 릴리스 빌드의 스택 트레이스를 읽을 수 있게 만드는 방법 — Android의 R8 매핑 파일, iOS의 dSYM, --obfuscate와 --split-debug-info를 쓸 때 Dart 스택 트레이스에 일어나는 일 — 을 설명합니다.
예제
Sophonz를 붙인 Flutter 앱의 전체 구성 — pubspec, 네이티브 파일, main.dart 시작 순서, traceparent를 보내는 Dio, go_router, 화면 로드를 감싸는 스팬, 처리된 오류, 사용자와 세션 정보 — 를 보여 줍니다.
업그레이드
Flutter 앱을 새 Sophonz Flutter SDK 릴리스로 옮기는 방법 — 모든 항목의 Git 태그 변경, pubspec.lock 갱신, Android Gradle 플러그인과 iOS SophonzIO pod를 릴리스의 네이티브 버전에 맞추기 — 을 설명합니다.
React Native
React Native
React Native SDK가 Android SDK와 Apple SDK 위에서 어떻게 동작하는지, 어떤 패키지로 이루어져 있는지, 문서를 어떤 순서로 읽으면 되는지 설명합니다.
설치
React Native 패키지를 추가하고, 비공개 네이티브 SDK 접근 권한을 준비하고, Expo 설정 플러그인이나 설치 마법사 또는 직접 설정으로 네이티브 SDK를 붙인 뒤 SDK를 시작하는 과정을 설명합니다.
설정
플랫폼별 앱 아이덴티티, 컬렉터 URL과 앱 키의 위치, iOS가 이를 결정하는 순서, initialize와 sdkConfig, sophonz-config.json, Expo 설정 플러그인의 모든 옵션을 설명합니다.
계측
React Native 앱이 코드 없이 수집하는 것(네이티브 크래시, ANR, 네트워크, 생명주기), initialize가 JavaScript 에러와 Promise 거부에 대해 더하는 것, 추가 패키지별로 기록되는 것, Android와 iOS의 차이를 설명합니다.
네트워크와 분산 추적
fetch와 XMLHttpRequest로 보낸 요청이 어떻게 수집되는지, traceparent 헤더가 Android와 iOS에서 백엔드 트레이스와 어떻게 연결되는지, JavaScript 스팬을 API로 전파하는 방법, SDK가 볼 수 없는 요청을 기록하는 방법을 설명합니다.
내비게이션
@sophonz/react-native-navigation으로 expo-router, React Navigation, react-native-navigation의 화면마다 ux.view 스팬을 기록하는 방법 — 설정, 스팬 이름과 속성, 앱 상태 처리, 옵션을 설명합니다.
Redux
@sophonz/react-native-redux 미들웨어를 훅을 쓰거나 쓰지 않고 Redux Toolkit 스토어에 추가하는 방법과, 디스패치된 액션마다 정확히 무엇이 기록되는지 설명합니다.
OpenTelemetry와 OTLP
@sophonz/react-native-tracer-provider로 OpenTelemetry JS API의 커스텀 스팬을 만드는 방법(설정, 컨텍스트, 스팬 컨텍스트, 플랫폼별 제한)과 @sophonz/react-native-otlp로 같은 텔레메트리를 다른 백엔드로도 보내는 방법을 설명합니다.
API 레퍼런스
React Native 패키지의 모든 export — 시작, 훅, 로그와 에러, 세션, 사용자, 네트워크 기록, 번들 ID, 타입, tracer provider, 내비게이션, Redux, OTLP — 의 시그니처와 기본값, Android와 iOS의 동작 차이를 설명합니다.
릴리스 빌드와 심볼리케이션
React Native 릴리스 빌드에서 읽을 수 있는 것(Hermes 번들의 JavaScript 스택 트레이스, Android의 R8 매핑, iOS의 dSYM)과 지금 Sophonz가 복원할 수 있는 범위, 피해야 할 Gradle 플러그인 설정을 설명합니다.
예제
SDK, tracer provider, React Navigation을 함께 쓰는 React Native 시작 순서 전체와, 추적되는 API 호출, 커스텀 스팬, 처리한 에러, 에러 경계, 로그아웃 흐름을 보여 줍니다.
백엔드 SDK
Node.js
Node.js
Sophonz Node.js SDK는 자동 계측, 프레임워크 미들웨어, 예외 캡처와 함께 Node.js 서버 애플리케이션에 OpenTelemetry 기반 옵저버빌리티를 제공합니다.
설치
Sophonz Node.js SDK 설치 및 초기화 — init()을 사용한 프로그래밍 방식 또는 opentelemetry-instrument 프리로드 바이너리 방식.
설정
Sophonz Node.js SDK 설정 레퍼런스 — init()/initSDK()의 SDKConfig 옵션과 SOPHONZ_* / OTEL_* 환경 변수.
미들웨어
Sophonz Node.js SDK로 Express, Koa, Fastify, NestJS의 요청 스팬 보강하기 — baggage, 클라이언트 IP, user-agent, 사용자 지정 속성, 에러 핸들러.
API 레퍼런스
Sophonz Node.js SDK 공개 API — init, shutdown, 미들웨어, 에러 핸들러, 트레이스 속성, 로거 트랜스포트, 제공되는 공식 OpenTelemetry API.
예제
Sophonz Node.js SDK로 Express, Koa, Fastify, NestJS 서버를 계측하는 완전한 실행 예제 — 초기화 순서, 요청 미들웨어, 로깅, 에러 핸들러.
Python
Python
Sophonz Python SDK는 Python 서버 애플리케이션의 트레이스, 메트릭, 로그를 Sophonz로 보내는 OpenTelemetry 배포판으로, 프레임워크 미들웨어와 예외 캡처를 제공합니다.
설치
Sophonz Python SDK 설치와 초기화 — init()으로 코드에서, 또는 opentelemetry-instrument 명령으로 — 그리고 gunicorn과 uvicorn에서 정상 종료하기.
설정
Sophonz Python SDK 설정 레퍼런스 — init()/init_sdk() 옵션, 계측 설정, PostgreSQL용 SQLCommenter, SOPHONZ_* / OTEL_* 환경 변수.
프레임워크 가이드
Flask, FastAPI, Django 애플리케이션과 운영 서버에 Sophonz Python SDK 연결하기 — gunicorn 워커, uvicorn과 lifespan, Django 진입점, 미들웨어 순서, 에러 처리.
미들웨어
Sophonz Python SDK로 Flask, FastAPI, Django의 요청 스팬 보강하기 — baggage와 session.id, 클라이언트 IP, user-agent, 사용자 지정 속성, 에러 핸들러.
계측
Sophonz Python SDK가 자동으로 캡처하는 것과 제어하는 방법 — 계측 로딩, 로그와 예외 캡처, 마스킹을 포함한 고급 네트워크 캡처, baggage 승격, 사용자 정의 스팬.
데이터베이스 트레이싱
psycopg, psycopg2, SQLAlchemy, Django ORM으로 Python의 PostgreSQL 쿼리를 트레이스하고, SQLCommenter로 트레이스를 데이터베이스까지 이어 pg_tracing이 같은 트레이스에 서버 측 스팬을 더하게 하기.
브라우저-백엔드 트레이싱
Sophonz Browser SDK가 시작한 트레이스를 Python 백엔드와 PostgreSQL까지 잇기 — tracePropagationTargets, traceparent·tracestate·baggage를 위한 CORS, 서버 스팬의 session.id, 연결 확인 방법.
배포
Sophonz SDK를 쓰는 Python 서비스를 운영 환경에서 실행하기 — 코드의 init()과 opentelemetry-instrument, 환경 변수와 시크릿 구성, 비루트 사용자와 읽기 전용 루트 파일시스템 컨테이너, Kubernetes 매니페스트, 정상 종료.
API 레퍼런스
Sophonz Python SDK의 공개 API — init, init_sdk, shutdown, force_flush, 트레이스 속성, 예외 기록, SophonzOptions, Flask·FastAPI·Django 헬퍼, 다시 내보내는 OpenTelemetry API.
예제
Sophonz 샘플 서버와 같은 구성으로 만든 Sophonz Python SDK의 Flask, FastAPI, Django 서버 전체 예제 — import 전 SDK 시작, 요청 헬퍼, 브라우저 트레이스를 위한 CORS, SQLCommenter를 쓰는 PostgreSQL, 로깅, 에러 처리.
Java
Go
Rust
Elixir
Ruby on Rails
인프라 계측
PostgreSQL
PostgreSQL 계측
PostgreSQL에서 수집할 수 있는 텔레메트리는 데이터베이스를 직접 운영하는지, 클라우드 관리형 서비스를 사용하는지에 따라 달라집니다. 두 환경의 수집 경로와 확보 가능한 속성을 정리합니다.
자체 운영 PostgreSQL
pg_tracing 확장을 사용하여 PostgreSQL이 직접 스팬을 전송하도록 구성합니다. 이미지 빌드, 서버 설정, 검증 절차와 앱 키 제약을 설명합니다.
클라우드 관리형 PostgreSQL
RDS, Aurora, Cloud SQL, Azure Database와 같이 확장을 설치할 수 없는 환경에서 사용 가능한 세 가지 경로인 클라이언트 스팬, 쿼리 통계 메트릭, 로그를 설명합니다.
대시보드
Grafana 대시보드
Grafana 대시보드 개요
Sophonz가 수집한 OpenTelemetry 원격 측정 데이터를 Grafana에서 시각화하는 방법을 설명합니다.
대시보드 상세
Sophonz가 제공하는 v3 대시보드 7개를 패널 단위로 정리합니다. 각 패널이 어떤 테이블에서 무엇을 어떻게 계산하는지, 변수와 드릴다운 링크가 대시보드 사이를 어떻게 잇는지 다룹니다.
대시보드 설정
Sophonz 인프라의 Grafana 데이터소스와 대시보드를 프로비저닝하는 방법을 설명합니다.
커스텀 패널
Sophonz가 직접 만들어 Grafana에 설치하는 6개 패널이 각각 무엇을 그리고, 어떤 데이터와 옵션을 받고, 대시보드 JSON에서 어떻게 설정되는지 정리합니다.
AI Agent
AI Agent
AI Agent 개요
Sophonz AI Agent가 실제 사용자 데이터에서 문제를 발견하고 코드 수정까지 자동으로 제안하는 방법을 소개합니다.
GitHub App
Sophonz GitHub App을 리포지토리에 설치하면 실제 사용자 에러 데이터를 분석해 자동으로 이슈를 생성하고 코드 수정 PR을 제안합니다.
GitLab App
Sophonz GitLab App을 프로젝트에 설치하면 실제 사용자 에러 데이터를 분석해 자동으로 이슈를 생성하고 코드 수정 MR을 제안합니다.
에러·크래시 자동 수정
프로덕션 에러·크래시를 AI 에이전트가 분석해 코드 수정 PR/MR까지 자동으로 작성하는 파이프라인입니다.
커버리지·테스트 생성
실제 사용자 세션에서 커버리지가 높은 경로를 찾아 자동 테스트 케이스로 변환하는 파이프라인입니다.
에이전트 오케스트레이션
에이전트를 정의·연결·실행·관찰하는 오케스트레이션 레이어와 에이전트 라이프사이클, MCP & Skills를 설명합니다.
활용 시나리오
Sophonz AI Agent가 실제 에러를 발견하고 이슈와 코드 수정 PR/MR을 자동으로 생성하는 엔드투엔드 시나리오를 설명합니다.