This is an automated email from the ASF dual-hosted git repository. robbie pushed a commit to branch new-logging in repository https://gitbox.apache.org/repos/asf/activemq-artemis.git
commit 6ee0ba94d3f0a48de1783c64a8be5e5be77f4ad0 Author: Robbie Gemmell <[email protected]> AuthorDate: Fri Sep 9 16:42:32 2022 +0100 update documentation around logging --- TODO-new-logging.txt | 3 +- docs/migration-guide/en/configuration.md | 2 +- docs/user-manual/en/logging.md | 178 ++++++++++++------------------- docs/user-manual/en/using-server.md | 2 +- 4 files changed, 74 insertions(+), 111 deletions(-) diff --git a/TODO-new-logging.txt b/TODO-new-logging.txt index 2c80d3a35f..d98ba62b9a 100644 --- a/TODO-new-logging.txt +++ b/TODO-new-logging.txt @@ -3,6 +3,5 @@ TODOs not explicitly noted in the code itself already: - Remove JBL use from last remaining tests etc tests still using it - Restore the Travis config file - Delete the old DELETE-ME-logging.properties and DELETE-ME-tests-logging.properties files once all needed comparisons during old test etc config replacements are done. -- Update references to JBL and logging.properties in the documentation - Decide what if anything should be done around the removed logging config reload bits (Log4J2 enables reload itself, via its own config...or updates via management) -- Decide if we should use the auto-detected log4j2.properties config filename instead +- Decide if we should use the auto-detected log4j2.properties config filename instead of -Dlog4j2.configurationFile=log4j2-config.properties specified file. diff --git a/docs/migration-guide/en/configuration.md b/docs/migration-guide/en/configuration.md index b2311598c5..1b6b2092fa 100644 --- a/docs/migration-guide/en/configuration.md +++ b/docs/migration-guide/en/configuration.md @@ -22,7 +22,7 @@ The main configuration file is `etc/broker.xml`. Similarly to ActiveMQ's `conf/a The `etc/artemis.profile` file is similar to the `bin/env` file in ActiveMQ. Here you can configure environment variables for the broker, mostly regular JVM args related to SSL context, debugging, etc. -There's not much difference in logging configuration between two brokers, so anyone familiar with Java logging systems in general will find herself at home here. The `etc/logging.properties` file is where it's all configured. +There's not much difference in logging configuration between two brokers, so anyone familiar with Java logging systems in general will find herself at home here. The `etc/log4j-config.properties` file is where it's all configured. Finally, we have JAAS configuration files (`login.config`, `artemis-users.properties` and `artemis-roles.properties`), which cover same roles as in ActiveMQ and we will go into more details on these in the article that covers security. diff --git a/docs/user-manual/en/logging.md b/docs/user-manual/en/logging.md index 4cd5f2b69a..5b1acbc33c 100644 --- a/docs/user-manual/en/logging.md +++ b/docs/user-manual/en/logging.md @@ -1,14 +1,16 @@ # Logging -Apache ActiveMQ Artemis uses the JBoss Logging framework to do its logging and is -configurable via the `logging.properties` file found in the `etc` directory. This -is configured by default to log to both the console and to a file. +Apache ActiveMQ Artemis uses the [SLF4J](https://www.slf4j.org/) logging facade for logging, +with the broker assembly providing [Log4J 2](https://logging.apache.org/log4j/2.x/manual/) +as the logging implementation. This is configurable via the `log4j2-config.properties` file +found in the broker instance `etc` directory, which is configured by default to log to +both the console and to a file. There are a handful of general loggers available: Logger | Description ---|--- -org.jboss.logging|Logs any calls not handled by the Apache ActiveMQ Artemis loggers +rootLogger|Logs any calls not handled by the Apache ActiveMQ Artemis loggers org.apache.activemq.artemis.core.server|Logs the core server org.apache.activemq.artemis.utils|Logs utility calls org.apache.activemq.artemis.journal|Logs Journal calls @@ -22,108 +24,79 @@ org.apache.activemq.audit.message|message audit log. Disabled by default Sometimes it is necessary to get more detailed logs from a particular logger. For example, when you're trying to troublshoot an issue. Say you needed to get TRACE -logging from the logger `org.foo`. First you would need to add `org.foo` to the -`loggers` list at the top of `logging.properties`, e.g.: - -``` -loggers=...,org.foo -``` +logging from the logger `org.foo`. Then you need to configure the logging level for the `org.foo` logger to `TRACE`, e.g.: ``` -logger.org.foo.level=TRACE +logger.my_logger_ref.name=org.foo +my_logger_ref.level=TRACE ``` -Lastly, you would need to update the `level` of the necessary `handler` -to allow the `TRACE` logging through, e.g.: - -``` -handler.CONSOLE.level=TRACE -``` -or -``` -handler.FILE.level=TRACE -``` - -## Logging in a client or with an Embedded server +## Logging in a client application Firstly, if you want to enable logging on the client side you need to -include the JBoss logging jars in your application. If you are using -Maven the simplest way is to use the "all" client jar, e.g.: +include a logging implement in your application which supports the +the SLF4J facade. Using Log4J2 as an example logging implementation, as +it used by the broker, if you are using Maven your client and logging +dependencies might be e.g.: ```xml <dependency> - <groupId>org.jboss.logmanager</groupId> - <artifactId>jboss-logmanager</artifactId> - <version>2.1.10.Final</version> + <groupId>org.apache.activemq</groupId> + <artifactId>artemis-jms-client</artifactId> + <version>@PROJECT_VERSION_FILTER_TOKEN@</version> </dependency> <dependency> - <groupId>org.apache.activemq</groupId> - <artifactId>activemq-core-client-all</artifactId> - <version>2.16.0</version> + <groupId>org.apache.logging.log4j</groupId> + <artifactId>log4j-slf4j-impl</artifactId> + <version>2.18.0</version> </dependency> ``` -There are 2 properties you need to set when starting your java program, -the first is to set the Log Manager to use the JBoss Log Manager, this -is done by setting the `-Djava.util.logging.manager` property i.e.: +The Log4J2 configuration can then be supplied via file on the classpath +called `log4j2.properties` which will be picked up automatically. + +Alternatively, use of a specific configuration file can be configured via system +property `log4j2.configurationFile`, e.g.: ``` --Djava.util.logging.manager=org.jboss.logmanager.LogManager +-Dlog4j2.configurationFile=file:///path/to/log4j2-config.properties ``` -The second is to set the location of the logging.properties file to use, -this is done via the `-Dlogging.configuration`, e.g.: -``` --Dlogging.configuration=file:///home/user/projects/myProject/logging.properties +The following is an example `log4j2.properties` for a client + ``` +# Log4J 2 configuration -> **Note:** -> -> The `logging.configuration` system property needs to be valid URL +rootLogger = INFO, console, log_file -The following is a typical `logging.properties` for a client +logger.activemq.name=org.apache.activemq +logger.activemq.level=INFO -``` -# Root logger option -loggers=org.jboss.logging,org.apache.activemq.artemis.core.server,org.apache.activemq.artemis.utils,org.apache.activemq.artemis.journal,org.apache.activemq.artemis.jms,org.apache.activemq.artemis.ra - -# Root logger level -logger.level=INFO -# Apache ActiveMQ Artemis logger levels -logger.org.apache.activemq.artemis.core.server.level=INFO -logger.org.apache.activemq.artemis.utils.level=INFO -logger.org.apache.activemq.artemis.jms.level=DEBUG - -# Root logger handlers -logger.handlers=FILE,CONSOLE - -# Console handler configuration -handler.CONSOLE=org.jboss.logmanager.handlers.ConsoleHandler -handler.CONSOLE.properties=autoFlush -handler.CONSOLE.level=FINE -handler.CONSOLE.autoFlush=true -handler.CONSOLE.formatter=PATTERN - -# File handler configuration -handler.FILE=org.jboss.logmanager.handlers.FileHandler -handler.FILE.level=FINE -handler.FILE.properties=autoFlush,fileName -handler.FILE.autoFlush=true -handler.FILE.fileName=activemq.log -handler.FILE.formatter=PATTERN - -# Formatter pattern configuration -formatter.PATTERN=org.jboss.logmanager.formatters.PatternFormatter -formatter.PATTERN.properties=pattern -formatter.PATTERN.pattern=%d{HH:mm:ss,SSS} %-5p [%c] %s%E%n +# Console appender +appender.console.type=Console +appender.console.name=console +appender.console.layout.type=PatternLayout +appender.console.layout.pattern=%d %-5level [%logger] %msg%n + +# Log file appender +appender.log_file.type = RollingFile +appender.log_file.name = log_file +appender.log_file.fileName = log/application.log +appender.log_file.filePattern = log/application.log.%d{yyyy-MM-dd} +appender.log_file.layout.type = PatternLayout +appender.log_file.layout.pattern = %d %-5level [%logger] %msg%n +appender.log_file.policies.type = Policies +appender.log_file.policies.cron.type = CronTriggeringPolicy +appender.log_file.policies.cron.schedule = 0 0 0 * * ? +appender.log_file.policies.cron.evaluateOnStartup = true ``` -## Configuring Audit Logging +## Configuring Broker Audit Logging There are 3 audit loggers that can be enabled separately and audit -different types of events, these are: +different types of broker events, these are: 1. **base**: This is a highly verbose logger that will capture most events that occur on JMX beans. @@ -138,34 +111,34 @@ different types of events, these are: > All extra logging will negatively impact performance. Whether or not > the performance impact is "too much" will depend on your use-case. -These three audit loggers are disabled by default in the -`logging.properties` configuration file: +These three audit loggers are disabled by default in the broker +`log4j2-config.properties` configuration file: ``` -loggers=...,org.apache.activemq.audit.base,org.apache.activemq.audit.message,org.apache.activemq.audit.resource ... -logger.org.apache.activemq.audit.base.level=ERROR -logger.org.apache.activemq.audit.base.handlers=AUDIT_FILE -logger.org.apache.activemq.audit.base.useParentHandlers=false - -logger.org.apache.activemq.audit.resource.level=ERROR -logger.org.apache.activemq.audit.resource.handlers=AUDIT_FILE -logger.org.apache.activemq.audit.resource.useParentHandlers=false - -logger.org.apache.activemq.audit.message.level=ERROR -logger.org.apache.activemq.audit.message.handlers=AUDIT_FILE -logger.org.apache.activemq.audit.message.useParentHandlers=false +# Audit loggers: to enable change levels from OFF to INFO +logger.audit_base = OFF, audit_log_file +logger.audit_base.name = org.apache.activemq.audit.base +logger.audit_base.additivity = false + +logger.audit_resource = OFF, audit_log_file +logger.audit_resource.name = org.apache.activemq.audit.resource +logger.audit_resource.additivity = false + +logger.audit_message = OFF, audit_log_file +logger.audit_message.name = org.apache.activemq.audit.message +logger.audit_message.additivity = false ... ``` -To *enable* the audit log change the `level` attributes to `INFO`, like +To *enable* the audit log change the level to `INFO`, like this: ``` -logger.org.apache.activemq.audit.base.level=INFO +logger.audit_base = INFO, audit_log_file ... -logger.org.apache.activemq.audit.resource.level=INFO +logger.audit_resource = INFO, audit_log_file ... -logger.org.apache.activemq.audit.message.level=INFO +logger.audit_message = INFO, audit_log_file ``` The 3 audit loggers can be disable/enabled separately. @@ -192,15 +165,6 @@ org.apache.activemq.artemis.spi.core.security.jaas.AuditLoginModule optional > This login module does no authentication, it is used only to catch client > information through which ever path a client takes -## Use Custom Handlers - -To use a different handler than the built-in ones, you either pick one from -existing libraries or you implement it yourself. All handlers must extends the -`java.util.logging.Handler` class. - -To enable a custom handler you need to append it to the handlers list -`logger.handlers` and add its configuration to the `logging.configuration`. +## More on Log4J2 configuration: -Last but not least, once you get your own handler please [add it to the boot -classpath](using-server.md#adding-bootstrap-dependencies) otherwise the log -manager will fail to load it! +For more detail on configuring Log4J 2, see its [manual](https://logging.apache.org/log4j/2.x/manual/). diff --git a/docs/user-manual/en/using-server.md b/docs/user-manual/en/using-server.md index 27673b7e4d..17e7707a22 100644 --- a/docs/user-manual/en/using-server.md +++ b/docs/user-manual/en/using-server.md @@ -441,7 +441,7 @@ further for additional details as appropriate. diverts, clustering; [full reference](configuration-index.md). - `jolokia-access.xml` - [security for Jolokia](https://jolokia.org/reference/html/security.html), specifically Cross-Origin Resource Sharing (CORS) - - `logging.properties` - [logging config](logging.md) like levels, log files + - `log4j2-config.properties` - [logging config](logging.md) like levels, log files locations, etc. - `login.config` - standard Java configuration for JAAS [security](security.md) - `management.xml` - remote connectivity and [security for JMX MBeans](management.md#role-based-authorisation-for-jmx)
