Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Proper ordering of the handlers chapters and addition of some examples in the Logging guide #34860

Merged
merged 1 commit into from
Jul 24, 2023
Merged

Proper ordering of the handlers chapters and addition of some examples in the Logging guide #34860

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
150 changes: 107 additions & 43 deletions docs/src/main/asciidoc/logging.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,12 +11,12 @@

Read about the use of logging API in Quarkus, configuring logging output, and using logging adapters to unify the output from other logging APIs.

Quarkus uses the JBoss Log Manager logging backend for publishing application and framework logs.

Check warning on line 14 in docs/src/main/asciidoc/logging.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.CaseSensitiveTerms] Use 'JBoss EAP' rather than 'JBoss'.

Raw Output:
{"message": "[Quarkus.CaseSensitiveTerms] Use 'JBoss EAP' rather than 'JBoss'.", "location": {"path": "docs/src/main/asciidoc/logging.adoc", "range": {"start": {"line": 14, "column": 18}}}, "severity": "INFO"}
Quarkus supports the JBoss Logging API as well as multiple other logging APIs, seamlessly integrated with JBoss Log Manager.

Check warning on line 15 in docs/src/main/asciidoc/logging.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.CaseSensitiveTerms] Use 'JBoss EAP' rather than 'JBoss'.

Raw Output:
{"message": "[Quarkus.CaseSensitiveTerms] Use 'JBoss EAP' rather than 'JBoss'.", "location": {"path": "docs/src/main/asciidoc/logging.adoc", "range": {"start": {"line": 15, "column": 22}}}, "severity": "INFO"}

Check warning on line 15 in docs/src/main/asciidoc/logging.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.CaseSensitiveTerms] Use 'JBoss EAP' rather than 'JBoss'.

Raw Output:
{"message": "[Quarkus.CaseSensitiveTerms] Use 'JBoss EAP' rather than 'JBoss'.", "location": {"path": "docs/src/main/asciidoc/logging.adoc", "range": {"start": {"line": 15, "column": 107}}}, "severity": "INFO"}
You can use any of the <<logging-apis, following APIs>>:
You can use any of the <<logging-apis,following APIs>>:

* link:https://github.com/jboss-logging/jboss-logging[JBoss Logging]
* JDK `java.util.logging` (JUL)

Check warning on line 19 in docs/src/main/asciidoc/logging.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.CaseSensitiveTerms] Use 'OpenJDK' rather than 'JDK'.

Raw Output:
{"message": "[Quarkus.CaseSensitiveTerms] Use 'OpenJDK' rather than 'JDK'.", "location": {"path": "docs/src/main/asciidoc/logging.adoc", "range": {"start": {"line": 19, "column": 3}}}, "severity": "INFO"}
* link:https://www.slf4j.org/[SLF4J]
* link:https://commons.apache.org/proper/commons-logging/[Apache Commons Logging]
* link:https://logging.apache.org/log4j/2.x/[Apache Log4j 2]
Expand Down Expand Up @@ -51,8 +51,8 @@
}
----

NOTE: While JBoss Logging routes log messages into JBoss Log Manager directly, one of your libraries might rely on a different logging API.

Check warning on line 54 in docs/src/main/asciidoc/logging.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.CaseSensitiveTerms] Use 'JBoss EAP' rather than 'JBoss'.

Raw Output:
{"message": "[Quarkus.CaseSensitiveTerms] Use 'JBoss EAP' rather than 'JBoss'.", "location": {"path": "docs/src/main/asciidoc/logging.adoc", "range": {"start": {"line": 54, "column": 13}}}, "severity": "INFO"}

Check warning on line 54 in docs/src/main/asciidoc/logging.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.CaseSensitiveTerms] Use 'JBoss EAP' rather than 'JBoss'.

Raw Output:
{"message": "[Quarkus.CaseSensitiveTerms] Use 'JBoss EAP' rather than 'JBoss'.", "location": {"path": "docs/src/main/asciidoc/logging.adoc", "range": {"start": {"line": 54, "column": 52}}}, "severity": "INFO"}
In such cases, you need to use a <<logging-apis, logging adapter>> to ensure that its log messages are routed to JBoss Log Manager as well.
In such cases, you need to use a <<logging-apis,logging adapter>> to ensure that its log messages are routed to JBoss Log Manager as well.

Check warning on line 55 in docs/src/main/asciidoc/logging.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.Fluff] Depending on the context, consider using 'Rewrite the sentence, or use 'must', instead of' rather than 'need to'.

Raw Output:
{"message": "[Quarkus.Fluff] Depending on the context, consider using 'Rewrite the sentence, or use 'must', instead of' rather than 'need to'.", "location": {"path": "docs/src/main/asciidoc/logging.adoc", "range": {"start": {"line": 55, "column": 20}}}, "severity": "INFO"}

Check warning on line 55 in docs/src/main/asciidoc/logging.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.CaseSensitiveTerms] Use 'JBoss EAP' rather than 'JBoss'.

Raw Output:
{"message": "[Quarkus.CaseSensitiveTerms] Use 'JBoss EAP' rather than 'JBoss'.", "location": {"path": "docs/src/main/asciidoc/logging.adoc", "range": {"start": {"line": 55, "column": 113}}}, "severity": "INFO"}

== Get an application logger

Expand All @@ -67,9 +67,9 @@

With this classic approach, you use a specific API to obtain a logger instance, store it in a static field of a class, and call logging operations upon this instance.

The same flow can be applied with any of the <<logging-apis, supported logging APIs>>.
The same flow can be applied with any of the <<logging-apis,supported logging APIs>>.

.An example of storing a logger instance into a static field by using the JBoss Logging API:

Check warning on line 72 in docs/src/main/asciidoc/logging.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.CaseSensitiveTerms] Use 'JBoss EAP' rather than 'JBoss'.

Raw Output:
{"message": "[Quarkus.CaseSensitiveTerms] Use 'JBoss EAP' rather than 'JBoss'.", "location": {"path": "docs/src/main/asciidoc/logging.adoc", "range": {"start": {"line": 72, "column": 75}}}, "severity": "INFO"}
[source,java]
----
package com.example;
Expand Down Expand Up @@ -230,9 +230,8 @@
[WARNING]
====
If you add these properties on the command line, ensure the `"` character is escaped properly:

----
`-Dquarkus.log.category.\"org.hibernate\".level=TRACE`
-Dquarkus.log.category.\"org.hibernate\".level=TRACE
----
====

Expand All @@ -251,9 +250,7 @@

If you want to configure something extra for a specific category, create a named handler like `quarkus.log.handler.[console|file|syslog].<your-handler-name>.*` and set it up for that category by using `quarkus.log.category.<my-category>.handlers`.

//TODO: Add a better, real-world example of a handler configuration for a more specific category. CC DML

An example use case can be a desire to use a different timestamp format for log messages which are saved to a file than the format used for other handlers.

Check warning on line 253 in docs/src/main/asciidoc/logging.adoc

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.TermsSuggestions] Depending on the context, consider using ', which (non restrictive clause preceded by a comma)' or 'that (restrictive clause without a comma)' rather than 'which'.

Raw Output:
{"message": "[Quarkus.TermsSuggestions] Depending on the context, consider using ', which (non restrictive clause preceded by a comma)' or 'that (restrictive clause without a comma)' rather than 'which'.", "location": {"path": "docs/src/main/asciidoc/logging.adoc", "range": {"start": {"line": 253, "column": 89}}}, "severity": "INFO"}

For further demonstration, see the outputs of the <<category-named-handlers-example,Attaching named handlers to a category>> example.

Expand Down Expand Up @@ -385,28 +382,109 @@
NOTE: Printing the details can be expensive as the values are retrieved from the caller.
The details include the source class name, source file name, source method name, and source line number.


== Log handlers

A log handler is a logging component responsible for the emission of log events to a recipient.
Quarkus includes several different log handlers: **console**, **file**, and **syslog**.

The featured examples use `com.example` as a logging category.

=== Console log handler

The console log handler is enabled by default, and it directs all log events to the application's console, usually the system's `stdout`.

* A global configuration example:
+
[source, properties]
----
quarkus.log.console.format=%d{yyyy-MM-dd HH:mm:ss} %-5p [%c] (%t) %s%e%n
----

* A per-category configuration example:
+
[source, properties]
----
quarkus.log.handler.console.my-console-handler.format=%d{yyyy-MM-dd HH:mm:ss} [com.example] %s%e%n

quarkus.log.category."com.example".handlers=my-console-handler
quarkus.log.category."com.example".use-parent-handlers=false
----

For details about its configuration, see the xref:#quarkus-log-logging-log-config_quarkus.log.console-console-logging[console logging configuration] reference.

=== Logging filters

Log handlers, including the console log handler, can be associated with a link:https://docs.oracle.com/en/java/javase/11/docs/api/java.logging/java/util/logging/Filter.html[filter] that determines whether a log record should be logged or not.
=== File log handler

To register a logging filter, annotate a (`final`) class that implements `java.util.logging.Filter` with `@io.quarkus.logging.LoggingFilter` and set the `name` property.
The filter is then attached to the appropriate handler using the `filter` configuration property.
By default, the file log handler in Quarkus is disabled.
Once enabled, it enables the logging of all events to a file on the application's host, while also supporting log file rotation.
Log file rotation ensures effective log file management over time by maintaining a specified number of backup log files, while keeping the primary log file up-to-date and manageable.

For instance, if you want to filter out log records containing specific text from the console logs, you can define the text as part of the application configuration instead of hardcoding it.
* A global configuration example:
+
[source, properties]
----
quarkus.log.file.enable=true
quarkus.log.file.path=application.log
quarkus.log.file.format=%d{yyyy-MM-dd HH:mm:ss} %-5p [%c] (%t) %s%e%n
----

.An example of how you can write a filter:
====
* A per-category configuration example:
+
[source, properties]
----
quarkus.log.handler.file.my-file-handler.enable=true
quarkus.log.handler.file.my-file-handler.path=application.log
quarkus.log.handler.file.my-file-handler.format=%d{yyyy-MM-dd HH:mm:ss} [com.example] %s%e%n

quarkus.log.category."com.example".handlers=my-file-handler
quarkus.log.category."com.example".use-parent-handlers=false
----

For details about its configuration, see the xref:#quarkus-log-logging-log-config_quarkus.log.file-file-logging[file logging configuration] reference.


=== Syslog log handler

The syslog handler in Quarkus follows the link:https://en.wikipedia.org/wiki/Syslog[Syslog] protocol, which is used to send log messages on Unix-like systems.
It utilizes the protocol defined in link:https://tools.ietf.org/html/rfc5424[RFC 5424].

By default, the syslog handler is disabled.
When enabled, it sends all log events to a syslog server, typically the local syslog server for the application.

* A global configuration example:
+
[source, properties]
----
quarkus.log.syslog.enable=true
quarkus.log.syslog.app-name=my-application
quarkus.log.syslog.format=%d{yyyy-MM-dd HH:mm:ss} %-5p [%c] (%t) %s%e%n
----

* A per-category configuration example:
+
[source, properties]
----
quarkus.log.handler.syslog.my-syslog-handler.enable=true
quarkus.log.handler.syslog.my-syslog-handler.app-name=my-application
quarkus.log.handler.syslog.my-syslog-handler.format=%d{yyyy-MM-dd HH:mm:ss} [com.example] %s%e%n

quarkus.log.category."com.example".handlers=my-syslog-handler
quarkus.log.category."com.example".use-parent-handlers=false
----

For details about its configuration, see the xref:#quarkus-log-logging-log-config_quarkus.log.syslog-syslog-logging[Syslog logging configuration] reference.


== Add a logging filter to your log handler

Log handlers, such as the console log handler, can be linked with a link:https://docs.oracle.com/en/java/javase/11/docs/api/java.logging/java/util/logging/Filter.html[filter] that determines whether a log record should be logged.

To register a logging filter:

. Annotate a `final` class that implements `java.util.logging.Filter` with `@io.quarkus.logging.LoggingFilter`, and set the `name` property:
+
.An example of writing a filter:
[source,java]
----
import io.quarkus.logging.LoggingFilter;
Expand All @@ -428,37 +506,22 @@
}
}
----

.Then, configure it in the usual Quarkus way, for example, by using `application.properties`:
[source,properties]
+
In this example, we exclude log records containing specific text from console logs.
The specific text to filter on is not hard-coded; instead, it is read from the `my-filter.part` configuration property.
+
.An example of Configuring the filter in `application.properties`:
[source, properties]
----
my-filter.part=TEST
----

.Lastly, register this filter to the console handler:
. Attach the filter to the corresponding handler using the `filter` configuration property, located in `application.properties`:
+
[source, properties]
----
quarkus.log.console.filter=my-filter
----
====

=== File log handler

By default, the file log handler in Quarkus is disabled.
Once enabled, it enables the logging of all events to a file on the application's host, while also supporting log file rotation.
Log file rotation ensures effective log file management over time by maintaining a specified number of backup log files, while keeping the primary log file up-to-date and manageable.

For details about its configuration, see the xref:#quarkus-log-logging-log-config_quarkus.log.file-file-logging[file logging configuration] reference.

=== Syslog log handler

The syslog handler in Quarkus follows the link:https://en.wikipedia.org/wiki/Syslog[Syslog] protocol, which is used to send log messages on Unix-like systems.
It utilizes the protocol defined in link:https://tools.ietf.org/html/rfc5424[RFC 5424].

By default, the syslog handler is disabled.
When enabled, it sends all log events to a syslog server, typically the local syslog server for the application.

For details about its configuration, see the xref:#quarkus-log-logging-log-config_quarkus.log.syslog-syslog-logging[Syslog logging configuration] reference.


== Logging configurations examples
Expand All @@ -475,10 +538,10 @@
quarkus.log.category."io.quarkus".level=INFO
----

NOTE: If you are adding these properties via command line make sure `"` is escaped.
For example `-Dquarkus.log.category.\"io.quarkus\".level=DEBUG`.
NOTE: If you add these properties in the command line, ensure `"` is escaped.
For example, `-Dquarkus.log.category.\"io.quarkus\".level=DEBUG`.

[#category-example]
[[category-example]]
.File TRACE logging configuration
[source, properties]
----
Expand All @@ -493,7 +556,7 @@
quarkus.log.category."io.undertow.request.security".level=TRACE
----

NOTE: As we don't change the root logger, console log will only contain `INFO` or higher order logs.
NOTE: As we don't change the root logger, the console log will only contain `INFO` or higher level logs.

[#category-named-handlers-example]
.Named handlers attached to a category
Expand Down Expand Up @@ -523,14 +586,15 @@
quarkus.log.handlers=CONSOLE_MIRROR
----


== Centralized log management

To send logs to a centralized tool such as Graylog, Logstash, or Fluentd, see the Quarkus xref:centralized-log-management.adoc[Centralized log management] guide.

== Configure logging for `@QuarkusTest`

To configure logging for your `@QuarkusTest`, ensure that you configure the `maven-surefire-plugin` accordingly.
Specifically, you need to set the appropriate `LogManager` by using the `java.util.logging.manager` system property.
Specifically, set the appropriate `LogManager` by using the `java.util.logging.manager` system property.

.Example Configuration
[source, xml]
Expand Down Expand Up @@ -571,7 +635,7 @@
Quarkus relies on the JBoss Logging library for all the logging requirements.

Suppose you use libraries that depend on other logging libraries, such as Apache Commons Logging, Log4j, or SLF4J.
In that case, you need to exclude them from the dependencies and use one of the JBoss Logging adapters.
In that case, exclude them from the dependencies and use one of the JBoss Logging adapters.

This is especially important when building native executables, as you could encounter issues similar to the following when compiling the native executable:

Expand Down
Loading