Configuring log aggregation and observability for sonataflow

Author: GitHub Actions

assemblies/extend_orchestrator-in-rhdh/assembly-configure-log-aggregation-and-observability-for-sonataflow.adoc

@@ -8,7 +8,7 @@ ifdef::context[:parent-context: {context}]
 :context: configure-log-aggregation-and-observability-for-sonataflow
 
 [role="_abstract"]
-You must implement a robust observability strategy to ensure your serverless workflows are production-ready. By configuring structured JSON logging and integrating OpenTelemetry, you enable automated log aggregation, process-instance correlation, and distributed tracing.
+You must implement an observability strategy to make sure your serverless workflows are production-ready. By configuring structured JSON logging and integrating OpenTelemetry, you enable automated log aggregation, process-instance correlation, and distributed tracing.
 
 // Enable structured JSON logging for SonataFlow workflows
 include::../modules/extend_orchestrator-in-rhdh/proc-enable-structured-json-logging-for-sonataflow-workflows.adoc[leveloffset=+1]

modules/extend_orchestrator-in-rhdh/proc-configure-telemetry-exporters.adoc

@@ -19,7 +19,7 @@ Choose an export strategy that matches your observability platform requirements:
 
 ** OTLP exporter with batch processing (Recommended)
 +
-For production environments, use an OTLP exporter with batch processing to reduce network overhead and improve performance.
+For production environments, use an OTLP exporter with batch processing to reduce network overhead and improve performance:
 +
 [source,bash]
 ----
@@ -37,7 +37,7 @@ quarkus.otel.bsp.max.queue.size=2048
 
 ** Direct export to an external platform
 +
-For development or simple integrations, use a direct export configuration.
+For development or simple integrations, use a direct export configuration:
 +
 [source,bash]
 ----

modules/extend_orchestrator-in-rhdh/proc-enable-structured-json-logging-for-sonataflow-workflows.adoc

@@ -4,7 +4,7 @@
 = Enable structured JSON logging for SonataFlow workflows
 
 [role="_abstract"]
-Configure your SonataFlow workflows to emit logs in structured JSON format. This enables machine processing and allows you to correlate log entries with specific process instances across your log aggregation stack.
+Configure your SonataFlow workflows to emit logs in structured JSON format. Structured logging enables machine processing and correlates log entries with specific process instances across your log aggregation stack.
 
 SonataFlow workflows support structured JSON logging with automatic process instance correlation through:
 
@@ -16,15 +16,13 @@ SonataFlow workflows support structured JSON logging with automatic process inst
 
 * You have deployed SonataFlow workflow using the SonataFlow Operator on {platform-generic} or Kubernetes.
 
-* The `io.quarkus:quarkus-logging-json` extension is included in your workflow `QUARKUS_EXTENSIONS` environment variable during the image build.
+* You have included the `io.quarkus:quarkus-logging-json` extension in your workflow `QUARKUS_EXTENSIONS` environment variable.
 
-* You have cluster admin permissions for deploying log aggregation stack.
-
-* You have knowledge of JSON logging and log aggregation tools.
+* You have `cluster-admin` permissions for deploying log aggregation stack.
 
 .Procedure
 
-. Update your workflow build configuration to include the required JSON logging extension:
+. Update your workflow build configuration to include the JSON logging extension:
 +
 [source,bash,subs=+attributes]
 ----
@@ -56,7 +54,7 @@ quarkus.log.category."org.kie.kogito.services.context".level=DEBUG
 
 . Save the ConfigMap and restart the workflow pod.
 +
-The following is an example of a workflow ConfigMap with JSON logging enabled:
+The following is an example of a workflow ConfigMap with an enabled JSON logging:
 +
 [source,yaml]
 ----
@@ -79,14 +77,14 @@ data:
 
 .Verification
 
-* Check the pod logs to ensure they are in JSON format and contain the `processInstanceId`:
+* Check the pod logs to verify the JSON format and the presence of the `processInstanceId`:
 +
 [source,bash,subs="+attributes,+quotes"]
 ----
 oc logs <workflow_pod_name> | grep processInstanceId
 ----
 +
-Example of expected output:
+.Example of expected output:
 +
 [source,bash]
 ----
@@ -95,9 +93,8 @@ Example of expected output:
 
 [NOTE]
 ====
-If the MDC fields are empty or missing, ensure that the JSON logging is active and verify the process context. Missing fields might indicate one of the following conditions:
-
-* The workflow has not processed any instances.
+If the Mapped Diagnostic Context (MDC) fields are empty, verify the following:
 
-* The SonataFlow version requires custom MDC configuration.
+* The workflow has processed at least one instance.
+* The SonataFlow version matches the required configuration for MDC propagation.
 ====