Micrometer Dynatrace

DeepSeek V3 中英对照 Dynatrace Micrometer Dynatrace

Dynatrace 是一个软件智能平台，具备应用性能监控（APM）、面向运维的人工智能（AIOps）、IT 基础设施监控、数字体验管理（DEM）以及数字业务分析能力。它能够摄取多用途的维度时间序列数据，并内置了仪表板功能。该平台提供了 SaaS 和自托管（托管）两种部署方式。

1. 安装 micrometer-registry-dynatrace

建议使用 Micrometer（或您的框架，如果有）提供的 BOM，您可以在此处查看如何配置它 这里。以下示例假设您正在使用 BOM。

1.1. Gradle

在 配置 好 BOM 之后，添加以下依赖项：

implementation 'io.micrometer:micrometer-registry-dynatrace'

备注

由于版本由 BOM 定义，因此此依赖项不需要版本。

1.2. Maven

在 配置 好 BOM 之后，添加以下依赖：

<dependency>
  <groupId>io.micrometer</groupId>
  <artifactId>micrometer-registry-dynatrace</artifactId>
</dependency>

备注

此依赖项不需要指定版本，因为其版本由 BOM 定义。

2. 配置

为了与 Dynatrace 建立新的集成，我们建议使用最新版本的 Dynatrace Metrics API（当前版本为 2）。如果你在 Spring Boot 中使用 Micrometer，请参阅 Dynatrace 文档 和 Spring Boot 文档。Dynatrace 提供了多种设置集成的方式：

2.1. 使用 Dynatrace 自动配置（推荐）

Dynatrace 自动配置适用于由 OneAgent 或 Kubernetes 的 Dynatrace Operator 监控的主机。

如果 Dynatrace OneAgent 安装在运行 Micrometer 的主机上，可以直接通过 OneAgent 导出指标，而无需指定端点 URI 或 API 令牌。如果在 Kubernetes 中运行并安装了 Dynatrace Operator，注册表将从 Operator 中获取您的端点 URI 和 API 令牌。在这种情况下，无需进行任何配置，因此您可以在项目中使用以下代码将 Micrometer 指标导出到 Dynatrace：

DynatraceConfig dynatraceConfig = new DynatraceConfig() {
    @Override
    @Nullable
    public String get(String k) {
        // This method of the interface is used by the other configuration methods and needs to be
        // implemented here. Returning null accepts the defaults for the other configuration items.
        return null;
    }
};
MeterRegistry registry = new DynatraceMeterRegistry(dynatraceConfig, Clock.SYSTEM);

如果你使用的是 Micrometer 1.10.0 或更高版本，你也可以使用 DEFAULT 配置来实现相同的功能，同时减少代码量：

MeterRegistry registry = new DynatraceMeterRegistry(DynatraceConfig.DEFAULT, Clock.SYSTEM);

你也可以通过创建 DynatraceConfig 的实例并覆盖相应的方法来更改其他属性。例如，你可以指定导出器版本，默认情况下为 v2，除非设置了 deviceId：

DynatraceConfig dynatraceConfig = new DynatraceConfig() {
    @Override
    public DynatraceApiVersion apiVersion() {
        return DynatraceApiVersion.V2;
    }

    @Override
    @Nullable
    public String get(String k) {
        return null; // accept the rest of the defaults
    }
};
MeterRegistry registry = new DynatraceMeterRegistry(dynatraceConfig, Clock.SYSTEM);

DynatraceConfig 是一个包含一组默认方法的接口。Spring Boot 的 Micrometer 支持将前缀为 management.dynatrace.metrics.export 的属性直接绑定到 DynatraceConfig 上。

备注

在 Spring Boot 3.0.0 版本中，绑定属性的属性名称发生了变化。如果你使用的是 3.0.0 之前的 Spring Boot 版本，请使用 management.metrics.export.dynatrace 而不是 management.dynatrace.metrics.export。

使用 Spring Boot 的 Micrometer 支持可以通过可用的属性来配置 Dynatrace 导出器。当在 Spring Boot 中使用 Micrometer 时，你无需手动实例化 DynatraceMeterRegistry，因为 Spring Boot 会自动为你完成这一操作。所有可以通过重写方法设置的配置选项也可以通过 Spring Boot 的属性来设置，而添加一个单独的 MeterRegistry 可能会导致指标无法导出，因为自动配置可能会被破坏。

要在您的 Spring Boot 项目中使用 Dynatrace 的 Micrometer 指标导出器，请包含 runtimeOnly 'io.micrometer:micrometer-registry-dynatrace' 依赖项。在此默认配置中，指标将导出到本地的 OneAgent 或 Kubernetes 操作员提供的端点。

2.2. 使用自定义端点

如果主机上不可用自动配置，则必须指定 Dynatrace Metrics API v2 端点和 API 令牌。Dynatrace API 令牌文档 包含有关如何创建 API 令牌的更多信息。要摄取指标，令牌上需要具备“摄取指标”（metrics.ingest）权限。我们建议将范围限制为仅此权限。

DynatraceConfig dynatraceConfig = new DynatraceConfig() {
    @Override
    public DynatraceApiVersion apiVersion() {
        // not strictly required, but makes the code more clear/explicit
        return DynatraceApiVersion.V2;
    }

    @Override
    public String uri() {
        // The endpoint of the Dynatrace Metrics API v2 including path, e.g.:
        // "https://{your-environment-id}.live.dynatrace.com/api/v2/metrics/ingest"
        String endpoint = System.getenv("ENVVAR_METRICS_INGEST_URL");
        return endpoint != null ? endpoint : DynatraceConfig.super.uri();
    }

    @Override
    public String apiToken() {
        // should be read from a secure source
        String token = System.getenv("ENVVAR_METRICS_INGEST_TOKEN");
        return token != null ? token : "";
    }

    @Override
    @Nullable
    public String get(String k) {
        return null; // accept the rest of the defaults
    }
};
MeterRegistry registry = new DynatraceMeterRegistry(dynatraceConfig, Clock.SYSTEM);

这些属性也可以通过 Spring Boot 进行设置，使用属性文件或 yaml 文件即可。你还可以通过使用 Spring 属性占位符来引用环境变量（例如 management.dynatrace.metrics.export.uri: ${DT_METRICS_INGEST_URL}）。

备注

除非设置了 deviceId，否则 v2 将作为默认的 API 版本，如下所述 below。

# For Spring Boot 3.0.0 and above:
management.dynatrace.metrics.export:
# For Spring Boot versions below 3.0.0, use the line below instead of the line above:
# management.metrics.export.dynatrace:
    # for SaaS: https://\{your-environment-id}.live.dynatrace.com/api/v2/metrics/ingest
    # for managed deployments: https://{your-domain}/e/\{your-environment-id}/api/v2/metrics/ingest
    uri: YOUR_METRICS_INGEST_URL

    # should be read from a secure source
    api-token: YOUR_METRICS_INGEST_TOKEN

2.3. 仪表元数据

从 Micrometer 1.12.0 开始，Dynatrace 注册表 v2 将仪表元数据导出到 Dynatrace。目前支持的元数据类型包括 unit（在 Micrometer 中称为“基本单位”）和 description。无需任何更改即可开始将元数据导出到 Dynatrace —— 只需升级到 1.12.0 或更高版本即可。有关指标元数据的更多信息，请参阅 Dynatrace 文档。

可以通过将 DynatraceConfig 上的 exportMeterMetadata 属性设置为 false 来禁用指标元数据的导出（请参阅下面的可用属性部分）。

3. API 版本

3.1. API v2

当 API 版本配置为 v2 时，注册表会使用 Metrics API v2 发送数据。为了保持向后兼容性，当设置了 deviceId 时（v1 需要此参数，而 v2 不使用），默认使用 v1。否则，版本默认为 v2，无需显式设置。如果没有设置端点 URI 和令牌，指标将被导出到本地 OneAgent 端点，或者在 Kubernetes 环境中安装了 Dynatrace Operator 的情况下，导出到 Operator 提供的端点。如果不需要自动配置，您可以显式指定端点和令牌，将指标导出到该特定端点。显式指定这些参数将覆盖自动配置。

使用 Dynatrace 自动配置的最小配置

在前面展示的最小配置中（没有 URI 或 API 令牌），v2 注册表尝试检索由 Dynatrace Kubernetes 操作员提供的端点。如果操作员未设置或未提供此信息，导出器会尝试将指标发送到本地 OneAgent 指标接收端点。请注意，这仅在主机上运行了 OneAgent 并且本地 OneAgent 指标 API 可用时才能正常工作。如果本地 OneAgent 的接收端口更改为自定义端口，则必须为 URI 属性提供完整的端点 URI（API 令牌留空）。

使用 URI 和 API 令牌进行配置

如果没有可用的自动配置，或者指标需要发送到不同的端点（例如不同的租户），您可以使用显式端点 URI 和 API 令牌 来配置 Dynatrace v2 导出器。该 API 令牌 必须具有 "Ingest metrics" (metrics.ingest) 权限集。我们建议将权限范围限制为仅此权限。

你必须指定完整的 Metrics v2 API 端点 URI，包括其路径 —— 即在 SaaS 和托管部署中为 /api/v2/metrics/ingest 路径，或在 OneAgent 端点为 /metrics/ingest 路径，如文档中所述。

v2 导出器中的可用属性

在使用 Dynatrace 指标 API v2 时，您可以设置以下属性：

DynatraceConfig dynatraceConfig = new DynatraceConfig() {
    @Override
    public DynatraceApiVersion apiVersion() {
        return DynatraceApiVersion.V2;
    }

    @Override
    public String uri() {
        // The endpoint of the Dynatrace Metrics API v2 including path, e.g.:
        // "https://{your-environment-id}.live.dynatrace.com/api/v2/metrics/ingest".
        String endpoint = System.getenv("ENVVAR_METRICS_INGEST_URL");
        return endpoint != null ? endpoint : DynatraceConfig.super.uri();
    }

    @Override
    public String apiToken() {
        // should be read from a secure source
        String token = System.getenv("ENVVAR_METRICS_INGEST_TOKEN");
        return token != null ? token : "";
    }

    @Override
    public String metricKeyPrefix() {
        // will be prepended to all metric keys
        return "your.desired.prefix";
    }

    @Override
    public boolean enrichWithDynatraceMetadata() {
        return true;
    }

    @Override
    public Map<String, String> defaultDimensions() {
        // create and return a map containing the desired key-value pairs.
        Map<String, String> dims = new HashMap<>();
        dims.put("dimensionKey", "dimensionValue");
        return dims;
    }

    // Only available in Micrometer 1.9.0 and above
    @Override
    public boolean useDynatraceSummaryInstruments() {
        return false;
    }

    // Only available in Micrometer 1.12.0 and above
    @Override
    public boolean exportMeterMetadata() {
        return true;
    }

    @Override
    @Nullable
    public String get(String k) {
        return null; // accept the rest of the defaults
    }
};

你也可以在 Spring Boot 配置文件中设置这些属性：

management.dynatrace.metrics.export:
    # Required only if not using the OneAgent endpoint
    # For SaaS: https://{your-environment-id}.live.dynatrace.com/api/v2/metrics/ingest
    # For managed deployments: https://{your-domain}/e/{your-environment-id}/api/v2/metrics/ingest
    uri: YOUR_METRICS_INGEST_URL

    # should be read from a secure source
    api-token: YOUR_METRICS_INGEST_TOKEN

    # These properties can only be used with the v2 exporter.
    v2:
        # Sets a prefix that is prepended to each exported metric key.
        metric-key-prefix: my.metric.key.prefix

        # If set to true and a local OneAgent or operator is running, retrieves metadata
        # and adds it as additional dimensions to all data points (default: true)
        enrich-with-dynatrace-metadata: true

        # Sets an arbitrary number of key-value pairs as default dimensions.
        # Micrometer tags will overwrite these dimensions, if they have the same key.
        # Each exported metric will contain these dimensions.
        default-dimensions:
            key1: "value1"
            key2: "value2"

        # (since 1.9.0) Whether or not to use the Dynatrace-specific summary instruments. (default: true)
        # This should only be disabled if problems with existing instrumentation are discovered after upgrading to 1.9.0.
        # Set to false, this will restore the previous (1.8.x) behavior for Timers and DistributionSummaries.
        use-dynatrace-summary-instruments: true

        # (since 1.12.0) Determines whether meter metadata (unit, description) should be exported.
        export-meter-metadata: true

    # The export interval in which metrics are sent to Dynatrace (default: 60s).
    step: 60s

有关 Dynatrace 元数据丰富功能所提取的元数据的更多信息，请参阅 Dynatrace 文档。

在 Micrometer 1.9.0 中，引入了 Dynatrace 特定的摘要型仪器（DynatraceTimer 和 DynatraceDistributionSummary）。这些专门的仪器专为 Dynatrace 指标摄取而设计，并防止创建无效的指标。它们从 1.9.0 版本开始可用，并默认作为即插即用的替代品。升级到 1.9.0 的用户无需采取任何操作。如果观察到的指标存在差异，可以通过将 useDynatraceSummaryInstruments 切换设置为 false 来恢复到之前的行为。

3.2. API v1（旧版）

当 apiVersion 配置为 v1 时，注册表会使用 Dynatrace 自定义指标的 Timeseries API v1 发送数据。如果指定了 deviceId，则默认为 v1，以保持与早期设置的向后兼容性。device-id 属性在 v1 中是必需的，而在 v2 中不使用。在更新到较新版本的 Micrometer 时，现有设置将继续工作。报告的指标会被分配到 Dynatrace 中的 自定义设备。

对于 v1 API，不要指定摄取路径，只需指定环境的基础 URL，例如 uri: [\{your-environment-id}.live.dynatrace.com](https://{your-environment-id}.live.dynatrace.com)：

DynatraceConfig dynatraceConfig = new DynatraceConfig() {
    @Override
    public String uri() {
        // The Dynatrace environment URI without any path, e.g.:
        // https://{your-environment-id}.live.dynatrace.com
        return MY_DYNATRACE_URI;
    }

    @Override
    public String apiToken() {
        // should be read from a secure source
        return MY_TOKEN;
    }

    @Override
    public String deviceId() {
        return MY_DEVICE_ID;
    }

    @Override
    @Nullable
    public String get(String k) {
        return null; // accept the rest of the defaults
    }
};
MeterRegistry registry = new DynatraceMeterRegistry(dynatraceConfig, Clock.SYSTEM);

management.dynatrace.metrics.export:
    # For v1 export, do not append a path to the endpoint URL, e.g.:
    # For SaaS: https://{your-environment-id}.live.dynatrace.com
    # For managed deployments: https://{your-domain}/e/{your-environment-id}
    uri: https://{your-environment-id}.live.dynatrace.com

    # should be read from a secure source
    api-token: MY_TOKEN

    # When setting the device id, metrics will be exported to the v1 timeseries endpoint
    # Using just device-id (without the v1 prefix) is deprecated, but will work to maintain backwards compatibility.
    v1:
        device-id: sample

    # To disable Dynatrace publishing, e.g. in a local development profile, use:
    # enabled: false

    # The interval at which metrics are sent to Dynatrace. The default is 1 minute.
    step: 1m