문서
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와 연동해, 네이티브가 만든 세션을 웹 화면이 그대로 이어받게 하는 방법입니다.
소스맵 업로드
Vite 플러그인을 사용해 빌드 후 소스맵을 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 확장.
레거시 — v1.0
Sophonz Android SDK v1.0 설치 및 설정 방법을 안내합니다.
레거시 — v1.1 Extension
Sophonz Android SDK v1.1 Extension 설치 및 설정 방법을 안내합니다.
레거시 — Vanilla
Sophonz Android Vanilla SDK v1.1 설치 및 설정 방법을 안내합니다.
iOS
Flutter
React Native
백엔드 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
Java
Go
Rust
Elixir
인프라 계측
PostgreSQL
PostgreSQL 계측
PostgreSQL에서 수집할 수 있는 텔레메트리는 데이터베이스를 직접 운영하는지, 클라우드 관리형 서비스를 사용하는지에 따라 달라집니다. 두 환경의 수집 경로와 확보 가능한 속성을 정리합니다.
자체 운영 PostgreSQL
pg_tracing 확장을 사용하여 PostgreSQL이 직접 스팬을 전송하도록 구성합니다. 이미지 빌드, 서버 설정, 검증 절차와 앱 키 제약을 설명합니다.
클라우드 관리형 PostgreSQL
RDS, Aurora, Cloud SQL, Azure Database와 같이 확장을 설치할 수 없는 환경에서 사용 가능한 세 가지 경로인 클라이언트 스팬, 쿼리 통계 메트릭, 로그를 설명합니다.
대시보드
Grafana 대시보드
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을 자동으로 생성하는 엔드투엔드 시나리오를 설명합니다.