modules/visualize_backtrace/README.txt

/** 
 * OVERVIEW
/* 
The Visualize Backtrace module enables you to visualize the sequential 
order of Drupal function calls for a given page load in both a hierarchical tree 
flowchart and table format. This is a developer's tool to help demystify the
Drupal API, and to help identify bottleneck Drupal functions.

An introductory screencast demonstrating the visualize backtrace module can be
seen here: http://blip.tv/file/431841 (be sure to expand to full screen mode.)

This module transforms trace files created by XDebug into flowcharts 
that include:
 * Hypertext links to the specific line number where the Drupal function 
   was executed within the source code -- the PHP-highlighted code 
   source pages are generated by this module.
 * Ability to plot all of the backtraces of a specific function call -- as
   well as an option to additionally plot the children functions in a
   "forwardtrace."
 * Ability to plot all of the bactraces and forwardtraces of the Drupal
   functions that were called from a specific module filename -- including the
   option of all contributed module functions.
 * Execution time for each function call -- as well as elapsed time of all
   children functions of a specific function.
 * Hypertext links to function descriptions at api.drupal.org to provide more
   context for each function.
 * Functions are labeled and color-coded according to which filename 
   called them.
 * Looping sets of 1, 2 or 3 function pairs are filtered out and labeled 
   as repeating.  
 * Procedural Drupal hooks are labeled with the PHP function & location
   that called it.
 * Sequential ordering of all of the Drupal function calls for a page load
   from top-to-bottom and left-to-right.
 * All text on the flowchart is searchable to quickly find functions or
   to step through sequential function calls


/** 
 * REQUIREMENTS 
/* 
This module requires that XDebug is properly set up in order to create 
the trace files, which more information on this can be found in the 
INSTALL.txt. You should have access to the php.ini and .htaccess files
to set it up.  You should also be able to have write permissions to the 
same directory where the trace files are generated (e.g. "/tmp"). Download
XDebug at http://xdebug.org

You can also optionally alter Apache httpd.conf permissions in order to 
automatically launch the ZGRViewer java applet flowchart viewer from the
command-line via Drupal. More details on installing ZGRViewer are also
in the INSTALL.txt.  It is also possible to copy and paste the CLI commands
into a UNIX terminal window if you have issues with doing it automatically 
-- or if the Drupal-launched terminal window is crashing after a couple
of minutes.  More details at http://zvtm.sourceforge.net/zgrviewer.html#download

Another option for viewing the *.dot flowcharts is to use GraphViz itself, 
which has a Mac OSX client at http://www.pixelglow.com/graphviz

Again, more set-up details can be found in the INSTALL.txt.


/** 
 * HOW TO TEST THAT XDEBUG IS WORKING PROPERLY
/* 
You can test to see if XDebug is properly creating trace files by going 
to the path: "/test_xdebug" -- that is after you've already enabled the 
module with proper access permission of "administer visualize backtrace."

If XDebug is not set up properly, then you may receive an infamous White 
Screen of Death if you've pre-maturely enabled the "Visualize Backtrace" 
block. This is because this block calls the xdebug_get_tracefile_name() 
function, which returns the latest trace file name & trace path (e.g.
"/tmp/trace.1191258238.xt")  

   
/** 
 * VISUALIZE BACKTRACE BLOCK
/* 
The easiest way to generate a function call flowchart for a given Drupal 
page load is to enable the "Visualize Backtrace" block. NOTE: Be sure 
that XDebug is properly installed first as detailed down below.  The following
two links provide an easy way to parse the XDebug trace files.

 * Generate Backtrace Data for this Page Load: 
   Quickly processes the XDebug trace file for the particular page load 
   and provides a splash page for accessing the other flowcharts and tables.

 * View All Past Trace Files
   Displays all of the XDebug trace files that have been created since the last
   time you rebooted or purged your trace file directory. Trace files that have
   already been parsed and displayed are highlighted. This could page is helpful
   in tracking down page loads from AJAX calls or that don't display the links
   from the Visualize Backtrace block.


/** 
 * WARNING: USE WITH CAUTION
/* 
I'd recommend using this within a localhost environment, but use caution 
when using this on a production server since permissions to this module
could reveal the source code of your PHP files. 

Another consideration is that the *.dot files are created within the 
publicly available /files folder, and could be theoretically be downloaded 
if one correctly guessed the *.dot filename.

Also be aware that you will probably need to periodically delete old 
XDebug trace files since they it can generate over 1MB worth of trace data
per Drupal page load.  If the trace files are stored in the /tmp directory, 
then they may automatically be purged when rebooting your computer.  

There are also 1-3MB of *.dot files are created whenever the trace files
are parsed, and so old *.dot files stored in the /files directory may also 
need to be periodically manually purged as well.

The visualize_backtrace module is currently maintained by:
- Kent Bye (http://drupal.org/user/21673) 

// $Id$
1	/**
2	* OVERVIEW
3	/*
4	The Visualize Backtrace module enables you to visualize the sequential
5	order of Drupal function calls for a given page load in both a hierarchical tree
6	flowchart and table format. This is a developer's tool to help demystify the
7	Drupal API, and to help identify bottleneck Drupal functions.
8
9	An introductory screencast demonstrating the visualize backtrace module can be
10	seen here: http://blip.tv/file/431841 (be sure to expand to full screen mode.)
11
12	This module transforms trace files created by XDebug into flowcharts
13	that include:
14	* Hypertext links to the specific line number where the Drupal function
15	was executed within the source code -- the PHP-highlighted code
16	source pages are generated by this module.
17	* Ability to plot all of the backtraces of a specific function call -- as
18	well as an option to additionally plot the children functions in a
19	"forwardtrace."
20	* Ability to plot all of the bactraces and forwardtraces of the Drupal
21	functions that were called from a specific module filename -- including the
22	option of all contributed module functions.
23	* Execution time for each function call -- as well as elapsed time of all
24	children functions of a specific function.
25	* Hypertext links to function descriptions at api.drupal.org to provide more
26	context for each function.
27	* Functions are labeled and color-coded according to which filename
28	called them.
29	* Looping sets of 1, 2 or 3 function pairs are filtered out and labeled
30	as repeating.
31	* Procedural Drupal hooks are labeled with the PHP function & location
32	that called it.
33	* Sequential ordering of all of the Drupal function calls for a page load
34	from top-to-bottom and left-to-right.
35	* All text on the flowchart is searchable to quickly find functions or
36	to step through sequential function calls
37
38
39	/**
40	* REQUIREMENTS
41	/*
42	This module requires that XDebug is properly set up in order to create
43	the trace files, which more information on this can be found in the
44	INSTALL.txt. You should have access to the php.ini and .htaccess files
45	to set it up. You should also be able to have write permissions to the
46	same directory where the trace files are generated (e.g. "/tmp"). Download
47	XDebug at http://xdebug.org
48
49	You can also optionally alter Apache httpd.conf permissions in order to
50	automatically launch the ZGRViewer java applet flowchart viewer from the
51	command-line via Drupal. More details on installing ZGRViewer are also
52	in the INSTALL.txt. It is also possible to copy and paste the CLI commands
53	into a UNIX terminal window if you have issues with doing it automatically
54	-- or if the Drupal-launched terminal window is crashing after a couple
55	of minutes. More details at http://zvtm.sourceforge.net/zgrviewer.html#download
56
57	Another option for viewing the *.dot flowcharts is to use GraphViz itself,
58	which has a Mac OSX client at http://www.pixelglow.com/graphviz
59
60	Again, more set-up details can be found in the INSTALL.txt.
61
62
63	/**
64	* HOW TO TEST THAT XDEBUG IS WORKING PROPERLY
65	/*
66	You can test to see if XDebug is properly creating trace files by going
67	to the path: "/test_xdebug" -- that is after you've already enabled the
68	module with proper access permission of "administer visualize backtrace."
69
70	If XDebug is not set up properly, then you may receive an infamous White
71	Screen of Death if you've pre-maturely enabled the "Visualize Backtrace"
72	block. This is because this block calls the xdebug_get_tracefile_name()
73	function, which returns the latest trace file name & trace path (e.g.
74	"/tmp/trace.1191258238.xt")
75
76
77	/**
78	* VISUALIZE BACKTRACE BLOCK
79	/*
80	The easiest way to generate a function call flowchart for a given Drupal
81	page load is to enable the "Visualize Backtrace" block. NOTE: Be sure
82	that XDebug is properly installed first as detailed down below. The following
83	two links provide an easy way to parse the XDebug trace files.
84
85	* Generate Backtrace Data for this Page Load:
86	Quickly processes the XDebug trace file for the particular page load
87	and provides a splash page for accessing the other flowcharts and tables.
88
89	* View All Past Trace Files
90	Displays all of the XDebug trace files that have been created since the last
91	time you rebooted or purged your trace file directory. Trace files that have
92	already been parsed and displayed are highlighted. This could page is helpful
93	in tracking down page loads from AJAX calls or that don't display the links
94	from the Visualize Backtrace block.
95
96
97	/**
98	* WARNING: USE WITH CAUTION
99	/*
100	I'd recommend using this within a localhost environment, but use caution
101	when using this on a production server since permissions to this module
102	could reveal the source code of your PHP files.
103
104	Another consideration is that the *.dot files are created within the
105	publicly available /files folder, and could be theoretically be downloaded
106	if one correctly guessed the *.dot filename.
107
108	Also be aware that you will probably need to periodically delete old
109	XDebug trace files since they it can generate over 1MB worth of trace data
110	per Drupal page load. If the trace files are stored in the /tmp directory,
111	then they may automatically be purged when rebooting your computer.
112
113	There are also 1-3MB of *.dot files are created whenever the trace files
114	are parsed, and so old *.dot files stored in the /files directory may also
115	need to be periodically manually purged as well.
116
117	The visualize_backtrace module is currently maintained by:
118	- Kent Bye (http://drupal.org/user/21673)
119
120	// $Id$