diff --git a/modules/ROOT/pages/monitoring/logging.adoc b/modules/ROOT/pages/monitoring/logging.adoc index e50bccdfd..bffd23733 100644 --- a/modules/ROOT/pages/monitoring/logging.adoc +++ b/modules/ROOT/pages/monitoring/logging.adoc @@ -29,6 +29,7 @@ For Debian and RPM packages run `journalctl --unit=neo4j`. | Log information required by Neo4j Customer Support to investigate problems. It is highly recommended to keep it enabled and not to alter the _debug.log_ format. If you require the _debug.log_ messages in a different format, create an additional Appender. +Starting from Neo4j 2025.01, the default format is JSON. | xref:configuration/configuration-settings.adoc#config_server.logs.debug.enabled[`server.logs.debug.enabled`] | `true` @@ -80,15 +81,19 @@ and xref:configuration/configuration-settings.adoc#config_db.logs.query.threshol Neo4j uses https://logging.apache.org/log4j/2.x/[Log4j 2] for logging. The logging configuration is located in the _conf_ directory and consists of two files: -* _user-log.xml_ -- provides configuration for _neo4j.log_. +* _user-logs.xml_ -- provides configuration for _neo4j.log_. * _server-logs.xml_ -- provides configuration for _debug.log_, _http.log_, _query.log_, and _security.log_. The _gc.log_ is handled by the Java Virtual Machine(JVM) and is configured using the JVM parameters. For details, see <>. -[TIP] +[json-format] +[NOTE] ==== -If you want to use a custom directory for your Log4j configuration files, set the new paths to your XML files in the _neo4j.conf_ file by using the parameters xref:configuration/configuration-settings.adoc#config_server.logs.user.config[`server.logs.user.config`] and xref:configuration/configuration-settings.adoc#config_server.logs.config[`server.logs.config`]. +Starting from Noe4j 2025.01, the default configuration files are located in the _server.directories.configuration=conf_ directory. +Therefore, the default paths to the configuration files are _/conf/user-logs.xml_ and _/conf/server-logs.xml_. +If you use a custom directory for your Log4j configuration files, update the paths to your XML files in the _neo4j.conf_ file to depend on rater than . +For example, xref:configuration/configuration-settings.adoc#config_server.logs.user.config[`server.logs.user.config=path/to/your/conf/user-logs.xml`] and xref:configuration/configuration-settings.adoc#config_server.logs.config[`server.logs.config=path/to/your/conf/server-logs.xml`]. ==== Each configuration file comprises two main elements: _Appenders_ and _Loggers_: @@ -113,14 +118,14 @@ For more details, see https://logging.apache.org/log4j/2.x/manual/configuration. The following example shows the default configuration of the _user-logs.xml_ file. -.Default _user-log.xml_ configuration -[source%linenums,xml,options="nowrap", role="nocopy"] +.Default _user-logs.xml_ configuration +[source,xml,options="nowrap", role="nocopy"] ---- @@ -138,11 +143,11 @@ The following example shows the default configuration of the _user-logs.xml_ fil \ #<2> filePattern="$${config:server.directories.logs}/neo4j.log.%02i"> #<4> - #<5> - \ #<6> - \ #<7> + #<6> + \ #<7> + \ #<8> - \ #<8> + \ #<9> @@ -151,9 +156,9 @@ The following example shows the default configuration of the _user-logs.xml_ fil - \ #<9> + \ #<10> - \ #<10> + \ #<11> @@ -168,26 +173,27 @@ The following example shows the default configuration of the _user-logs.xml_ fil The following example shows the default configuration of the _server-logs.xml_ file. .Default _server-logs.xml_ configuration -[source%linenums,xml,options="nowrap", role="nocopy"] +[source,xml,options="nowrap", role="nocopy"] ---- \ #<1> \ #<2> - + filePattern="$${config:server.directories.logs}/debug.log.%02i"> \ #<4> - \ #<5> - \ #<6> - \ #<7> + + \ #<5> + + + \ #<6> + + \ #<7> + \ #<8> - \ #<8> + \ #<9> - \ #<9> + \ #10> - \ #<10> + \ #<11> - \ #<11> + \ #<12> @@ -277,30 +288,36 @@ See <> for more information. <4> `filePattern` specifies a file pattern to be used when the file is rolled. The pattern renames the files to _debug.log.01_ and _http.log.01_ when they reach the defined trigger. -<5> `PatternLayout` defines the layout for the appender, in this case with the `GMT+2` timezone. +<5> The `JsonTemplateLayout` layout is used to format the log messages in JSON format. +Starting from Neo4j 2025.01, the default _debug.log_ format is JSON, and it is recommended to keep it enabled to ensure the best support. +If you require the _debug.log_ messages in a different format, create an additional Appender since the default one is used by the Neo4j Support team. +If you require to use the text format, you can uncomment entry <6>. + +<6> `PatternLayout` defines the layout for the appender, in this case, with the `GMT+2` timezone. +Note that this is used in the 5.x series and is now disabled by default. See <> for more information. -<6> The `Policies` element defines when the files are rolled and how many files to keep as history before they are deleted. +<7> The `Policies` element defines when the files are rolled and how many files to keep as history before they are deleted. -<7> The `SizeBasedTriggeringPolicy` defines when the files are rolled. +<8> The `SizeBasedTriggeringPolicy` defines when the files are rolled. In this case, when the size of the files reaches 20 MB, the files are renamed according to the `filePattern`, and the log files start over. In Neo4j 4.0, this was configured with the parameter `dbms.logs.user.rotation.size`. -<8> The `DefaultRolloverStrategy` defines how many files to keep as history. + +<9> The `DefaultRolloverStrategy` defines how many files to keep as history. + The `fileIndex=min` implies that the minimum/the lowest number is the most recent one. + The `max` attribute defines the number of files to keep as history before they are deleted, in this case, 7 files. In Neo4j 4.0, this was configured with the parameter `dbms.logs.user.rotation.keep_number`. -<9> Loggers are used to define the log level and which appender to use for the log messages. +<10> Loggers are used to define the log level and which appender to use for the log messages. The loggers are referenced by the `name` attribute. See <> for more information. -<10> The root logger is a "catch-all" logger that catches everything that is not caught by the other loggers and sends it to the appender(s) specified in the `AppenderRef` element(s). +<11> The root logger is a "catch-all" logger that catches everything that is not caught by the other loggers and sends it to the appender(s) specified in the `AppenderRef` element(s). The root logger is referenced by the `Root` element. It can be set to `DEBUG`, `INFO`, `WARN`, `ERROR`, or `OFF`. The default log level is `INFO`. -<11> You can also define custom loggers to catch specific log events and send them to the appender(s) specified in the `AppenderRef` element(s). +<12> You can also define custom loggers to catch specific log events and send them to the appender(s) specified in the `AppenderRef` element(s). For example, the `QueryLogger` logger (configured in _server-logs.xml_) is used to catch log events with a log level of `INFO` or above and send them to the `QueryLog` appender. + The `additivity="false"` is set to fully consume the log event and not send it to the root logger. + If `additivity="true"` is set, which is the default, the log event is also sent to the root logger. @@ -428,23 +445,16 @@ a| `%n` For all available converters, consult the https://logging.apache.org/log4j/2.x/manual/layouts.html#PatternLayout[Log4j 2 Pattern Layout documentation]. -[[general-logging-debug-log-pattern]] -==== `` - -The `` layout is essentially the same as the xref:monitoring/logging.adoc#general-logging-pattern-layout[`PatternLayout`]. -The main difference is that a header is injected at the start of the log file with diagnostic information useful for Neo4j developers. -This layout should typically only be used for the _debug.log_ file. - -.An example usage of the Neo4j debug log layout -[source,xml] ----- - ----- - [[general-logging-json-template-layout]] ==== `` -The `` is equivalent to the pattern layout. -For more information, see the https://logging.apache.org/log4j/2.x/manual/json-template-layout.html[Log4j official documentation]. +The `` is equivalent to the pattern layout and is used to format log messages in JSON format. + +[NOTE] +==== +Starting from Neo4j 2025.01, JSON is the default format for the _debug.log_. +It is highly recommended not to alter the _debug.log_ format as it is required by Neo4j Customer Support to investigate problems. +If you require the _debug.log_ messages in a different format, create an additional Appender. +==== There are two ways of configuring the JSON template layout. @@ -458,7 +468,7 @@ The JSON template file can be on the file system. * The JSON event template file can be embedded in the XML configuration: + -[source%linenums,xml,highlight=4..12] +[source,xml,highlight=4..12] ---- @@ -514,6 +524,21 @@ There are also a couple of built-in templates available from the classpath, for | Same layout as the less flexible ``. |=== +For more information, see the https://logging.apache.org/log4j/2.x/manual/json-template-layout.html[Log4j official documentation]. + +[[general-logging-debug-log-pattern]] +==== `` + +The `` layout is essentially the same as the xref:monitoring/logging.adoc#general-logging-pattern-layout[`PatternLayout`]. +The main difference is that a header is injected at the start of the log file with diagnostic information useful for Neo4j developers. +This layout should typically only be used for the _debug.log_ file. + +.An example usage of the Neo4j debug log layout +[source,xml] +---- + +---- + === Filters You can also configure filters to determine if and what log events are published and how. @@ -575,7 +600,7 @@ The root logger is a special logger that matches everything, so if another logge Therefore, it is best practice always to include a root logger so that no log events are missed. .Configuration of loggers -[source%linenums,xml,options="nowrap"] +[source,xml,options="nowrap"] ---- @@ -684,7 +709,7 @@ dbms.security.log_successful_authentication=false The security log can use a JSON layout. To change the format, the layout for the `SecurityLogger` must be changed from using the `PatternLayout`: -[source%linenums,xml,options="nowrap",highlight=4] +[source,xml,options="nowrap",highlight=4] ---- @@ -698,7 +723,7 @@ To change the format, the layout for the `SecurityLogger` must be changed from u to using the `JsonTemplateLayout`: -[source%linenums,xml,options="nowrap",highlight=4] +[source,xml,options="nowrap",highlight=4] ---- @@ -1131,7 +1156,7 @@ In Neo4j Browser and Bloom, the user-provided metadata is always replaced by the The query log can use a JSON layout. To change the format, the layout for the `QueryLogger` must be changed from using the `PatternLayout`: -[source%linenums,xml,options="nowrap",highlight=4] +[source,xml,options="nowrap",highlight=4] ---- @@ -1145,7 +1170,7 @@ To change the format, the layout for the `QueryLogger` must be changed from usin to using the `JsonTemplateLayout`: -[source%linenums,xml,options="nowrap",highlight=4] +[source,xml,options="nowrap",highlight=4] ---- @@ -1310,7 +1335,7 @@ Additionally, GQL codes for external procedures are not yet stable. The following are examples of the `errorInfo` JSON object: .`errorInfo` JSON object of a database error -[source%linenums,xml,options="nowrap",highlight=4] +[source,xml,options="nowrap",highlight=4] ---- ... "errorInfo": { @@ -1327,7 +1352,7 @@ The following are examples of the `errorInfo` JSON object: ---- .`errorInfo` JSON object of a client error -[source%linenums,xml,options="nowrap",highlight=4] +[source,xml,options="nowrap",highlight=4] ---- ... "errorInfo": {