Edgewall Software

Changes between Version 10 and Version 11 of TracTroubleshooting


Ignore:
Timestamp:
Feb 8, 2015, 3:47:47 PM (9 years ago)
Author:
figaro
Comment:

Cosmetic changes

Legend:

Unmodified
Added
Removed
Modified

  • TracTroubleshooting

    v10 v11  
    11[[PageOutline(2-5)]]
    2 = Trac Troubleshooting or ''"When Things Go Wrong"'' =
     2
     3= Trac Troubleshooting
    34
    45This is a collection of recipes you can use to troubleshoot Trac and help us to fix bugs.
    56
    6 == RTFW (''Read the Fine Wiki'') ==
     7== RTFW (''Read the Fine Wiki'')
    78
    8 Trac comes with extensive documentation in form of a collection of Wiki pages.
    9 Some are present in each Trac installation (those that are part of the TracGuide), while most are only found on this site.
    10 Among the latter is the TracFaq (frequently asked questions).
     9Trac comes with extensive documentation in form of [http://trac.edgewall.org/wiki Wiki pages].
     10Some are present in each Trac installation, for example those that are part of the TracGuide, while most are only found on this site, for example the TracFaq (frequently asked questions).
    1111
    12 A few subsystems have their dedicated page with a troubleshooting section:
     12Some subsystems have their dedicated page with a troubleshooting section:
    1313 - PySqlite#Troubleshooting
     14 - MySqlDb#Troubleshooting
    1415 - TracSubversion#Troubleshooting
    1516 - TracModPython#Troubleshooting
    … …  
    1718 - TracNotification#Troubleshooting
    1819
    19 Then, use the TracSearch to dig through existing tickets, looking for past issues similar to yours thanks to carefully selected keywords. The Trac ["MailingList"]s are also usually of some help.
     20Then, use the TracSearch to dig through existing tickets describing issues similar to yours. The Trac ["MailingList"]s are also usually of some help.
    2021
    2122And don't forget it's a Wiki, so feel free to enhance its content while you're at it.
    2223
    23 Now, assuming you're facing a new problem, the next step is to try to find out what's really wrong.
     24If you're facing a new problem, the next step is to try to find out the root cause.
    2425
    25 == Debugging Trac ==
     26== Debugging Trac
    2627
    27 === Python errors ===
     28=== Python errors
    2829
    29 First, it should be noted that debugging Python errors in Trac is much more convenient since [milestone:0.11]:
    30 when you get an internal error and provided you have the TRAC_ADMIN privilege, the error page will show you an interactive stack trace, which enables you to see the faulty line of code in its context and to view the values of the local variables.
     30Debugging Python errors in Trac is much more convenient since [milestone:0.11]: when you get an internal error and provided you have the TRAC_ADMIN privilege, the error page will show you an interactive stack trace, which enables you to see the faulty line of code in its context and to view the values of the local variables.
    3131
    3232Now, before describing the specific debugging techniques you can use, some basic understanding of the way Trac is working is needed.
    3333
    34 Trac uses a model-view-controller approach. The ''controller'' is a Python class called a "module" which inherits from the Component class implementing the `IRequestHandler` interface (a ''Component'' is the basic building block in the TracDev/ComponentArchitecture, it ''implements'' some ''Interface''s). The controller reacts on user requests and prepares the data that will be used by a template engine to fill the adequate template, in order to render the ''view'' which will be sent back to the user.
     34Trac uses a [http://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller model-view-controller approach]. The ''controller'' is a Python class called a "module" which inherits from the Component class implementing the `IRequestHandler` interface. A ''Component'' is the basic building block in the TracDev/ComponentArchitecture, it ''implements'' some ''Interface''s. The controller reacts on user requests and prepares the data that will be used by a template engine to fill the adequate template, in order to render the ''view'' which will be sent back to the user.
    3535
    36 Other resources from TracDev can be useful reading here, in particular TracDev/HowTracWorks.
     36The TracDev collection of development guides can be useful here.
    3737
    38 ==== Inspecting the Template data ====
    39 ===== Clearsilver's HDF =====
     38==== Inspecting the Template data
     39===== Clearsilver's HDF
    4040
    4141Before [milestone:0.11], Trac was using ClearSilver as its template engine.
    4242Clearsilver uses a so-called ''Hierarchical Data Format'' which is prepared by the controller.
    43 In order to inspect this ''HDF'', a simple trick is to append to the URL the `?hdfdump=1` string (or `&hdfdump=1`, in case other parameters are already present in the URL).
     43In order to inspect this ''HDF'', a simple trick is to append to the URL the `?hdfdump=1` string or `&hdfdump=1`, in case other parameters are already present in the URL.
    4444
    45 ===== Genshi data dictionary =====
     45===== Genshi data dictionary
     46
    4647Starting with [milestone:0.11], Trac uses the [http://genshi.edgewall.org Genshi] template engine.
    4748As this template engine is also written in Python, no specific data format is needed and a simple Python dictionary is used to feed the engine. It's very easy to inspect any part of this data by modifying the template and inserting `${pprint(...)}` statements, possibly in between `<pre>...</pre>` tags.
    … …  
    5253}}}
    5354
    54 ==== Modifying the Code ====
     55==== Modifying the Code
    5556
    56 TracStandalone is the indispensable companion whether you intend to develop or debug Trac. In particular, check out the `-r` (auto-reload) feature, which will make Trac notice any change to one of its source file and restart automatically. You can therefore see Trac react immediately to your code changes (provided you don't have syntax errors outside of a method...).
     57TracStandalone is the indispensable companion whether you intend to develop or debug Trac. In particular, check out the `-r` (auto-reload) feature, which will make Trac notice any change to one of its source file and restart automatically. You can therefore see Trac react immediately to your code changes, provided you don't have syntax errors outside of a method.
    5758
    58 In this setup, you're free to try out modification, dump additional information to the log or insert direct `print` statements... (ugly but effective way of debugging).
     59In this setup, you're free to try out modification, dump additional information to the log or insert direct `print` statements; an ugly but effective way of debugging.
    5960
    60 It's probably possible to run `tracd` with a debugger, but I'll skip that paragraph for now ;)
     61It may even be possible to run `tracd` with a debugger, but not explored here.
    6162
    62 Best is to start from a [TracSubversion checkout] of the pristine source code you're interested to debug (or develop for).
     63Best is to start from a [TracSubversion checkout] of the pristine source code you're interested to debug or develop for.
    6364Then, you can run the standalone server by doing:
    6465{{{
    … …  
    7071$ python trac/web/standalone.py <options>
    7172}}}
    72 Note that the very first time (in a fresh working copy), you'll have to at least initialize the ''Trac.egg-info'' folder, by doing:
     73Note that the very first time in a fresh working copy, you'll have to at least initialize the ''Trac.egg-info'' folder, by doing:
    7374{{{
    7475$ python setup.py egg_info
    7576}}}
    7677
     78=== System Errors
    7779
     80By system errors, we mean serious issues like segmentation faults or process hangs. This usually involves some C extensions used by Trac, either due to a bug or a misconfiguration in those libraries, or to an incorrect usage within Trac.
    7881
    79 === System Errors ===
     82In this case, the first thing to do is to identify the subsystem involved, by getting the ''stack trace'' of the process. This can be done using `gdb` on Unix or [http://www.microsoft.com/whdc/devtools/debugging/default.mspx WinDbg] on Windows or MS Developer Studio.
    8083
    81 By system errors, we mean serious issues like segmentation faults or process hangs.
    82 This usually involves some C extensions used by Trac, either due to a bug or a misconfiguration in those libraries, or to an incorrect usage within Trac.
    83 
    84 In this case, the first thing to do is to identify the subsystem involved, by getting the ''stack trace'' of the process. This can be done using `gdb` on Unix or [http://www.microsoft.com/whdc/devtools/debugging/default.mspx WinDbg] on Windows (or MS Developer Studio).
    85 
    86 With GDB, you can also make the link between the C stack trace and the Python backtrace. For this, you need to teach `gdb` a few additional commands: Get the following  [http://hg.python.org/cpython/file/2.7/Misc/gdbinit gdbinit] script, and "source" it.
     84With [https://www.gnu.org/software/gdb/ GDB] you can also make the link between the C stack trace and the Python backtrace. For this, you need to teach `gdb` a few additional commands: Get the following  [http://hg.python.org/cpython/file/2.7/Misc/gdbinit gdbinit] script, and "source" it.
    8785You should be able to issue interesting commands like `pystack`, `pyframe`, `pylocals`, etc.
    8886
    8987If you're using a gdb 7.x version built "`--with-python`", you can instead "`source`" [http://hg.python.org/cpython/file/2.7/Tools/gdb/libpython.py  libpython.py] and use `py-bt` (see also [http://sourceware.org/gdb/current/onlinedocs/gdb/Python.html Scripting gdb using Python]).
    9088
    91 ==== Debugging Segmentation Faults ====
     89==== Debugging Segmentation Faults
    9290
    93 Getting a backtrace for `tracd`
     91Getting a backtrace for `tracd`:
    9492{{{
    9593$ gdb $(which python)
    9694(gdb) run /opt/trac-0.10/scripts/tracd -p 8080 /srv/trac/yourproject
    9795}}}
    98 (of course, adapt the paths and the options to match what's relevant for you)
     96Of course, adapt the paths and the options to match what's relevant for you.
    9997
    10098Getting a backtrace for Apache's `httpd` can be done in a similar way:
    … …  
    108106Another very useful command is "`info shared`", which gives you a list of the shared libraries actually used.
    109107
    110 ==== Debugging a Hanging Process ====
     108==== Debugging a Hanging Process
    111109
    112110Here it might be interesting to just "attach" to an already running process:
    … …  
    143141}}}
    144142
    145 In the above, the `Loaded symbols ... ` part usually already interesting.
    146 You may find out that the libraries actually used are not the one that you expected, or you might notice interesting things, like the presence of mod_php triggering the load of an alternate sqlite library, etc.
     143The `Loaded symbols ... ` part usually provides interesting information.
     144You may find out that the libraries actually used are not the one that you expected, or you might notice the presence of mod_php triggering the load of an alternate sqlite library.
    147145That kind of information is also available without `gdb` by looking in the `/proc/28221/maps` file (to reuse the same pid from the above example).
    148146