docs: guide instructions to create KeptnMetric resource (#2381)

Co-authored-by: RealAnna <89971034+RealAnna@users.noreply.github.com>
Co-authored-by: Moritz Wiesinger <moritz.wiesinger@dynatrace.com>

docs/content/en/docs/implementing/evaluatemetrics.md

@@ -28,6 +28,11 @@ Keptn metrics are implemented with two resources:
 * [KeptnMetricsProvider](../yaml-crd-ref/metricsprovider.md) --
   define the configuration for a data provider
 
+As soon as you define and apply
+your `KeptnMetricsProvider` and `KeptnMetric` resources,
+Keptn begins collecting the metrics you defined.
+You do not need to do anything else.
+
 ### Define KeptnMetricsProvider resources
 
 You must define a
@@ -95,14 +100,80 @@ spec:
     key: DT_TOKEN
 ```
 
-## Accessing Metrics via the Kubernetes Custom Metrics API
+### Define KeptnMetric information
+
+The [KeptnMetric](../yaml-crd-ref/metric.md) resource
+defines the information you want to gather,
+specified as a query for the particular observability platform
+you are using.
+You can define any type of metric from any data source.
+
+In our example, we define two bits of information to retrieve:
+
+* Number of CPUs, fetched from the `dev-prometheus` data platform
+* `availability` SLO, fetched from the `dev-dynatrace` data platform
 
-`KeptnMetrics` can also be retrieved via the Kubernetes Custom Metrics API.
+Each of these are configured to fetch data every 10 seconds
+but you could configure a different `fetchIntervalSeconds` value
+for each metric.
 
-### Retrieve KeptnMetric values with kubectl
+The
+[keptn-metric.yaml](https://github.com/keptn-sandbox/klt-on-k3s-with-argocd/blob/main/simplenode-dev/keptn-metric.yaml)
+file for our example looks like:
+
+```yaml
+apiVersion: metrics.keptn.sh/v1alpha2
+kind: Keptnmetric
+metadata:
+  name: available-cpus
+  namespace: simplenode-dev
+spec:
+  provider:
+    name: dev-prometheus
+  query: "sum(kube_node_status_capacity{resources`cpu`})"
+  fetchIntervalSeconds: 10
+---
+apiVersion: metrics.keptn.sh/v1alpha2
+kind: Keptnmetric
+metadata:
+  name: availability-slo
+  namespace: simplenode-dev
+spec:
+  provider:
+    name: dev-dynatrace
+  query: "func:slo.availability_simplenodeservice"
+  fetchIntervalSeconds: 10
+```
+
+Note the following:
+
+* Each metric should have a unique `name`.
+* The value of the `spec.provider.name` field
+  must correspond to the name assigned in
+  the `metadata.name` field of a `KeptnMetricsProvider` resource.
+* Information is fetched in on a continuous basis
+  at a rate specified
+  by the value of the `spec.fetchIntervalSeconds` field.
+
+## Observing the metrics
+
+### Accessing Metrics via the Kubernetes Custom Metrics API
+
+`KeptnMetrics` can be retrieved using the `kubectl` command and the
+[KeptnMetric](../yaml-crd-ref/metric.md)
+API.
+This section shows how to do that.
+
+Metrics can also be displayed on a Grafana or other dashboard
+or they can be exposed as OpenTelemetry metrics; see
+[Access Keptn metrics as OpenTelementry metrics](otel.md/#access-keptn-metrics-as-opentelemetry-metrics)
+for instructions.
+
+### Retrieve KeptnMetric values with kubectl and the KeptnMetric API
 
 Use the `kubectl get --raw` command
-to retrieve the values of a `KeptnMetric`, as in the following example:
+to retrieve the values of a `KeptnMetric` resource,
+as in the following example:
 
 ```shell
 $ kubectl get --raw "/apis/custom.metrics.k8s.io/v1beta2/namespaces/podtato-kubectl/keptnmetrics.metrics.sh/keptnmetric-sample/keptnmetric-sample" | jq .
@@ -171,12 +242,14 @@ $ kubectl get --raw "/apis/custom.metrics.k8s.io/v1beta2/namespaces/podtato-kube
 }
 ```
 
-## Querying Metrics over a Timerange
+### Query Metrics over a Timerange
 
 You can query metrics over a specified timeframe.
-Let's suppose you set the `range.interval` field to be `3m`,
-the Keptn Metrics Operator would query the metrics for the
-last 3 minutes which means the
+For example, if you set the `range.interval` field
+in the `KeptnMetric` resource to be `3m`,
+the Keptn Metrics Operator queries the metrics for the
+last 3 minutes.
+In other words, the span is
 `from = currentTime - range.interval` and `to = currentTime`.
 
 The default value is set to be `5m` if the `range.interval` is not set.

docs/content/en/docs/yaml-crd-ref/metric.md

@@ -66,9 +66,10 @@ spec:
     that monitors the production deployment.
   * **query** (required) -- String in the provider-specific query language,
     used to obtain a metric.
+
   * **fetchIntervalSeconds** (required) -- Number of seconds between updates of the metric.
   * **range**
-    * **interval** -- Timeframe for which the metric would be queried.
+    * **interval** -- Timeframe for which the metric is queried.
     Defaults to 5m.
 
 * **status**
@@ -82,6 +83,11 @@ spec:
 
 ## Usage
 
+As soon as you define and apply
+your `KeptnMetricsProvider` and `KeptnMetric` resources,
+Keptn begins collecting the metrics you defined.
+You do not need to do anything else.
+
 A `KeptnMetric` resource must be located
 in the same namespace as the associated
 [KeptnMetricsProvider](metricsprovider.md)