Configuration

This page includes a comprehensive list of all the configurable parameters available for the agent, including those you can set during initialization and those you can adjust dynamically afterward.

Just getting started? Start with Getting started.

Available from the Elastic agent builder shown in Agent setup, the following are its available parameters.

Providing your application name, version, and environment:

class MyApp : android.app.Application {

    override fun onCreate() {
        super.onCreate()
        val agent = ElasticApmAgent.builder(this)
            .setServiceName("My app name") 
            .setServiceVersion("1.0.0") 
            .setDeploymentEnvironment("prod") 
            // ...
            .build()
    }
}

Configuring where your app’s telemetry will be exported.

class MyApp : android.app.Application {

    override fun onCreate() {
        super.onCreate()
        val agent = ElasticApmAgent.builder(this)
            // ...
            .setExportUrl("https://my-elastic-apm-collector.endpoint") 
            .setExportAuthentication(Authentication.ApiKey("my-api-key")) 
            .setExportProtocol(ExportProtocol.HTTP) 
            .build()
    }
}

You can provide an interceptor for the signals' export request headers, where you can read/modify them if needed.

class MyApp : android.app.Application {

    override fun onCreate() {
        super.onCreate()
        val agent = ElasticApmAgent.builder(this)
            // ...
            .setExportHeadersInterceptor(interceptor)
            .build()
    }
}

You can provide global interceptors for all spans and logs attributes, which will be executed on every span or log creation, where you can read/modify them if needed.

This is useful for setting dynamic global attributes. If you’d like to set static global attributes (which are also applied to metrics) take a look at intercepting resources.

class MyApp : android.app.Application {

    override fun onCreate() {
        super.onCreate()
        val agent = ElasticApmAgent.builder(this)
            // ...
            .addSpanAttributesInterceptor(interceptor)
            .addLogRecordAttributesInterceptor(interceptor)
            .build()
    }
}

The agent creates a resource for your signals, which is essentially a set of static global attributes. These attributes help Kibana properly display your application’s data.

You can intercept these resources and read/modify them as shown below.

class MyApp : android.app.Application {

    override fun onCreate() {
        super.onCreate()
        val agent = ElasticApmAgent.builder(this)
            // ...
            .setResourceInterceptor(interceptor)
            .build()
    }
}

The agent configures exporters for each signal (spans, logs, and metrics), to manage features like disk buffering and also to establish a connection with the Elastic export endpoint based on the provided export connectivity values. You can intercept these to add your own logic on top, such as logging each signal that gets exported, or filtering some items that don’t make sense for you to export.

class MyApp : android.app.Application {

    override fun onCreate() {
        super.onCreate()
        val agent = ElasticApmAgent.builder(this)
            // ...
            .addSpanExporterInterceptor(interceptor)
            .addLogRecordExporterInterceptor(interceptor)
            .addMetricExporterInterceptor(interceptor)
            .build()
    }
}

This is a convenience tool to intercept HTTP-related spans. By default, the agent enhances HTTP span names to include domain:port when only an HTTP verb is set, which is often the case for HTTP client span names.

You can override this behavior by setting your own interceptor (or you can choose to set it to null to just disable it all).

class MyApp : android.app.Application {

    override fun onCreate() {
        super.onCreate()
        val agent = ElasticApmAgent.builder(this)
            // ...
            .setHttpSpanInterceptor(interceptor)
            .build()
    }
}

Part of the work that the agent does when configuring the OpenTelemetry SDK on your behalf, is to provide processors, which are needed to delegate data to the exporters. For spans, the agent provides a BatchSpanProcessor; for logs, a BatchLogRecordProcessor; whereas for metrics, it’s a PeriodicMetricReader (which is analogous to a processor, despite not having that word included on its name).

In case you wanted to provide your own ones, you can do so by setting a custom ProcessorFactory, as shown below. The factory will be called once during initialization and will need to provide a processor per signal. Each processor-provider-method within the factory will contain the pre-configured exporter for that signal as an argument so that it’s included into the processor as its delegate exporter.

class MyApp : android.app.Application {

   override fun onCreate() {
      super.onCreate()
      val agent = ElasticApmAgent.builder(this)
         // ...
         .setProcessorFactory(factory)
         .build()
   }
}

The agent creates logs, by using Android’s Log type, to notify about its internal events so that you can check them out in logcat for debugging purposes. By default, all of the logs are printed for a debuggable app build, however, in the case of non-debuggable builds, only logs at the INFO level and above are printed.

If you would like to show some specific logs from the agent, or even disable them altogether, you can do so by providing your own LoggingPolicy configuration. The following example shows how to allow all logs of level WARN and higher to be printed, whereas those below WARN will be ignored.

class MyApp : android.app.Application {

    override fun onCreate() {
        super.onCreate()
        val agent = ElasticApmAgent.builder(this)
            // ...
            .setInternalLoggingPolicy(LoggingPolicy.enabled(LogLevel.WARN))
            .build()
    }
}

These are available from an already built agent.

You can change any of the configuration values provided as part of the export connectivity setters, at any time, by setting a new ExportEndpointConfiguration object, which will override them all.

class MyApp : android.app.Application {

    override fun onCreate() {
        super.onCreate()
        val agent = ElasticApmAgent.builder(this)
            // ...
            .build()
        agent.setExportEndpointConfiguration(configuration)
    }
}