AWS Distro for OpenTelemetry

Auto-Instrumentation for Traces and RUM Events with the Swift Agent

Auto-Instrumentation for Traces and RUM Events with the Swift Agent

Introduction

The AWS Distro for OpenTelemetry (ADOT) Swift Auto-Instrumentation Agent can be installed onto any iOS application running on iOS 16+ to gather real user monitoring (RUM) telemetry data. The agent will automatically initialize the OpenTelemetry (OTel) SDK at application startup to collect tracing and RUM event data. It is preconfigured for compatibility with AWS CloudWatch RUM but can also be used with any other tracing backend. Out of the box, it propagates traces using W3C Trace Context.

The agent is the recommended way to instrument your iOS application for Traces and RUM Events.



Requirements

Currently, the Swift Agent is only officially supported on applications running on iOS 16 (or later). We do not have official out-of-the-box support for macOS, tvOS, watchOS, and visionOS at this time. Swift 5.9 (or later) is recommended to build the Agent into your application.



Installation

The ADOT Swift Agent is available to consume via Swift Package Manager (SPM). You should add the Swift SDK to your Package.swift :

1dependencies: [
2    .package(url: "https://github.com/aws-observability/aws-otel-swift.git", .upToNextMajor(from: "1.0.0"))
3]

Then, to start using the Agent, you will need to add AwsOpenTelemetryAgent to target dependencies:

1targets: [
2    .target(
3        name: "<your app target>",
4        dependencies: [
5            .product(name: "AwsOpenTelemetryAgent", package: "aws-otel-swift")
6        ]
7    )
8]

The AwsOpenTelemetryAgent dependency will automatically initialize the OTel SDK and instrument core vital signals out of the box in your application as Traces and RUM events. Next, you will need to configure the agent.



Configuring the agent with AWS CloudWatch RUM

ADOT Swift is pre-configured to work out of the box with AWS CloudWatch RUM. To export RUM telemetry to CloudWatch RUM, you will need to first create an app monitor, ideally with resource-based policies. Next, add aws_config.json to your application bundle:

1{
2  "aws": {
3    "region": "<your region>",
4    "rumAppMonitorId": "<your app monitor id>",
5    
6    // optional, if you have a resource-based policy with an alias
7    "rumAlias": "<your rum alias"
8  },
9  
10  // optional resource attributes, but recommended
11  "otelResourceAttributes": {
12    "service.name": "MyApplication",
13    "service.namespace": "MyTeam",
14    "service.version": "1.0.0",
15    "deployment.environment": "production"
16    // ... plus any additional custom resource attributes you want to define
17  }
18}

That's it! This is the minimum configuration to begin exporting RUM telemetry to CloudWatch RUM. From there, you can use CloudWatch RUM and CloudWatch Application Signals to monitor your application health and track long-term application performance against your business objectives.

Application Signals provides you with a unified, application-centric view of your applications, services, and dependencies, and helps you monitor and triage application health.

Get started with CloudWatch Application Signals

Use resource-based policies with CloudWatch RUM

Configuring session sampling

The agent can be configured to use a custom session id ratio sampler strategy for Traces. For example, to configure a session sampling rate of 30%:

1{
2  "aws": {
3    "region": "<your region>",
4    "rumAppMonitorId": "<your app monitor id>",
5  },
6  "otelResourceAttributes": {
7    "service.name": "MyApplication",
8    "service.version": "1.0.0"
9  },
10  "sessionSampleRate": 0.3
11}

Advanced configuration

For more advanced configuration options, refer to the ADOT Swift GitHub repository.



Telemetry you get out of the box

You can expect Auto-Instrumentation on the following:

  • App launch (cold, warm and pre-warm) spans
  • SwiftUI View lifecycle and performance spans
  • UIKit View lifecycle and performance spans
  • HTTP / HTTPS client spans and end-to-end tracing for URLSession requests
  • Crash reporting via KSCrash
  • Application hang reporting
  • Session monitoring that will keep track of individual real user sessions

For more information, refer to the aws-otel-swift documentation.

On this page