Update Documentation to reflect Spring Boot config changes

Author: pirgeo

src/docs/implementations/dynatrace.adoc

@@ -10,7 +10,7 @@ include::install.adoc[]
 
 == Configuring
 
-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] (`api-version: v2`).
+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]]
@@ -39,13 +39,9 @@ MeterRegistry registry = new DynatraceMeterRegistry(dynatraceConfig, Clock.SYSTE
 `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 enable the export to the local OneAgent, use:
 
-[source,yml]
-----
-management.metrics.export.dynatrace:
-    api-version: v2
-----
+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 v2 endpoint.
 
 === Using a custom endpoint
 
@@ -67,13 +63,15 @@ DynatraceConfig dynatraceConfig = new DynatraceConfig() {
         // 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.
-        return MY_DYNATRACE_URI;
+        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.
-        return MY_TOKEN;
+        String token = System.getenv("DT_METRICS_INGEST_API_TOKEN");
+        return token != null ? token : "";
     }
 
     @Override
@@ -84,19 +82,23 @@ DynatraceConfig dynatraceConfig = new DynatraceConfig() {
     }
 };
 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 the Spring Boot properties file.
 It is possible to reference environment variables using the Spring property placeholder notation here (`${VAR_NAME}`).
+When running the Micrometer exporter for Spring Boot, `v2` is used as the default API version.
 
 [source,yml]
 ----
 management.metrics.export.dynatrace:
-    api-version: v2
+    # 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: ${DT_METRICS_INGEST_URL}
 
-    # e.g.: https://{your-environment-id}.live.dynatrace.com/api/v2/metrics/ingest
-    uri: ${ENV_VAR_DT_INGEST_URI}
-    api-token: ${ENV_VAR_DT_INGEST_TOKEN}
+    # should not be hardcoded but rather read from a secure source, like environment variables.
+    api-token: ${DT_METRICS_INGEST_API_TOKEN}
 ----
 
 == API Versions
@@ -105,8 +107,10 @@ management.metrics.export.dynatrace:
 
 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].
 The v2 exporter does not require any properties to be set except for the version.
-In this case, metrics will be exported to the local OneAgent endpoint.
-If no OneAgent is running on the target host, it is possible to specify an endpoint and an API token in order to export metrics to that specific endpoint.
+When running Micrometer without Spring Boot, the default version is `v1` in order to maintain backwards compatibility.
+The version is assumed to be `v2` automatically when using Spring Boot, and does not have to be set explicitly in that case.
+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*
 
@@ -129,45 +133,101 @@ When using the https://www.dynatrace.com/support/help/dynatrace-api/environment-
 [source,yml]
 ----
 management.metrics.export.dynatrace:
-    # required to use the properties below
-    api-version: v2
-
-    # required if not using a local OneAgent endpoint.
-    uri: https://{your-environment-id}.live.dynatrace.com/api/v2/metrics/ingest
-    # or https://{your-domain}/e/{your-environment-id}/api/v2/metrics/ingest on Managed
+    # 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: ${DT_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. using `api-token: ${ENV_VAR_DT_INGEST_TOKEN}` to read from the environment.
-    api-token: MY_TOKEN
-
-    # 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 the same key appears twice.
-    # Each exported metric will contain these dimensions.
-    default-dimensions:
-        key1: "value1"
-        key2: "value2"
+    # 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: ${DT_METRICS_INGEST_API_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.
+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 : "";
+    }
 
-For more information about the metadata picked up by the enrichment, see https://www.dynatrace.com/support/help/how-to-use-dynatrace/metrics/metric-ingestion/ingestion-methods/enrich-metrics/[the Dynatrace documentation].
+    @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)
 
-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].
+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 no `apiVersion` is specified, it will default to `v1` for backwards compatibility with earlier setups.
+When using Spring Boot, `v1` can be turned on by specifying the `device-id` property, which is required for `v1` and not used in `v2`.
+Therefore, when running Spring Boot with the `v1` exporter and a configuration with the required `device-id` property, metrics will be exported to the v1 API.
+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.
-If no apiVersion is specified, it will default to "v1" for backwards-compatibility with earlier setups.
+
 
 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`
 
@@ -204,14 +264,18 @@ MeterRegistry registry = new DynatraceMeterRegistry(dynatraceConfig, Clock.SYSTE
 [source,yml]
 ----
 management.metrics.export.dynatrace:
-    # This is required
-    uri: https://your-environment-id.live.dynatrace.com
+    # 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
+    # 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
 
     # To disable Dynatrace publishing, e.g. in a local development profile, use:
     # enabled: false