Native iOS uygulamasını OTel ile bağlamak
Native iOS uygulaması (Swift, SwiftUI ya da UIKit) opentelemetry-swift ile URLSession çağrılarını, session'ları, ekranları, uygulama açılışını ve bildirdiğiniz hataları gönderir. Çağrılar backend'e traceparent ile bağlanır, sonuç APM → Son kullanıcı sayfasında görünür. Ortak değerler: genel bakış.
Sürüm tablosu
| Parça | Paket | Sürüm |
|---|---|---|
Swift package https://github.com/open-telemetry/opentelemetry-swift |
OpenTelemetryProtocolExporterHTTP, Sessions, URLSessionInstrumentation |
2.6.0 |
Bağımlılığı opentelemetry-swift-core |
OpenTelemetryApi, OpenTelemetrySdk |
2.6.0 |
| Uygulama | iOS | 13 ve sonrası |
| Derleme makinesi | Xcode | 16 ve sonrası (Swift 6 tools) |
Sürümünüzü bulun: xcodebuild -version. Rehberi paketin 2.6.0 dokümanına ve kaynak koduna göre yazdık, gerçek cihazda çalıştırmadık. Sınırları açık söyleyelim: bu paket crash toplamaz (yakaladığınız hataları Otel.error(_:) ile bildirin) ve Spitfire dSYM dosyası okumaz, iOS stack'leri geldiği gibi görünür.
Doğrulandı: 2026-11-09. Kaynak: OTel Swift, opentelemetry-swift 2.6.0.
Gerekenler
- Spitfire adresi
https://<spitfire>(HTTPS: iOS düz HTTP'yi reddeder); servis adı<service-name>, sürüm<service-version>, ortam<environment> - Uygulamanın kaynak klasörü (burada
/srv/app/MyApp,@maindosyasının olduğu yer) ve Xcode
iOS
Anahtarı oluşturun: Yönetim → Entegrasyonlar → Entegrasyon ekle → Tarayıcı ve uygulama anahtarı, İzin verilen kökenler boş kalsın;
sfrum_…anahtarını kopyalayın (APM).Xcode'da: File → Add Package Dependencies…, bu adresi yapıştırın, Exact Version
2.6.0seçin,OpenTelemetryProtocolExporterHTTP,SessionsveURLSessionInstrumentationürünlerini uygulama target'ına ekleyin:
https://github.com/open-telemetry/opentelemetry-swift/srv/app/MyApp/Otel.swiftdosyasını oluşturup yapıştırın ve uygulama target'ına ekleyin:
// IS_OTEL_ENABLED=true: OTel on; any other value: off.
import Foundation
import OpenTelemetryApi
import OpenTelemetrySdk
import OpenTelemetryProtocolExporterCommon
import OpenTelemetryProtocolExporterHttp
import Sessions
import URLSessionInstrumentation
let IS_OTEL_ENABLED = "true"
let OTEL_ENDPOINT = "https://<spitfire>/otlp"
let OTEL_KEY = "sfrum_…"
enum Otel {
static var on = false
static var screen = ""
static var launch = Date()
static var started = false
static var urlSession: URLSessionInstrumentation?
/// Call first, in the App's init (SwiftUI) or application(_:didFinishLaunchingWithOptions:).
static func start() {
guard IS_OTEL_ENABLED == "true" else { return }
let v = ProcessInfo.processInfo.operatingSystemVersion
let resource = Resource().merging(other: Resource(attributes: [
"service.name": .string("<service-name>"),
"service.version": .string("<service-version>"),
"deployment.environment.name": .string("<environment>"),
"spitfire.eum.platform": .string("ios"),
"os.name": .string("iOS"),
"os.version": .string("\(v.majorVersion).\(v.minorVersion)"),
]))
let config = OtlpConfiguration(headers: [("Authorization", "Bearer \(OTEL_KEY)")])
let sessions = SessionManager()
SessionManagerProvider.register(sessionManager: sessions)
let tracerProvider = TracerProviderBuilder()
.with(resource: resource)
.add(spanProcessor: SessionSpanProcessor(sessionManager: sessions))
.add(spanProcessor: ScreenSpanProcessor())
.add(spanProcessor: BatchSpanProcessor(spanExporter: OtlpHttpTraceExporter(
endpoint: URL(string: "\(OTEL_ENDPOINT)/v1/traces")!, config: config)))
.build()
OpenTelemetry.registerTracerProvider(tracerProvider: tracerProvider)
let loggerProvider = LoggerProviderBuilder()
.with(resource: resource)
.with(processors: [SessionLogRecordProcessor(
nextProcessor: BatchLogRecordProcessor(logRecordExporter: OtlpHttpLogExporter(
endpoint: URL(string: "\(OTEL_ENDPOINT)/v1/logs")!, config: config)),
sessionManager: sessions)])
.build()
OpenTelemetry.registerLoggerProvider(loggerProvider: loggerProvider)
urlSession = URLSessionInstrumentation(configuration: URLSessionInstrumentationConfiguration(
shouldInstrument: { !($0.url?.absoluteString.hasPrefix(OTEL_ENDPOINT) ?? false) },
semanticConvention: .stable))
launch = Date()
on = true
}
/// A screen was shown: its name goes on what follows; the first one ends the app start.
static func screen(_ name: String) {
guard on else { return }
screen = name
let tracer = OpenTelemetry.instance.tracerProvider.get(instrumentationName: "app")
if !started {
started = true
tracer.spanBuilder(spanName: "AppStart").setStartTime(time: launch).startSpan().end()
}
tracer.spanBuilder(spanName: "screen.view").startSpan().end()
}
/// An error the app caught.
static func error(_ error: Error) {
guard on else { return }
OpenTelemetry.instance.loggerProvider.get(instrumentationScopeName: "app").logRecordBuilder()
.setEventName("exception")
.setSeverity(.error)
.setAttributes([
"exception.type": .string(String(describing: type(of: error))),
"exception.message": .string(error.localizedDescription),
"app.screen.name": .string(screen),
])
.emit()
}
}
/// Adds app.screen.name to every span.
final class ScreenSpanProcessor: SpanProcessor {
let isStartRequired = true
let isEndRequired = false
func onStart(parentContext: SpanContext?, span: ReadableSpan) {
if !Otel.screen.isEmpty { span.setAttribute(key: "app.screen.name", value: .string(Otel.screen)) }
}
func onEnd(span: ReadableSpan) {}
func shutdown(explicitTimeout: TimeInterval?) {}
func forceFlush(timeout: TimeInterval?) {}
}- Önce onu başlatın. SwiftUI'da
@mainApp içinde:
init() {
Otel.start()
}- Her ekran göründüğünde adını verin (SwiftUI; UIKit:
viewDidAppeariçinde):
.onAppear { Otel.screen("Cart") }- Yakaladığınız hataları bildirin:
do { try await api.placeOrder() } catch { Otel.error(error) }- Release build alın: Product → Archive.
Doğrulama
- Spitfire anahtarı bir uygulamadan (
Originolmadan) kabul ediyor:
curl -s -o /dev/null -w '%{http_code}' -X POST https://<spitfire>/otlp/v1/traces -H 'Authorization: Bearer sfrum_…' -H 'Content-Type: application/json' -d '{}' | grep -q '^200$' && echo OK- Uygulama OpenTelemetry'yi başlatıyor:
grep -rq 'Otel.start()' /srv/app/MyApp && grep -q 'IS_OTEL_ENABLED = "true"' /srv/app/MyApp/Otel.swift && echo OK- Uygulamayı telefonda açın, sonra APM → Son kullanıcı:
<service-name>uygulaması bir dakika içinde bir açılış gösterir.
Kapatma ve kaldırma
- Kapatma:
Otel.swiftdosyasındalet IS_OTEL_ENABLED = "false"yazın, yeniden build alın. - Kaldırma:
Otel.swiftdosyasını veOtel.satırlarını silin, sonra Xcode'daopentelemetry-swiftpaketini kaldırın (Package Dependencies, −).
Sık karşılaşılan sorunlar
| Belirti | Çözüm |
|---|---|
No such module 'Sessions' |
Adım 2: üç ürünü uygulama target'ına ekleyin |
| Swift tools 6.0 build hatası | Xcode 16 ve sonrası |
401 |
Anahtar sfrum_… olmalı ve açık olmalı; OTEL_KEY onu Bearer olmadan tutar |
429 |
Anahtarın Dakikada gönderim değerini artırın |
| Çağrılar backend trace'ine bağlanmıyor | Çağrılar URLSession ile gitmeli (Alamofire de, URLSession kullanır) |
| Ekran adları yok | Her ekranın onAppear içinde Otel.screen(…) çağırın |
| Telefondan veri gelmiyor | Telefon https://<spitfire> adresine ulaşabilmeli |