Configure the EDOT iOS SDK

Stack Serverless Observability EDOT iOS

Configure the SDK with AgentConfigBuilder passing the AgentConfiguration to the start function.

let config = AgentConfigBuilder() .withServerUrl(URL(string: "http://localhost:8200")) .withSecretToken("<Token>") .build() ElasticApmAgent.start(with:config) 

You can configure the AgentConfigBuilder with the following functions.

• Type: URL
• Default: nil

The URL host endpoint that handles both OTLP data export as well as Elastic Central Config. This configuration option is deprecated. Use withExportUrl instead.

• Type: URL
• Default: http://127.0.0.1:8200

The host endpoint handling OTLP exports. This configuration will override withServerUrl when set.

• Type: URL
• Default: ${exportUrl}/config/v1/agents

The URL endpoint that handles Elastic Central Config. It must be set with the correct path, e.g.: /config/v1/agents. For backwards compatibility purposes, if this config is unset the SDK will use the value set by withExportUrl as the host.

This config is intended to be used in conjunction with withExportUrl.

• Type: Bool
• Default: true

Controls whether the SDK attempts to contact Elastic Central Config for runtime configuration updates.

• Type: String
• Default: nil
• Env: OTEL_EXPORTER_OTLP_HEADERS

Sets the secret token for connecting to an authenticated APM Server. If using the env-var, the whole header map must be defined per OpenTelemetry Protocol Exporter Config (e.g.: OTEL_EXPORTER_OTLP_HEADERS="Authorization=bearer <secret token>")

This setting is mutually exclusive with withApiKey.

• Type: String
• Default: nil
• Env: OTEL_EXPORTER_OTLP_HEADERS

Sets the API Token for connecting to an authenticated APM Server. If using the env-var, the whole header map must be defined per OpenTelemetry Protocol Exporter Config (e.g.: OTEL_EXPORTER_OTLP_HEADERS="Authorization=ApiKey <key>")

This setting is mutually exclusive with withSecretToken

Turns off the Elastic SDK. This is useful for disabling the SDK during development without having to remove the Elastic SDK completely. A log will report "Elastic APM Agent has been disabled."

• Type: @escaping (ReadableSpan) → Bool
• Default: nil

Adds an anonymous function that will be executed on each span in the span processor to decide if that span should be sent to the back end.

• Type: @escaping (Metric) → Bool
• Default: nil

Adds an anonymous function that will be executed on each metric in the span processor to decide if that metric should be sent to the back end.

• Type: @escaping (ReadableLogRecord) → Bool
• Default: nil

Adds an anonymous function that will be executed on each log in the span processor to decide if that log should be sent to the back end.

• Type: any Interceptor<[String:AttributeValue>]
• Default: nil

You can provide interceptors for all spans attributes, which will be executed on every span created, where you can read/modify them if needed.

• Type: any Interceptor<[String:AttributeValue>]
• Default: nil

You can provide interceptors for all LogRecord attributes, which will be executed on every span created, where you can read or modify them if needed.

The ElasticApmAgent.start provides an additional optional parameter for configuring instrumentation. In the following example, an instrumentation configuration is passed to Agent.start with default values. This is equivalent to calling ElasticApmAgent.start with no instrumentation configuration passed.

let config = ... let instrumentationConfig = InstrumentationConfigBuilder().build() ElasticApmAgent.start(with:config, instrumentationConfig) 

You can configure the InstrumentationConfigBuilder with the following functions.

• Type: Bool
• Default: true

Use this option to turn on or turn off the crash reporting functionality of the agent.

• Type: Bool
• Default: true

Use this option to turn on or turn off the network tracing instrumentation.

• Type: Bool
• Default: true

Use this option to turn on or turn off the view controller tracing instrumentation.

• Type: Bool
• Default: true

Use this option to turn on or turn off MetricKit instrumentation.

• Type: Bool
• Default: true

Use this option to turn on or turn off systems metrics instrumentation (CPU & memory usage).

• Type: Bool
• Default: true

Use this option to turn on or turn off lifecycle events.

• Type: PersistencePerformancePreset
• Default: .lowRuntimeImpact

Use this option to configure the behavior of the persistent stores for traces, metrics, and logs.

In v0.5.0, the SDK provides a means to set resource attributes using the OTEL_RESOURCE_ATTRIBUTES env-var. This env-var also works through the application plist. Any resource attribute can be overridden using this method, so care should be taken, as some attributes are critical to the functioning of the kibana UI.

Deployment environment is set to default. This can be overridden using the OTEL_RESOURCE_ATTRIBUTES set in your deployment’s plist. Use the field key as OTEL_RESOURCE_ATTRIBUTES and the value as deployment.environment=staging

Dynamic configurations are available through the kibana UI and are read by the SDK remotely to apply configuration on all active agents deployed in the field. More info on dynamic configurations can be found in agent configurations.

A boolean specifying if the SDK should be recording or not. When recording, the SDK instruments incoming HTTP requests, tracks errors and collects and sends metrics. When not recording, the SDK works as a noop, not collecting data and not communicating with the APM sever, except for polling the central configuration endpoint. As this is a reversible switch, SDK threads are not being killed when inactivated, but they will be mostly idle in this state, so the overhead should be negligible.

You can set this setting to dynamically disable Elastic APM at runtime.

A double specifying the likelihood all data generated during a session should be recorded on a specific device. Value may range between 0 and 1. 1 meaning 100% likely, and 0 meaning 0% likely. Everytime a new session starts, this value will be checked against a random number between 0 and 1, and will sample all data recorded in that session of the random number is below the session sample rate set.

This session focused sampling technique is to preserve related data points, as opposed to sampling signal by signal, where valuable context can be lost.

You can set this value dynamically at runtime.