diff --git a/modules/ROOT/pages/release-notes.adoc b/modules/ROOT/pages/release-notes.adoc index 02cf33a5ed..577c9ca0b2 100644 --- a/modules/ROOT/pages/release-notes.adoc +++ b/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 diff --git a/modules/setup-dev-environment/images/logging/NewLog4jParser.gif b/modules/setup-dev-environment/images/logging/NewLog4jParser.gif new file mode 100644 index 0000000000..49bc0efd41 Binary files /dev/null and b/modules/setup-dev-environment/images/logging/NewLog4jParser.gif differ diff --git a/modules/setup-dev-environment/images/logging/NewTraceCompassProject.gif b/modules/setup-dev-environment/images/logging/NewTraceCompassProject.gif new file mode 100644 index 0000000000..b2f4dc949a Binary files /dev/null and b/modules/setup-dev-environment/images/logging/NewTraceCompassProject.gif differ diff --git a/modules/setup-dev-environment/images/logging/OpenTrace.gif b/modules/setup-dev-environment/images/logging/OpenTrace.gif new file mode 100644 index 0000000000..f0fb733c52 Binary files /dev/null and b/modules/setup-dev-environment/images/logging/OpenTrace.gif differ diff --git a/modules/setup-dev-environment/images/logging/SelectParser.gif b/modules/setup-dev-environment/images/logging/SelectParser.gif new file mode 100644 index 0000000000..9c0b562dd7 Binary files /dev/null and b/modules/setup-dev-environment/images/logging/SelectParser.gif differ diff --git a/modules/setup-dev-environment/pages/logging.adoc b/modules/setup-dev-environment/pages/logging.adoc index 519d02a6a0..b845044504 100644 --- a/modules/setup-dev-environment/pages/logging.adoc +++ b/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 ---- +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] +---- +%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} +---- + +`%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.