« 支持的技术 常见问题解答 »
Elastic 文档 ›

配置

编辑

配置编辑

Gradle 配置编辑

在应用程序的 build.gradle 文件中，在编译时配置您的应用程序

// Android app's build.gradle file
plugins {
    //...
    id "co.elastic.apm.android" version "[latest_version]" 
}

elasticApm {
    // Minimal configuration
    serverUrl = "https://your.elastic.server"

    // Optional
    serviceName = "your app name" 
    serviceVersion = "0.0.0" 
    apiKey = "your server api key" 
    secretToken = "your server auth token" 
}

您可以在 Gradle 插件门户 中找到最新版本。

默认为您的 android.defaultConfig.applicationId 值。

默认为您的 android.defaultConfig.versionName 值。

默认为 null。有关 API 密钥的更多信息，请 点击此处。

默认为 null。

当同时提供 secretToken 和 apiKey 时，apiKey 优先，secretToken 被忽略。

Gradle 配置中提供的所有值都可以使用以下环境变量覆盖

配置 关联的环境变量

serviceName

ELASTIC_APM_SERVICE_NAME

serviceVersion

ELASTIC_APM_SERVICE_VERSION

serverUrl

ELASTIC_APM_SERVER_URL

apiKey

ELASTIC_APM_API_KEY

secretToken

ELASTIC_APM_SECRET_TOKEN

运行时配置编辑

运行时配置在初始化 Elastic 代理时，在您的 Application 类中提供。此配置将覆盖任何先前设置的编译时配置。

运行时配置通过提供您自己的 ElasticApmConfiguration 类实例来实现，如下所示

// Application class

class MyApp extends android.app.Application {

    @Override
    public void onCreate() {
        super.onCreate();
        ElasticApmAgent.initialize(this, ElasticApmConfiguration.builder().build());
    }
}

APM 服务器连接编辑

APM 服务器连接参数可以在编译时提供，方法是使用 Gradle DSL 配置或提供如上所述的 APM 服务器连接相关环境变量。之后，当应用程序运行时，可以通过在初始化 Elastic 代理时提供自定义 Connectivity 实例来覆盖连接参数。

创建 Connectivity 实例后，您可以将其设置到代理的初始化中，如下所示

class MyApp extends android.app.Application {

    @Override
    public void onCreate() {
        super.onCreate();
        Connectivity myCustomConnectivity = Connectivity.simple(/*params*/);
        ElasticApmAgent.initialize(this, myCustomConnectivity);

        // Optionally if you also define a custom configuration:
        // ElasticApmAgent.initialize(this, ElasticApmConfiguration.builder().build(), myCustomConnectivity);
    }
}

OpenTelemetry 资源编辑

您可以提供您自己的 资源 对象，该对象将用于所有 OpenTelemetry 信号（跨度、指标和日志），如下所示

class MyApp extends android.app.Application {

    @Override
    public void onCreate() {
        super.onCreate();

        Resource myResource = Resource.create(Attributes.builder().put(RESOURCE_KEY, RESOURCE_VALUE).build());
        ElasticApmConfiguration configuration = ElasticApmConfiguration.builder()
                .setResource(myResource)
                .build();
        ElasticApmAgent.initialize(this, configuration);
    }
}

APM 服务器导出协议编辑

信号默认使用 gRPC 协议导出。您可以使用 ExportProtocol 配置将导出协议更改为 HTTP，如下所示

class MyApp extends android.app.Application {

    @Override
    public void onCreate() {
        super.onCreate();
        ElasticApmConfiguration configuration = ElasticApmConfiguration.builder()
                .setExportProtocol(ExportProtocol.HTTP) 
                .build();
        ElasticApmAgent.initialize(this, configuration);
    }
}

请注意，如果设置了 自定义信号配置，此配置可能无法正常工作。

APM 服务器版本 8.3.0+ 支持通过 HTTP 协议传输 OTLP。APM 服务器版本 7.12.0+ 支持通过 gRPC 协议传输 OTLP。

持久化配置编辑

默认情况下，所有 APM 数据都会立即发送到后端。但是，对于 Android 应用程序来说，这可能不可行或不可取。例如，Android 设备可能会遇到网络问题，或者由于移动数据连接和电池寿命，设备可能需要以特定方式处理资源。为了防止这些问题，代理提供了磁盘持久化或本地缓存支持。这使您能够首先将 APM 数据存储在磁盘中，并定义数据应该多久导出到后端一次。

以下示例展示了如何启用和配置持久化功能。

class MyApp extends android.app.Application {

    @Override
    public void onCreate() {
        super.onCreate();
        PersistenceConfiguration persistenceConfiguration = PersistenceConfiguration.builder()
                .setEnabled(true) 
                .setMaxCacheSize(60 * 1024 * 1024) 
                .setExportScheduler(ExportScheduler.getDefault(60 * 1000)) 
                .build();
        ElasticApmConfiguration configuration = ElasticApmConfiguration.builder()
                .setPersistenceConfiguration(persistenceConfiguration)
                .build();
        ElasticApmAgent.initialize(this, configuration);
    }
}

默认为 false。

默认为 60 MB。

默认为一分钟。默认的 ExportScheduler 仅在主机应用程序运行时运行，但您可以创建自己的实现来为您的应用程序提供更合适的调度程序。

应用程序 ID 配置编辑

在构建 ElasticApmConfiguration 实例时，您可以动态提供应用程序名称、版本和环境，如下所示

class MyApp extends android.app.Application {

    @Override
    public void onCreate() {
        super.onCreate();
        ElasticApmConfiguration configuration = ElasticApmConfiguration.builder()
                .setServiceName("my-custom-name")
                .setServiceVersion("1.0.0")
                .setDeploymentEnvironment("debug")
                .build();
        ElasticApmAgent.initialize(this, configuration);
    }
}

采样率配置编辑

采样率应用于 会话，这意味着如果采样率值为 0.5，则只有半数会话会被采样。您可以设置一个会话采样率，该采样率将在每次创建新会话时进行评估，以确定是否导出或忽略整个会话。会话目前是基于时间的，并且至少会保持 30 分钟的活动状态。在计时器结束之前，每个信号都会发送一个 session.id 属性，并在创建新信号时重置计时器。

当时间到期时，将生成一个新的会话 ID，并评估采样率以确定是否导出或忽略新会话的信号。

您可以通过编程方式（如下所示）或通过 中央配置 远程设置采样率值。通过中央配置设置的值将覆盖通过编程方式设置的值。

class MyApp extends android.app.Application {

    @Override
    public void onCreate() {
        super.onCreate();
        ElasticApmConfiguration configuration = ElasticApmConfiguration.builder()
                .setSampleRate(0.5) 
                .build();
        ElasticApmAgent.initialize(this, configuration);
    }
}

仅限 0 到 1 之间的值。

信号过滤编辑

您可以提供您自己的过滤器来指定哪些跨度、日志和指标可以导出到后端。使用此工具，您可以在运行时根据自己的业务逻辑实质上打开或关闭其中一些信号（或全部信号）。

为此，您需要在代理配置中为每个信号提供您自己的过滤器，如下所示

class MyApp extends android.app.Application {

    @Override
    public void onCreate() {
        super.onCreate();
        ElasticApmConfiguration configuration = ElasticApmConfiguration.builder()
                .addLogFilter(new LogFilter(){/*...*/})
                .addMetricFilter(new MetricFilter(){/*...*/})
//                .addMetricFilter(new MetricFilter(){/*...*/}) You can add multiple filters per signal.
                .addSpanFilter(new SpanFilter() {
                    @Override
                    public boolean shouldInclude(ReadableSpan readableSpan) {
                        if (thisSpanIsAllowedToContinue(readableSpan)) {
                            return true;
                        }
                        return false;
                    }
                })
                .build();
        ElasticApmAgent.initialize(this, configuration);
    }
}

每个过滤器都将包含一个 shouldInclude 函数，该函数提供要评估的信号项。此函数必须返回一个布尔值——当提供的项允许继续时返回 true，当必须丢弃该项时返回 false。

您可以为每个信号添加多个过滤器，这些过滤器将被迭代（按添加顺序），直到所有过滤器都被检查或直到其中一个过滤器决定丢弃提供的信号项。

自动检测启用/禁用编辑

代理为其 支持的技术 提供自动检测，这些检测默认情况下都已启用。您可以选择哪些要保持启用状态，以及在运行时禁用不需要的检测，如下所示

class MyApp extends android.app.Application {

    @Override
    public void onCreate() {
        super.onCreate();

        // When building an InstrumentationConfiguration object using `InstrumentationConfiguration.builder()`
        // all of the instrumentations are disabled by default, so you only need to enable the ones you need.
        InstrumentationConfiguration instrumentations = InstrumentationConfiguration.builder()
            .enableHttpTracing(true)
            .build();
        ElasticApmConfiguration configuration = ElasticApmConfiguration.builder()
                .setInstrumentationConfiguration(instrumentations)
                .build();
        ElasticApmAgent.initialize(this, configuration);
    }
}

使用 InstrumentationConfiguration.builder() 构建 InstrumentationConfiguration 对象时，所有检测默认情况下都已禁用。仅使用构建器设置方法启用您需要的检测。

HTTP 配置编辑

代理为 HTTP 相关的跨度提供了一个名为 HttpTraceConfiguration 的配置对象。您可以在初始化代理时将它的实例传递给 ElasticApmConfiguration 对象，以自定义如何处理 HTTP 跨度。

过滤 HTTP 请求以防止被跟踪编辑

默认情况下，您的应用程序的所有 HTTP 请求都会被跟踪。您可以通过创建您自己的 HttpExclusionRule 来避免某些请求被跟踪。例如，这是一个排除规则，它可以防止所有主机为 127.0.0.1 的请求被跟踪

class MyHttpExclusionRule extends HttpExclusionRule {

    @Override
    public boolean exclude(HttpRequest request) {
        return request.url.getHost().equals("127.0.0.1");
    }
}

然后，您需要通过其 HttpTraceConfiguration 将其添加到 Elastic 的代理配置中，如下所示

class MyApp extends android.app.Application {

    @Override
    public void onCreate() {
        super.onCreate();
        HttpTraceConfiguration httpConfig = HttpTraceConfiguration.builder()
            .addExclusionRule(new MyHttpExclusionRule())
            .build();
        ElasticApmConfiguration configuration = ElasticApmConfiguration.builder()
                .setHttpTraceConfiguration(httpConfig)
                .build();
        ElasticApmAgent.initialize(this, configuration);
    }
}
向 HTTP 请求的跨度添加额外的属性编辑

如果 默认提供的 HTTP 跨度属性不够，您可以附加您自己的 HttpAttributesVisitor 来向每个被跟踪的 HTTP 请求添加额外的参数。例如

class MyHttpAttributesVisitor implements HttpAttributesVisitor {

    public void visit(AttributesBuilder attrsBuilder, HttpRequest request) {
        attrsBuilder.put("my_custom_attr_key", "my_custom_attr_value");
    }
}

然后，您需要通过其 HttpTraceConfiguration 将其添加到 Elastic 的代理配置中，如下所示

class MyApp extends android.app.Application {

    @Override
    public void onCreate() {
        super.onCreate();
        HttpTraceConfiguration httpConfig = HttpTraceConfiguration.builder()
        .addHttpAttributesVisitor(new MyHttpAttributesVisitor())
        .build();
        ElasticApmConfiguration configuration = ElasticApmConfiguration.builder()
                .setHttpTraceConfiguration(httpConfig)
                .build();
        ElasticApmAgent.initialize(this, configuration);
    }
}

跟踪跨度属性说明编辑

Elastic APM 代理会为每个跨度收集 通用属性。但是，由于 Android 操作系统的性质，要收集一些与设备相关的数据，上述资源中的一些需要主机应用程序（您的应用程序）授予特定的运行时权限。如果没有授予相应的权限，则不会收集设备数据，并且不会发送这些属性的任何内容。此表概述了属性及其相应的权限

属性 使用于 需要权限

net.host.connection.subtype

所有跨度

READ_PHONE_STATE

内部日志记录策略编辑

默认情况下，此库创建的所有日志都会为可调试应用程序构建打印出来。对于不可调试构建，仅打印 INFO 级别及以上的日志。

如果您想创建自定义日志策略，甚至完全禁用来自此库的所有日志，您可以通过提供您自己的 LoggingPolicy 配置来实现。以下示例策略将允许打印所有级别为 WARN 及更高的日志。低于 WARN 的级别将被忽略。

class MyApp extends android.app.Application {

    @Override
    public void onCreate() {
        super.onCreate();
        // This example policy will allow all logs of level WARN and higher to get printed, ignoring levels below it.
        LoggingPolicy loggingPolicy = LoggingPolicy.enabled(LogLevel.WARN);

        ElasticApmConfiguration.builder()
                .setLibraryLoggingPolicy(loggingPolicy)
                .build();
        ElasticApmAgent.initialize(this, configuration);
    }
}

高级可配置选项编辑

自定义 SignalConfiguration编辑

SignalConfiguration 对象包含 OpenTelemetry 的所有信号处理器：跨度、指标和日志。代理会根据代理初始化期间传递的 连接性参数 以及为将数据发送到 APM Server 选择的 导出协议 创建默认的 SignalConfiguration 实现。但是，如果您需要更多地控制 OpenTelemetry 的处理器和导出器，您可以覆盖默认的 SignalConfiguration 对象，并提供您自己的自定义处理器和/或导出器，如下所示

class MyApp extends android.app.Application {

    @Override
    public void onCreate() {
        super.onCreate();
        SpanExporter mySpanExporter;
        LogRecordExporter myLogRecordExporter;
        MetricExporter myMetricExporter;

        // You could also pass processors instead of exporters.
        SignalConfiguration mySignalConfiguration = SignalConfiguration.custom(mySpanExporter, myLogRecordExporter, myMetricExporter); 

        ElasticApmConfiguration.builder()
                .setSignalConfiguration(mySignalConfiguration)
                .build();
        ElasticApmAgent.initialize(this, configuration);
    }
}

您可以为 SignalConfiguration 接口创建自己的实现，也可以使用 SignalConfiguration.custom 函数并传递您对 OpenTelemetry 处理器和/或导出器的实现。

来自 OpenTelemetry SDK 的进一步配置。编辑

Elastic APM 代理提供的可配置参数旨在帮助以简单的方式配置常见用例，在大多数情况下，这意味着充当您的应用程序和 OpenTelemetry Java SDK 之间的门面，该代理构建在此 SDK 之上。如果您的项目需要配置 APM 进程的更高级方面，您可以直接使用 OpenTelemetry SDK 应用该配置，该 SDK 通过添加 Elastic 代理插件在您的项目中可用，如 代理设置指南 中所述。该配置将由 Elastic 代理用于它开箱即用的 信号。

动态配置 动态配置编辑

标记为“动态”为真的配置选项可以在运行时从 Kibana 的 中央配置 设置时更改。

选项参考编辑

这是所有配置选项的列表。

recording ( [0.4.0] 在 0.4.0 中添加。 )编辑

一个布尔值，指定代理是否应该记录。当记录时，代理会检测传入的 HTTP 请求，跟踪错误并收集和发送指标。当不记录时，代理会作为无操作工作，不会收集数据，也不会与 APM 服务器通信，除了轮询中央配置端点。由于这是一个可逆的开关，代理线程在停用时不会被杀死，但它们在此状态下将大部分处于空闲状态，因此开销应该可以忽略不计。

您可以使用此设置在运行时动态禁用 Elastic APM。

dynamic config

默认值 类型 动态

true

布尔值

true

session_sample_rate ( [0.9.0] 在 0.9.0 中添加。 )编辑

默认情况下，代理将对您的应用程序生成的（例如跨度、指标和日志）的所有信号进行采样。为了减少开销和存储需求，您可以将采样率设置为 0.0 到 1.0 之间的值。当降低到低于 1.0 时，数据将按会话进行采样。这样做是为了避免在给定会话中丢失上下文。您可以使用此设置通过将采样率设置为 0 在运行时动态禁用 Elastic APM。

dynamic config

默认值 类型 动态

1.0

浮点数

true
« 支持的技术 常见问题解答 »