Skip to content
This repository
Fetching contributors…

Octocat-spinner-32-eaf2f5

Cannot retrieve contributors at this time

file 134 lines (107 sloc) 4.617 kb
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133
== link:index.html[Index] -> link:dev.html[Development info]

Development: Debugging Cherokee
-------------------------------

[[cherokee-admin]]
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]]
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 V=1 CFLAGS="-O0 -gdb3"
----
+
And then you will be able to execute under a debugger (gdb).

* 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
----

* If you want a code backtrace printed each time an error message is
  generated, add the following `configure` parameter:
+
----
  --enable-backtraces
----
+
* 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 1.0.0b5077 (May 12 2010): Listening on port ALL:80, 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

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:
+
[cols="20%,80%",options="header"]
|==================================================================
|Keyword |Description
|all |Activates all the trace points
|time |Prints the time at the beginning of the line
|thread |Prints the thread ID
|from=<IP> |Restrict the tracing to the information generated by certain IP or Subnet.
|==================================================================

* You can also access the functionality of CHEROKEE_TRACE through
  `cherokee-tweak`. Refer to the apropriate section of the
  documentation to learn more about this:
  link:other_bundle_cherokee-tweak.html[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 a colorized output. Even if it is not terribly
complicated, it is a handy script to trace the server more easily.

image::media/images/tracelor.png[Output of tracelor.py]
Something went wrong with that request. Please try again.