SpitfireLoad Testing & APMWhat's new

Connecting a native iOS app with OTel

A native iOS app (Swift, SwiftUI or UIKit) sends URLSession calls, sessions, screens, the app start and the errors you report with opentelemetry-swift. Calls link to your backend with traceparent, and the result shows under APM → End users. Shared values: overview.

Version table

Part Package Version
Swift package https://github.com/open-telemetry/opentelemetry-swift OpenTelemetryProtocolExporterHTTP, Sessions, URLSessionInstrumentation 2.6.0
Its dependency opentelemetry-swift-core OpenTelemetryApi, OpenTelemetrySdk 2.6.0
App iOS 13 and later
Build machine Xcode 16 and later (Swift 6 tools)

Find your version: xcodebuild -version. We wrote this guide from the package's 2.6.0 documentation and source and did not run it on a device. The limits, plainly: this package does not collect crashes (report the errors you catch with Otel.error(_:)), and Spitfire does not read dSYM files, so iOS stacks show as they come.

Verified: 2026-11-09. Source: OTel Swift, opentelemetry-swift 2.6.0.

What you need

  • Spitfire address https://<spitfire> (HTTPS: iOS refuses plain HTTP); service name <service-name>, version <service-version>, environment <environment>
  • The app's source folder (here /srv/app/MyApp, where the @main file is) and Xcode

iOS

  1. Create the key: Admin → Integrations → Add integration → Browser and app key, leave Allowed origins empty; copy sfrum_… (APM).

  2. In Xcode: File → Add Package Dependencies…, paste this address, choose Exact Version 2.6.0, and add the products OpenTelemetryProtocolExporterHTTP, Sessions and URLSessionInstrumentation to your app target:

text
https://github.com/open-telemetry/opentelemetry-swift
  1. Create /srv/app/MyApp/Otel.swift, paste, and add it to the app target:
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. Start it first. SwiftUI, in the @main App:
swift
init() {
  Otel.start()
}
  1. Name each screen when it appears (SwiftUI; UIKit: in viewDidAppear):
swift
.onAppear { Otel.screen("Cart") }
  1. Report the errors you catch:
swift
do { try await api.placeOrder() } catch { Otel.error(error) }
  1. Build the release: Product → Archive.

Verify

  1. Spitfire takes the key from an app (no Origin):
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. The app starts OpenTelemetry:
bash
grep -rq 'Otel.start()' /srv/app/MyApp && grep -q 'IS_OTEL_ENABLED = "true"' /srv/app/MyApp/Otel.swift && echo OK
  1. Open the app on a phone, then APM → End users: the app <service-name> shows an app start within a minute.

Turning off and removing

  1. Turn off: in Otel.swift write let IS_OTEL_ENABLED = "false", then build again.
  2. Remove: delete Otel.swift and the Otel. lines, then in Xcode remove the opentelemetry-swift package (Package Dependencies, −).

Common problems

Symptom Fix
No such module 'Sessions' Step 2: add the three products to the app target
Build error about Swift tools 6.0 Xcode 16 or later
401 The key is sfrum_… and enabled; OTEL_KEY holds it without Bearer
429 Raise the key's Exports per minute
Calls are not linked to a backend trace The calls must go through URLSession (Alamofire too, it uses URLSession)
No screen names Call Otel.screen(…) in each screen's onAppear
No data from the phone The phone must reach https://<spitfire>