docs: Improve log usability (#2947)

Add more context to bonita Runtime logs.
Explain how to configure the log pattern and use logs in Trace Compass.

Closes [BPM-331](https://bonitasoft.atlassian.net/browse/BPM-331)
---------

Co-authored-by: Vincent Hémery <[email protected]>

modules/ROOT/pages/release-notes.adoc

@@ -8,6 +8,14 @@ The {bonitaVersion} version is in development.
 
 == New available values
 
+=== Enhanced Log Tracing and Filtering
+
+Log tracing and filtering in Bonita have been enhanced using MDC (Mapped Diagnostic Context) to add contextual information across all scopes.
+This improvement ensures higher-quality, more readable logs and simplifies integration with third-party monitoring tools, helping customers troubleshoot issues and monitor performance more effectively.
+
+You can see the xref:setup-dev-environment:logging.adoc#logging-configuration[logging configuration] for more details.
+
+
 == Deprecations and removals
 
 === API removals

modules/setup-dev-environment/pages/logging.adoc

@@ -46,6 +46,32 @@ Here is an example of the Log4j2 configuration for the logger used in the exampl
 <Logger name="org.bonitasoft.groovy.script" level="TRACE"/>
 ----
 
+Bonita Runtime uses Mapped Diagnostic Context (MDC) to bring contextual information into your logs. You can configure the log pattern with the `LOG_PATTERN` property. The default value is:
+
+[source,xml]
+----
+<Property name="LOG_PATTERN">%highlight{%d{ISO8601_OFFSET_DATE_TIME_HHMM} | ${hostName} | %-5p%notEmpty{[%marker]} | [%t|%T] %c{1.} - %m%notEmpty{ - %X}%n}{FATAL=Bright red, ERROR=red, WARN=yellow bold, INFO=Normal, DEBUG=green bold, TRACE=blue}</Property>
+----
+
+`%X` brings all the contextual information in the log. You can also write your own pattern to pick specific information. E.g. use `%X\{userId\}` to get the id of the authenticated user. All the usable variables such as `userId` are in the https://github.com/bonitasoft/bonita-engine/blob/{bonitaTechnicalVersion}/services/bonita-commons/src/main/java/org/bonitasoft/engine/mdc/MDCConstants.java[MDCConstants class].
+
+
+==== HTTP Request tracing configuration
+
+Troubleshooting HTTP requests can be challenging, especially in distributed systems.
+To simplify tracing, each HTTP request is now identified by a requestId attached to the request. For distributed systems, a correlationId can be used to identify a transaction.  By default, the custom HTTP headers used to trace a request are:
+
+[source,properties]
+----
+req.requestId.attributeName             track.requestId
+req.requestId.headerName                X-Request-ID
+req.correlationId.attributeName         track.correlationId
+req.correlationId.headerName            X-Correlation-ID
+----
+
+This properties could be update in the console-config.properties file. You need to use the setup tool provided in `workspace/tomcat/setup/` to update `console-config.properties`.
+
+
 === Bonita Studio
 
 To change the Bonita Studio log level (usually to debug Studio), go to the Studio installation folder, configuration directory, and edit the `config.ini` file. You need to set the property `eclipse.log.level` to one of the following values: INFO, WARNING or ERROR.
@@ -103,3 +129,35 @@ On a Bonita bundle, you can configure the log level, and you can access the log
 Each file name includes the date when the file was created. Log files:
 
 * _bonita.date_.log is the Bonita log file.
+
+== Integrate Bonita Runtime logs into an external Log Management System
+
+You can exploit the Mapped Diagnostic Context (MDC) information from the Bonita Runtime log to integrate it in an external Log Management System. +
+These instructions demonstrate how to do it with https://eclipse.dev/tracecompass/[Eclipse Trace Compass] a free and open source traces and logs manager. You can adapt these to your favorite tool of choice.
+
+
+. Download, install and launch Trace Compass.
+. Create a new project. Import your logs file in the Traces.
++
+image::logging/NewTraceCompassProject.gif[New Trace Compass project]
+. Create a custom parser to parse the log4j lines. +
+  With the default `LOG_PATTERN` property, you can use this pattern in Trace Compass (adapt it otherwise):
++
+[source,regex]
+----
+\s*\D*\d*m([^+]*)\+\d*\s+\|\s+(\S*)\s+\|\s+(\S*)\s+\|\s+\[([\w-]*)\|(\d*)\]\s*([\w\.]*)\s*\-\s*(.*?)(?: \- \{(?:req.correlationId=(\w*)|req.requestId=(\w*)|req.requestURL=(\S*)|txUid=([\w:]*)|userId=([\d]*)|rootProcessInstanceId=([\d]*)|.*?)+\})?
+----
++
+You can add/remove as many `propertyName=([...]*)|` blocks as you want to match MDC variables from the https://github.com/bonitasoft/bonita-engine/blob/{bonitaTechnicalVersion}/services/bonita-commons/src/main/java/org/bonitasoft/engine/mdc/MDCConstants.java[MDCConstants class]. +
+Use `yyyy-MM-ddTHH:mm:ss,SSS` for Time Stamp value.
+Test your pattern on an example log line.
++
+image::logging/NewLog4jParser.gif[New Log4j parser]
+. Select your custom parser for the trace type.
++
+image::logging/SelectParser.gif[Select parser]
+. Open the trace to visualize.
++
+image::logging/OpenTrace.gif[Open the trace]
+
+You can also configure Trace Compass to visualize the logs live from a stream. https://eclipse.dev/tracecompass/#docs[Read the documentation] for more information.