Index → Development info

Development: Debugging Cherokee

cherokee-admin

Cherokee Admin is written in Python. While making changes, you can use the -x or —debug parameter to see the Python back traces in the active console.

cherokee

If you need to debug the behavior of the web server (or an application), there are some helpful tools available for you.

To start with, if you are using gcc and you want to compile Cherokee with debug information just execute make like this:
```
  make CFLAGS="-O0 -g3"
```
And then you'll be able to execute gdb, cgdb, gdbtui..

You can use autoconf to set up Cherokee to use static modules:

  ./autogen.sh --localstatedir=/var --prefix=/usr --sysconfdir=/etc  \
  --with-wwwroot=/var/www --enable-static-module=all --enable-static \
  --enable-shared=no

You can also enable a cool feature: the CHEROKEE_TRACE environment variable to trace what is going on inside the server. To enable it you must add a special flag to your configure or autogen.sh statement:
```
  --enable-trace
```
This will let you trace the behavior with a human-readable output.

Note that by enabling tracing you will be making Cherokee a lot slower. Keep this in mind when deploying in production environments.

Now, when you are going to launch the web server, just add the CHEROKEE_TRACE variable, with the desired options:

cherokee# CHEROKEE_TRACE="common" cherokee

Cherokee Web Server 0.98.0 (Jan 19 2009): Listening on ports ALL:80,

ALL:443(TLS), TLS disabled, IPv6 enabled, using epoll, 1024 fds system

limit, max. 505 connections, caching I/O, 10 threads, 50 connections per

thread, standard scheduling policy, tracing common

handler_common.c:0143 ( stat_file): /var/www//images/powered_by_cherokee.png, use_iocache=0 re=0

handler_common.c:0190 ( cherokee_handler_common_new): request: /images/powered_by_cherokee.png, local: /var/www//images/powered_by_cherokee.png, exists 1

handler_common.c:0236 ( cherokee_handler_common_new): going for handler_file

handler_common.c:0143 ( stat_file): /var/www//images/default-bg.png, use_iocache=0 re=0

handler_common.c:0190 ( cherokee_handler_common_new): request: /images/default-bg.png, local: /var/www//images/default-bg.png, exists 1

handler_common.c:0236 ( cherokee_handler_common_new): going for handler_file

handler_common.c:0143 ( stat_file): /var/www//images/cherokee-logo.png, use_iocache=0 re=0

handler_common.c:0190 ( cherokee_handler_common_new): request: /images/cherokee-logo.png, local: /var/www//images/cherokee-logo.png, exists 1

handler_common.c:0236 ( cherokee_handler_common_new): going for handler_file

Of course, you can trace all the modules (handlers, loggers..) you need:
```
CHEROKEE_TRACE="common,static,io_cache" /usr/bin/cherokee
CHEROKEE_TRACE="all" /usr/bin/cherokee
```
By default the environment variable contains a list of comma separated words, that point the server which parts and actions are interesting for your trace. Besides, there are a few special cases:
- all: Activates all the trace points
- time: Prints the time at the beginning of the line
- thread: Prints the thread ID
You can also access the functionality of CHEROKE_TRACE through cherokee-tweak. Refer to the apropriate section of the documentation to learn more about this: cherokee-tweak.
Lastly a utility is provided, contrib/tracelor.py, to provide further help to these tracing abilities. It is a little script that helps to read the tracing logs by colorizing the thread references and highlighting the words passed through the command line.

An example of usage would be:
```
CHEROKEE_TRACE=thread,all ./cherokee | ../contrib/tracelor.py iocache
```
And it would yield an output such as the following. Even if it is not terribly complicated, it is a handy script to trace the server more easily.