개요

다음의 경우 OpenTelemetry API를 사용해 애플리케이션을 수동으로 계측해야 합니다.

• Datadog이 지원하는 라이브러리 계측을 사용하고 있지 않습니다.
• ddtrace 라이브러리의 기능을 확장하고 싶습니다.
• 애플리케이션 계측을 보다 세밀하게 제어해야 합니다.

ddtrace 라이브러리는 이러한 목표를 달성하는 데 도움이 됩니다. 다음 섹션에서는 커스텀 계측을 위해 Datadog과 OpenTelemetry API를 함께 사용하는 방법을 다룹니다.

Requirements and limitations

• DatadogTrace for iOS and tvOS version 2.12.0+.

Tracing iOS applications with OpenTelemetry

1. Declare the library as a dependency depending on your package manager. Swift Package Manager (SPM) is recommended.

.package(url: "https://github.com/Datadog/dd-sdk-ios.git", .upToNextMajor(from: "2.0.0"))

DatadogCore
DatadogTrace

pod 'DatadogCore'
pod 'DatadogTrace'

github "DataDog/dd-sdk-ios"

OpenTelemetryApi.xcframework
DatadogInternal.xcframework
DatadogCore.xcframework
DatadogTrace.xcframework

2. Initialize the library with your application context and your Datadog client token. For security reasons, you must use a client token: you cannot use Datadog API keys to configure the dd-sdk-ios library as they would be exposed client-side in the iOS application IPA byte code.

For more information about setting up a client token, see the client token documentation.

import DatadogCore

Datadog.initialize(
    with: Datadog.Configuration(
        clientToken: "<client token>",
        env: "<environment>",
        service: "<service name>"
    ),
    trackingConsent: trackingConsent
)

import DatadogCore

Datadog.initialize(
    with: Datadog.Configuration(
        clientToken: "<client token>",
        env: "<environment>",
        site: .eu1,
        service: "<service name>"
    ),
    trackingConsent: trackingConsent
)

import DatadogCore

Datadog.initialize(
    with: Datadog.Configuration(
        clientToken: "<client token>",
        env: "<environment>",
        site: .us3,
        service: "<service name>"
    ),
    trackingConsent: trackingConsent
)

import DatadogCore

Datadog.initialize(
    with: Datadog.Configuration(
        clientToken: "<client token>",
        env: "<environment>",
        site: .us5,
        service: "<service name>"
    ),
    trackingConsent: trackingConsent
)

import DatadogCore

Datadog.initialize(
    with: Datadog.Configuration(
        clientToken: "<client token>",
        env: "<environment>",
        site: .us1_fed,
        service: "<service name>"
    ),
    trackingConsent: trackingConsent
)

import DatadogCore

Datadog.initialize(
    with: Datadog.Configuration(
        clientToken: "<client token>",
        env: "<environment>",
        site: .ap1,
        service: "<service name>"
    ),
    trackingConsent: trackingConsent
)

To be GDPR compliant, the SDK requires the trackingConsent value at initialization. The trackingConsent can be one of the following values:

• .pending: The SDK starts collecting and batching the data but does not send it to Datadog. The SDK waits for the new tracking consent value to decide what to do with the batched data.
• .granted: The SDK starts collecting the data and sends it to Datadog.
• .notGranted: The SDK does not collect any data: logs, traces, and RUM events are not sent to Datadog.

To change the tracking consent value after the SDK is initialized, use the Datadog.set(trackingConsent:) API call.

The SDK changes its behavior according to the new value. For example, if the current tracking consent is .pending:

• If changed to .granted, the SDK sends all current and future data to Datadog;
• If changed to .notGranted, the SDK wipes all current data and stops collecting any future data.

Before data is uploaded to Datadog, it is stored in cleartext in the cache directory (Library/Caches) of your application sandbox. The cache directory cannot be read by any other app installed on the device.

When writing your application, enable development logs to log to console all internal messages in the SDK with a priority equal to or higher than the provided level.

Datadog.verbosityLevel = .debug

3. Datadog tracer implements the Open Telemetry standard. Enable the Datadog tracer, register the tracer provider, and get the tracer instance:

import DatadogTrace
import OpenTelemetryApi

Trace.enable(
    with: Trace.Configuration(
        networkInfoEnabled: true
    )
)

OpenTelemetry.registerTracerProvider(
    tracerProvider: OTelTracerProvider()
)

let tracer = OpenTelemetry
    .instance
    .tracerProvider
    .get(instrumentationName: "", instrumentationVersion: nil)

4. Instrument your code with the OpenTelemetry API:

let span = tracer.spanBuilder(spanName: "<span_name>").startSpan()
// do something you want to measure ...
// ... then, when the operation is finished:
span.end()

5. (Optional) Set child-parent relationship between your spans:

let responseDecodingSpan = tracer.spanBuilder(spanName: "response decoding")
    .setParent(networkRequestSpan) // make it child of `networkRequestSpan`
    .startSpan()

// ... decode HTTP response data ...
responseDecodingSpan.end()

6. (Optional) Provide additional attributes alongside your span:

span.setAttribute(key: "http.url", value: url)

7. (Optional) Attach an error to a span:

span.status = .error(description: "Failed to decode response")

8. (Optional) Add span links to your span:

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()