libraries/logging/src/docs/logging.txt - polygene-java - Git at Google

 //////////////////////
  * Copyright (c) 2007-2012, Niclas Hedhman. All Rights Reserved.
  *
  * Licensed 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.
 //////////////////////

 [[library-logging, Logging Library]]
 = Logging =

 [devstatus]
 --------------
 source=libraries/logging/dev-status.xml
 --------------

 First of all, Zest™ is taking a fresh look at all things that we take for granted. Logging is one such thing.

 It should (but is not) obvious that Logging are used for three very distinct purposes, and in our opinion the concepts
 are not related and should not be abstracted in the same fashion, as has been the norm in Log4j, JDK logging, Commons
 Logging and most other similar packages and APIs.

 * *Tracing* - Developers often need to trace where the application has been, recording the sequence of execution to see if
 the logic is correct. This is often a choice when stepping through with a debugger is not possible for whatever reason.

 * *Debugging* - Developers like to get additional information out from a running system. This could be information about
 conditions, events or unexpected results that we want to record and analyse later.

 * *Logging* - The requirements of an application sometimes specifies that events or conditions should be recorded for
 auditing purposes. These are often described as domain events and written to a special log file and/or printed to
 log printer.

 Although similar in nature, the audience are very different in Logging vs Debugging/Tracing and their requirements are
 not only different, but if not handled properly the debug log is mixed up with the audit logs, which in turn can lead
 to turning off whole or parts of the domain logging by mistake. We want to avoid this, and instead crystalize the needs
 for each scenario and audience.

 Another drastic difference from previous frameworks is that we don't have an Appender notion. All messages are entities
 which are stored in a configured entity store. This means that especially the domain log can be more easily be given a
 user interface suitable for the domain, without complex parsing of message strings

 include::../../build/docs/buildinfo/artifact.txt[]

 == Logging ==

 Logging is still not finalized and will need a lot more thought before considered done.

 == Debugging ==

 To produce debugging output in your code you just need to add the field

 [snippet,java]
 -----------
 source=libraries/logging/src/test/java/org/qi4j/logging/docsupport/LoggingDocs.java
 tag=logging1
 -----------

 and then check for null at each usage

 [snippet,java]
 -----------
 source=libraries/logging/src/test/java/org/qi4j/logging/docsupport/LoggingDocs.java
 tag=logging2
 -----------

 The Debug mixin can be either added to the composite declaration, or it can be added as a contextual fragment during
 bootstrap.

 You will also need to declare a DebugService to be visible to the composite where the debug output is coming from. And
 the DebugService in turn will use the default UnitOfWork and associated entity store, which must also be configured and
 visible.

 == Tracing ==

 Tracing is the process of tracking all the methods that has been called. There are two levels of tracing available in
 Zest. Either Trace All or trace where a annotation has been given.

 If the TraceAllConcern is added to a composite, and there is a TraceService visible, then all method calls into that
 composite is traced.

 If a subset of the methods want to be traced, you can annotate those methods with @Trace in either the Composite Type
 interface or the mixin implementation. You will also need to add the TraceConcern to the composite.

 [snippet,java]
 -----------
 source=libraries/logging/src/test/java/org/qi4j/logging/docsupport/LoggingDocs.java
 tag=logging3
 -----------

 In the above sample code, the findImportantStuff() method is not traced, whereas the other two will be traced if there
 is a TraceConcern declared on the composite, and a TraceService visible from that composite.

 The fact that each TraceConcern (and TraceAllConcern) will use the TraceService that is visible, allows you to enable
 or disable tracing per module, simply by adding or removing a TraceService with Visibility.module in each module you
 want it, or expose Visibility.layer and turn on/off tracing by layers. The TraceConcern has the TraceService as
 optional.

 The recommended way to enable tracing is to use contexual fragments, a feature that allows you to add concerns,
 sideeffects and mixins to composites during the bootstrap phase instead of hard-coded into the composite declaration.

 [snippet,java]
 -----------
 source=libraries/logging/src/test/java/org/qi4j/logging/docsupport/LoggingDocs.java
 tag=logging4
 -----------
	//////////////////////
	* Copyright (c) 2007-2012, Niclas Hedhman. All Rights Reserved.
	*
	* Licensed 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.
	//////////////////////

	[[library-logging, Logging Library]]
	= Logging =

	[devstatus]
	--------------
	source=libraries/logging/dev-status.xml
	--------------

	First of all, Zest™ is taking a fresh look at all things that we take for granted. Logging is one such thing.

	It should (but is not) obvious that Logging are used for three very distinct purposes, and in our opinion the concepts
	are not related and should not be abstracted in the same fashion, as has been the norm in Log4j, JDK logging, Commons
	Logging and most other similar packages and APIs.

	* Tracing - Developers often need to trace where the application has been, recording the sequence of execution to see if
	the logic is correct. This is often a choice when stepping through with a debugger is not possible for whatever reason.

	* Debugging - Developers like to get additional information out from a running system. This could be information about
	conditions, events or unexpected results that we want to record and analyse later.

	* Logging - The requirements of an application sometimes specifies that events or conditions should be recorded for
	auditing purposes. These are often described as domain events and written to a special log file and/or printed to
	log printer.

	Although similar in nature, the audience are very different in Logging vs Debugging/Tracing and their requirements are
	not only different, but if not handled properly the debug log is mixed up with the audit logs, which in turn can lead
	to turning off whole or parts of the domain logging by mistake. We want to avoid this, and instead crystalize the needs
	for each scenario and audience.

	Another drastic difference from previous frameworks is that we don't have an Appender notion. All messages are entities
	which are stored in a configured entity store. This means that especially the domain log can be more easily be given a
	user interface suitable for the domain, without complex parsing of message strings

	include::../../build/docs/buildinfo/artifact.txt[]

	== Logging ==

	Logging is still not finalized and will need a lot more thought before considered done.

	== Debugging ==

	To produce debugging output in your code you just need to add the field

	[snippet,java]
	-----------
	source=libraries/logging/src/test/java/org/qi4j/logging/docsupport/LoggingDocs.java
	tag=logging1
	-----------

	and then check for null at each usage

	[snippet,java]
	-----------
	source=libraries/logging/src/test/java/org/qi4j/logging/docsupport/LoggingDocs.java
	tag=logging2
	-----------

	The Debug mixin can be either added to the composite declaration, or it can be added as a contextual fragment during
	bootstrap.

	You will also need to declare a DebugService to be visible to the composite where the debug output is coming from. And
	the DebugService in turn will use the default UnitOfWork and associated entity store, which must also be configured and
	visible.

	== Tracing ==

	Tracing is the process of tracking all the methods that has been called. There are two levels of tracing available in
	Zest. Either Trace All or trace where a annotation has been given.

	If the TraceAllConcern is added to a composite, and there is a TraceService visible, then all method calls into that
	composite is traced.

	If a subset of the methods want to be traced, you can annotate those methods with @Trace in either the Composite Type
	interface or the mixin implementation. You will also need to add the TraceConcern to the composite.

	[snippet,java]
	-----------
	source=libraries/logging/src/test/java/org/qi4j/logging/docsupport/LoggingDocs.java
	tag=logging3
	-----------

	In the above sample code, the findImportantStuff() method is not traced, whereas the other two will be traced if there
	is a TraceConcern declared on the composite, and a TraceService visible from that composite.

	The fact that each TraceConcern (and TraceAllConcern) will use the TraceService that is visible, allows you to enable
	or disable tracing per module, simply by adding or removing a TraceService with Visibility.module in each module you
	want it, or expose Visibility.layer and turn on/off tracing by layers. The TraceConcern has the TraceService as
	optional.

	The recommended way to enable tracing is to use contexual fragments, a feature that allows you to add concerns,
	sideeffects and mixins to composites during the bootstrap phase instead of hard-coded into the composite declaration.

	[snippet,java]
	-----------
	source=libraries/logging/src/test/java/org/qi4j/logging/docsupport/LoggingDocs.java
	tag=logging4
	-----------