Set up the Agentedit

Requirementsedit

This project requires Swift 5.7, and is intended for use in Swift-base mobile apps.

Other platform requires:

Add the Agent dependencyedit

Add the Elastic APM iOS Agent to your Xcode project or your Package.swift.

Here are instructions for adding a package dependency to a standard Xcode poject.

Details of adding dependencies to your Package.swift can be found on Add a Dependency on Another Swift Package. Below is a helpful code-snippet:

package.swift:

Package(
    dependencies:[
         .package(name: "apm-agent-ios", url: "https://github.com/elastic/apm-agent-ios.git", from: "0.6.0"),
    ],
  targets:[
    .target(
        name: "MyApp",
        dependencies: [
            .product(name: "iOSAgent", package: "apm-agent-ios")
        ]
    ),
])

Initialize the agentedit

Once the Agent has been added as a dependency, it must be initialized.

If you’re using SwiftUI to build your app add the following to your App.swift:

import SwiftUI
import iOSAgent

@main
struct MyApp: App {
    init() {
        var config = AgentConfigBuilder()
                       .withServerUrl(URL(string:"http://127.0.0.1:8200")) 
                       .withSecretToken("<SecretToken>") 
                       .build()

        Agent.start(with: config)
    }
    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

If you’re not using SwiftUI you can alternatively add the same thing to your AppDelegate file:

AppDelegate.swift

import UIKit
import iOSAgent
@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
var config = AgentConfigBuilder()
                       .withServerUrl(URL(string:"http://127.0.0.1:8200")) 
                       .withSecretToken("<SecretToken>") 

        Agent.start(with: config)
        return true
    }
}

Instrumentation Configurationedit

An optional parameter for configuring instrumentation is also available on Agent.start:

    ...

    let instrumentationConfig = InstrumentationConfigBuilder()
                                         .withCrashReporting(true)
                                         .build()

    Agent.start(with: config, instrumentationConfig)

Configuration Optionsedit

withCrashReporting(_ enable: Bool) -> Selfedit

Toggle for crash reporting. Enabled by default. Since only one crash reporter can be set in iOS, this allows for 3rd party crash reporter preference without conflict.

withAppMetricInstrumentation(_ enable: Bool) -> Selfedit

Toggles AppMetric instrumentation.

withURLSessionInstrumentation(_ enable: Bool) -> Selfedit

Toggles network instrumentation.

withViewControllerInstrumentation(_ enable: Bool) -> Selfedit

Toggles view controller instrumentation.

withSystemMetrics(_ enable: Bool) -> Selfedit

Toggles metric generation for memory and cpu usage.

withLifecycleEvents(_ enable: Bool) -> Selfedit

Toggles event generation for lifecycle events.

View instrumentationedit

The agent provides SwiftUI.View and UIViewController instrumentation, where the load time of a View is measured using spans. All Views simultaneously loaded will be grouped under the same starting span. The spans' names will be dictated by the following rules, from least to highest precedence:

The View’s class name will be a swift name-mangled string, and is the least desirable naming method. If it’s possible, set a navigation title on your views:

AllProductsList.swift

struct AllProductsList: View {
    @EnvironmentObject var modelData : ModelData

    var body: some View {
        VStack {
            List(modelData.products, id: \.id) { product in
                AdminProductRow(product: product)

            }
        }.onAppear  {
            modelData.loadProducts()
        }.navigationTitle("All Products")
    }
}

You’ll see "All Products - view appearing" in Kibana.

If it isn’t possible to set a navigation title, use reportName(_ name: String) -> View to set the name that will show in Kibana:

AllProductsList.swift

struct AllProductsList: View {
    @EnvironmentObject var modelData : ModelData

    var body: some View {
        VStack {
            List(modelData.products, id: \.id) { product in
                AdminProductRow(product: product)

            }
        }.onAppear  {
            modelData.loadProducts()
        }.reportName("All Products - view appearing")
    }
}

MetricKit Instrumentationedit

Available for iOS 13 and greater, the agent provides instrumentation of key MetricKit data points:

Technical details on the metric generated can be found in the Mobile spec

application.launch.timeedit

This histogram metric provides launch duration broken down by first draw, first draw (optimized), and resumed. More details about the MetricKit data point can be found in the Apple documentation.

application.responsiveness.hangtimeedit

A histogram of the different durations of time in which the app is too busy to handle user interaction responsively. More details about the MetricKit data point can be found in the Apple documentation.

application.exitsedit

A count of application exits categorized by various attributes: foreground or background, and normal or abnormal, where abnormal exits are further subdivided. More details can be found in the Apple documentation.

Application Lifecycle Eventsedit

In v0.5.0 the application lifecycle events are automatically instrumented. The technical details can be found in the Mobile spec.