Skip to content

RHIDP-11676: Orchestrator - Migrate doc for Log aggregation and Open Telemetry feature#2027

Open
jmagak wants to merge 9 commits intoredhat-developer:mainfrom
jmagak:RHIDP-11676-Orchestrator-Migrate-doc-for-Log-aggregation-and-Open-Telemetry-feature
Open

RHIDP-11676: Orchestrator - Migrate doc for Log aggregation and Open Telemetry feature#2027
jmagak wants to merge 9 commits intoredhat-developer:mainfrom
jmagak:RHIDP-11676-Orchestrator-Migrate-doc-for-Log-aggregation-and-Open-Telemetry-feature

Conversation

@jmagak
Copy link
Copy Markdown
Member

@jmagak jmagak commented Apr 8, 2026

IMPORTANT: Do Not Merge - To be merged by Docs Team Only

Version(s): 1.9, 1.10, main

Issue: RHIDP-11676

Preview:
8. Configure log aggregation and observability for SonataFlow
9. Configure OpenTelemetry for SonataFlow workflows

@rhdh-bot
Copy link
Copy Markdown
Collaborator

rhdh-bot commented Apr 8, 2026

Content Quality Assessment Results

CQA Report

  • CQA-00a: Orphaned modules
  • CQA-00b: Directory structure
  • CQA-01: Vale AsciiDoc DITA compliance
  • CQA-02: Verify assembly structure
  • CQA-03: Verify content type metadata (11 issues)
    • [AUTOFIX] modules/extend_orchestrator-in-rhdh/proc-enable-structured-json-logging-for-sonataflow-workflows.adoc: Line 78: Multiple unnumbered items in .Verification -- convert to numbered
    • [AUTOFIX] modules/extend_orchestrator-in-rhdh/proc-configure-file-based-json-logging-and-log-rotation.adoc: Line 20: Mixed list in .Procedure -- convert to numbered
    • [AUTOFIX] modules/extend_orchestrator-in-rhdh/proc-configure-file-based-json-logging-and-log-rotation.adoc: Line 81: Multiple unnumbered items in .Verification -- convert to numbered
    • [AUTOFIX] modules/extend_orchestrator-in-rhdh/proc-correlate-logs-with-opentelemetry-traces.adoc: Line 36: Multiple unnumbered items in .Verification -- convert to numbered
    • [AUTOFIX] modules/extend_orchestrator-in-rhdh/proc-aggregate-logs-using-the-plg-stack.adoc: Line 231: Multiple unnumbered items in .Verification -- convert to numbered
    • [AUTOFIX] modules/extend_orchestrator-in-rhdh/proc-configure-alerts-for-workflow-health.adoc: Line 62: Multiple unnumbered items in .Verification -- convert to numbered
    • [AUTOFIX] modules/extend_orchestrator-in-rhdh/proc-integrate-workflows-with-external-systems.adoc: Line 37: Multiple unnumbered items in .Verification -- convert to numbered
    • [AUTOFIX] modules/extend_orchestrator-in-rhdh/proc-troubleshoot-observability-and-logging-issues.adoc: Line 17: Mixed list in .Procedure -- convert to numbered
    • [AUTOFIX] modules/extend_orchestrator-in-rhdh/proc-troubleshoot-observability-and-logging-issues.adoc: Line 83: Multiple unnumbered items in .Verification -- convert to numbered
    • [AUTOFIX] modules/extend_orchestrator-in-rhdh/proc-enable-opentelemetry-for-sonataflow-workflows.adoc: Line 73: Multiple unnumbered items in .Verification -- convert to numbered
    • [AUTOFIX] modules/extend_orchestrator-in-rhdh/ref-observability-configuration-examples.adoc: Line 1: Content type: CONCEPT -> REFERENCE
  • CQA-04: Verify module templates
  • CQA-05: Verify required modular elements (14 issues)
    • [MANUAL] modules/extend_orchestrator-in-rhdh/proc-enable-structured-json-logging-for-sonataflow-workflows.adoc: Non-standard block title: .Example of expected output:
    • [MANUAL] modules/extend_orchestrator-in-rhdh/ref-telemetry-configuration-properties.adoc: Line 9: Non-standard block title: .OpenTelemetry configuration properties for SonataFlow
    • [MANUAL] modules/extend_orchestrator-in-rhdh/ref-observability-configuration-examples.adoc: Line 13: Non-standard block title: .Jaeger all-in-one deployment (development and testing)
    • [MANUAL] modules/extend_orchestrator-in-rhdh/ref-observability-configuration-examples.adoc: Line 106: Non-standard block title: .OpenShift route for UI access
    • [MANUAL] modules/extend_orchestrator-in-rhdh/ref-observability-configuration-examples.adoc: Line 126: Non-standard block title: .Workflow configuration for Jaeger
    • [MANUAL] modules/extend_orchestrator-in-rhdh/ref-observability-configuration-examples.adoc: Line 141: Non-standard block title: .Production deployment with Elasticsearch
    • [MANUAL] modules/extend_orchestrator-in-rhdh/ref-observability-configuration-examples.adoc: Line 183: Non-standard block title: .Loki configuration for OpenTelemetry
    • [MANUAL] modules/extend_orchestrator-in-rhdh/ref-observability-configuration-examples.adoc: Line 239: Non-standard block title: .Loki deployment
    • [MANUAL] modules/extend_orchestrator-in-rhdh/ref-observability-configuration-examples.adoc: Line 323: Non-standard block title: .Workflow configuration for Loki and Jaeger
    • [MANUAL] modules/extend_orchestrator-in-rhdh/ref-observability-configuration-examples.adoc: Line 358: Non-standard block title: .Collector pipeline configuration
    • [MANUAL] modules/extend_orchestrator-in-rhdh/ref-troubleshoot-opentelemetry-connectivity.adoc: Line 9: Non-standard block title: .OpenTelemetry troubleshooting guide
    • [MANUAL] modules/extend_orchestrator-in-rhdh/ref-troubleshoot-opentelemetry-connectivity.adoc: Line 33: Non-standard block title: .Diagnosing missing traces
    • [MANUAL] modules/extend_orchestrator-in-rhdh/ref-troubleshoot-opentelemetry-connectivity.adoc: Line 56: Non-standard block title: .Configuring authentication headers
    • [MANUAL] modules/extend_orchestrator-in-rhdh/ref-troubleshoot-opentelemetry-connectivity.adoc: Line 64: Non-standard block title: .Resolving context propagation issues
  • CQA-06: Verify assemblies follow official template (one user story)
  • CQA-07: Verify TOC depth (max 3 levels)
  • CQA-08: Verify short description content quality
  • CQA-09: Verify short description format (2 issues)
    • [MANUAL] assemblies/extend_orchestrator-in-rhdh/assembly-configure-opentelemetry-for-sonataflow-workflows.adoc: Line 11: Abstract too long (317 chars, maximum 300)
    • [MANUAL] modules/extend_orchestrator-in-rhdh/proc-configure-telemetry-exporters.adoc: Line 7: Abstract too long (336 chars, maximum 300)
  • CQA-10: Verify titles are brief, complete, and descriptive (9 issues)
    • [AUTOFIX] modules/extend_orchestrator-in-rhdh/proc-aggregate-logs-using-the-plg-stack.adoc: ID: aggregate-logs-using-the-plg-stack -> aggregate-logs-using-the-promtail-loki-and-grafana-plg-stack
    • [AUTOFIX] modules/extend_orchestrator-in-rhdh/proc-aggregate-logs-using-the-plg-stack.adoc: File: proc-aggregate-logs-using-the-plg-stack.adoc -> proc-aggregate-logs-using-the-promtail-loki-and-grafana-plg-stack.adoc
    • [AUTOFIX] modules/extend_orchestrator-in-rhdh/proc-configure-alerts-for-workflow-health.adoc: File: proc-configure-alerts-for-workflow-health.adoc -> proc-configure-alerts-for-workflow-conditions.adoc
    • [AUTOFIX] modules/extend_orchestrator-in-rhdh/proc-troubleshoot-observability-and-logging-issues.adoc: ID: troubleshoot-observability-and-logging-issues -> troubleshoot-observability-and-log-aggregation-in-sonataflow
    • [AUTOFIX] modules/extend_orchestrator-in-rhdh/proc-troubleshoot-observability-and-logging-issues.adoc: File: proc-troubleshoot-observability-and-logging-issues.adoc -> proc-troubleshoot-observability-and-log-aggregation-in-sonataflow.adoc
    • [AUTOFIX] modules/extend_orchestrator-in-rhdh/proc-configure-telemetry-exporters.adoc: ID: configure-telemetry-exporters -> configure-telemetry-data-exporters-for-observability-platforms
    • [AUTOFIX] modules/extend_orchestrator-in-rhdh/proc-configure-telemetry-exporters.adoc: File: proc-configure-telemetry-exporters.adoc -> proc-configure-telemetry-data-exporters-for-observability-platforms.adoc
    • [AUTOFIX] modules/extend_orchestrator-in-rhdh/ref-observability-configuration-examples.adoc: ID: observability-configuration-examples -> observability-tool-configuration-examples
    • [AUTOFIX] modules/extend_orchestrator-in-rhdh/ref-observability-configuration-examples.adoc: File: ref-observability-configuration-examples.adoc -> con-observability-tool-configuration-examples.adoc
  • CQA-11: Verify procedure prerequisites
  • CQA-12: Verify grammar and style (Vale)
  • CQA-13: Verify content matches declared type (1 issues)
    • [AUTOFIX] modules/extend_orchestrator-in-rhdh/ref-observability-configuration-examples.adoc: Filename prefix mismatch: expected con- for CONCEPT (got: ref-observability-configuration-examples) -- rename to con-observability-configuration-examples.adoc
  • CQA-14: Verify no broken links
  • CQA-15: Check redirects
  • CQA-16: Verify official product names
  • CQA-17: Verify legal disclaimers for preview features

Summary

Checks: 19 total, 14 pass, 5 fail
Issues: 37 total (21 autofixable, 16 manual, 2 delegated)
Run node build/scripts/cqa/index.js --fix --all to auto-resolve 21 issues.


Automated CQA check run on the entire repository — 2026-04-18 03:58:23 UTC

@rhdh-bot
Copy link
Copy Markdown
Collaborator

rhdh-bot commented Apr 8, 2026

❌ Build failed

33/33 titles built successfully | 0 failed | 116s

CQA (Content Quality Assessment)

19 checks: 18 pass, 1 fail

CQA checklist

CQA Report

  • CQA-00a: Orphaned modules (2 issues)
    • [AUTOFIX] assemblies/extend_orchestrator-in-rhdh/assembly-configure-log-aggregation-and-observability-for-sonataflow.adoc: Orphaned .adoc file (not included anywhere)
    • [AUTOFIX] assemblies/extend_orchestrator-in-rhdh/assembly-configure-opentelemetry-for-sonataflow-workflows.adoc: Orphaned .adoc file (not included anywhere)
  • CQA-00b: Directory structure
  • CQA-01: Vale AsciiDoc DITA compliance
  • CQA-02: Verify assembly structure
  • CQA-03: Verify content type metadata
  • CQA-04: Verify module templates
  • CQA-05: Verify required modular elements
  • CQA-06: Verify assemblies follow official template (one user story)
  • CQA-07: Verify TOC depth (max 3 levels)
  • CQA-08: Verify short description content quality
  • CQA-09: Verify short description format
  • CQA-10: Verify titles are brief, complete, and descriptive
  • CQA-11: Verify procedure prerequisites
  • CQA-12: Verify grammar and style (Vale)
  • CQA-13: Verify content matches declared type
  • CQA-14: Verify no broken links
  • CQA-15: Check redirects
  • CQA-16: Verify official product names
  • CQA-17: Verify legal disclaimers for preview features

Summary

Checks: 19 total, 18 pass, 1 fail
Issues: 2 total (2 autofixable, 0 manual, 1 delegated)
Run node build/scripts/cqa/index.js --fix --all to auto-resolve 2 issues.

Run node build/scripts/cqa/index.js --all locally for details.

View full logs | 4/18/2026, 3:59:12 AM

@jmagak jmagak force-pushed the RHIDP-11676-Orchestrator-Migrate-doc-for-Log-aggregation-and-Open-Telemetry-feature branch from a4de0f2 to a75f23b Compare April 15, 2026 00:08
@jmagak jmagak force-pushed the RHIDP-11676-Orchestrator-Migrate-doc-for-Log-aggregation-and-Open-Telemetry-feature branch from a75f23b to 319b85f Compare April 15, 2026 09:53
@jmagak jmagak force-pushed the RHIDP-11676-Orchestrator-Migrate-doc-for-Log-aggregation-and-Open-Telemetry-feature branch from 319b85f to 66af450 Compare April 15, 2026 10:25
@jmagak jmagak force-pushed the RHIDP-11676-Orchestrator-Migrate-doc-for-Log-aggregation-and-Open-Telemetry-feature branch from 66af450 to 9af3061 Compare April 15, 2026 11:40
Copy link
Copy Markdown

@gabriel-farache gabriel-farache left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Some comments
In addition: should the telemetries that are actually produced be describes somewhere as well so the user knows what to look for in loki/grafana:

  • Span attributes (sonataflow.process.id, sonataflow.process.instance.id, sonataflow.workflow.state, sonataflow.transaction.id, sonataflow.tracker.*,
    etc.)
  • Process lifecycle events (process.instance.start, process.instance.complete, process.instance.error, state.started, state.completed, log.message)
  • Function call attributes (sonataflow.function.name, http.method, http.url, etc.)
  • Context propagation headers (X-TRANSACTION-ID, X-TRACKER-*)


|`quarkus.otel.exporter.otlp.protocol`
|The transport protocol. Supported values are `grpc` or `http/protobuf`.
|`grp`
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

typo: should be grpc

----
# Enable OpenTelemetry integration
quarkus.otel.enabled=true
quarkus.otel.exporter.otlp.traces.endpoint=http://jaeger-collector:14268/api/traces
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the port here is wrong, should be 4317 (gRPC) or 4318 (HTTP) and I think the other modules use 4317 for the OLTP port

+
[source,bash]
----
kubectl logs -n workflows deployment/onboarding-workflow | grep "sonataflow-addons-quarkus-opentelemetry"
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

should we use oc instead of kubectl as the target env is OpenShift AFAIK?

@jmagak jmagak force-pushed the RHIDP-11676-Orchestrator-Migrate-doc-for-Log-aggregation-and-Open-Telemetry-feature branch from 84e4421 to 1cca704 Compare April 18, 2026 03:56
@sonarqubecloud
Copy link
Copy Markdown

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants