News

Elastic APM iOS agent technical preview released

By
Bryce Buchanan

We are proud to announce the preview release of the Elastic APM iOS agent! This release is intended to elicit feedback from the community, while providing some initial functionality within the Elastic Observability stack and is not intended for production use. Now is your chance to influence the direction of this new iOS agent and let us know what you think on our discussion forum. If you find an issue, or would like to contribute yourself, visit the GitHub repository.

Elastic APM is an Application Performance Monitoring solution from Elastic and alongside the iOS agent, there are official agents available for Java, Node.js, Python, Ruby, JavaScript/RUM, .NET, PHP, and Go. Elastic APM helps you to gain insight into the performance of your application, track errors, and gauge the end-user experience in the browser.

I’ll be going into the details of the release below, but if you’re ready to jump into the documentation right away you can find it at the Elastic APM iOS agent documentation.

Supported frameworks

The Elastic APM iOS agent is built on the opentelementry-swift sdk. This means that any frameworks or libraries that are instrumented with Open Telemetry will be captured by the Elastic APM iOS agent. Additionally, any custom OTel instrumentation you add to your application will be picked up by our agent.

We are initially providing auto instrumentation of following:

  • URLSession
  • CPU & Memory usage
  • Network connectivity
  • Device & Application attributes

Our main focus is to provide insight into your backend services from the perspective of your mobile application, automatically displaying distributed traces starting at your mobile app.

Downloading the agent

The agent will initially be provided through the Swift Package Manager. It can be added to an iOS project through the Xcode SPM dependency manager or through a Package.swift file. 

Simply add the following to your Package.swift dependencies 

         dependencies: [ 
        .package(name: "apm-agent-ios", url: "https://github.com/elastic/apm-agent-ios", .branch(“v0.1.0")), 
…

And add “iOSAgent” to the targets you wish to instrument: 

.target( 
            name: "MyLibrary", 
            dependencies: [ 
                .product(name: "iOSAgent", package: "apm-agent-ios") 
            ]),

The agent API

The Elastic APM iOS Agent has a few project requirements:

  • It’s only compatible with Swift (sorry Objective-C engineers) 
  • It requires Swift v5.3
  • It requires the minimum of iOS v11

The agent API is fairly slim. We provide a configuration object that allows the agent to be set up for an on-prem or cloud solution.

If you’re using SwiftUI to build your app, you can set up the agent as follows:  

struct MyApp: App { 
    init() { 
        var config = AgentConfiguration() 
        config.collectorAddress = "127.0.0.1"  
        config.collectorPort = 8200  
        config.collectorTLS = false  
        config.secretToken = "<secret token>"  
        Agent.start(with: config) 
    }

 Read up more on configuration in the “Set up the Agent” doc.

The agent also captures any data recorded through the OpenTelementry-Swift APIs, including traces and metrics. Here’s an example on how to start a simple trace: 

let instrumentationLibraryName = "SimpleExporter" 
let instrumentationLibraryVersion = "semver:0.1.0" 
var instrumentationLibraryInfo = InstrumentationLibraryInfo(name: instrumentationLibraryName, version: instrumentationLibraryVersion) 
var tracer = OpenTelemetrySDK.instance.tracerProvider.get(instrumentationName: instrumentationLibraryName, instrumentationVersion: instrumentationLibraryVersion) as! TracerSdk 
func simpleSpan() { 
    let span = tracer.spanBuilder(spanName: "SimpleSpan").setSpanKind(spanKind: .client).startSpan() 
    span.setAttribute(key: sampleKey, value: sampleValue) 
    Thread.sleep(forTimeInterval: 0.5) 
    span.end() 
}

You can find more examples on how to use the OTel API at OpenTelementry-Swift examples.

If you decide to go this route, you may have to add OpenTelemetry-Swift as a dependency to your project as well. 

Summary and future

We would be thrilled to receive your feedback in our discussion forum or in our GitHub repository. Please keep in mind that the current release is a preview and we may introduce breaking changes. We are excited to be launching this mobile offering and already have many ideas for what comes next, but we want the community to help guide our direction. Check out our CONTRIBUTING.md and let the PRs fly!