> ## Documentation Index
> Fetch the complete documentation index at: https://docs.honeycomb.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Started with Honeycomb for iOS

> Instrument your iOS application with the Honeycomb OpenTelemetry Swift SDK, send telemetry to Honeycomb, and measure real device performance in production.

Use the [Honeycomb OpenTelemetry Swift SDK](https://github.com/honeycombio/honeycomb-opentelemetry-swift) to collect telemetry data from your iOS application and send it to Honeycomb.
Instrumenting your application lets you measure how it behaves on actual devices, detect performance issues, and better understand how users experience your application.

This guide walks you through the process of instrumenting an application in your local development environment and verifying that telemetry is successfully flowing to Honeycomb.

## Before You Begin

Before getting started, make sure you have:

* A Honeycomb account
  If you don't already have an account, sign up for one.
  Honeycomb stores your data in either a US-based or EU-based location, depending on your account region:

  * [Create a US account](https://ui.honeycomb.io/signup)
  * [Create an EU account](https://ui.eu1.honeycomb.io/signup)

* Required Tools

  * [Swift](https://www.swift.org/) 5.10+
  * An existing iOS 13+ application to instrument

* A Honeycomb Ingest API Key
  For this guide, you'll need a [Honeycomb Ingest API Key](/configure/environments/manage-api-keys/#create-api-key) with the **Can create services/datasets** permission.
  This key lets your application send telemetry to Honeycomb and create a dataset for your service.

  <Tip>
    When deploying to production, replace this key with a separate key that does not allow dataset creation.
    This helps protect your data structure in live environments.
  </Tip>

## Add Dependencies

To send telemetry from your application, add the Honeycomb OpenTelemetry Swift SDK to your project.
The Honeycomb OpenTelemetry Swift SDK is compatible with applications targeting iOS 13+.

### Using Xcode

If you manage dependencies using Xcode:

1. In Xcode, navigate to **File** > **Add Package Dependencies...**
2. When prompted for a repository URL, enter `https://github.com/honeycombio/honeycomb-opentelemetry-swift`.
3. Get the version number for the [latest release](https://github.com/honeycombio/honeycomb-opentelemetry-swift/releases).
4. [Add the `Honeycomb` package to your application's target dependencies](https://developer.apple.com/documentation/xcode/adding-package-dependencies-to-your-app).

### Using Package.swift

If you manage dependencies manually:

1. Add the SDK to your `Package.swift` file:

   ```swift theme={}
   dependencies: [
     .package(url: "https://github.com/honeycombio/honeycomb-opentelemetry-swift.git",
             from: "0.0.10")
   ],
   ```

2. Add `Honeycomb` to your target dependencies:

   ```swift theme={}
   dependencies: [
     .product(name: "Honeycomb", package: "honeycomb-opentelemetry-swift"),
   ],
   ```

## Configure the SDK

To start collecting telemetry, configure the SDK early in your application's lifecycle.
This ensures that events such as startup time and early view loads are captured.
We recommend setting it up in the `init()` method of your `App` class, or something equivalent.

Here's an example configuration using the `HoneycombOptions.Builder()`, which lets us use the builder pattern to set configuration options:

```swift theme={}
import Honeycomb
import SwiftUI

@main
struct ExampleApp: App {
    init() {
        do {
            let options = try HoneycombOptions.Builder()
                // Uncomment the line below to send to EU instance. Defaults to US.
                // .setAPIEndpoint("https://api.eu1.honeycomb.io:443")
                .setAPIKey("YOUR-API-KEY")
                .setServiceName("YOUR-SERVICE-NAME")
                .setServiceVersion("0.0.1")
                .setDebug(true)
                .build()
            try Honeycomb.configure(options: options)
        } catch {
            NSException(name: NSExceptionName("HoneycombOptionsError"),
                        reason: "\(error)").raise()
        }
    }
}
```

In this example, key configuration options include:

**APIEndpoint**
: URL where your telemetry is sent.
: Defaults to `https://api.honeycomb.io:443` (the Honeycomb US instance URL).
: For EU instances, set this to `https://api.eu1.honeycomb.io:443`.
: If you're using an OpenTelemetry Collector, use your collector's URL instead.

**APIKey**
: Your [Ingest API Key](/configure/environments/manage-api-keys/#create-api-key), which authorizes your application to send telemetry directly to Honeycomb.

**serviceName**
: The name of your application, which Honeycomb will use as your dataset name.
Choose something meaningful and consistent.

<Tip>
  If you don't provide a service name, the dataset name will be inferred from your bundle.
</Tip>

**serviceVersion**
: The current version of your application.
This helps track changes in behavior across different versions of your application.

**debug**
: Set to `true` to enable debug logs, which can help troubleshoot configuration issues during development.

### Enable Automatic Instrumentation

The Honeycomb OpenTelemetry Swift SDK includes built-in support for capturing common system and runtime events.
These can provide useful context without requiring additional code.
These include:

* [MetricKit](https://developer.apple.com/documentation/metrickit)
  : Captures system-level performance data, such as CPU and memory usage.
* [UIKit](https://developer.apple.com/documentation/uikit)
  : Captures view controller lifecycle events.
* Touch Events
  : Tracks screen touches and gestures.
  : This is off by default to reduce noise but may be useful for interaction-heavy apps.
* URLSession
  : Captures network requests made with `URLSession`.
* Unhandled Exceptions
  : Records crashes and other unhandled exceptions.

By default, most of these instrumentation libraries are enabled.
You can selectively turn them on or off in your configuration:

```swift theme={}
let options = try HoneycombOptions.Builder()
    // ...
    .setMetricKitInstrumentationEnabled(true)
    .setURLSessionInstrumentationEnabled(true)
    .setUIKitInstrumentationEnabled(true)
    .setTouchInstrumentationEnabled(false)
    .setUnhandledExceptionInstrumentationEnabled(true)
    // ...
    .build()

try Honeycomb.configure(options: options)
```

## Verify That Data is Being Sent

Once your application is instrumented, check that telemetry data is reaching Honeycomb:

1. Confirm that debugging is enabled by setting `.setDebug(true)` in your SDK configuration.

2. Build and run your application.

3. Check your logs for output like this:

   ```text theme={}
   🐝 Honeycomb SDK Debug Mode Enabled 🐝
   Honeycomb options: HoneycombOptions(...)
   Not sampling, emitting all spans
   ```

4. Log in to Honeycomb, and open your environment.
   You should see a new dataset named after your `serviceName` value.

If you don’t see any data, visit [Troubleshooting](#troubleshooting).

## Explore Your Data

Take a look at the data that you have generated using automatic instrumentation through the iOS Launchpad or a custom Board.

### Explore with the iOS Launchpad

If you're using [Honeycomb for Frontend Observability](https://www.honeycomb.io/frontend-observability/), the [iOS Launchpad](/observe/ios-launchpad/) provides a starting point for reviewing the telemetry from your iOS application.
The Launchpad helps you:

* Monitor cold start and resume times
* Detect app hangs and crashes
* Identify views with high render times

It's a great place to start exploring how your application behaves in real-world conditions.

### Explore using Boards

You can also explore your data by creating a [Board](/observe/boards/) from a [pre-configured Board template](/observe/boards/templates/).
Our specialized template for mobile iOS data includes a curated set of ready-made queries and visualizations based on the fields collected by the Honeycomb OpenTelemetry Swift SDK.

This template gives you an immediate, actionable view into common mobile metrics, like application start times, cold launches, crashes, and session flows, without needing to build anything from scratch.
You can use it as-is or customize it to fit your needs.

To learn more, visit [Use Board Templates](/observe/boards/templates/).

## Troubleshooting

Running into issues? Here are some common problems and ways to fix them.

<Tip>
  Still stuck? Check out our [Support Knowledge Base](/troubleshoot/customer-support/) or post a question in our [Pollinators Community](/troubleshoot/community/).
</Tip>

### My dataset isn't showing up in Honeycomb

Make sure that you:

* Replaced `"YOUR-API-KEY"` with a valid [Ingest API Key](/configure/environments/manage-api-keys/#create-api-key).
* Gave the key **Can create datasets** permission.

The Honeycomb OpenTelemetry Swift SDK uses the value passed to `.setApiKey()` to send your telemetry data.
This must be set correctly for data to reach Honeycomb.

### My dataset name looks wrong

Check the value passed to `.setServiceName()`.
This value determines the name of your dataset in Honeycomb.
If you leave it blank, the default will be inferred from your bundle, which might not be descriptive or consistent across builds.