Commit a84b84b2 authored by Sarah White's avatar Sarah White

adr(logging): revise document for clarity

parent 4cc7a13d
= ADR 0003: Logging Mechanism
revdate: 2017-11-18
== Status
......@@ -7,31 +8,41 @@ Accepted
== Context
Antora needs to capture, record, and communicate information about what's happening in the pipeline.
To the end user, the application needs to communicate information that keep the users informed of the application's progress and any decisions it makes.
To the end user, the application needs to communicate information about the application's progress and any decisions it makes.
To the developer, the application needs to capture and record information to aid in debugging when the application malfunctions.
Reporting this diagnostic information is called logging.
Logging helps both end users and developers understand better how the application works.
Logging helps end users and developers understand better how the application works.
Messages should not be sent directly to the standard streams as these are hard to control and couple the application to a console environment.
Instead, messages should be sent to a logging subsystem that allows the user, whether an end user or a developer, to tune the verbosity of the messages, control where they are written, and customize how they are organized and formatted.
We can imagine in the future wanting to sent messages to an external service for monitoring.
Messages *should not* be sent directly to the standard streams.
This would make the messages hard to control and couple the application to a console environment.
Node does not provide a standard logging module.
Therefore, we will need to evaluate available logging libraries and select one.
Instead, messages should:
* be sent to a logging subsystem
* include the timestamp when the message was recorded
* have minimal impact on the application's performance
The logging library should allow the user to:
* tune the verbosity of the messages
* control where messages are written
* customize how the messages are organized and formatted
Logging should have minimal impact on the application's performance.
One of the most important pieces of information in the message is the timestamp at which it was recorded.
In the future, we anticipate wanting to send messages to an external service for monitoring.
Node does not provide a standard logging module.
Therefore, we had to evaluate available logging libraries and select one.
== Decision
We evaluated the following logging libraries:
* https://yarnpkg.com/en/package/winston[winston] - a multi-transport sync logging library for Node.js
* https://yarnpkg.com/en/package/aurelia-logging[aurelia-logging] - a minimal but effective logging mechanism with support for log levels and pluggable log appenders
* https://yarnpkg.com/en/package/winston[Winston] - a multi-transport sync logging library for Node.js
* https://yarnpkg.com/en/package/aurelia-logging[Aurelia Logging] - a minimal but effective logging mechanism with support for log levels and pluggable log appenders
We have decided to select *winston* because it's both robust and flexible, it's broadly adopted, and has strong documentation.
Specifically, we want to use *winston 3* (currently in pre-release at the time of this writing) because it adds custom message formatting.
We have decided to select *Winston* because it's both robust and flexible, it's broadly adopted, and has strong documentation.
Specifically, we want to use *Winston 3* (currently in pre-release at the time of this writing) because it adds custom message formatting.
In particular, here's what we like about it:
......@@ -42,9 +53,9 @@ In particular, here's what we like about it:
* custom levels
* exception handling
* profiling
* single package w/ small size (~ 232K + 400K dependencies)
* single package and small size (~ 232K + 400K dependencies)
Here's a basic example of how to use winston to log a message:
Here's a basic example of how to use Winston to log a message:
[source,js]
----
......@@ -66,11 +77,12 @@ const logger = winston.loggers.add('antora', {
logger.info('holler')
----
We can start by creating a global logger that is either passed to each of the components or accessible through a globally accessible component.
As we become more familiar with it, we may learn better ways to use it.
We decided against Aurelia Logging because it does not offer some of the capabilities mentioned above and lacks documentation.
== Consequences
Adding the logging library Winston to Antora allows us to send customized messages to a logging subsystem with minimum impact to the pipeline's performance.
A logging library adds a dependency to the project.
However, since Node does not provide a built-in logging mechanism, this is unavoidable (as we've already ruled out logging to standard streams).
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment