Getting Started
This page will show you how to get started with OpenTelemetry in Swift.
You will instrument a simple application to emit traces, metrics, and logs (including events) to the console.
Prerequisites
Ensure that you have the following installed locally:
Example Application
The following example uses a basic Vapor application. If you are not using Vapor, that’s OK — you can use OpenTelemetry Swift with any Swift application, no matter if they run on a server or on an iOS device.
For more examples, see examples.
Dependencies
To begin, create a file called Package.swift in a new directory with the
following content:
// swift-tools-version:6.0
import PackageDescription
let package = Package(
name: "dice-server",
platforms: [
.macOS(.v13)
],
dependencies: [
.package(url: "https://github.com/vapor/vapor.git", from: "4.99.0")
],
targets: [
.executableTarget(
name: "DiceApp",
dependencies: [
.product(name: "Vapor", package: "vapor")
],
path: "."
)
]
)
Create and launch an HTTP Server
In the same folder, create a file called main.swift and add the following code
to the file:
import Vapor
@main
enum Entrypoint {
static func main() async throws {
let app = try await Application.make(.detect())
do {
app.get("rolldice") { req in
let result = Int.random(in: 1..<7)
return String(result)
}
try await app.execute()
try await app.asyncShutdown()
} catch {
try? await app.asyncShutdown()
throw error
}
}
}
Build and run the application with the following command, then open http://localhost:8080/rolldice in your web browser to ensure it is working.
swift run
Stop the server with Ctrl+C before continuing.
Instrumentation
To add OpenTelemetry to your application, update Package.swift with the
following dependencies. Version 2.6.0 provides the APIs used below.
// swift-tools-version:6.0
import PackageDescription
let package = Package(
name: "dice-server",
platforms: [
.macOS(.v13)
],
dependencies: [
.package(url: "https://github.com/vapor/vapor.git", from: "4.99.0"),
.package(url: "https://github.com/open-telemetry/opentelemetry-swift-core.git", from: "2.6.0"),
.package(url: "https://github.com/open-telemetry/opentelemetry-swift.git", from: "2.6.0"),
],
targets: [
.executableTarget(
name: "DiceApp",
dependencies: [
.product(name: "Vapor", package: "vapor"),
.product(name: "OpenTelemetryApi", package: "opentelemetry-swift-core"),
.product(name: "OpenTelemetrySdk", package: "opentelemetry-swift-core"),
.product(name: "StdoutExporter", package: "opentelemetry-swift-core"),
.product(name: "ResourceExtension", package: "opentelemetry-swift"),
],
path: "."
)
]
)
Update main.swift to configure stdout exporters for all three signals. Each
rolldice request creates a server span, increments a counter, emits a log
record, and emits a named event:
import Vapor
import OpenTelemetryApi
import OpenTelemetrySdk
import StdoutExporter
import ResourceExtension
@main
enum Entrypoint {
static func main() async throws {
let resources = DefaultResources().get()
let instrumentationScopeName = "DiceServer"
let instrumentationScopeVersion = "semver:0.1.0"
let spanExporter = StdoutSpanExporter()
let spanProcessor = SimpleSpanProcessor(spanExporter: spanExporter)
OpenTelemetry.registerTracerProvider(tracerProvider:
TracerProviderBuilder()
.add(spanProcessor: spanProcessor)
.with(resource: resources)
.build()
)
let tracer = OpenTelemetry.instance.tracerProvider.get(
instrumentationName: instrumentationScopeName,
instrumentationVersion: instrumentationScopeVersion
)
let metricReader = PeriodicMetricReaderBuilder(
exporter: StdoutMetricExporter(isDebug: false)
).setInterval(timeInterval: 1).build()
let meterProvider = MeterProviderSdk.builder()
.setResource(resource: resources)
.registerMetricReader(reader: metricReader)
.registerView(
selector: InstrumentSelector.builder()
.setMeter(name: instrumentationScopeName)
.build(),
view: View.builder().build()
)
.build()
OpenTelemetry.registerMeterProvider(meterProvider: meterProvider)
let meter = meterProvider.meterBuilder(
name: instrumentationScopeName
).build()
let diceRolls = meter.counterBuilder(name: "dice.rolls").build()
OpenTelemetry.registerLoggerProvider(loggerProvider:
LoggerProviderBuilder()
.with(resource: resources)
.with(processors: [
SimpleLogRecordProcessor(logRecordExporter: StdoutLogExporter())
])
.build()
)
let logger = OpenTelemetry.instance.loggerProvider.get(
instrumentationScopeName: instrumentationScopeName
)
let app = try await Application.make(.detect())
do {
app.get("rolldice") { req in
tracer.spanBuilder(spanName: "GET /rolldice")
.setSpanKind(spanKind: .server)
.withActiveSpan { _ in
let result = Int.random(in: 1..<7)
diceRolls.add(value: 1)
logger.logRecordBuilder()
.setSeverity(.info)
.setBody(.string("Rolled a dice"))
.emit()
logger.logRecordBuilder()
.setEventName("dice.rolled")
.setAttributes(["dice.value": .int(result)])
.emit()
return String(result)
}
}
try await app.execute()
try await app.asyncShutdown()
} catch {
try? await app.asyncShutdown()
throw error
}
}
}
Start your server again, then send a request from another terminal:
swift run
curl http://localhost:8080/rolldice
The exporters print JSON to the server console. Look for these fields (IDs and dice values will vary):
| Signal | Fields in the output |
|---|---|
| Trace | span named GET /rolldice and spanKind set to server |
| Metric | name set to dice.rolls and a dataPoints value |
| Log | body containing Rolled a dice |
| Event | eventName set to dice.rolled and a dice.value attribute |
The view selects instruments from the DiceServer meter. The metric reader
exports cumulative counter values once per second. The event uses the logs API
and appears as a log record with an eventName.
withActiveSpan makes the request span active inside the closure, so the log
and event include its trace and span IDs. It ends the span when the closure
returns.
Next Steps
Enrich your instrumentation generated automatically with manual instrumentation of your own codebase. This gets you customized observability data.
Take a look at available instrumentation libraries that generate telemetry data for popular frameworks and libraries.
Feedback
Was this page helpful?
Thank you. Your feedback is appreciated!
Please let us know how we can improve this page. Your feedback is appreciated!