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")
  .useConnectionType(.http)
  .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")!)
  .useConnectionType(.http)
  .build()
		

1. The base endpoint that receives OTLP data.
2. The OTLP transport. Use .http for OTLP/HTTP or .grpc for OTLP/gRPC.

Sets the OTLP endpoint provided by an Elastic Agent or EDOT Collector gateway.

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.

Make sure the endpoint supports the selected transport. EDOT Collector 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: use withExportUrl(_:) for OTLP data export and withManagementUrl(_:) for central configuration instead.

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 an EDOT Collector through an 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-edot-collector: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.

Controls whether EDOT iOS contacts central configuration for runtime configuration updates. Set it to false to turn off remote management entirely.

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()
  .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()
  .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()
  .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["app.release_channel"] = .string("beta")
  return updatedAttributes
}

let configuration = AgentConfigBuilder()
  .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["app.release_channel"] = .string("beta")
  return updatedAttributes
}

let configuration = AgentConfigBuilder()
  .addLogRecordAttributeInterceptor(interceptor)
  .build()
		

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

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.

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.

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.

You can provide this value through 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.

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 an EDOT Collector through OpAMP.

To use an EDOT Collector OpAMP endpoint:

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

ElasticApmAgent.start(with: configuration)
		

Refer to Central configuration for EDOT SDKs for EDOT Collector and Kibana setup.