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@mainfile is) and Xcode
iOS
Create the key: Admin → Integrations → Add integration → Browser and app key, leave Allowed origins empty; copy
sfrum_…(APM).In Xcode: File → Add Package Dependencies…, paste this address, choose Exact Version
2.6.0, and add the productsOpenTelemetryProtocolExporterHTTP,SessionsandURLSessionInstrumentationto your app target:
https://github.com/open-telemetry/opentelemetry-swift- Create
/srv/app/MyApp/Otel.swift, paste, and add it to the app target:
// 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?) {}
}- Start it first. SwiftUI, in the
@mainApp:
init() {
Otel.start()
}- Name each screen when it appears (SwiftUI; UIKit: in
viewDidAppear):
.onAppear { Otel.screen("Cart") }- Report the errors you catch:
do { try await api.placeOrder() } catch { Otel.error(error) }- Build the release: Product → Archive.
Verify
- Spitfire takes the key from an app (no
Origin):
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- The app starts OpenTelemetry:
grep -rq 'Otel.start()' /srv/app/MyApp && grep -q 'IS_OTEL_ENABLED = "true"' /srv/app/MyApp/Otel.swift && echo OK- 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
- Turn off: in
Otel.swiftwritelet IS_OTEL_ENABLED = "false", then build again. - Remove: delete
Otel.swiftand theOtel.lines, then in Xcode remove theopentelemetry-swiftpackage (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> |