Merge pull request #26258 from pirgeo

* gh-26258:
  Polish "Refine documentation"
  Refine documentation
  Polish "Add properties for Dynatrace metrics API v2 ingest with Micrometer"
  Add properties for Dynatrace metrics API v2 ingest with Micrometer

Closes gh-26258

spring-boot-project/spring-boot-docs/src/docs/asciidoc/actuator/metrics.adoc

@@ -147,7 +147,68 @@ You can also change the interval at which metrics are sent to Datadog:
 
 [[actuator.metrics.export.dynatrace]]
 ==== Dynatrace
-Dynatrace registry pushes metrics to the configured URI periodically.
+Dynatrace offers two metrics ingest APIs, both of which are implemented for {micrometer-registry-docs}/dynatrace[Micrometer].
+Config properties in the `v1` namespace only apply when exporting to the {dynatrace-help}/dynatrace-api/environment-api/metric-v1/[Timeseries v1 API].
+Config properties in the `v2` namespace only apply when exporting to the {dynatrace-help}/dynatrace-api/environment-api/metric-v2/post-ingest-metrics/[Metrics v2 API].
+Please note that this integration can only export to either the `v1` or `v2` version of the API at a time.
+If the `device-id` (required for v1, but not used in v2) is set in the `v1` namespace, metrics will be exported to the `v1` endpoint.
+Otherwise, `v2` is assumed.
+
+
+
+[[actuator.metrics.export.dynatrace.v2-api]]
+===== v2 API
+The v2 API can be used in two ways.
+
+If a local OneAgent is running on the host, metrics will be automatically exported to the {dynatrace-help}/how-to-use-dynatrace/metrics/metric-ingestion/ingestion-methods/local-api/[local OneAgent ingest endpoint].
+The ingest endpoint forwards the metrics to the Dynatrace backend.
+This is the default behaviour and requires no special setup beyond a dependency on `io.micrometer:micrometer-registry-dynatrace`.
+
+If no local OneAgent is running, the endpoint of the {dynatrace-help}/dynatrace-api/environment-api/metric-v2/post-ingest-metrics/[Metrics v2 API] and an API token are required.
+The {dynatrace-help}/dynatrace-api/basics/dynatrace-api-authentication/[API token] must have the "Ingest metrics" (`metrics.ingest`) permission set.
+It is recommended to limit the scope of the token to this one permission.
+Please ensure that the endpoint URI contains the path (e.g. `/api/v2/metrics/ingest`).
+
+[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
+----
+	management:
+	  metrics:
+	    export:
+	      dynatrace:
+	        # uri: "https://{your-domain}/e/{your-environment-id}/api/v2/metrics/ingest" for managed deployments.
+	        uri: "https://{your-environment-id}.live.dynatrace.com/api/v2/metrics/ingest"
+	        api-token: "YOUR_TOKEN" # should be read from a secure source and not hard-coded.
+----
+
+When using the Dynatrace v2 API, the following optional features are available:
+
+* Metric key prefix: sets a prefix that will be prepended to all exported metric keys.
+* Enrich with Dynatrace metadata: if a OneAgent or Dynatrace operator is running, enrich metrics with additional metadata (e.g. about the host, process or pod).
+* Default dimensions: specify key-value pairs that are added to all exported metrics.
+  If tags with the same key are specified using Micrometer, they overwrite the default dimensions.
+
+
+[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
+----
+	management:
+	  metrics:
+	    export:
+	      dynatrace:
+	        # specify token and uri or leave blank for OneAgent export
+	        v2:
+	          metric-key-prefix: "your.key.prefix"
+	          enrich-with-dynatrace-metadata: true
+	          default-dimensions:
+	            key1: "value1"
+	            key2: "value2"
+----
+
+
+
+[[actuator.metrics.export.dynatrace.v1-api]]
+===== v1 API (Legacy)
+The Dynatrace v1 API metrics registry pushes metrics to the configured URI periodically using the {dynatrace-help}/dynatrace-api/environment-api/metric-v1/[Timeseries v1 API].
+For backwards-compatibility with existing setups, when `device-id` is set (required for v1, but not used in v2), metrics will be exported to the Timeseries v1 endpoint.
 To export metrics to {micrometer-registry-docs}/dynatrace[Dynatrace], your API token, device ID, and URI must be provided:
 
 [source,yaml,indent=0,subs="verbatim",configprops,configblocks]
@@ -156,12 +217,21 @@ To export metrics to {micrometer-registry-docs}/dynatrace[Dynatrace], your API t
 	  metrics:
 	    export:
 	      dynatrace:
-	        api-token: "YOUR_TOKEN"
-	        device-id: "YOUR_DEVICE_ID"
-	        uri: "YOUR_URI"
+	        # uri: "https://{your-domain}/e/{your-environment-id}" on managed deployments.
+	        uri: "https://{your-environment-id}.live.dynatrace.com"
+	        api-token: "YOUR_TOKEN" # should be read from a secure property source
+	        v1:
+	          device-id: "YOUR_DEVICE_ID"
 ----
 
-You can also change the interval at which metrics are sent to Dynatrace:
+For the v1 API, the base environment URI must be specified without a path as the v1 endpoint path will be added automatically.
+
+
+
+[[actuator.metrics.export.dynatrace.version-independent-settings]]
+===== Version-independent Settings
+In addition to the API endpoint and token, you can also change the interval at which metrics are sent to Dynatrace.
+The default export interval is `60s`.
 
 [source,yaml,indent=0,subs="verbatim",configprops,configblocks]
 ----
@@ -172,6 +242,8 @@ You can also change the interval at which metrics are sent to Dynatrace:
 	        step: "30s"
 ----
 
+More information on how to set up the Dynatrace exporter for Micrometer can be found in {micrometer-registry-docs}/dynatrace[the Micrometer documentation].
+
 
 
 [[actuator.metrics.export.elastic]]
@@ -188,8 +260,6 @@ The location of the Elastic server to use can be provided using the following pr
 	        host: "https://elastic.example.com:8086"
 ----
 
-
-
 [[actuator.metrics.export.ganglia]]
 ==== Ganglia
 By default, metrics are exported to {micrometer-registry-docs}/ganglia[Ganglia] running on your local machine.

spring-boot-project/spring-boot-docs/src/docs/asciidoc/attributes.adoc

@@ -93,6 +93,7 @@
 :spring-webservices-docs: https://docs.spring.io/spring-ws/docs/{spring-webservices-version}/reference/html/
 :ant-docs: https://ant.apache.org/manual
 :dependency-management-plugin-code: https://github.com/spring-gradle-plugins/dependency-management-plugin
+:dynatrace-help: https://www.dynatrace.com/support/help
 :embedded-mongo-code: https://github.com/flapdoodle-oss/de.flapdoodle.embed.mongo/blob/de.flapdoodle.embed.mongo-{embedded-mongo-version}
 :gradle-docs: https://docs.gradle.org/current/userguide
 :hibernate-docs: https://docs.jboss.org/hibernate/orm/5.4/userguide/html_single/Hibernate_User_Guide.html