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

配置

编辑

配置

编辑

此功能处于技术预览阶段，可能会在未来的版本中更改或删除。Elastic 将努力修复任何问题，但技术预览版中的功能不受正式 GA 功能的支持 SLA 约束。

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 代理时，在您的 应用程序类中提供。此配置将覆盖任何先前设置的编译时配置。

运行时配置通过提供您自己的 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 信号（Span、指标和日志），如下所示

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 之间的值。

信号过滤

编辑

您可以提供自己的过滤器来指定允许将哪些 Span、日志和指标导出到后端。使用此工具，您可以根据自己的业务逻辑，在运行时基本上打开和关闭某些（或全部）这些信号。

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

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 对象时，默认情况下禁用所有检测。仅使用构建器 setter 方法启用您需要的检测。

HTTP 配置

编辑

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

过滤不被跟踪的 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 请求的 Span 添加额外属性
编辑

如果默认提供的 HTTP Span 属性不够，您可以附加自己的 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);
    }
}

跟踪 Span 属性说明

编辑

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

属性 使用位置 需要权限

net.host.connection.subtype

所有 Span

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 用于所有信号（span、指标和日志）的处理器。代理会基于代理初始化期间传递的连接参数以及用于将数据发送到 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 之间的外观。如果您的项目需要配置整个 APM 流程的更高级方面，您可以使用 OpenTelemetry SDK 直接应用该配置，通过添加 Elastic 代理插件，可以在您的项目中使用该 SDK，如代理设置指南中所述。Elastic 代理将使用此配置来处理它开箱即用的信号。

动态配置 动态配置

编辑

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

选项参考

编辑

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

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

编辑

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

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

dynamic config

默认 类型 动态

true

布尔值

true

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

编辑

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

dynamic config

默认 类型 动态

1.0

浮点数

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