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

Fixing and adding missing abstracts in the Logging guide #35022

Merged
merged 1 commit into from
Jul 27, 2023
Merged

Fixing and adding missing abstracts in the Logging guide #35022

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
73 changes: 40 additions & 33 deletions docs/src/main/asciidoc/logging.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
[id="logging"]
= Logging configuration
include::_attributes.adoc[]
:categories: core,getting-started
:categories: core,getting-started,observability
:diataxis-type: reference

Read about the use of logging API in Quarkus, configuring logging output, and using logging adapters to unify the output from other logging APIs.
Expand All @@ -23,11 +23,11 @@
* link:https://logging.apache.org/log4j/1.2/[Apache Log4j 1]

[[jboss-logging]]
== Use JBoss Logging for application logging

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

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.Headings] Use sentence-style capitalization in 'Use JBoss Logging for application logging'.

Raw Output:
{"message": "[Quarkus.Headings] Use sentence-style capitalization in 'Use JBoss Logging for application logging'.", "location": {"path": "docs/src/main/asciidoc/logging.adoc", "range": {"start": {"line": 26, "column": 4}}}, "severity": "INFO"}

Check warning on line 26 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": 26, "column": 8}}}, "severity": "INFO"}

No additional dependencies are needed when using the JBoss Logging API; it is automatically provided.
When using the JBoss Logging API, your application requires no additional dependencies, as Quarkus automatically provides it.

Check warning on line 28 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": 28, "column": 16}}}, "severity": "INFO"}

.An example of using the JBoss Logging API to log a message:

Check warning on line 30 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": 30, "column": 26}}}, "severity": "INFO"}
[source,java]
----
import org.jboss.logging.Logger;
Expand Down Expand Up @@ -58,11 +58,11 @@

In Quarkus, the most common ways to obtain an application logger are by:

* <<declaring-a-loger-field,Declaring a logger field>>
* <<simplified-logging,Simplified logging>>
* <<injection-of-a-configured-logger,Injecting a configured logger>>
* <<declaring-a-logger-field>>
* <<simplified-logging>>
* <<injection-of-a-configured-logger>>

[[declaring-a-loger-field]]
[[declaring-a-logger-field]]
=== Declaring a logger field

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.
Expand Down Expand Up @@ -120,8 +120,7 @@
[[injection-of-a-configured-logger]]
=== Injecting a configured logger

The last alternative is to inject a configured `org.jboss.logging.Logger` logger instance by using the `@Inject` annotation.
This approach is applicable only for CDI beans.
The injection of a configured `org.jboss.logging.Logger` logger instance with the `@Inject` annotation is another alternative to adding an application logger, but is applicable only to CDI beans.

You can use `@Inject Logger log`, where the logger gets named after the class you inject it to, or `@Inject @LoggerName("...") Logger log`, where the logger will receive the specified name.
Once injected, you can use the `log` object to invoke logging methods.
Expand Down Expand Up @@ -154,6 +153,8 @@

== Use log levels

Quarkus provides different log levels, which helps developers control the amount of information logged based on the severity of the events.

.Log levels used by Quarkus

[horizontal]
Expand Down Expand Up @@ -199,11 +200,11 @@
|===


== Configure the log level, category and format
== Configure the log level, category, and format

Runtime logging is configured in the `application.properties` file.
JBoss Logging is built into Quarkus and provides link:https://quarkus.io/developer-joy/[unified configuration] for all <<logging-apis,supported logging APIs>>.

Check warning on line 205 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": 205, "column": 1}}}, "severity": "INFO"}

Because JBoss Logging is built in to Quarkus, link:https://quarkus.io/developer-joy/[unified configuration] is provided for all <<logging-apis,supported logging APIs>>.
Configure the runtime logging in the `application.properties` file.

.An example of how you can set the default log level to `INFO` logging and include Hibernate `DEBUG` logs:
[source, properties]
Expand Down Expand Up @@ -292,9 +293,8 @@

== Logging format

Quarkus uses a pattern-based logging formatter that generates human-readable text logs by default.
Quarkus uses a pattern-based logging formatter that generates human-readable text logs by default, but you can also configure the format for each log handler by using a dedicated property.

You can configure the format for each log handler by using a dedicated property.
MichalMaler marked this conversation as resolved.
Show resolved Hide resolved
For the console handler, the property is `quarkus.log.console.format`.

The logging format string supports the following symbols:
Expand Down Expand Up @@ -416,8 +416,12 @@

=== 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.
To log events to a file on the application's host, use the Quarkus file log handler.
The file log handler is disabled by default, so you must first enable it.

The Quarkus file log handler supports log file rotation.
Log file rotation ensures effective log file management over time by maintaining a specified number of backup log files, while also keeping the primary log file up-to-date and manageable.

MichalMaler marked this conversation as resolved.
Show resolved Hide resolved
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.

* A global configuration example:
Expand Down Expand Up @@ -526,7 +530,7 @@

== Logging configurations examples

This chapter provides examples of frequently used logging configurations.
The following examples show some of the ways in which you can configure logging in Quarkus:

Check warning on line 533 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": 533, "column": 37}}}, "severity": "INFO"}

.Console DEBUG logging except for Quarkus logs (INFO), no color, shortened time, shortened category prefixes
[source, properties]
Expand Down Expand Up @@ -589,14 +593,18 @@

== Centralized log management

Use a centralized location to efficiently collect, store, and analyze log data from various components and instances of the application.

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.

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

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.Spelling] Use correct American English spelling. Did you really mean 'Graylog'?

Raw Output:
{"message": "[Quarkus.Spelling] Use correct American English spelling. Did you really mean 'Graylog'?", "location": {"path": "docs/src/main/asciidoc/logging.adoc", "range": {"start": {"line": 598, "column": 33}}}, "severity": "WARNING"}

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

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.Spelling] Use correct American English spelling. Did you really mean 'Logstash'?

Raw Output:
{"message": "[Quarkus.Spelling] Use correct American English spelling. Did you really mean 'Logstash'?", "location": {"path": "docs/src/main/asciidoc/logging.adoc", "range": {"start": {"line": 598, "column": 42}}}, "severity": "WARNING"}

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

View workflow job for this annotation

GitHub Actions / Linting with Vale 

[vale] reported by reviewdog 🐶
[Quarkus.Spelling] Use correct American English spelling. Did you really mean 'Fluentd'?

Raw Output:
{"message": "[Quarkus.Spelling] Use correct American English spelling. Did you really mean 'Fluentd'?", "location": {"path": "docs/src/main/asciidoc/logging.adoc", "range": {"start": {"line": 598, "column": 55}}}, "severity": "WARNING"}


== Configure logging for `@QuarkusTest`

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

The system property must be set early on to be effective, so it is recommended to configure it in the build system.

.Example Configuration
.Setting the `java.util.logging.manager` system property in the Maven Surefire plugin configuration
[source, xml]
----
<build>
Expand Down Expand Up @@ -735,14 +743,14 @@

Quarkus overrides log MDC (Mapped Diagnostic Context) to improve the compatibility with its reactive core.

==== Adding and reading MDC data
==== Add and read MDC data

To add data to the MDC and extract it in your log output, you need to:
To add data to the MDC and extract it in your log output:

1. Use the `MDC` class to set the data
2. Customize the log format to use `%X\{mdc-key\}`
. Use the `MDC` class to set the data.
. Customize the log format to use `%X\{mdc-key\}`.

Let's consider the following code:

Check warning on line 753 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": 753, "column": 11}}}, "severity": "INFO"}

[source, java]
.Example with JBoss Logging and `io.quarkus.logging.Log`
Expand Down Expand Up @@ -789,23 +797,22 @@
Depending on the API you use, the MDC class is slightly different.
However, the APIs are very similar:

* log4j 1 - `org.apache.log4j.MDC.put(key, value)`
* log4j 2 - `org.apache.logging.log4j.ThreadContext.put(key, value)`
* slf4j - `org.slf4j.MDC.put(key, value)`
* Log4j 1 - `org.apache.log4j.MDC.put(key, value)`
* Log4j 2 - `org.apache.logging.log4j.ThreadContext.put(key, value)`
* SLF4J - `org.slf4j.MDC.put(key, value)`

[[mdc-propagation]]
==== MDC propagation

Under the hood, Quarkus provides a specific implementation of the MDC provider handling the reactive context.
Thus, the MDC data is propagated even when using reactive and asynchronous processing.
In Quarkus, the MDC provider has a specific implementation for handling the reactive context, ensuring that MDC data is propagated during reactive and asynchronous processing.

Consequently, the MDC data is still available:
As a result, you can still access the MDC data in various scenarios:

- after async calls (like a REST client returning a Uni)
- in the code submitted to the `ManagedExecutor` (`@Inject org.eclipse.microprofile.context.ManagedExecutor executor`)
- in the code executed using `vertx.executeBlocking()`
* After asynchronous calls, for example, when a REST client returns a Uni.
* In code submitted to `org.eclipse.microprofile.context.ManagedExecutor`.
* In code executed with `vertx.executeBlocking()`.

NOTE: When available, the MDC data is stored on a _duplicated context_ which is an isolated context for your processing.
NOTE: If applicable, MDC data is stored in a _duplicated context_, which is an isolated context for processing a single task (request).


[[loggingConfigurationReference]]
Expand Down
Loading