docs: fix context information in guides (keptn#2902)

Signed-off-by: RealAnna <[email protected]>
Signed-off-by: RealAnna <[email protected]>
Co-authored-by: Florian Bacher <[email protected]>
Co-authored-by: Meg McRoberts <[email protected]>
Co-authored-by: Moritz Wiesinger <[email protected]>

.github/actions/spelling/expect.txt

@@ -379,6 +379,7 @@ Lifcycle
 lifecyclekeptnsh
 linenums
 linkedin
+linkedtrace
 livenessprobe
 loadtests
 LOCALBIN
@@ -564,6 +565,7 @@ slo
 softprops
 sonarcloud
 spanhandler
+spanid
 spanitem
 spdx
 spf
@@ -622,6 +624,7 @@ tplvalues
 traceparent
 tracerfactory
 tracetest
+traceid
 trivy
 trivyignore
 trunc

docs/docs/guides/assets/metadata/keptn-app-context.yaml

@@ -0,0 +1,9 @@
+apiVersion: lifecycle.keptn.sh/v1beta1
+kind: KeptnAppContext
+metadata:
+  name: keptndemoapp
+  namespace: keptndemo
+spec:
+  metadata:
+    commit-id: "1234"
+    author: "myUser"

docs/docs/guides/assets/otel/keptn-app-context-span.yaml

@@ -0,0 +1,11 @@
+apiVersion: lifecycle.keptn.sh/v1beta1
+kind: KeptnAppContext
+metadata:
+  name: keptndemoapp
+  namespace: keptndemo
+spec:
+  metadata:
+    commit-id: "1234"
+    author: "myUser"
+  spanLinks:
+    - "00-c088f5c586bab8649159ccc39a9862f7-f862289833f1fba3-01"

docs/docs/guides/assets/tasks/dummy-task.yaml

@@ -0,0 +1,13 @@
+apiVersion: lifecycle.keptn.sh/v1alpha3
+kind: KeptnTaskDefinition
+metadata:
+  name: dummy-task
+  namespace: "default"
+spec:
+  function:
+    secureParameters:
+      secret: my-secret
+    inline:
+      code: |
+        let secret_text = Deno.env.get("SECURE_DATA");
+        // secret_text = "foo"

docs/docs/guides/assets/tasks/job-context.yaml

@@ -0,0 +1,25 @@
+apiVersion: batch/v1
+kind: Job
+spec:
+  template:
+    spec:
+      containers:
+        - name: "my-task-container"
+          env:
+            - name: KEPTN_CONTEXT
+              value: '{
+                         "workloadName":"waiter-waiter",
+                         "appName":"waiter",
+                         "appVersion":"",
+                         "workloadVersion":"0.4",
+                         "taskType":"pre",
+                         "objectType":"Workload",
+                         "metadata":{
+                            "commit-id":"1234",
+                            "stage":"dev",
+                            "test-metadata":"test-metadata",
+                            "traceparent": "00-traceid-spanid-01"
+                         }
+                      }'
+            - name: SCRIPT
+              value: /var/data/function.ts

docs/docs/guides/assets/tasks/multi-secret.yaml

@@ -0,0 +1,15 @@
+apiVersion: lifecycle.keptn.sh/v1alpha3
+kind: KeptnTaskDefinition
+metadata:
+  name: dummy-task
+  namespace: "default"
+spec:
+  function:
+    secureParameters:
+      secret: my-secret
+    inline:
+      code: |
+        let secret_text = Deno.env.get("SECURE_DATA");
+        let secret_text_obj = JSON.parse(secret_text);
+        // secret_text_obj["foo"] = "bar"
+        // secret_text_obj["foo2"] = "bar2"

docs/docs/guides/assets/tasks/secret-data.yaml

@@ -0,0 +1,8 @@
+apiVersion: v1
+kind: Secret
+metadata:
+  name: deno-demo-secret
+  namespace: default
+type: Opaque
+data:
+  SECURE_DATA: YmFyCg== # base64 encoded string, e.g. 'bar'

docs/docs/guides/assets/tasks/slack.yaml

@@ -0,0 +1,13 @@
+apiVersion: lifecycle.keptn.sh/v1alpha2
+kind: KeptnTaskDefinition
+metadata:
+  name: slack-notification-dev
+spec:
+  function:
+    functionRef:
+      name: slack-notification
+    parameters:
+      map:
+        textMessage: "This is my configuration"
+    secureParameters:
+      secret: slack-token

docs/docs/guides/assets/tasks/taskdef-secure-data.yaml

@@ -0,0 +1,16 @@
+apiVersion: lifecycle.keptn.sh/v1alpha3
+kind: KeptnTaskDefinition
+metadata:
+  name: deployment-hello
+  namespace: "default"
+spec:
+  function:
+    secureParameters:
+      secret: deno-demo-secret
+    inline:
+      code: |
+        console.log("Deployment Hello Task has been executed");
+
+        let foo = Deno.env.get('SECURE_DATA');
+        console.log(foo);
+        Deno.exit(0);

docs/docs/guides/metadata.md

@@ -0,0 +1,124 @@
+---
+comments: true
+---
+
+# Context metadata
+
+This guide walks you through the usage of context metadata in Keptn.
+
+After reading this guide you will be able to:
+
+- add metadata to applications, workloads
+  and tasks in two ways
+- add metadata information about applications to their traces
+
+## Introduction
+
+Context metadata in Keptn is defined as all additional information that can
+be added to applications, workloads and tasks.
+
+Context metadata can be added to your application
+in either of the following ways:
+
+- Use the `keptn.sh/metadata` annotation in any of
+your workloads you plan to deploy with Keptn
+- Apply a `KeptnAppContext` custom resource
+
+In the following section we will explore both.
+
+Common uses of this feature include:
+
+- adding a commit ID or references related to your GitOps and CI-CD tooling
+- referencing different stages and actors
+  such as: who committed the change, in what repo, for what ticket...
+
+### Before you start
+
+1. [Install Keptn](../installation/index.md)
+2. Deploy an application, for instance, you can follow
+   [a demo app installation here](../getting-started/observability.md#step-3-deploy-demo-application)
+
+To collect traces you will require Jaeger.
+To visualise and inspect the traces, you can either use
+the Jaeger UI or Grafana.
+
+1. Install
+   [Grafana](https://grafana.com/grafana/)
+   following the instructions in [Grafana Setup](https://grafana.com/docs/grafana/latest/setup-grafana/)
+   or the visualization tool of your choice.
+2. Install
+   [Jaeger](https://www.jaegertracing.io/)
+   or a similar tool for traces following the instructions in
+   [Jaeger Setup](https://www.jaegertracing.io/docs/1.50/getting-started/).
+
+## Include metadata in workload traces
+
+To enrich workload traces with custom metadata, use the
+`keptn.sh/metadata` annotation in your
+[Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment)
+resource.
+The values specified in the annotation
+are added as key-value attributes to the workload trace.
+
+Modify your workload (for example your YAML file containing a Deployment)
+adding an annotation with any metadata you prefer,
+for instance, to add information about a stage, you could add:
+`keptn.sh/metadata: "stage=dev"`.
+
+To see the changes Keptn must redeploy: increment the `app.kubernetes.io/version` value
+(ex. if you are following our getting started guide, change the version
+from `0.0.2` to `0.0.3`) or change the `keptn.sh/version` value
+if you used the Keptn specific labels in your deployment YAML file.
+
+This way, after the re-deployment, the workload trace will contain the `stage=dev` attribute.
+
+## Include metadata in application traces
+
+Similar to the previous step, custom metadata can also be added to application traces via the
+[KeptnAppContext](../reference/api-reference/lifecycle/v1beta1/index.md#keptnappcontext) CRD.
+
+`KeptnAppContext` is a custom resource definition in Keptn that allows you to add metadata
+and links to traces for a specific application.
+This enables you to enrich your Keptn resources and your traces with additional
+information, making it easier to understand and analyze
+the performance of your applications.
+
+In the `.spec.metadata` field you can define multiple key-value pairs, which are propagated
+to the application trace as attributes in the same manner as for workloads.
+
+> **Note** The key-value pairs that are added to the application trace are also added
+to each workload trace that is part of the application.
+If the same key is specified for both
+application and workload metadata attributes,
+values specified for the workload take precedence.
+
+A `KeptnAppContext` custom resource looks like the following:
+
+```yaml
+{% include "./assets/metadata/keptn-app-context.yaml" %}
+```
+
+After applying the `KeptnAppContext` to your cluster, you need to increment the version of your
+application by modifying your deployment file and changing the
+value of the`app.kubernetes.io/version` field (or `keptn.sh/version` if you used the Keptn specific labels earlier).
+(Alternatively you could apply the context resource before or together with the workloads.)
+
+After deploying the `KeptnAppContext` resource and re-deploying the application,
+Keptn triggers another deployment of your application with the new context metadata,
+and all traces will contain the new metadata as defined in the above code example.
+In other words, you should be able to see the application trace as well as the workload trace
+contain the defined metadata as key-value attributes.
+
+## What's next?
+
+Congratulations!
+You've learned how to use the `KeptnAppContext` CRD to add
+metadata to applications and their traces.
+This can be valuable for understanding the context of your traces and
+establishing connections between
+different versions and stages of your application.
+
+Explore more about [traces on Keptn](./otel.md).
+The paragraph on
+[linking traces between different application](./otel.md#advanced-tracing-configurations-in-keptn-linking-traces)
+also uses KeptnAppContext.

docs/docs/guides/otel.md

@@ -53,7 +53,7 @@ you must have the following on your cluster:
     to watch resources of your Keptn namespace
     (default is `keptn-system`).
     See
-    [Setup for Monitoring other Namespaces](https://prometheus-operator.dev/docs/kube/monitoring-other-namespaces/)).
+    [Setup for Monitoring other Namespaces](https://prometheus-operator.dev/docs/kube/monitoring-other-namespaces/).
 
 - To install Prometheus into the `monitoring` namespace
   using the example configuration included with Keptn,
@@ -84,7 +84,7 @@ kubectl apply -f config/prometheus/
 
   - Follow the instructions in the Grafana
     [README](https://github.com/keptn/lifecycle-toolkit/blob/main/dashboards/grafana/README.md)
-    file to configure the Grafana dashboard(s) for Keptn..
+    file to configure the Grafana dashboard(s) for Keptn.
 
     Metrics can also be retrieved without a dashboard.
     See
@@ -160,3 +160,35 @@ kubectl port-forward deployment/metrics-operator 9999 -n keptn-system
 ```
 
 You can access the metrics from your browser at: `http://localhost:9999`
+
+## Advanced tracing configurations in Keptn: Linking traces
+
+In Keptn you can connect multiple traces, for instance to connect deployments
+of the same application through different stages.
+To create connections between the traces of versions of your application, you can enrich the
+`KeptnAppContext` resource with
+[OpenTelemetry span links](https://opentelemetry.io/docs/concepts/signals/traces/#span-links).
+You can retrieve the span link from the JSON representation of the trace in Jaeger, where
+it has the following structure:
+
+```yaml
+00-<trace-id>-<span-id>-01
+```
+
+Use this value to populate the `spanLinks` field
+of your `KeptnAppContext` resource
+to connect traces of different versions of the application.
+
+```yaml
+{% include "./assets/otel/keptn-app-context-span.yaml" %}
+```
+
+> **Note**
+> Please be aware that the span link is just an example, and you need to retrieve the traceID and spanID
+> of the application trace stored in the `KeptnAppVersion` resource you want to link.
+
+To store this new information in the traces, you need to increment the version
+of your application and apply the`KeptnAppContext`.
+Keptn will re-deploy your application and Jaeger should show a link to the previous trace in the references section.
+
+![linked trace](./assets/linkedtrace.png)