Log format fields may not be clear

[mbroz2]

Document: Log and trace configuration
http://openliberty.io/docs/latest/log-trace-configuration.html

A question was posed by a user as to what the I, A, O letters stand for when the SIMPLE (default) log format is used.
It does not seem as though we explain the log formats, but rather only provide an example. Therefore it may not be clear as to what the various parts of some of the formats represent (like the consoleLogLevel represented by the first letter of the valid values).

[dmuelle]

Hi @mbroz2 @pgunapal

I've updated the log formats section here to include details abut the log-level codes:

https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/log-trace-configuration.html#log-level

What other information do we want to include about the fields in different log formats? Depending on what other information we need, the organization of this info might change, particularly if we explain all fields for each format.

[pgunapal]

@dmuelle Looks good, just a minor type where there is an extra ":" after A and E.

Regarding the different fields for each log format, I suggest we can specify the "Template" of how the message would look like based on the different log format and provided the example for each format. It would be more clear to users on the contents of the logs based on the different log formats.

For example, something like the following:
For Dev log format, the messages should appear in the following format:
<LogLevel> <MessageID> <Message>

Similarly, for Simple/TBASIC log format:
<Time Stamp> <ThreadID> <Fully qualified className> <Log Level Attribute> <MessageID> <Message>

For JSON, Enhanced, Advanced, are self-explanatory, since the corresponding fields have field names, as well as, JSON format has its own section.

[dmuelle]

Thanks @pgunapal - I've updated the format descriptions with a "template" for simple and tbasic

https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/log-trace-configuration.html#log-level

I'm not sure if we should include more info for Enhanced and Advanced- although the enhanced has field names, both these formats contain elements that are not addressed by the current descriptions and I wasn't sure how to define/explain them. Let me know what you think. Thanks!

[pgunapal]

@dmuelle
Is the extra space between the <, >, and field names required, in the template?
There is an extra ":" after A and E.

The field names in the Enhanced format are components from the Log Record for that particular trace message, that provided additional details about the trace message. It contains the type of the message, the date and time, messageID, fully qualified classname, severity level, log level, method name, classname, level value, thread name, correlationID, or, product, component, message and objectID.

For Advanced, it is similar to Enhanced, but the format is similar to how the Advanced traceFormat in traditional WAS is. It preserves more specific trace information.

[dmuelle]

Thanks @pgunapal - i've updated the draft:

https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/log-trace-configuration.html#log-level

• removed spaces from field name examples
• removed extra : from table
• added new descriptions for ADVANCED and ENHANCED formats

If any further edits are needed, just let me know. When you're satisfied with the update, you can add the technical reviewed label to sign off and the update will publish with the 23.0.0.11 docs release. Thanks!

[pgunapal]

Looks good, added the technical reviewed label

[dmuelle]

Hi @ramkumar-k-9286 - this update is ready for peer review. Only the linked section of the doc needs review.

https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/log-trace-configuration.html#log_formats

[ramkumar-k-9286]

Peer Review

The log format has an anchor and is linked in the beginning, but JSON logging is not. Should it not be linked?

---

For example, you might choose to output your messages log in JSON format if it is consumed by a log analysis platform.
->
For example, you might choose to output your message log in JSON format if a log analysis platform uses it.

Acrolinx suggestion - consumed -> used - simpler usage.

I see that the file name is messages.log, but Acrolinx picks up " output your messages log in JSON format " -> so can we say " output your message log file in JSON format"?

---

[AUDIT ] CWWKF0011I: The defaultServer server is ready to run a smarter planet. The defaultServer server started in 7.967 seconds.
->
[AUDIT] CWWKF0011I: The defaultServer server is ready to run a smarter planet. The defaultServer server started in 7.967 seconds.

in the code-block [AUDIT] -> is not showing up correctly (square brackets).

---

For more information, see JSON logging.
->
In the document, [+] is showing up before "For more information, see".

---

In this example, the A attribute that precedes the CWWKF0011I message ID code indicates that the message log level is AUDIT.
->
In the document, [+] is showing up before "In this example, the A attribute".

---

For more information about TBASIC, see TBASIC log format.
->
In the document, [+] is showing up before "For more information about TBASIC, see".

---

Messages in ENHANCED format include field names that are components from the log record for the particular trace message, which provide additional details about the trace message. These details include the message type, the date and time, messageID, fully qualified class name, severity level, log level, method name, class name, level value, thread name, correlationID (or product, component, message and objectID).
->
Messages in ENHANCED format include field names that are components from the log record for the particular trace message, which provide additional details about the trace message. These details include the message type, the date and time, messageID, fully qualified class name, severity level, log level, method name, class name, level value, thread name, correlationID (or product, component, message**,** and objectID).

Acrolinx -> replace additional with more.
These details include the message type, the date and time, messageID, fully qualified class name, severity level, log level, method name, class name, level value, thread name, correlationID (or product, component, message and objectID). -> too complex

Q: -> ...thread name, correlationID (or product, component, message**,** and objectID). -> is the or placed correctly?

---

Messages that are in DEV format print the full log-level name before the message ID code. Messages that are in JSON or ENHANCED format include a loglevel property that identifies the message log level.
->
Messages that are in DEV format print the full log-level name before the message ID code. Messages that are in JSON or ENHANCED format include a loglevel property that identifies the message log level.

---

Messages that are in SIMPLE or TBASIC format include one of the following message log-level attributes directly before the message ID code:
->
Messages that are in SIMPLE or TBASIC format include one of the following message log-level attributes directly before the message ID code:

---

Info messages are written to the system output stream.
->
Information messages are written to the system output stream.

---

I saw that log level is mentioned in 2 ways across the document: log level and log-level - Which one should be used?

---

The TBASIC logging format provides a consistent log format across your Open Liberty console, message, and trace log files. The BASIC logging format exists for the trace log. However, the output differs between the trace log and that of the console and messages logs. The TBASIC format provides a consistent format option for the trace, console, and messages logs that matches the BASIC option for the trace log. The TBASIC format acts as an alias for the BASIC option.
->
The TBASIC logging format provides a consistent log format across your Open Liberty console, message, and trace log files. The BASIC logging format exists for the trace log. However, the output differs between the trace log and that of the console and messages logs. The TBASIC format provides a consistent format option for the trace, console, and messages logs that match the BASIC option for the trace log. The TBASIC format acts as an alias for the BASIC option.

---

You can also specify the TBASIC log format for the messages and console logs as an environment variable in your server.env file, as shown in the following example:
->
You can also specify the TBASIC log format for the messages and console logs as an environment variable in your server.env file, as shown in the following example:

---

[dmuelle]

Thanks for reviewing- all suggestions implemented except:

Information messages are written to the system output stream.-

"Info" is the message type

Q: -> ...thread name, correlationID (or product, component, message**,** and objectID). -> is the or placed correctly?

yes, the latter three are an alternative to the first

I saw that log level is mentioned in 2 ways across the document: log level and log-level - Which one should be used?

log-level is used when the term is a compound adjective describing the attributes, otherwise "log level".