Editing
Loggifier.unkrig.de
(section)
Jump to navigation
Jump to search
Warning:
You are not logged in. Your IP address will be publicly visible if you make any edits. If you
log in
or
create an account
, your edits will be attributed to your username, along with other benefits.
Anti-spam check. Do
not
fill this in!
== Loggification == The LOGGIFIER loads a class file and analyzes the bytecode of the class's constructors and methods. Looking at the code, it identifies "interesting" points where logging code could be inserted. Each of the logging points is characterized by an [[#Logging actions|action]]. For each logging point, the relevant [[#Loggification rules|loggification rules]] are executed, and the first that matches determines at what level the logging event is to be logged (or if no logging code is injected for this logging point). Loggification rules optionally have a [[#Discriminator expression|discriminator expression]], which has a set of [[#Discriminator expression parameters|parameters]]. === Logging actions === Each section of code is characterized by an 'Action'. For example, the JVM bytecodes <code>PUTFIELD</code> and <code>PUTSTATIC</code> are characterized by action '''PUT'''. {| class="wikitable" |- |'''ALOAD''' ||Log array type, array value, index and element value read from an array |- |'''ARITH''' ||Log operands, operator (+, -, ...) and result of an arithmetic operation |- |'''ASTORE''' ||Log the array, the index and the value being stored in an array |- |'''CAST''' ||Log the type to which the operand is casted |- |'''CATCH''' ||Log the declared catch type and the actually caught exception |- |'''CLINIT''' ||Log the name of a class that is initialized |- |'''CONST''' ||Log the value of a constant being pushed on the operand stack |- |'''CONVERT''' ||Log a value that is arithmetically converted and the conversion result |- |'''ENTRY''' ||Log the target object (if non-static) and the arguments as a method begins execution |- |'''GET''' ||Log declaring class of, name of, source instance of (if non-static) and value read from a field |- |'''INVOKE''' ||Log signature, target object (if non-static) and arguments right before a method is invoked |- |'''INSTANCEOF'''||Log the type to which the operand type is compared |- |'''LENGTH''' ||Log the array who's length is determined |- |'''LOAD''' ||Log type of, name of and value read from a local variable |- |'''NEW''' ||Log the type of a new object being instantiated |- |'''PUT''' ||Log declaring class of, name of, target instance of (if non-static) and value assigned to field |- |'''RESULT''' ||Log method signature and invocation result (if not 'void') |- |'''RETURN''' ||Log the value that is being returned by a method (if not 'void') |- |'''STORE''' ||Log value assigned to, type of and name of a local variable |- |'''SWITCH''' ||Log the integer value that a switch is being executed on |- |'''THROW''' ||Log an exception right before it is thrown |} === Loggification rule syntax === A rule triggers if and only if * It applies to the action of the loggification point (ENTRY, EXIT, THROW, ...) * Its discriminator expression (if any) evaluates to TRUE for the actual point (who's properties are availables as variables in the discriminator expression, see above) The syntax of all loggification rules is: loggification-rule := ( action { ',' action } | 'ALL' ) '=' level [ ':' discriminator-expression ] action := (One of the actions documented above) level := 'SEVERE' | 'WARNING' | 'INFO' | 'CONFIG' | 'FINE' | 'FINER' | 'FINEST' discriminator-expression := (Syntax defined below) Examples of valid loggification rules are: ALL=FINE ENTRY=FINE ARITH=FINE LOAD,CONVERT,ARITH,STORE=FINE ALL=FINE:class =* "de.*" (<code>=*</code> is the 'glob matching operator', e.g. "hello" matches "he*".) === Loggification rule precedence === The sequence of checked rules for each logging point is as follows: ;If the constructor or method being instrumented has a '@Loggify' annotation (not for action CLINIT) :Its values in reverse order (i.e. the last value/rule takes the highest precedence). ;If a field 'static final String $$loggifierRules = "xyz"' was declared before the contructor or method being instrumented :Its value, split at '\n', in reverse order (i.e. the last fragment/rule takes the highest precedence). ;If the class or interface being instrumented has a '@Loggify' annotation :Its values of in reverse order (i.e. the last value/rule takes the highest precedence). ;If using the four-parameter [[Loggifier.unkrig.de / Tools / LoggifyingClassLoader|LoggifyingClassLoader]] constructor :The 'logLevelCalculator' argument. ;If using the [[Loggifier.unkrig.de / Tools / Ant task|ANT task]] :<code><rule></code> subelements, in reverse order (i.e. the last <code><rule></code> takes the highest precedence). ;If using the [[Loggifier.unkrig.de / Tools / Command line tool|LOGGIFIER command line tool]] :The '-rule' options, in reverse order (i.e. the last '-rule' option takes the highest precedence). ;If using the [[Loggifier.unkrig.de / Tools / Eclipse plug-in|ECLIPSE plug-in]] :The levels on the "Loggifier" property page of each project. (This rule ALWAYS applies, hence the following rules are never executed). ;If using the [[Loggifier.unkrig.de / Tools / Java agent|Java agent]] :Its argument string passed to the agent, split at '\n', in reverse order (i.e. the last fragment/rule takes the highest precedence). ;If the action is LOAD or STORE, and the local variable's name ends with '__' :FINER ;If the action is GET or PUT, and the field's name ends with '__' :FINER ;If the action is NEW, CAST or INSTANCEOF, and the target class's name ends with '__' :FINER ;If the action is ENTRY, RETURN or THROW :FINER ;Last resort (when none of the above rules triggered) :OFF Notice that non-static fields (a.k.a. 'instance variables') are initialized by the class's constructors. Static fields ('class variables') are initialized by the synthetic <code><clinit>()</code> method, which cannot be annotated in source code. === Discriminator expression === Discriminator expressions are implemented by means of <code>de.unkrig.commons.text.expression.ExpressionEvaluator</code>; find the expression syntax documented [http://commons.unkrig.de/javadoc/de/unkrig/commons/text/expression/Parser.html here]. === Discriminator expression parameters === To provide fine-grained control over loggification, the properties of each loggification point are provided as parameters to the discriminator expression: ;action :One of the [[#Logging actions|documented logging actions]] ;source :The name of the Java source file that JAVAC stores in each <code>.class</code> file if enabled by <code>-g:source</code>. ;classAccess :The accessibility of the class being instrumented (<code>public</code>, <code>protected</code> or <code>private</code>) ;class :The fully qualified name of the class being instrumented, e.g. <code>pkg.MyClass</code> ;methodAccess :The accessibility of the method being instrumented (<code>public</code>, <code>protected</code> or <code>private</code>) ;method :The enhanced, dequalified name of the method being instrumented, e.g. <code>meth(String, MyClass)</code> or <code><T extends IOException>meth(T, MyClass, List<T>)</code> ;line :The line number related to the code point being instrumented that JAVAC stores in each .class file if enabled by <code>-g:lines</code> ;type :The relevant type for the operation, e.g. <code>pkg.Class</code>, <code>pkg.Class[][]</code>, <code>int[][]</code> (only for actions '''CAST''', '''INSTANCEOF''' and '''NEW''') ;classAndField :The subject class and field, e.g. <code>pkg.Class.field</code> (only for actions '''GET''' and '''PUT''') ;variable :The name of the subject local variable (only for actions '''LOAD''' and '''STORE''') At each loggification point, the LOGGIFIER determines if logging code is to be inserted or not ('discrimination') and on which level the event will be logged at runtime ('level'). This is achieved by checking the 'loggification rules'.
Summary:
Please note that all contributions to unkrig.de may be edited, altered, or removed by other contributors. If you do not want your writing to be edited mercilessly, then do not submit it here.
You are also promising us that you wrote this yourself, or copied it from a public domain or similar free resource (see
Unkrig.de:Copyrights
for details).
Do not submit copyrighted work without permission!
Cancel
Editing help
(opens in new window)
Navigation menu
Personal tools
Not logged in
Talk
Contributions
Create account
Log in
Namespaces
Page
Discussion
English
Views
Read
Edit
View history
More
Search
Navigation
Main page
Recent changes
Random page
Help
Tools
What links here
Related changes
Special pages
Page information