SpitfireYük Testi ve APMYenilikler

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, @main dosyasının olduğu yer) ve Xcode

iOS

  1. 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).

  2. Xcode'da: File → Add Package Dependencies…, bu adresi yapıştırın, Exact Version 2.6.0 seçin, OpenTelemetryProtocolExporterHTTP, Sessions ve URLSessionInstrumentation ürünlerini uygulama target'ına ekleyin:

text
https://github.com/open-telemetry/opentelemetry-swift
  1. /srv/app/MyApp/Otel.swift dosyasını oluşturup yapıştırın ve uygulama target'ına ekleyin:
swift
// 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?) {}
}
  1. Önce onu başlatın. SwiftUI'da @main App içinde:
swift
init() {
  Otel.start()
}
  1. Her ekran göründüğünde adını verin (SwiftUI; UIKit: viewDidAppear içinde):
swift
.onAppear { Otel.screen("Cart") }
  1. Yakaladığınız hataları bildirin:
swift
do { try await api.placeOrder() } catch { Otel.error(error) }
  1. Release build alın: Product → Archive.

Doğrulama

  1. Spitfire anahtarı bir uygulamadan (Origin olmadan) kabul ediyor:
bash
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
  1. Uygulama OpenTelemetry'yi başlatıyor:
bash
grep -rq 'Otel.start()' /srv/app/MyApp && grep -q 'IS_OTEL_ENABLED = "true"' /srv/app/MyApp/Otel.swift && echo OK
  1. 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

  1. Kapatma: Otel.swift dosyasında let IS_OTEL_ENABLED = "false" yazın, yeniden build alın.
  2. Kaldırma: Otel.swift dosyasını ve Otel. satırlarını silin, sonra Xcode'da opentelemetry-swift paketini 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

İlgili sayfalar