Configuration

Configure the agent 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)

The AgentConfigBuilder can be configured with the following functions:

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

• 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

Disables the Elastic agent. This is useful for disabling the agent during development without having to remove the Elastic agent 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.

The ElasticApmAgent.start provides an additional optional parameter for configuring instrumentation. In the below 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)

InstrumentationConfigBuilder can be configured with the following functions.

• Type: Bool
• Default: true

This option can be used to enable/disable the crash reporting functionality of the agent.

• Type: Bool
• Default: true

This option can be used to enable/disable the network tracing instrumentation.

• Type: Bool
• Default: true

This option can be used to enable/disable the view controller tracing instrumentation.

• Type: Bool
• Default: true

This option can be used to enable/disable MetricKit instrumentation.

• Type: Bool
• Default: true

This option can be used to enable/disable systems metrics instrumentation (CPU & memory usage).

• Type: Bool
• Default: true

This option can be used to enable/disable lifecycle events.

• Type: PersistencePerformancePreset
• Default: .lowRuntimeImpact

This option can be used to configure the behavior of the persistent stores for traces, metrics, and logs.

In v0.5.0, the agent 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 agent 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 agent should be recording or not. When recording, the agent instruments incoming HTTP requests, tracks errors and collects and sends metrics. When not recording, the agent 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, agent 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.