juneau-doc/docs/Topics/11.juneau-microservice-core/09.Logging.html

<!--
/***************************************************************************************************************************
 * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *  
 *  http://www.apache.org/licenses/LICENSE-2.0
 *  
 * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations under the License.
 ***************************************************************************************************************************/
 -->

{8.0.0-new, 8.1.2-deprecated} 
Logging

<p>
	The Microservice API provides build-in but configurable and overridable support for logging.
</p>
<p>
	The method for configuring logging is as follows:
</p>
<ul class='javatree'>
	<li class='jc'>{@link oaj.microservice.MicroserviceBuilder}
	<ul>
		<li class='jm'>{@link oaj.microservice.MicroserviceBuilder#logConfig(LogConfig) logConfig(LogConfig)} 
		<li class='jm'>{@link oaj.microservice.MicroserviceBuilder#logger(Logger) logger(Logger)} 
	</ul>
</ul>
<p>
	If not specified, the logging configuration is pulled in from the configuration file:
</p>
<p class='bpcode w800'>
	<jc>#=======================================================================================================================
	# Logger settings
	#-----------------------------------------------------------------------------------------------------------------------
	# See FileHandler Java class for details.
	#=======================================================================================================================</jc>
	<cs>[Logging]</cs>
	
	<jc># The directory where to create the log file.
	# Default is "."</jc>
	<ck>logDir</ck> = <cv>logs</cv>
	
	<jc># The name of the log file to create for the main logger.
	# The logDir and logFile make up the pattern that's passed to the FileHandler
	# constructor.
	# If value is not specified, then logging to a file will not be set up.</jc>
	<ck>logFile</ck> = <cv>microservice.%g.log</cv>
	
	<jc># Whether to append to the existing log file or create a new one.</jc>
	<ck>append</ck> = <cv>false</cv>
	
	<jc># The SimpleDateFormat format to use for dates.</jc>
	<ck>dateFormat</ck> = <cv>yyyy.MM.dd hh:mm:ss</cv>
	
	<jc># The log message format.
	# The value can contain any of the following variables:
	# 	{date} - The date, formatted per dateFormat.
	#	{class} - The class name.
	#	{method} - The method name.
	#	{logger} - The logger name.
	#	{level} - The log level name.
	#	{msg} - The log message.
	#	{threadid} - The thread ID.
	#	{exception} - The localized exception message.</jc>
	<ck>format</ck> = <cv>[{date} {level}] {msg}%n</cv>
	
	<jc># The maximum log file size.
	# Suffixes available for numbers.
	# See Config.getInt(String,int) for details.</jc>
	<ck>limit</ck> = <cv>1M</cv>
	
	<jc># Max number of log files.</jc>
	<ck>count</ck> = <cv>5</cv>
	
	<jc># Default log levels.
	# Format is lax-JSON.
	# Keys are logger names.
	# Values are serialized Level POJOs (SEVERE, WARNING, INFO, CONFIG, FINE, FINER, FINEST)</jc>
	<ck>levels</ck> = 
		<cv>{ 
			'': 'WARNING', 
			org.apache.juneau: 'WARNING', 
			org.eclipse.jetty: 'WARNING' 
		}</cv>
	
	<jc># Only print unique stack traces once and then refer to them by a simple 8 character hash identifier.
	# Useful for preventing log files from filling up with duplicate stack traces.</jc>
	<ck>useStackTraceHashes</ck> = <cv>true</cv>
	
	<jc># The default level for the console logger.
	# Values are serialized Level POJOs (SEVERE, WARNING, INFO, CONFIG, FINE, FINER, FINEST)</jc>
	<ck>consoleLevel</ck> = <cv>WARNING</cv>
	
	<jc># The default level for the file logger.
	# Values are serialized Level POJOs (SEVERE, WARNING, INFO, CONFIG, FINE, FINER, FINEST)</jc>
	<ck>fileLevel</ck> = <cv>INFO</cv>
</p>
<p>
	The logging configuration can also be defined programmatically through the following API:
</p>
<ul class='javatree'>
	<li class='jc'>{@link oaj.microservice.LogConfig}
	<ul>
		<li class='jm'>{@link oaj.microservice.LogConfig#create() create()} 
		<li class='jm'>{@link oaj.microservice.LogConfig#append() append()} 
		<li class='jm'>{@link oaj.microservice.LogConfig#consoleLevel(Level) consoleLevel(Level)} 
		<li class='jm'>{@link oaj.microservice.LogConfig#count(int) count(int)} 
		<li class='jm'>{@link oaj.microservice.LogConfig#fileLevel(Level) fileLevel(Level)} 
		<li class='jm'>{@link oaj.microservice.LogConfig#formatter(Formatter) formatter(Formatter)} 
		<li class='jm'>{@link oaj.microservice.LogConfig#level(String,Level) level(String,Level)} 
		<li class='jm'>{@link oaj.microservice.LogConfig#levels(Map) levels(Map)} 
		<li class='jm'>{@link oaj.microservice.LogConfig#limit(int) limit(int)} 
		<li class='jm'>{@link oaj.microservice.LogConfig#logDir(String) logDir(String)} 
		<li class='jm'>{@link oaj.microservice.LogConfig#logFile(String) logFile(String)} 
	</ul>
</ul>
<h5 class='figure'>Example:</h5>
<p class='bpcode w800'>
	<jk>public static void</jk> main(String[] args) {
		
		LogConfig logConfig = LogConfig
			.<jsm>create</jsm>()
			.append(<jk>true</jk>)
			.consoleLevel(<jsf>FINE</jsf>)
			.level(<js>"org.mylogger"</js>, <jsf>FINER</jsf>)
			.logDir(<js>"my-log-files"</js>);
		
		Microservice
			.<jsm>create</jsm>() 
			.args(args)
			.logConfig(logConfig)
			.build()
			.start()
			.join()
		;
	}
</p>
<p>
	If you wish to bypass the default logging configuration entirely, you can pass in your own logger via
	the {@link oaj.microservice.MicroserviceBuilder#logger(Logger)} method. 
</p>
<p>
	In addition to configuring the built-in Java logging framework, the following convenience methods are also
	provided on the {@link oaj.microservice.Microservice} class for logging.
</p>

<ul class='javatree'>
	<li class='jc'>{@link oaj.microservice.Microservice}
	<ul>
		<li class='jm'>{@link oaj.microservice.Microservice#getLogger() getLogger()} 
		<li class='jm'>{@link oaj.microservice.Microservice#out(MessageBundle,String,Object...) out(MessageBundle,String,Object...)} 
		<li class='jm'>{@link oaj.microservice.Microservice#err(MessageBundle,String,Object...) err(MessageBundle,String,Object...)} 
	</ul>
</ul>