DiagnosticsKit

DiagnosticsKit은 Apple의 Logger와 OSSignposter를 한 곳에서 다룰 수 있게 정리한 경량 진단 패키지입니다.

• 로그 기록: trace, debug, info, notice, error, fault
• signpost 기록: begin, end, event, measure
• privacy 제어: .auto, .public, .private, .sensitive
• signpost 카테고리 제어: .pointsOfInterest, .dynamicTracing, .dynamicStackTracing, .custom

Requirements

• Swift 6
• iOS 15+
• macOS 12+

Installation

Swift Package Manager로 추가할 수 있습니다.

dependencies: [
    .package(url: "https://github.com/lgvv/diagnostics-kit.git", branch: "main")
]

타깃 의존성에 DiagnosticsKit을 추가합니다.

.target(
    name: "YourFeature",
    dependencies: [
        .product(name: "DiagnosticsKit", package: "diagnostics-kit")
    ]
)

Quick Start

기본 진입점은 DiagnosticsClient.live입니다.

import DiagnosticsKit

let diagnostics = DiagnosticsClient.live

Logging

diagnostics.trace("View did load")
diagnostics.debug("User tapped refresh", privacy: .public)
diagnostics.info("Loaded profile", privacy: .private)
diagnostics.error("Request failed", privacy: .sensitive)

Signpost Event

diagnostics.event("RefreshButtonTapped")
diagnostics.event("CacheHit", type: .dynamicTracing)
diagnostics.event("ImageDecoded", type: .custom(category: "ImagePipeline"))

Interval Measurement

직접 begin / end를 사용할 수도 있고, measure로 감싸서 더 간단하게 측정할 수도 있습니다.

let state = diagnostics.begin("FetchHomeFeed", type: .pointsOfInterest)
defer { diagnostics.end("FetchHomeFeed", state, type: .pointsOfInterest) }

// work

let result = diagnostics.measure("DecodePayload", type: .dynamicTracing) {
    try decoder.decode(Response.self, from: data)
}

let image = try await diagnostics.measure("DownloadImage", type: .custom(category: "ImagePipeline")) {
    try await imageService.fetchImage()
}

Privacy

로그 메시지 보간에는 다음 privacy 옵션을 사용할 수 있습니다.

• .auto: 시스템 기본 정책 사용
• .public: 공개 문자열로 기록
• .private: 비공개 문자열로 기록
• .sensitive: 민감 정보로 기록

diagnostics.notice("User ID: \(userID)", privacy: .private)
diagnostics.fault("Access token expired", privacy: .sensitive)

Signposter Types

DiagnosticsSignposterType으로 Instruments에서 볼 카테고리를 선택할 수 있습니다.

• .pointsOfInterest: 기본 카테고리
• .dynamicTracing: 동적 tracing 카테고리
• .dynamicStackTracing: stack trace 수집이 포함된 tracing 카테고리
• .custom(category:): 문자열 기반 사용자 정의 카테고리

Design Notes

• 로그와 signpost를 같은 DiagnosticsClient API에서 다룹니다.
• subsystem은 현재 모듈의 bundleIdentifier를 사용하고, 없으면 기본값으로 대체합니다.
• 동기/비동기 measure 모두 interval signpost를 시작하고 종료합니다.

Testing

swift test

현재 테스트는 다음 동작을 검증합니다.

• signpost 메타데이터 전달
• 로그 메시지와 privacy 전달
• sync/async measure의 begin/end 보장
• 에러 발생 시 interval 종료
• privacy 분기 처리