설정

Sophonz.Options의 전체 항목과 캡처 서비스 빌더, 서비스별 옵션, 그리고 전송 경로의 현재 상태를 정리합니다.

설정은 Sophonz.start(options:)에 넘기는 Sophonz.Options 하나로 끝납니다. 시작 이후에 바꿀 수 있는 것은 로그 레벨뿐이므로, 필요한 값은 시작 시점에 모두 정해야 합니다.

시작 모드

Options를 만드는 공개 경로는 셋이며, 서로 배타적입니다.

	`fromPlist`	`withCollector`	`withLocalConfiguration`
식별	`Sophonz-Info.plist`의 `AppKey`	인자로 전달한 앱 키	없음
업로드	수집기로 OTLP/JSON	같음	만들어지지 않음
원격 설정	사용	사용	사용 안 함. `SophonzConfigurable`을 직접 구현
`otel`	선택	선택	필수

fromPlist는 파일이 없거나 수집기 주소·키가 비어 있으면 nil을 돌려줍니다. 그 빌드는 시작하지 말아야 하는 빌드입니다.

CAUTION — withAppId는 레거시입니다

Embrace 계열의 5자 appId 경로가 아직 남아 있습니다. 기본 엔드포인트가 appId로부터 .invalid 도메인으로 만들어지므로(RFC 2606의 예약 TLD) 어디에도 도달하지 않고, 앱 키를 보낼 방법도 없습니다. 새 코드에서 쓰지 마세요.

Sophonz.Options

항목	타입	기본값
`ingest`	`SophonzIngest?`	`fromPlist` · `withCollector`가 채웁니다
`appId`	`String?`	레거시 `withAppId` 전용
`platform`	`SophonzPlatform`	`.default`
`endpoints`	`SophonzEndpoints?`	수집기 주소에서 유도
`captureServices`	`CaptureServicesOptions`	`.default()`
`crashReporter`	`CrashReporter`	`.sophonz`
`logLevel`	`SophonzLogLevel`	`.default`
`otel`	`OTelOptions?`	`nil`
`runtimeConfiguration`	`SophonzConfigurable?`	`withLocalConfiguration`에서만 유효

SophonzIngest

항목	보내는 값	plist 키
`collectorUrl`	—	`CollectorURL`
`appKey`	`service.key`	`AppKey`
`appName`	`service.name`	`AppName`
`project`	`service.namespace`	`Project`
`deploymentEnvironment`	`deployment.environment.name`	`DeploymentEnvironment`

appName은 번들 식별자에서 유도되는 기본값(<번들ID>:<프로세스명>)을 덮어씁니다. 포털이 (프로젝트, service.name)으로 앱을 찾기 때문에, 등록한 이름과 다르면 데이터가 들어와도 앱 화면에는 보이지 않습니다.

전송 경로

수집기 주소 아래의 /v1/traces와 /v1/logs로 OTLP/JSON을 gzip으로 압축해 보냅니다. 첨부 파일은 /v2/attachments입니다. 앱 키는 service.key 리소스 속성으로 나가며, Android SDK와 같은 모양입니다.

변환은 보내는 시점에 일어납니다. 저장은 SDK 자체 형식 그대로 두기 때문에, 저장 우선순위·크래시 복원·재시도가 저장된 모양 위에서 계속 동작합니다.

업로드는 세션 파트가 끝날 때 일어납니다 — 앱이 백그라운드로 갈 때, 또는 강제 종료 뒤 다음 실행 때입니다. 주기적인 타이머가 아니므로, 포그라운드에 오래 떠 있는 앱은 그동안 아무것도 보내지 않습니다.

NOTE — 등록되지 않은 키는 조용히 버려집니다

수집기는 service_key_mode: enforce로 동작합니다. 키가 없거나 해석되지 않으면 오류 없이 버려지므로, 잘못 설정한 빌드는 정상으로 보이면서 아무것도 남기지 않습니다.

SDK 자신의 업로드는 네트워크 계측에서 제외됩니다. 그렇지 않으면 업로드마다 /v1/traces 요청 스팬이 생기고, 그 스팬이 다음 업로드에 실려 또 스팬을 만듭니다.

Sophonz 수집기 대신 직접 익스포터를 붙이려면 withLocalConfiguration으로 시작합니다.

let otel = Sophonz.OTelOptions(
  spanExporters: [myOtlpSpanExporter],
  logExporters: [myOtlpLogExporter]
)
 
try Sophonz.start(options: .withLocalConfiguration(otel: otel))

OTelOptions

항목	타입	기본값
`resource`	`Resource?`	`nil`
`spanProcessors`	`[SpanProcessor]`	`[]`
`spanExporters`	`[SpanExporter]`	`[]`
`logProcessors`	`[LogRecordProcessor]`	`[]`
`logExporters`	`[LogRecordExporter]`	`[]`

service.name, service.version, telemetry.sdk.language는 SDK가 항상 설정하며 resource로 덮어쓸 수 없습니다.

캡처 서비스 선택

기본 목록을 그대로 쓰려면 아무것도 넘기지 않습니다. 조정하려면 빌더를 씁니다.

let services = Sophonz.CaptureServicesOptionsBuilder()
  .addDefaults()
  .addHangCaptureService()
  .build()
 
try Sophonz.start(options: .withCollector(
  url: "https://in.sophonz.ai",
  appKey: "sk_…",
  captureServices: services
))

CAUTION — 빌더는 비어 있는 상태에서 시작합니다

addDefaults()를 부르지 않으면 기본 서비스가 하나도 설치되지 않습니다. 일부만 빼려는 의도였다면 addDefaults() 뒤에 remove(...)를 쓰세요.

메서드	대상
`addDefaults()`	기본 6종 (행·푸시 알림 제외)
`addUrlSessionCaptureService(withOptions:)`	네트워크
`addViewCaptureService(withOptions:)`	화면
`addTapCaptureService(withOptions:)`	탭
`addWebViewCaptureService(withOptions:)`	WebView
`addLowMemoryWarningCaptureService()`	메모리 경고
`addLowPowerModeCaptureService()`	저전력 모드
`addHangCaptureService()`	행 감지
`addPushNotificationCaptureService(withOptions:)`	푸시 알림
`add(_:)`	직접 만든 서비스
`remove(ofType:)` · `remove(sophonzType:)`	제거

서비스별 옵션

네트워크

항목	타입	기본값
`ignoredURLs`	`[String]`	`[]` — 부분 문자열로 비교
`traceparent.onlyAllowDomains`	`[String]?`	`nil` — 제한 없음
`requestsDataSource`	`URLSessionRequestsDataSource?`	`nil`

onlyAllowDomains를 빈 배열로 두면 어떤 도메인에도 traceparent를 붙이지 않습니다. 항목은 호스트 이름만 넣습니다. /나 공백이 들어가거나 점으로 시작하면 예외 없이 경고만 남기고 버려지므로, 조용히 적용되지 않는 상황을 피하려면 값을 정확히 쓰세요.

화면

항목	타입	기본값
`instrumentVisibility`	`Bool`	`true`
`instrumentFirstRender`	`Bool`	`true`
`viewControllerBlockList.types`	`[AnyClass]`	`[]`
`viewControllerBlockList.names`	`[String]`	`[]` — 대문자 부분 일치
`viewControllerBlockList.blockHostingControllers`	`Bool`	`true`

NOTE — SwiftUI 화면은 기본적으로 제외됩니다

blockHostingControllers가 true이므로 UIHostingController와 그 하위가 화면 계측에서 빠집니다. SwiftUI 화면을 계측하려면 이 값을 끄거나, sophonzTrace(_:) 뷰 수정자를 쓰세요.

instrumentFirstRender는 원격 설정과 함께 평가됩니다. 로컬에서 켜도 원격에서 꺼져 있으면 동작하지 않습니다.

탭

항목	타입	기본값
`captureTapCoordinates`	`Bool`	`true`
`ignoredViewTypes`	`[AnyClass]`	`[]`
`tapPhase`	`.onStart` · `.onEnd`	`.onStart`
`delegate`	`TapCaptureServiceDelegate?`	`nil`

키보드 뷰는 자동으로 제외됩니다.

WebView

항목	타입	기본값
`stripQueryParams`	`Bool`	`false`
`fragmentHandling`	`.keep` · `.redact` · `.remove`	`.keep`

.redact는 프래그먼트 안의 키=값 형태만 값을 지우고 해시 라우트와 짧은 앵커는 남깁니다. 쿼리 파라미터 설정과는 독립적으로 동작합니다.

푸시 알림

항목	타입	기본값
`captureData`	`Bool`	`false`

행 감지

옵션 구조체 대신 HangLimits를 받으며, 시작 시 원격 설정 값으로 덮어써집니다.

항목	기본값
행 판정 임계값	0.249초
세션당 최대 기록 수	20
샘플링 시작 임계값	0.15초
샘플링 주기	0.05초

로그 레벨

시작 이후에도 바꿀 수 있는 유일한 값입니다. SDK 자체의 콘솔 출력 수준이며, 수집하는 로그와는 무관합니다.

Sophonz.shared.logLevel = .debug