Update documentation with Dynatrace API v2 usage information

src/docs/implementations/dynatrace.adoc

@@ -3,27 +3,263 @@
 :sectnums:
 :system: dynatrace
 
-Dynatrace is a dimensional time-series SaaS with built-in dashboarding.
+https://www.dynatrace.com/[*Dynatrace*] is a Software Intelligence Platform featuring application performance monitoring (APM), artificial intelligence for operations (AIOps), IT infrastructure monitoring, digital experience management (DEM), and digital business analytics capabilities.
+It can ingest multi-purpose dimensional time-series data and has built-in dashboarding. Both SaaS and self-hosted (Managed) deployments are offered.
 
 include::install.adoc[]
 
 == Configuring
 
-The following listing configures a Dynatrace instance:
+For setting up new integrations with Dynatrace, it is recommended to use the latest version of the https://www.dynatrace.com/support/help/dynatrace-api/environment-api/metric-v2/[Dynatrace Metrics API] (v2).
+Dynatrace provides different ways of setting up integrations:
+
+=== Using a Dynatrace OneAgent installed on the host (preferred) [[bookmark-oneagent-example]]
+
+If a Dynatrace OneAgent is installed on the host running Micrometer, metrics can be exported directly using the OneAgent without having to specify an endpoint URI or API token.
+Use the following code in your project to export Micrometer metrics to the https://www.dynatrace.com/support/help/how-to-use-dynatrace/metrics/metric-ingestion/ingestion-methods/local-api/[local OneAgent endpoint]:
+
+[source,java]
+----
+DynatraceConfig dynatraceConfig = new DynatraceConfig() {
+    @Override
+    @Nullable
+    public String get(String k) {
+        // This method for retrieving arbitrary config items introduced by the interface is currently not used in DynatraceConfig.
+        return null;
+    }
+};
+MeterRegistry registry = new DynatraceMeterRegistry(dynatraceConfig, Clock.SYSTEM);
+Metrics.addRegistry(registry);
+----
+
+It is also possible to specify the exporter version explicitly, which defaults to `v2` unless a deviceId is set:
+
+[source,java]
+----
+DynatraceConfig dynatraceConfig = new DynatraceConfig() {
+    @Override
+    public DynatraceApiVersion apiVersion() {
+        return DynatraceApiVersion.V2;
+    }
+
+    @Override
+    @Nullable
+    public String get(String k) { return null; }
+};
+----
+
+
+`DynatraceConfig` is an interface with a set of default methods.
+Micrometer's Spring Boot support binds properties prefixed with `management.metrics.export.dynatrace` directly to the `DynatraceConfig`.
+This allows configuring the Dynatrace exporter by using the <<bookmark-available-properties, the available properties>>.
+
+To use the Dynatrace metrics exporter for Micrometer in your Spring Boot project, it is enough to include the `runtimeOnly 'io.micrometer:micrometer-registry-dynatrace'` dependency.
+In this default configuration, metrics will be exported to the local OneAgent endpoint.
+
+=== Using a custom endpoint
+
+If no Dynatrace OneAgent is available on the host, both the Dynatrace Metrics API v2 endpoint and an API token have to be specified.
+The https://www.dynatrace.com/support/help/dynatrace-api/basics/dynatrace-api-authentication/[Dynatrace API token documentation] contains more information on how to create an API token.
+The 'Ingest metrics' (`metrics.ingest`) permission is required on the token in order to ingest metrics.
+It is recommended to limit scope to only this permission.
 
 [source,java]
 ----
 DynatraceConfig dynatraceConfig = new DynatraceConfig() {
+    @Override
+    public DynatraceApiVersion apiVersion() {
+        // not strictly required, but makes the code more clear.
+        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".
+        // Should be read from a secure source and not hard-coded.
+        // This example shows how it could be read from an environment variable:
+        String endpoint = System.getenv("YOUR_METRICS_INGEST_URL");
+        return endpoint != null ? endpoint : DynatraceConfig.super.uri();
+    }
+
     @Override
     public String apiToken() {
-        return MY_TOKEN;
+        // It is *not* recommended to place secrets in config files but to read them from a secure source.
+        String token = System.getenv("YOUR_METRICS_INGEST_TOKEN");
+        return token != null ? token : "";
     }
 
+    @Override
+    @Nullable
+    public String get(String k) {
+        // This method for retrieving arbitrary config items introduced by the interface is currently not used in DynatraceConfig.
+        return null;
+    }
+};
+MeterRegistry registry = new DynatraceMeterRegistry(dynatraceConfig, Clock.SYSTEM);
+// Register the Dynatrace registry with the global MeterRegistry.
+Metrics.addRegistry(registry);
+----
+
+These properties can also be set via Spring Boot, using the properties file.
+It is possible to reference environment variables using the Spring property placeholder notation here (e.g. `uri: ${DT_METRICS_INGEST_URL}`), if they are set up in your environment.
+`v2` is used as the default API version unless a deviceId is set (<<bookmark-apiv1, see below>>).
+
+[source,yml]
+----
+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 not be hardcoded but rather read from a secure source, like environment variables.
+    api-token: YOUR_METRICS_INGEST_TOKEN
+----
+
+== API Versions
+
+=== API v2 [[bookmark-apiv2]]
+
+When the API version is configured to `v2`, the registry will send data using the https://www.dynatrace.com/support/help/dynatrace-api/environment-api/metric-v2/[Metrics API v2].
+In order to maintain backwards compatibility, when a `deviceId` is set (which is required for `v1` and not used in `v2`), `v1` is used as the default.
+Otherwise, the version defaults to `v2`, and does not have to be set explicitly.
+With no endpoint URL and token set, metrics will be exported to the local OneAgent endpoint.
+If no OneAgent is running on the target host, it is possible to specify endpoint and token explicitly, in order to export metrics to that specific endpoint.
+
+*Minimal configuration with a local Dynatrace OneAgent*
+
+In the minimal configuration <<bookmark-oneagent-example, shown above>> (no URI or API token), the v2 exporter will attempt to export to the https://www.dynatrace.com/support/help/how-to-use-dynatrace/metrics/metric-ingestion/ingestion-methods/local-api/[local OneAgent metrics ingest endpoint].
+Note that this only works if the a OneAgent is running on the host and the https://www.dynatrace.com/support/help/how-to-use-dynatrace/metrics/metric-ingestion/ingestion-methods/local-api/#enable-the-oneagent-metric-api[local OneAgent Metric API] is available.
+If the ingestion port was changed to a custom one, the full endpoint URI has to be provided for the URI property (with API token left empty).
+
+*Configuration with URI and API token*
+
+If no local OneAgent is running on the host or the metrics should be sent to a different endpoint (e.g. a different tenant), the Dynatrace v2 exporter can be configured with an explicit endpoint URI and an https://www.dynatrace.com/support/help/dynatrace-api/basics/dynatrace-api-authentication/[API token].
+The https://www.dynatrace.com/support/help/dynatrace-api/basics/dynatrace-api-authentication/[API token] must have the https://www.dynatrace.com/support/help/shortlink/api-authentication#token-permissions["Ingest metrics"] (`metrics.ingest`) permission set.
+It is recommended to limit scope to only this permission.
+
+The entire Metrics v2 API endpoint URI has to be specified including its path, i.e., with the path `/api/v2/metrics/ingest` on SaaS and managed deployments, or `/metrics/ingest` for OneAgent endpoints as mentioned in the https://www.dynatrace.com/support/help/dynatrace-api/environment-api/metric-v2/post-ingest-metrics/[documentation].
+
+*Properties available in the v2 exporter* [[bookmark-available-properties]]
+
+When using the https://www.dynatrace.com/support/help/dynatrace-api/environment-api/metric-v2/[Dynatrace metrics API v2], the following properties can be set:
+
+[source,yml]
+----
+management.metrics.export.dynatrace:
+    # 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
+
+    # It is *not* recommended to put the token into the YAML or properties file directly.
+    # It should be read from a secure source instead, e.g. from environment variables.
+    # E.g. using `api-token: ${DT_METRICS_INGEST_API_TOKEN}` to read from the environment.
+    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"
+
+    # The export interval in which metrics are sent to Dynatrace (default: 60s).
+    step: 60s
+----
+
+These properties can also be set in code by overwriting the respective methods of the `DynatraceConfig` class:
+
+[source,java]
+----
+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".
+        // Should be read from a secure source and not hard-coded.
+        String endpoint = System.getenv("DT_METRICS_INGEST_URL");
+        return endpoint != null ? endpoint : DynatraceConfig.super.uri();
+    }
+
+    @Override
+    public String apiToken() {
+        // It is *not* recommended to place secrets in config files but to read them from a secure source.
+        String token = System.getenv("DT_METRICS_INGEST_API_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<String,String>();
+        dims.put("dimensionKey", "dimensionValue");
+        return dims;
+    }
+
+    @Override
+    @Nullable
+    public String get(String k) {
+        // This method for retrieving arbitrary config items introduced by the interface is currently not used in DynatraceConfig.
+        return null;
+    }
+};
+----
+
+For more information about the metadata picked up by the Dynatrace metadata enrichment feature, see https://www.dynatrace.com/support/help/how-to-use-dynatrace/metrics/metric-ingestion/ingestion-methods/enrich-metrics/[the Dynatrace documentation].
+
+=== API v1 (Legacy) [[bookmark-apiv1]]
+
+When the apiVersion is configured to `v1`, the registry will send data using the https://www.dynatrace.com/support/help/dynatrace-api/environment-api/metric-v1/custom-metrics/[Dynatrace Timeseries API v1 for custom metrics].
+If a `deviceId` is specified, it will default to `v1` for backwards compatibility with earlier setups.
+The `device-id` property is required for `v1` and not used in `v2`.
+Existing setups will continue to work when updating to newer versions of Micrometer.
+The reported metrics will be assigned to https://www.dynatrace.com/support/help/dynatrace-api/environment-api/topology-and-smartscape/custom-device-api/report-custom-device-metric-via-rest-api/[custom devices] in Dynatrace.
+
+
+For the v1 API, do not specify the ingest path, but only the base URL of your environment, e.g.: `uri: https://{your-environment-id}.live.dynatrace.com`
+
+[source,java]
+----
+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() {
+        // It is *not* recommended to place secrets in config files, but to read them from a secure source.
+        return MY_TOKEN;
+    }
+
     @Override
     public String deviceId() {
         return MY_DEVICE_ID;
@@ -38,22 +274,24 @@ DynatraceConfig dynatraceConfig = new DynatraceConfig() {
 MeterRegistry registry = new DynatraceMeterRegistry(dynatraceConfig, Clock.SYSTEM);
 ----
 
-`DynatraceConfig` is an interface with a set of default methods. If, in the implementation of `get(String k)`, rather than returning `null`, you instead bind it to a property source, you can override the default configuration. For example, Micrometer's Spring Boot support binds properties that are prefixed with `management.metrics.export.dynatrace` directly to the `DynatraceConfig`:
-
 [source,yml]
 ----
 management.metrics.export.dynatrace:
-    # This required
-    api-token: YOURKEY
+    # 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
 
-    # This is required
-    uri: https://XXXXXXX.live.dynatrace.com
+    # This should not be hardcoded but rather read from a secure source.
+    api-token: MY_TOKEN
 
-    # This is required
-    device-id: sample
+    # 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
 
-    # You will probably want disable Dynatrace publishing in a local development profile.
-    enabled: true
+    # 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