log
Product: xTier™/LWC 2.3 Whitepaper: n/a	support@fitechlabs.com  Download  Buy
Depends: n/a  Related: n/a
xTier™ Navigator: cache cluster config email i18n ioc info jmx jndi security log marshal objpool os fs tx uidgen workflow jobs db startup jms grid

Description
The 'log' service provides similar functionality to Log4J or Java logging infrastructure. However it adds several important enchacments and provides tight intergration with xTier™ system. Main features of the xTier™ 'log' service include:

• Categorized output.
• Several ways to limit the log output: logging masks, associated with each sink and logger, log filters, XML defined categories.
• Ability to provide time, logging level, name of thread for each log record.
• Pre-built log sinks for standard (console) output, JMS, file output and microkernel logging.
• Pre-built log formatters for stadard (console) output, xml-formatted output, and customly configurable formatter.
• Pre-built default log error handler.
• Pre-built adapter for log sink.
• Integration sinks for Log4j and Java logging facility.
• Unified XML-based configuration.

 Top

Configuration
The 'log' service is configured via pre-defined xtier_log.xml configuration file. This file follows standard xTier™ service configuration pattern that can be demonstrated by the following complete example of 'log' configuration:

1		<xtier-log>
2		<!-- Example log configuration. -->
3		<region name="examples">
4		<!-- Log formatter declaration. -->
5		<ioc policy="new" uid="xml.fmt">
6		<java class="com.fitechlabs.xtier.services.log.
7		formatters.LogXmlFormatter"/>
8		<clr class="Foo.Bar.Formatter" assembly="asm"/>
9		</ioc>
10
11		<!-- Log formatter declaration. -->
12		<ioc policy="new" uid="con.fmt">
13		<java class="com.fitechlabs.xtier.services.log.
14		formatters.LogConsoleFormatter"/>
15		<clr class="Foo.Bar.Formatter" assembly="asm"/>
16		</ioc>
17
18		<!-- Custom log formatter declaration. -->
19		<ioc policy="new" uid="cstm.fmt">
20		<clr class="Foo.Bar.Formatter" assembly="asm"/>
21
22		<java class="com.fitechlabs.xtier.services.log.
23		formatters.LogCustomFormatter">
24		<ctor>
25		<!-- Following substitution variables can be used:
26		**************************************************
27		%s - sequence number.
28		%h - thread name.
29		%d - date and time.
30		%x - thrown exception, if any.
31		%z - thrown exception's stack trace.
32		%c - log category.
33		%l - log level.
34		%e - time elpased since the last log.
35		%m - log message.
36		%n - new line ('\n')
37		%t - tabulation ('\t')
38		%% - '%' character.
39		-->
40		<!-- Optional header. -->
41		<arg type="string">
42		Header: generated by xTier.
43		</arg>
44
45		<!-- Optional footer. -->
46		<arg type="string">
47		Footer: generated by xTier.
48		</arg>
49
50		<!-- Template. -->
51		<arg type="string">
52		<![CDATA[%d <%s><%c:%h> <%l> %m%n%z]]>
53		</arg>
54		</ctor>
55		</java>
56		</ioc>
57
58		<!-- Log error handler declaration. -->
59		<ioc policy="new" uid="dflt.handler">
60		<java class="com.fitechlabs.xtier.services.log.
61		handlers.LogDefaultErrorHandler "/>
62		<clr class="Foo.Bar.ConsoleHandler" assembly="asm"/>
63		</ioc>
64
65		<!-- Sink declaration. -->
66		<sink>
67		<ioc policy="new">
68		<clr class="Foo.Bar.Sink" assembly="asm"/>
69
70		<java class="com.fitechlabs.xtier.services.
71		log.sinks.file.LogFileSink">
72		<!-- Constructor arguments. -->
73		<ctor>
74		<!-- Sink name. -->
75		<arg type="string">custom.file.sink</arg>
76
77		<!-- Sink's formatter. -->
78		<arg ref-uid="cstm.fmt"/>
79
80		<!-- Sink's filter (optional). -->
81		<arg null="true"/>
82
83		<!-- Sink's error handler. -->
84		<arg ref-uid="dflt.handler"/>
85
86		<!-- File sink destination folder. -->
87		<arg type="string">log/custom</arg>
88
89		<!-- File sink filename. -->
90		<arg type="string">test-log.txt</arg>
91
92		<!-- Maximum file size in bytes. -->
93		<arg type="int32">50000</arg>
94
95		<!--
96		File sink mode: "clean" and "append"
97		are the two valid values.
98		-->
99		<arg type="string">append</arg>
100		</ctor>
101		</java>
102		</ioc>
103
104		<level-mask>
105		<level value="error"/>
106		<level value="warning"/>
107		</level-mask>
108		</sink>
109
110		<!--
111		Enforcing log level on specific category.
112		Note that if level is not set,
113		zero-mask is assumed (no logging).
114		Note also, that regexp must be Java compatible.
115		Note that categories are separated by '/'.
116		Note also that the order in which regexps
117		are applied is undefined.
118		-->
119		<category>
120		<!--
121		Disable any log from loggers that have
122		"DO_NOT_SHOW" in their categories.
123		-->
124		<regexp><![CDATA[.*DO_NOT_SHOW.*]]></regexp>
125		</category>
126		<category>
127		<regexp><![CDATA[.*ONLY_TRACE.*]]></regexp>
128		<level-mask>
129		<level value="trace"/>
130		</level-mask>
131		</category>
132		</region>
133		</xtier-log>

Logging configuration region is composed of sink definitions. <sink> XML tag consists of mangatory <ioc> tag that defines LogSink implementation and optional <level-mask> and <level-from> tags. See IocService for <ioc> tag usage details.

Level mask defines which log levels are active in the sink. There are 6 log levels in xTier™:

• debug
• trace
• info
• log
• warning
• error

value

Log level. Can be one of the following values: debug - debug log level. trace - trace log level. info - info log level. log - log log level. warning - warning log level. error - error log level.

<level-from> tag indicates that mentioned level and all higher levels are enabled in the sink. Log levels are regulated in increasing order from debug to error. For example if level-from is info, this means that info, log, warning, error are enabled and debug and trace are disabled in the sink. <level-from> XML tag has the following required attributes:

value

Log level. Can be one of log levels. This level and all higher levels are enabled.

 Top

Categories are defined by <category> tag. <category> XML tag includes one mandatory <regex> tag and zero or more <level-mask> tags, which specify level masks associated with given category. <regex> tag specify regular expression. All loggers whose categories names match this regular expression get associated with this XML-defined category and therefore will be set with specified level mask. Infomation about regular expression can be found at: http://www.regxlib.com

Following example illustrates how logging categories may be configured in 'log' service configuration:

1		<xtier-log>
2		<region name="test">
3		<!--
4		...
5		-->
6
7		<!--
8		Enforcing log level on specific category.
9		Note that if level is not set,
10		zero-mask is assumed (no logging).
11		Note also, that regexp must be Java
12		compatible.
13		Note that categories are separated by '/'.
14		Note also that the order in which regexps are
15		applied is undefined.
16		-->
17		<category>
18		<!--
19		Disable any log from loggers that have
20		"DO_NOT_SHOW" in their categories.
21		-->
22		<regexp><![CDATA[.*DO_NOT_SHOW.*]]></regexp>
23		</category>
24		<category>
25		<regexp><![CDATA[.*ONLY_TRACE.*]]></regexp>
26		<level-mask>
27		<level value="trace"/>
28		</level-mask>
29		</category>
30		</region>
31		</xtier-log>

 Top

1		<xtier-log>
2		<region name="my.region">
3		<!-- Log formatter declaration. -->
4		<ioc policy="new" uid="con.fmt">
5		<java class="com.fitechlabs.xtier.services.log.
6		formatters.LogConsoleFormatter"/>
7		</ioc>
8
9		<!-- Sink declaration. -->
10		<sink>
11		<ioc policy="new">
12		<java class="com.fitechlabs.xtier.services.log.
13		sinks.console.LogConsoleSink">
14		<!-- Constructor arguments. -->
15		<ctor>
16		<!-- Sink name. -->
17		<arg type="string">console.sink</arg>
18
19		<!-- Sink's formatter. -->
20		<arg ref-uid="con.fmt"/>
21		</ctor>
22		</java>
23		</ioc>
24
25		<level-from value="debug"/>
26		</sink>
27		</region>
28		</xtier-log>

 Top

Examples
Usage of 'log' service follows the standard pattern of using xTier™ service: you need to obtain an instance of xTier™ kernel that serves as a service registry. Once you have xTier™ kernel you can get an instance of any service, in our case the 'log' service. Once the service instance is obtained the service API can be used. Following example illustrates these basic steps:

1		// Get the instance of xTier kernel.
2		XtierKernel xtier = XtierKernel.getInstance();
3
4		// Get the instance of 'log' service.
5		LogService log = xtier.log();
6
7		// Get XML-defined logger of category "logger-example".
8		Logger logger = log.getLogger("logger-example");
9
10		Exception e = new Exception("Exception's example");
11
12		// Debug output.
13		logger.debug("Debug message.");
14		logger.debug("Debug message.", e);
15
16		// Error output.
17		logger.error("Error message.");
18		logger.error("Error message.", e);
19
20		// Info output.
21		logger.info("Info message.");
22		logger.info("Info message.", e);
23
24		// Log output.
25		logger.log("Log message.");
26		logger.log("Log message.", e);
27
28		// Trace output.
29		logger.trace("Trace message.");
30		logger.trace("Trace message.", e);
31
32		// Warning output.
33		logger.warning("Warning message.");
34		logger.warning("Warning message.", e);
35
36		// Raw output.
37		logger.rawLog(Logger.LOG, "Raw message.", e);

 Top