Configure the EDOT iOS SDK

This page contains the configuration available for EDOT iOS, including values you set during initialization and values you can update remotely afterward.

Just getting started? Complete Agent setup first.

Create an AgentConfiguration with AgentConfigBuilder and pass it to ElasticApmAgent.start:

import ElasticApm
import Foundation

let configuration = AgentConfigBuilder()
  .withExportUrl(URL(string: "https://your-otlp-endpoint")!)
  .withApiKey("your-api-key")
  .build()

ElasticApmAgent.start(with: configuration)

Configure where EDOT iOS exports telemetry and which OTLP transport it uses:

let configuration = AgentConfigBuilder()
  .withExportUrl(URL(string: "https://collector.example.com:4318")!)
  .build()

1. The base endpoint that receives OTLP data.

Sets the required OTLP endpoint provided by an Elastic Agent OTLP endpoint or the Elastic Cloud Managed OTLP Endpoint. An enabled agent does not start without a valid http or https URL with a host.

When the connection type is .http, EDOT iOS appends /v1/traces, /v1/metrics, or /v1/logs to the configured path for each signal. When the connection type is .grpc, all signals use the configured gRPC endpoint.

Selects the OTLP transport:

• .grpc uses the OTLP/gRPC exporters.
• .http uses the OTLP/HTTP exporters.

OTLP/HTTP is the default. Use .useConnectionType(.grpc) only when the OTLP endpoint requires gRPC. The export URL controls security: https enables TLS and http uses plaintext. Make sure the endpoint supports the selected transport. An Elastic OTLP endpoint commonly listens on port 4317 for gRPC and 4318 for HTTP.

Sets a single URL host endpoint that handles both OTLP data export and central configuration. This option is deprecated: do not use it for new integrations. Use withExportUrl(_:) for OTLP data export and withManagementUrl(_:) for central configuration instead. It remains temporarily source compatible; when both URL methods are called, withExportUrl(_:) takes precedence.

AgentConfiguration.collectorHost, collectorPath, collectorPort, and collectorTLS are deprecated compatibility properties. Do not use them for new integrations. Configure the full endpoint with withExportUrl(_:) and start with ElasticApmAgent.start(with:) instead.

Existing integrations can temporarily mutate one or more of these properties after build(). When no full export URL is supplied, EDOT iOS synthesizes an HTTP(S) endpoint from their live values and logs a migration warning. When a full export URL is supplied, it remains authoritative, the mutations are ignored, and EDOT iOS logs an ignored-mutation warning.

EDOT iOS supports APM agent keys and secret tokens. Configure only one authentication method. If you call both methods, the last value set on the builder is used.

Sets an APM agent key and sends it in the Authorization header using the ApiKey scheme:

let configuration = AgentConfigBuilder()
  .withExportUrl(URL(string: "https://your-otlp-endpoint")!)
  .withApiKey("your-api-key")
  .build()

Create an APM agent key for EDOT SDKs to use least-privilege credentials.

Sets an APM secret token and sends it in the Authorization header using the Bearer scheme:

let configuration = AgentConfigBuilder()
  .withExportUrl(URL(string: "https://your-otlp-endpoint")!)
  .withSecretToken("your-secret-token")
  .build()

Refer to APM secret tokens for deployment requirements.

EDOT iOS retrieves central configuration from a central configuration (OpAMP) endpoint.

Sets the OpAMP endpoint used for central configuration. Set it explicitly and enable OpAMP:

let configuration = AgentConfigBuilder()
  .withExportUrl(URL(string: "https://your-otlp-endpoint")!)
  .withManagementUrl(
    URL(string: "https://your-opamp-endpoint:4320/v1/opamp")!
  )
  .useOpAMP()
  .build()

Enables OpAMP-based central configuration. When enabled, EDOT iOS treats withManagementUrl(_:) as an OpAMP endpoint.

Refer to Central configuration for the complete setup.

Set to true to start the legacy central configuration poll when OpAMP is not enabled. This setting does not affect central configuration selected with useOpAMP().

EDOT iOS emits current OpenTelemetry semantic-convention names by default.

Restores the telemetry names emitted before the semantic-convention cleanup. Use this temporary compatibility option only until dashboards, alerts, or other consumers migrate to the current names:

let configuration = AgentConfigBuilder()
  .withExportUrl(URL(string: "https://your-otlp-endpoint")!)
  .useLegacyAttributeNames(true)
  .build()

When enabled, this option restores the following legacy output:

• URLSession spans use the old HTTP attributes such as http.method, http.url, and http.status_code instead of stable HTTP attributes.
• Application lifecycle events use lifecycle and lifecycle.state instead of device.app.lifecycle and ios.app.state.
• CPU and memory gauges use system.cpu.usage and system.memory.usage with state set to app. CPU values use the previous percent-sum scale instead of the process.cpu.utilization ratio.
• Crash log records use the crash event name instead of app.crash.
• Build identity uses service.build instead of app.build_id, and telemetry.sdk.version uses the previous semver: prefix.

The option changes only these compatibility names and the CPU value coupled to its metric name. It does not turn off other fixes or instrumentation.

ElasticAttributes and all of its cases are deprecated in source in EDOT iOS 2.1.0. New integrations must use the upstream OpenTelemetry semantic convention constants:

• Replace ElasticAttributes.deviceIdentifier with SemanticConventions.Device.id.
• Replace ElasticAttributes.sessionId with SemanticConventions.Session.id.
• Replace ElasticAttributes.serviceBuild with SemanticConventions.App.buildId.
• ElasticAttributes.exportTimestamp has no semantic-convention attribute replacement. Use the timestamps carried by OpenTelemetry signals.

The deprecated enum remains available for source compatibility.

EDOT iOS makes a span sampling decision when a new app session begins.

Sets the probability that spans from a new session are sampled. A value of 1.0 samples every session, 0.0 samples none. Values outside this range are clamped to the closest valid value.

let configuration = AgentConfigBuilder()
  .withExportUrl(URL(string: "https://your-otlp-endpoint")!)
  .withSessionSampleRate(0.5)
  .build()

The sampling decision is reused for the session so related spans are kept together. A session expires after 30 minutes of inactivity.

Filters run before spans or log records are exported. Return true to keep a signal or false to drop it.

Adds a span filter:

let configuration = AgentConfigBuilder()
  .withExportUrl(URL(string: "https://your-otlp-endpoint")!)
  .addSpanFilter { span in
    span.name != "health-check"
  }
  .build()

You can add multiple filters. A span is dropped when any filter returns false.

Adds a log record filter:

let configuration = AgentConfigBuilder()
  .withExportUrl(URL(string: "https://your-otlp-endpoint")!)
  .addLogFilter { logRecord in
    logRecord.severity != .trace
  }
  .build()

You can add multiple filters. A log record is dropped when any filter returns false.

Attribute interceptors run on every span or log record and can read, add, replace, or remove attributes.

Adds an interceptor for span attributes:

import ElasticApm
import OpenTelemetryApi

let interceptor = ClosureInterceptor<[String: AttributeValue]> { attributes in
  var updatedAttributes = attributes
  updatedAttributes["myapp.release_channel"] = .string("beta")
  return updatedAttributes
}

let configuration = AgentConfigBuilder()
  .withExportUrl(URL(string: "https://your-otlp-endpoint")!)
  .addSpanAttributeInterceptor(interceptor)
  .build()

Adds an interceptor for log record attributes:

import ElasticApm
import OpenTelemetryApi

let interceptor = ClosureInterceptor<[String: AttributeValue]> { attributes in
  var updatedAttributes = attributes
  updatedAttributes["myapp.release_channel"] = .string("beta")
  return updatedAttributes
}

let configuration = AgentConfigBuilder()
  .withExportUrl(URL(string: "https://your-otlp-endpoint")!)
  .addLogRecordAttributeInterceptor(interceptor)
  .build()

You can add multiple interceptors. EDOT iOS runs them in the order they were added.

Adds an interceptor for the resource. When EDOT iOS starts, resource interceptors receive the detected resource attributes merged with OTEL_RESOURCE_ATTRIBUTES. Their output is the resource on every exported span, log record, and metric.

import ElasticApm
import OpenTelemetryApi
import OpenTelemetrySdk

let interceptor = ClosureInterceptor<Resource> { resource in
  resource.merging(other: Resource(attributes: [
    "myapp.release_channel": .string("beta")
  ]))
}

let configuration = AgentConfigBuilder()
  .withExportUrl(URL(string: "https://your-otlp-endpoint")!)
  .addResourceInterceptor(interceptor)
  .build()

If you add more than one resource interceptor, each one receives the output of the interceptor added before it.

Resource attribute keys must be non-empty, at most 255 characters long, and printable ASCII. When any key breaks these rules, Resource(attributes:) keeps none of the attributes passed to it. If the resource returned by an interceptor has no attributes, EDOT iOS ignores that interceptor's output, passes the resource it received on to the next interceptor, and logs an error.

Builds a configuration that prevents EDOT iOS from starting:

let configuration = AgentConfigBuilder()
  .disableAgent()
  .build()

ElasticApmAgent.start(with: configuration)

Use this when you need to keep the dependency in your app but disable it for a build or environment. Intentionally disabled configurations do not require an export URL because they do not initialize telemetry.

Create an InstrumentationConfiguration with InstrumentationConfigBuilder and pass it as the second argument to ElasticApmAgent.start:

let agentConfiguration = AgentConfigBuilder()
  .withExportUrl(URL(string: "https://your-otlp-endpoint")!)
  .build()

let instrumentationConfiguration = InstrumentationConfigBuilder()
  .withCrashReporting(false)
  .withSystemMetrics(false)
  .build()

ElasticApmAgent.start(
  with: agentConfiguration,
  instrumentationConfiguration
)

Turns crash reporting on or off.

Turns URLSession instrumentation on or off.

Turns SwiftUI and UIViewController instrumentation on or off.

Previously turned MetricKit instrumentation on or off. This option is deprecated and has no effect because MetricKit instrumentation is incompatible with OpenTelemetry-Swift 2.x metrics.

Turns CPU and memory metrics on or off.

Turns application lifecycle events on or off.

Configures persistent storage for traces, metrics, and logs:

let instrumentationConfiguration = InstrumentationConfigBuilder()
  .withPersistentStorageConfiguration(.instantDataDelivery)
  .build()

The available upstream presets are:

• .lowRuntimeImpact, the default, which favors lower runtime overhead.
• .instantDataDelivery, which checks for exportable data more often.

EDOT iOS detects app, device, operating system, process, and telemetry SDK resource attributes. It also reads custom resource attributes from OTEL_RESOURCE_ATTRIBUTES.

EDOT iOS 2.1+ The Elastic Distribution of OpenTelemetry (EDOT) iOS SDK collects performance metrics, traces, and logs in OpenTelemetry format, and sends them to Elastic Observability. Availability Generally available since 2.1 This functionality is generally available and ready for production usage. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. By default, the resource includes app.installation.id, a random UUID created the first time the app opens and persisted in UserDefaults for the lifetime of the installation. The default value resets when the app is uninstalled and is never derived from a device identifier.

To override this identifier or provide other custom resource attributes, set OTEL_RESOURCE_ATTRIBUTES in the process environment or your app's Info.plist:

<key>OTEL_RESOURCE_ATTRIBUTES</key>
<string>deployment.environment.name=staging,service.name=my-ios-app</string>

The format is a comma-separated list of key=value pairs. Values from the process environment override matching values from Info.plist.

EDOT iOS 2.2+ The Elastic Distribution of OpenTelemetry (EDOT) iOS SDK collects performance metrics, traces, and logs in OpenTelemetry format, and sends them to Elastic Observability. Availability Generally available since 2.2 This functionality is generally available and ready for production usage. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. To set resource attributes in code, use addResourceInterceptor(_:). Values set in code take precedence over OTEL_RESOURCE_ATTRIBUTES from both the process environment and Info.plist.

Resource attributes affect how Kibana identifies and groups telemetry. Take care when overriding attributes such as service.name, service.version, and deployment.environment.name.

EDOT iOS sets deployment.environment.name to default. Override it with OTEL_RESOURCE_ATTRIBUTES:

deployment.environment.name=staging

Dynamic settings can change after EDOT iOS starts. The SDK retrieves them through Central configuration.

Controls whether EDOT iOS processes and exports log records. Central configuration polling remains active when recording is disabled.

Controls the probability that spans from a new session are sampled. The value can range from 0.0 to 1.0.

The setting is evaluated when a new session begins. This keeps related spans together instead of making a separate decision for every span.

EDOT iOS receives central configuration from a central configuration (OpAMP) endpoint.

To use an OpAMP endpoint:

let configuration = AgentConfigBuilder()
  .withExportUrl(URL(string: "https://your-otlp-endpoint")!)
  .withManagementUrl(
    URL(string: "https://your-opamp-endpoint:4320/v1/opamp")!
  )
  .withApiKey("your-api-key")
  .useOpAMP()
  .build()

ElasticApmAgent.start(with: configuration)

Refer to Central configuration for EDOT SDKs for Elastic Agent and Kibana setup.

EDOT iOS 2.1+ The Elastic Distribution of OpenTelemetry (EDOT) iOS SDK collects performance metrics, traces, and logs in OpenTelemetry format, and sends them to Elastic Observability. Availability Generally available since 2.1 This functionality is generally available and ready for production usage. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. The OpAMP elastic config map uses these keys.