| log_expr ::= LOG (string | ident) arguments attributes LEVEL level |
hunk ./doc/bolt.html 144
-| attribute ::= NAME string | PROPERTIES expr | EXCEPTION expr |
+| attribute ::= NAME string | (PROPERTIES | WITH) expr | (EXCEPTION | EXN) expr |
hunk ./doc/bolt.html 148
-The string following the LOG keyword is the message of the log event. This string can be followed by expressions; in this case the string is interpreted as a printf format string, using the following expressions as values for the % placeholders of the format string.
+The string following the LOG keyword is the message of the log event, it can be either a literal string or an identifier whose type is string. This string can be followed by expressions; in this case the string is interpreted as a printf format string, using the following expressions as values for the % placeholders of the format string.
hunk ./doc/bolt.html 259
-paje whose format is the Pajé trace format6;
+paje, and paje_noheader whose format is the Pajé trace format6 (the two format only differ in that the latter one does not output definitions, which is useful when one wants to merge several files);
+daikon_decls, and daikon_trace that respectively follow Daikon7 declaration (i.e. program points, and associated variable types) and trace format (i.e. actual variable values for the various program points visits);
hunk ./doc/bolt.html 262
-xml whose format is xml(compatible with log4j).
-XXX Paje
Two other layouts are predefined:
+
xml, or log4j whose format is xml (compatible with log4j).
+
+Pajé layouts
+The Pajé layout support the file format as defined at https://gforge.inria.fr/projects/paje/; however, Bolt does not support the extensibility feature of the Pajé format. This means that only the kinds of events predefined by the standard are available. Nevertheless, it is still possible to add new fields to predefined events.
+Code sample 6 shows how the functions from the Paje module could be used to record the fact that a container cnt change its state when receiving and handling a mail. The full list of supported event can be found in the ocamldoc of the Paje module.
+| Code sample 6: Pajé example. |
+
+
+LOG Paje.t
+ PROPERTIES Paje.new_event ~typ:"mail" ~container:"cnt" ~value:msg []
+ LEVEL TRACE;
+LOG Paje.t
+ PROPERTIES Paje.set_state ~typ:"state" ~container:"cnt" ~value:"computing" []
+ LEVEL TRACE;
+(...)
+LOG Paje.t
+ PROPERTIES Paje.set_state ~typ:"state" ~container:"cnt" ~value:"waiting" []
+ LEVEL TRACE;
+
+Daikon layouts
+When using the Daikon tool, one is usually interested in having both the declaration and the traces for the program to analyze. As a result, the configuration file is similar to the one depicted in 7. The program to be analyzed should itself contain log statement to record information to be fed to the Daikon analyzer. Program 8 shows a simple program producing Daikon data.
+
+The result of Daikon analysis with the aforementioned log configuration and program will be the following:
+
===========================================================================
+f:::ENTER
+===========================================================================
+f:::EXIT1
+"x" == orig("x")
+"res" one of { 0, 1 }
+"res" <= "x"
+Each Daikon-related element should use Daikon.t as the log message, and one of the property-building functions from the Daikon module to build a list of element. As of version 1.2, these functions are:
+
-
+enter that is used to mark the start of a function, giving its name and parameters;
+
- exit that is used to mark the end of a function, giving its name, return value and parameters;
+
- point that can be used to mark any point in a program, associating it with a list of values.
+
Values, independently of their kind (parameters, return values, bare variables) are encoded using a variable-build function from the Daikon module. All these functions take as first parameter the name of the value, and as second parameter the value itself. As of version 1.2, they are:
+
-
+t for type t;
+
- t_list for type t list;
+
- t_array for type t array;
+
+where t is one of bool, int, float, or string.
+| Code sample 7: Daikon configuration. |
+
+
+[]
+level=trace
+filter=all
+layout=daikon_decls
+output=file
+name=daikon.decls
+
+[]
+level=trace
+filter=all
+layout=daikon_dtrace
+output=file
+name=daikon.dtrace
+
+| Code sample 8: Daikon-instrumented program. |
+
+
+ let f x =
+ LOG Daikon.t
+ WITH Daikon.enter "f" [Daikon.int "x" x] LEVEL TRACE;
+ let res = (x * x) mod 2 in
+ LOG Daikon.t
+ WITH Daikon.exit "f" (Daikon.int "res" res) [Daikon.int "x" x] LEVEL TRACE;
+ res
+
+let () =
+ let l = [1; 2; 3; 4; 5; 6; 7; 8; 9; 10] in
+ let l = List.map f l in
+ List.iter (Printf.printf "%d\n") l
+
+Pattern and comma-separated layouts
+Two other layouts are predefined:
hunk ./doc/bolt.html 374
-There are three predefined outputs, namely void, growlnotify7, and file. The void output discards all data. The file output writes data to a bare file, the name property (or the string value when using Bolt.Logger.register) defines the path of the file to be used, and the rotate property (or the float option value when using Bolt.Logger.register) gives the rates in seconds at which files will be rotated.
+There are three predefined outputs, namely void, growlnotify8, and file. The void output discards all data. The file output writes data to a bare file, the name property (or the string value when using Bolt.Logger.register) defines the path of the file to be used9, and the rotate property (or the float option value when using Bolt.Logger.register) gives the rates in seconds at which files will be rotated. It is also possible to use the signal property (set to one one the following values: SIGHUP, SIGUSR1, SIGUSR2) in order to request rotation upon signal reception.
hunk ./doc/bolt.html 376
-When using rotation or several program instances in parallel, it is necessary for the name to contain a piece of information ensuring that the file name will be unique; otherwise, the same file will be written over and over again. In version 1.0, Bolt supported the % special character that was substituted by a timestamp.
+When using rotation or several program instances in parallel, it is convenient for the name to contain a piece of information ensuring that the file name will be unique; otherwise, the same file will be written over and over again. In version 1.0, Bolt supported the % special character that was substituted by a timestamp.
hunk ./doc/bolt.html 385
-Once the log information has been produced by the application, the developper and/or the user will have to review it. Although this can easily be done using classical Unix commands (such as grep, cut, sed; etc), a dedicated tool such as a GUI can be helpful. For this reason, the XML layout of Bolt produces log4j-compatible XML files allowing the use of the Apache Chainsaw application8.
-Code sample 6 shows a XML file that could be used to wrap the XML data produced by Bolt (in bolt.xml file) in such a way that Chainsaw can load it. This code sample is a reproduction of the one provided in the Javadoc of the log4j org.apache.log4j.xml.XMLLayout class9.
+Once the log information has been produced by the application, the developper and/or the user will have to review it. Although this can easily be done using classical Unix commands (such as grep, cut, sed; etc), a dedicated tool such as a GUI can be helpful. For this reason, the XML layout of Bolt produces log4j-compatible XML files allowing the use of the Apache Chainsaw application10.
+Code sample 9 shows a XML file that could be used to wrap the XML data produced by Bolt (in bolt.xml file) in such a way that Chainsaw can load it. This code sample is a reproduction of the one provided in the Javadoc of the log4j org.apache.log4j.xml.XMLLayout class11.
hunk ./doc/bolt.html 388
-
| Code sample 6: Wrapping produced XML data into a Chainsaw-compatible XML. |
+| Code sample 9: Wrapping produced XML data into a Chainsaw-compatible XML. |
hunk ./doc/bolt.html 400
-Code sample 7 shows a short program using the implicit logging feature of Bolt. The program can be compiled and executed by the Makefile shown by code sample 8.
+Code sample 10 shows a short program using the implicit logging feature of Bolt. The program can be compiled and executed by the Makefile shown by code sample 11.
hunk ./doc/bolt.html 405
-| Code sample 7: Source example. |
+| Code sample 10: Source example. |
hunk ./doc/bolt.html 421
-| Code sample 8: Makefile example. |
+| Code sample 11: Makefile example. |
hunk ./doc/bolt.html 442
-The target run of the Makefile shows that the environment variable BOLT_FILE should be set to the path of the configuration file defining the actual runtime-configuration of logging. The related configuration file is represented by code sample 9. As a result of execution, a plain text file named log will be produced, and can be viewed using the view target of the Makefile.
-| Code sample 9: Configuration example. |
+The target run of the Makefile shows that the environment variable BOLT_FILE should be set to the path of the configuration file defining the actual runtime-configuration of logging. The related configuration file is represented by code sample 12. As a result of execution, a plain text file named log will be produced, and can be viewed using the view target of the Makefile.
+| Code sample 12: Configuration example. |
hunk ./doc/bolt.html 460
-Code sample 10 shows how to register a new filter that keeps only event with an even line number, and a new layout programmed using the Printf.sprintf machinery.
+Code sample 13 shows how to register a new filter that keeps only event with an even line number, and a new layout programmed using the Printf.sprintf machinery.
hunk ./doc/bolt.html 462
-| Code sample 10: Customizing Bolt with new filter and layout. |
+| Code sample 13: Customizing Bolt with new filter and layout. |
hunk ./doc/bolt.html 491
-