OpenTelemetry API를 사용한 iOS·tvOS 커스텀 계측 (iOS and tvOS Custom Instrumentation using the OpenTelemetry API)
iOS·tvOS 애플리케이션을 OpenTelemetry API로 계측해 트레이스를 Datadog으로 보내는 방법이에요. Datadog SDK로 지원하지 않는 부분을 직접 계측해야 할 때 유용해요.
출처: 문서
본문
Datadog와 함께 OpenTelemetry를 언제 사용해야 할지 모르겠다면 OpenTelemetry API 커스텀 계측부터 시작해 알아보세요.
개요 (Overview)
OpenTelemetry API로 애플리케이션을 수동 계측해야 하는 이유는 몇 가지가 있어요.
- Datadog 지원 라이브러리 계측을 사용하지 않는 경우.
ddtrace라이브러리의 기능을 확장하고 싶은 경우.- 애플리케이션 계측을 더 세밀하게 제어해야 하는 경우.
ddtrace 라이브러리는 이러한 목표를 달성하는 데 도움이 되는 여러 기법을 제공해요. 다음 섹션은 Datadog에서 사용하기 위해 커스텀 계측에 OpenTelemetry API를 사용하는 방법을 보여줘요.
요구사항과 제한 사항 (Requirements and limitations)
- iOS·tvOS용 DatadogTrace 버전 2.12.0 이상.
OpenTelemetry로 iOS 애플리케이션 트레이싱하기 (Tracing iOS applications with OpenTelemetry)
-
패키지 관리자에 따라 라이브러리를 의존성으로 선언하세요. Swift Package Manager(SPM)를 권장해요.
- Swift Package Manager (SPM): Apple의 Swift Package Manager로 통합하려면
Package.swift에 다음을 의존성으로 추가하세요.
.package(url: "https://github.com/Datadog/dd-sdk-ios.git", .upToNextMajor(from: "2.0.0"))프로젝트에서 다음 라이브러리를 링크하세요.
DatadogCore DatadogTrace- CocoaPods: CocoaPods로
dd-sdk-ios를 설치할 수 있어요.
pod 'DatadogCore' pod 'DatadogTrace'- Carthage: Carthage로
dd-sdk-ios를 설치할 수 있어요.
github "DataDog/dd-sdk-ios" - Swift Package Manager (SPM): Apple의 Swift Package Manager로 통합하려면
Xcode에서 다음 프레임워크를 링크하세요.
OpenTelemetryApi.xcframework
DatadogInternal.xcframework
DatadogCore.xcframework
DatadogTrace.xcframework
애플리케이션 컨텍스트와 Datadog 클라이언트 토큰으로 라이브러리를 초기화하세요. 보안상의 이유로 클라이언트 토큰을 사용해야 해요. Datadog API 키는 iOS 애플리케이션 IPA 바이트 코드에 클라이언트 측으로 노출되므로 dd-sdk-ios 라이브러리 구성에 사용할 수 없어요.
클라이언트 토큰 설정에 대한 자세한 내용은 클라이언트 토큰 문서를 참고하세요.
app.datadoghq.com 사이트 사용자의 경우:
import DatadogCore
Datadog.initialize(
with: Datadog.Configuration(
clientToken: "<client token>",
env: "<environment>",
service: "<service name>"
),
trackingConsent: trackingConsent
)
다른 사이트 사용자는 초기화 시 site: 매개변수에 해당 사이트를 지정하면 됩니다. app.datadoghq.eu는 .eu1, us3.datadoghq.com은 .us3, us5.datadoghq.com은 .us5, app.ddog-gov.com은 .us1_fed, us2.ddog-gov.com은 .us2_fed, ap1.datadoghq.com은 .ap1, ap2.datadoghq.com은 .ap2, uk1.datadoghq.com은 .uk1로 지정하면 돼요.
GDPR 규정을 준수하기 위해 SDK는 초기화 시 trackingConsent 값을 요구해요. trackingConsent는 다음 값 중 하나일 수 있어요.
.pending: SDK가 데이터 수집·배치를 시작하지만 Datadog으로 보내지는 않아요. SDK는 배치된 데이터를 어떻게 처리할지 결정하기 위해 새 추적 동의 값을 기다립니다..granted: SDK가 데이터 수집을 시작하고 Datadog으로 보내요..notGranted: SDK가 어떤 데이터도 수집하지 않아요. 로그·트레이스·RUM 이벤트가 Datadog으로 보내지지 않아요.
SDK 초기화 후 추적 동의 값을 바꾸려면 Datadog.set(trackingConsent:) API 호출을 사용하세요.
SDK는 새 값에 따라 동작을 바꿔요. 예를 들어 현재 추적 동의가 .pending이라면:
.granted로 바꾸면 SDK가 현재·향후 모든 데이터를 Datadog으로 보내요..notGranted로 바꾸면 SDK가 현재 모든 데이터를 지우고 향후 데이터 수집을 중지해요.
데이터가 Datadog으로 업로드되기 전에 애플리케이션 샌드박스의 캐시 디렉터리(Library/Caches)에 평문으로 저장돼요. 캐시 디렉터리는 기기에 설치된 다른 어떤 앱도 읽을 수 없어요.
애플리케이션을 작성할 때 개발 로그를 활성화해 SDK의 모든 내부 메시지를 제공된 레벨 이상의 우선순위로 콘솔에 기록할 수 있어요.
Datadog.verbosityLevel = .debug
Datadog SDK는 Open Telemetry 표준을 구현해요. Datadog SDK를 활성화하고, 트레이서 제공자를 등록하고, 트레이서 인스턴스를 얻으세요.
import DatadogTrace
import OpenTelemetryApi
Trace.enable(
with: Trace.Configuration(
networkInfoEnabled: true
)
)
OpenTelemetry.registerTracerProvider(
tracerProvider: OTelTracerProvider()
)
let tracer = OpenTelemetry
.instance
.tracerProvider
.get(instrumentationName: "", instrumentationVersion: nil)
OpenTelemetry API로 코드를 계측하세요.
let span = tracer.spanBuilder(spanName: "<span_name>").startSpan()
// 측정하려는 것을 수행하세요 ...
// ... 그런 다음 작업이 끝나면:
span.end()
(선택) 스팬 사이의 자식-부모 관계를 설정하세요.
let responseDecodingSpan = tracer.spanBuilder(spanName: "response decoding")
.setParent(networkRequestSpan) // make it child of `networkRequestSpan`
.startSpan()
// ... HTTP 응답 데이터 디코딩 ...
responseDecodingSpan.end()
(선택) 스팬에 추가 속성을 제공하세요.
span.setAttribute(key: "http.url", value: url)
(선택) 스팬에 오류를 첨부하세요.
span.status = .error(description: "Failed to decode response")
(선택) 스팬에 span link를 추가하세요.
let linkedSpan = tracer.spanBuilder(spanName: "linked span").startSpan()
linkedSpan.end()
let spanWithLinks = tracer.spanBuilder(spanName: "span with links")
.addLink(spanContext: linkedSpan.context)
.startSpan()
spanWithLinks.end()