docs: Document how to ship OTEL traces (#753)

* docs: Document how to ship OTEL traces

* Update docs/modules/opa/pages/usage-guide/OpenTelemetry.adoc

Co-authored-by: Nick <[email protected]>

* Apply suggestions from code review

Co-authored-by: Andrew Kenworthy <[email protected]>

* Update docs/modules/opa/pages/usage-guide/OpenTelemetry.adoc

* mention GitHub issue

---------

Co-authored-by: Nick <[email protected]>
Co-authored-by: Andrew Kenworthy <[email protected]>

Author: 3 people

docs/modules/opa/pages/usage-guide/OpenTelemetry.adoc

@@ -0,0 +1,30 @@
+= OpenTelemetry
+:description: Ship OPA traces and logs to OpenTelemetry
+:opa-docs: https://v1-4-2--opa-docs.netlify.app/configuration/#distributed-tracing
+
+Opa supports sending OpenTelemetry traces as stated in {opa-docs}[the documentation].
+
+As of SDP 25.7, `configOverrides` are (still) not supported, we are tracking the progress in https://github.com/stackabletech/opa-operator/issues/756[this GitHub issue].
+To enable traces you need to modify the config and thus xref:opa:usage-guide/operations/cluster-operations.adoc[pause the reconciliation] of your OpaCluster, so that changes to the ConfigMap aren't immediately overridden by the opa-operator.
+
+WARNING: It's not encouraged to pause the reconciliation more than just temporarily. We recommend disabling it while you debug e.g. performance problems and re-enabling it afterwards. This problem will be solved once we support configOverrides for OPA.
+
+Afterwards you can edit the `<stacklet-name>-server-default` ConfigMap and append a `distributed_tracing` section as follows.
+Please check the {opa-docs}[OPA documentation] to see what other settings you can configure.
+
+[source,yaml]
+----
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: opa-server-default
+data:
+  config.json: |-
+    {
+      <<< existing JSON >>>
+      "distributed_tracing": {
+        "address": "jaeger-collector.default.svc.cluster.local:4317",
+        "type": "grpc"
+      }
+    }
+----

docs/modules/opa/pages/usage-guide/configuration-environment-overrides.adoc

@@ -8,7 +8,7 @@ This will lead to faulty installations.
 
 == Configuration properties
 
-Currently, not supported for `config.yaml`.
+Currently, not supported for `config.json`.
 
 == Environment variables
 

docs/modules/opa/partials/nav.adoc

@@ -8,6 +8,7 @@
 ** xref:opa:usage-guide/resources.adoc[]
 ** xref:opa:usage-guide/logging.adoc[]
 ** xref:opa:usage-guide/monitoring.adoc[]
+** xref:opa:usage-guide/OpenTelemetry.adoc[]
 ** xref:opa:usage-guide/configuration-environment-overrides.adoc[]
 ** xref:opa:usage-guide/tls.adoc[]
 ** xref:opa:usage-guide/operations/index.adoc[]