Manual - Ocamlviz
Contents
1. Bytes Collected Bytes Killed Bytes 2 Tree nodes Node List Bytes length s sl length s length I Child List Bytes Child index 13 This coding allows to keep the sharing Tree coding example D Nodes Value to code Meaning 8 Tree 5 nodes 0 1 length D D 0 0 child 1 1 length E E 0 0 child 2 1 length B B 2 2 children 0 node 0 1 node 1 3 1 length C C 0 0 child 4 1 length A A 2 2 children 2 node 2 3 node 3 e Hashtable Bytes 4 4 4 4 Hashtable entries elements empty buckets max bucket length e Log Bytes 1 Log 10 Float String List 14 4 3 6 Command Declare Bytes 1 2 1 Value 0 tag kind string Send Bytes 1 2 Value 1 tag value Bind Bytes 1 2 Value 1 tag 4 4 Architecture This is the architecture of OCAMLVIZ When a program is monitored a server is created sending the binary data on the network to its clients Each client will decode every binary data and store them into its own database Server Clients Binary Protocol Database Database 15 References 1 Jacqu2. some cells there is a second information which is the last time the data was modified The color of the text can be red value was killed or green value was garbage collected Cells can also contain check boxes These check boxes once checked allow to create graphs and lists in new pages or existing pages through the menu Visualize in or shortcuts A list can contain any data but a graph can only display data of the same type representing integers floating points percentages or bytes It is possible to pause the GUI and even to travel back in time through the record panel The database will store one minute of data by default but this can be changed in the menu preferences The maximum window is one hour Menu Visualizein Preferences Refresh Period Record Panel 00 Gn 100 al ms 0 sec 0 sec Stats lt gt Values lt gt Tags Hashtables lt lt Trees 5 Log 5 Gc 5 sharing amp El A 31 Expand L 75 Refresh v shared v node 5 v shared Menu Visualize in Preferences Refresh Period gt m Ems Record Panel 0 684 sec 0 00 a 0 684 sec Stats gt Name Elements Values Tags Empty Buckets Array Size Filling Rate h2 1501 O o h 2327 2302 O 1151 O O 2303 0O 0 Hash tables Ocan Name Elements Empty Buc
3. variant variant name string mutable variant_children variant list For instance let node x y Protocol variant_name x Protocol variant children y let treel node 1 node 1 1 node 1 2 1 let _ Tree observe tree1 fun gt treel 3 1 7 Log This function builds a log and expands it For each call it will store the string along with its time let _ log d This is how we use s in s 1 log ocamlviz log ff It is b that log works like ocaml printf functions 2 true 3 1 8 Kill In some modules there are functions called killed Calling this function will stop the monitoring of a data This can be usefull if the data won t change anymore and if its monitoring costs a lot of ressources 3 1 9 Wait_for_connected_clients amp wait for killed clients OCAMLVIZ provides two functions to blocks the program execution e wait for connected clients i this hangs up the program execution until clients are connected e wait_for_killed_clients this hangs up the program execution until every clients are disconnected 3 1 10 Automating Instrumentation using Camlp4 It is possible to instrument automatically a file using camlp4 For this purpose a pre processor called pa_ocamlviz is provided It is used as follows ocamlopt c pp camlp4 pa_o cmo str cma pa_ocamlviz cmo pr_o cmo source_file ml This will modify the following top level instructions e
4. OCAMLVIZ Julien Robert and Guillaume Von Tokarski September 17 2009 Contents 1 Introduction 2 Installation 22 gt ETE E aisr 8 a ea tee cha es aN Le AS aa es 2 2 Compiling from sources ok aS a 3 User Manual 3 1 Instrumenting User Code for Monitoring sl Module Point rds an irran a a eiar awn TS 3 1 2 Module Time ME A gk ene 3 153 Module Tagin Et Bs We keh e E a E a Sy 3 1 4 Module A eee ee i Ce cle ee ate 3 1 5 Module Hashtable cc E ate Bote Se Gh ES Ge ee 3 1 6 Module Tree ada de eds at oi en hs ok i Re et Se o rte Do Sek Saher ve Sede a her casita ss en er At len ofa AA AS see hy eo DS cee eaten he eat fe eee ewe a ee 3 1 9 Wait for connected clients amp wait_for_killed_clients 3 1 10 Automating Instrumentation using Camlp4 3 2 Dinking wath Ocamilyviz dse da e ted was eis es is he Se a 3 3 Visualizing Monitoring Results 2 ls DP Ae ee eee Ook GU A o AE aed a a ee oe eS Se SI eT coe es igs ace a ee gee a kre Be Bes 4 Developer Manual Al Source Mille as ih Se A a ot heel oe OE sheeted oh e Seren ih inthe ere ices DES AD ARTONOCO 25 N fa ob 2 Cosa 5M hme ah De Reh e A Odd ced 4 3 Binary Implementation of the Protocol Ads Actes da Mee IR ga AES E A A RR Oana Ao Name nia A id e A a e Nh athe 4 3AA A A A A ety Sead he ay 4 A A A A a A 4 3 0 Commands s ts atera at A ee e II NN Ww ONDDDWOTOTOOTBKHRWWWDY y 1 Introduction OCAML
5. References on integers floating points booleans strings e Hash tables e Functions time and calls monitoring If the data are visualized through the GUI for a file called file data names will be file_ name For example a function f from a file g ml will be displayed as g f 3 2 Linking with Ocamlviz To link the user code with Ocamlviz use ocamlc unix cma libocamlviz cma lt your files gt in bytecode and ocamlopt unix cmxa libocamlviz cmxa lt your files gt in native code Note that Ocamlviz init or Ocamlviz threads init must be called somewhere in the user code Once linked with Ocamlviz the user code acts like a server The default port used by this server is 51000 Another port can be specified using the OCAMLVIZ_PORT environment variable The server s default timer is 0 1 seconds you can specify another timer by changing the OCAMLVIZ_PERIOD environment variable We advise to keep a timer greater or equal than 0 1 seconds Calculing the size of living data in the heap can cost a lot of ressources and con siderably affect the program execution The computational complexity of this calculus is O n n being the number of blocks of the heap The default period of this calculus is 1 0 second You can specify another period by changing the OCAMLVIZ_HEAP_PERIOD environment variable We advise to keep a period greater or equal than 0 1 seconds NB this doesn t affect the heap s total si
6. VIZ is a free software funded by Jane Street Capital within the framework of Jane Street Summer Project It allows the monitoring of OBJECTIVE CAML programs and values in real time by using the OCAMLVIZ library OCAMLVIZ can also be used as a debugging tool 2 Installation 2 1 Prerequisites You need Objective Caml gt 3 10 0 to compile Ocamlviz To compile the GUI you also need Lablgtk2 gt 2 10 1 2 1 and Libcairo ocaml gt 20070908 1build1 2 If one of these libraries is missing the compilation will proceed but the GUI will not be compiled To display trees within the GUI you need Graphviz 3 to be installed But Graphviz is not required to compile Ocamlviz 2 2 Compiling from sources Within Ocamlviz sources configure with configure Compile with make As superuser install with make install 3 User Manual The documentation can be found at the following adress http ocamlviz lri fr doc Monitor_sig Monitor html or by compiling with the command make doc the index of the documentation will be the file index html inside the folder doc 3 1 Instrumenting User Code for Monitoring Two libraries are provided e Ocamlviz This is the main library It uses alarms to collect and send data If the monitored program also uses alarms open the Ocamlviz_threads library instead Ocamlviz may not work properly in native compilation if the monitored program doesn t trigger the GC If this happens compile the program in b
7. es Garrigue Lablgtk an OBJECTIVE CAML interface to Gtk http wwwfun kurims kyoto u ac jp soft 1s1 lablgtk html 2 Cairo a 2D graphics library with support for multiple output devices http cairographics org cairo ocaml 3 Graphviz an open source graph visualization software http www graphviz org 16
8. kets me Array Size Filling Rate Longest Bucket M h2 18845 O 0 O h 18456 18430 18431 18431 Menu Visualize in Preferences Refresh Period Record Pane 100 4 576 sec Stats Values 5 Tags Max Size 3 932 MB 3 932 MB Total Size Living B 2 737 100 E 0 O 2 O 1 18456 O 1 2 359 MB 1 179 MB 50 40 10 e Gc Period 10 ms i HEM Total size NEM max size v amp MN Living Bytes Y E 3 3 2 ASCII Client This client logs the monitored data into a file 9 The ASCII client is launched with ocamlviz ascii options Command line options are server to specify the server machine the default is the local host port to specify the server port the default value is 51000 o to specify the output file the default value is ascii log If no Ocamlviz server is running the ASCII client fails with the error message connection couldn t connect to the server machine port 4 Developer Manual Source Files ascii ml this is the ASCII client it writes monitored data into a file binary ml contains functions that code and decode several OBJECTIVE CAML types in a buffer bproto ml contains the functions that code and decode the OCAMLVIZ messages see protocol mli db ml the client database that stores the data and gives functi
9. onitored The period is in milliseconds For each tag OCAMLVIZ goes through its elements in the heap The bigger the elements the slower the program so correctly adjust the period 3 1 4 Module Value This module allows the monitoring of values with the following OBJECTIVE CAML types e integers e floating point numbers e booleans e strings For instance let let let let let let let let f b X x 0 1 Value observe_float_fct period 2000 f 2 fun O gt f 2 weak Value observe_string s s Value observe_string_fct weak true fct_s fun gt s Value observe_int_ref a ref 0 ref true Value observe_float_ref b b The argument weak means that the value can be attached to a weak pointer and garbage collected 3 1 5 Module Hashtable This module is meant to monitor OBJECTIVE CAML hash tables It monitors the e hash table length number of elements inside the table e array length number of entries of the table e number of empty buckets e hash table filling rate e longest bucket length e mean bucket length For instance let h Hashtable observe period 1000 h Hashtbl create 17 OCAMLVIZ goes through the whole hash table in the heap The bigger the table the slower the program so correctly adjust the period 4 3 1 6 Module Tree This module allows the monitoring of polymorphic variants once they were changed into the following type type
10. ons to acces them dot ml contains functions that create dot files graphviz from a variant see protocol mli graph ml a module that create a graph on a cairo canvas and functions to manage the graph gui_misc ml contains miscellaneous functions for the GUI gui ml the main file of the GUI containing the main and the functions to build the notebook and export data into graphs and pages gui_models ml contains the functions that create the models and refresh them gui_pref ml contains the functions that create the preferences dialog windows and manage preferences gui_view ml contains the functions that create the views associated to the models see gui_models ml monitor impl ml contains the monitoring API net ml contains the client side network 10 e ocamlviz ml includes monitor_impl ml and contains the server for alarms e ocamlviz_threads ml includes monitor_impl ml and contains the server for threads e preflexer mll parses the file called preferences if it exists to apply the user preferences e protocol mli contains the protocol types e timemap ml a module to store data in an array and retrieve them with a logarith mic complexity e tree _panel ml contains the functions to create and display a tree container 4 2 Protocol The protocol is made of three types of messages e Declare to declare a new tag to a client e Send to send a tag s value only after this tag was declared e Bind
11. to bind tags together optionnal These 3 messages have the following structure command arguments Declare tag kind name Send tag value Bind tag list 4 3 Binary Implementation of the Protocol 4 3 1 Tag A tag is an integer coded on 2 bytes 4 3 2 Kind Each kind is assigned to an integer This integer is then coded on 1 byte 11 Kind Point Time Value_int Value float Value_bool Value string Tag_count Tag_size Special K Tree Hash KLog CO CO NI MH OU BY 0 DO FE E E E 4 33 Name A name is coded into two parts the first part being the string s length on 4 bytes and the second being the string itself on length bytes Bytes 4 n Value length n contents 4 3 4 List A list is coded into two parts the first part being the list s length on 2 bytes and the second being the elements The way the elements are coded will depend on their types Bytes 2 2 e Value length element 1 elements tn 4 3 5 Value e Int Bytes 114 Native Int 31 0 2 Bytes 1 8 Native Int 63 1 2 e Float Bytes 1 8 Float 2 f 12 String Bool Int64 Collected Killed Tree Bytes String length n Bytes Bool Bytes Int64
12. yte code e Ocamlviz_threads This is the library that should be used if the user program already uses alarms Note that OBJECTIVE CAML threads are not efficient and this solution is a patch You have to call Ocamlviz init or Ocamlviz_threads init in your code You may use Ocamlviz send_now or Ocamlviz_threads send_now to force a sending 3 1 1 Module Point This module is a check point tool When putting a Point observe annotation it will sum every time the program goes through this line of code For instance let pointi Point create observe f let _ Point observe pointl 3 1 2 Module Time This module is a chronograph tool The timer that was created can be started and stopped Note that a stopped timer can be restarted For instance let timeri Time create time in function f let f QO begin Time start timerl Time stop timerl end let g a b c d atbtctd let _ Time call time in function g g 1234 3 1 3 Module Tag The module Tag allows creating sets of OBJECTIVE CAML data It s possible to monitor the cardinal number and the size of these sets The sets can contain any value of any type For instance let tag Tag create size true count true period 1000 tag example 8 8 P 8 p let x Tag mark tag true let y Tag mark tag Random float 10 Random int 20 let z Tag mark tag string The set tag contains these 3 elements The size and the cardinal number of this set will be m
13. ze which is got according to server timer 3 3 Visualizing Monitoring Results OCAMLVIZ provides two clients to visualize the monitored data 3 3 1 GUI The GUI is launched with ocamlviz gui options Command line options are server to specify the server machine the default is the local host port to specify the server port the default value is 51000 If no Ocamlviz server is running the GUI fails with the error message connection couldn t connect to the server machine port Otherwise it opens a main window which looks like Menu Visualize in Preferences Record Panel 00 0 00 Refresh Period a 1 min 57 sec 57 72 sec 1 min 57 sec Log E Gc gt Total Size Max Size Living Bytes 656 842 MB 1 000 GB 558 209 MB O 100 E ms Trees gt Stats Values Tags gt Hash tables gt 1 1 500 GB 1 226 GB 953 368 MB 679 740 MB 50 40 30 20 10 o 132 485 MB Gc Period 100 ms x MI Total size amp NME MaxSize v amp MN Living Bytes V E3 The data are displayed in a notebook in the following pages e Stats displays Point and Time e Values displays Value Tags displays Tag Hash tables displays Hashtable Trees displays Tree Log displays the log e Gc displays the garbage collector informations about the size of the heap the size of living data in the heap along with their representation on a graph Inside
Download Pdf Manuals
Related Search