Skip to content

Commit

Permalink
Fixing abstracts in the Logging guide
Browse files Browse the repository at this point in the history 
Co-authored by Ladislav Thon

Apply suggestions from code review

Co-authored-by: Michelle Purcell <92924207+michelle-purcell@users.noreply.github.com>

Apply suggestions from code review

Co-authored-by: Michelle Purcell <92924207+michelle-purcell@users.noreply.github.com>
Co-authored-by: Ladislav Thon <ladicek@gmail.com>
  • Loading branch information
@MichalMaler @michelle-purcell @Ladicek
3 people committed Jul 26, 2023
1 parent da3b113 commit d77413f
Showing 1 changed file with 40 additions and 33 deletions.
73 changes: 40 additions & 33 deletions docs/src/main/asciidoc/logging.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
[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 @@ -25,7 +25,7 @@ You can use any of the <<logging-apis,following APIs>>:
[[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]
Expand Down Expand Up @@ -58,11 +58,11 @@ In such cases, you need to use a <<logging-apis,logging adapter>> to ensure that

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 @@ WARNING: Only use the `Log` API in application classes, not in external dependen
[[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 @@ NOTE: The logger instances are cached internally. Therefore, when a logger is in

== 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 @@ FINEST:: Increased debug output compared to `TRACE`, which might have a higher f
|===


== 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 @@ Although the root logger's handlers are usually configured directly via `quarkus

== 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.
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 @@ For details about its configuration, see the xref:#quarkus-log-logging-log-confi

=== 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.

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 @@ quarkus.log.console.filter=my-filter

== 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 @@ quarkus.log.handlers=CONSOLE_MIRROR

== 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,12 +743,12 @@ implementation("org.jboss.slf4j:slf4j-jboss-logmanager")

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"}

Expand Down Expand Up @@ -789,23 +797,22 @@ You get messages containing the MDC data:
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

0 comments on commit d77413f

Please sign in to comment.