You already know from Section 13.1 that cache.log contains various operational messages Squid thinks are important enough to tell you about. We also refer to these as debugging messages. You can use the debug_options directive to control the verbosity of messages that appear in cache.log. By increasing the debugging levels, you'll see more detailed messages that may help you understand what Squid is doing. For example:
debug_options ALL,1 11,3 20,3
Every debugging message in the Squid source code has two numeric attributes: a section and a level. Sections range from 0 to 100, and levels range from 0 to 10. In general, section numbers correspond to particular components of the source code. In other words, all the messages within a single source file have the same section number. In some cases, multiple files use the same debugging section. This tends to happen when a source file becomes too large and is split into smaller chunks.
The top of each source file has line that mentions the debugging section. It looks like this:
* DEBUG: section 9 File Transfer Protocol (FTP)
I don't expect you to look at the source files to find the section numbers. The same information appears here in Table 16-1.
Number |
Description |
Source file(s) |
---|---|---|
0 |
Client Database |
client_db.c |
1 |
Startup and Main Loop |
main.c |
2 |
Unlink Daemon |
unlinkd.c |
3 |
Configuration File Parsing |
cache_cf.c |
4 |
Error Generation |
errorpage.c |
5 |
Socket Functions |
comm.c |
5 |
Socket Functions |
comm_select.c |
6 |
Disk I/O Routines |
disk.c |
7 |
Multicast |
multicast.c |
8 |
Swap File Bitmap |
filemap.c |
9 |
File Transfer Protocol (FTP) |
ftp.c |
10 |
Gopher |
gopher.c |
11 |
Hypertext Transfer Protocol (HTTP) |
http.c |
12 |
Internet Cache Protocol |
icp_v2.c |
12 |
Internet Cache Protocol |
icp_v3.c |
13 |
High Level Memory Pool Management |
mem.c |
14 |
IP Cache |
ipcache.c |
15 |
Neighbor Routines |
neighbors.c |
16 |
Cache Manager Objects |
cache_manager.c |
17 |
Request Forwarding |
forward.c |
18 |
Cache Manager Statistics |
stat.c |
19 |
Store Memory Primitives |
stmem.c |
20 |
Storage Manager |
store.c |
20 |
Storage Manager Client-Side Interface |
store_client.c |
20 |
Storage Manager Heap-Based Replacement |
repl/heap/store_heap_replacement.c |
20 |
Storage Manager Logging Functions |
store_log.c |
20 |
Storage Manager MD5 Cache Keys |
store_key_md5.c |
20 |
Storage Manager Swapfile Metadata |
store_swapmeta.c |
20 |
Storage Manager Swapin Functions |
store_swapin.c |
20 |
Storage Manager Swapout Functions |
store_swapout.c |
20 |
Store Rebuild Routines |
store_rebuild.c |
21 |
Misc Functions |
tools.c |
22 |
Refresh Calculation |
refresh.c |
23 |
URL Parsing |
url.c |
24 |
WAIS Relay |
wais.c |
25 |
MIME Parsing |
mime.c |
26 |
Secure Sockets Layer Proxy |
ssl.c |
27 |
Cache Announcer |
send-announce.c |
28 |
Access Control |
acl.c |
29 |
Authenticator |
auth/basic/auth_basic.c |
29 |
Authenticator |
auth/digest/auth_digest.c |
29 |
Authenticator |
authenticate.c |
29 |
NTLM Authenticator |
auth/ntlm/auth_ntlm.c |
30 |
Ident (RFC 1413) |
ident.c |
31 |
Hypertext Caching Protocol |
htcp.c |
32 |
Asynchronous Disk I/O |
fs/aufs/async_io.c |
33 |
Client-Side Routines |
client_side.c |
34 |
Dnsserver Interface |
dns.c |
35 |
FQDN Cache |
fqdncache.c |
37 |
ICMP Routines |
icmp.c |
38 |
Network Measurement Database |
net_db.c |
39 |
Cache Array Routing Protocol |
carp.c |
40 |
Referer Logging |
referer.c |
40 |
User-Agent Logging |
useragent.c |
41 |
Event Processing |
event.c |
42 |
ICMP Pinger Program |
pinger.c |
43 |
AIOPS |
fs/aufs/aiops.c |
44 |
Peer Selection Algorithm |
peer_select.c |
45 |
Callback Data Registry |
cbdata.c |
45 |
Callback Data Registry |
leakfinder.c |
46 |
Access Log |
access_log.c |
47 |
Store COSS Directory Routines |
fs/coss/store_dir_coss.c |
47 |
Store Directory Routines |
fs/aufs/store_dir_aufs.c |
47 |
Store Directory Routines |
fs/diskd/store_dir_diskd.c |
47 |
Store Directory Routines |
fs/null/store_null.c |
47 |
Store Directory Routines |
fs/ufs/store_dir_ufs.c |
47 |
Store Directory Routines |
store_dir.c |
48 |
Persistent Connections |
pconn.c |
49 |
SNMP Interface |
snmp_agent.c |
49 |
SNMP Support |
snmp_core.c |
50 |
Log File Handling |
logfile.c |
51 |
File Descriptor Functions |
fd.c |
52 |
URN Parsing |
urn.c |
53 |
AS Number Handling |
asn.c |
54 |
Interprocess Communication |
ipc.c |
55 |
HTTP Header |
HttpHeader.c |
56 |
HTTP Message Body |
HttpBody.c |
57 |
HTTP Status-Line |
HttpStatusLine.c |
58 |
HTTP Reply (Response) |
HttpReply.c |
59 |
Auto-Growing Memory Buffer with printf |
MemBuf.c |
60 |
Packer: A Uniform Interface to Store Like Modules |
Packer.c |
61 |
Redirector |
redirect.c |
62 |
Generic Histogram |
StatHist.c |
63 |
Low Level Memory Pool Management |
MemPool.c |
64 |
HTTP Range Header |
HttpHdrRange.c |
65 |
HTTP Cache Control Header |
HttpHdrCc.c |
66 |
HTTP Header Tools |
HttpHeaderTools.c |
67 |
String |
String.c |
68 |
HTTP Content-Range Header |
HttpHdrContRange.c |
69 |
HTTP Header: Extension Field |
HttpHdrExtField.c |
70 |
Cache Digest |
CacheDigest.c |
71 |
Store Digest Manager |
store_digest.c |
72 |
Peer Digest Routines |
peer_digest.c |
73 |
HTTP Request |
HttpRequest.c |
74 |
HTTP Message |
HttpMsg.c |
75 |
WHOIS Protocol |
whois.c |
76 |
Internal Squid Object handling |
internal.c |
77 |
Delay Pools |
delay_pools.c |
78 |
DNS Lookups; interacts with lib/rfc1035.c |
dns_internal.c |
79 |
Squid-Side DISKD I/O Functions |
fs/diskd/store_io_diskd.c |
79 |
Storage Manager COSS Interface |
fs/coss/store_io_coss.c |
79 |
Storage Manager UFS Interface |
fs/ufs/store_io_ufs.c |
80 |
WCCP Support |
wccp.c |
82 |
External ACL |
external_acl.c |
83 |
SSL Accelerator Support |
ssl_support.c |
84 |
Helper Process Maintenance |
helper.c |
Debugging levels are assigned such that more important messages have smaller values and less important messages have higher values. Level is for very important messages, while level 10 is for those that are relatively unimportant. Other than that, there are no strict guidelines or requirements. Developers are generally free to choose which debugging levels are appropriate.
The debug_options directive determines which messages appear in cache.log. Its syntax is:
debug_options section,level section,level ...
The default setting is ALL,1 such that Squid prints any debugging message with level 0 or 1. If you want to make even less output appear in cache.log, you can set debug_options to ALL,0.
If you want to see additional debugging for a particular component, simply add the appropriate section and level to the end of the debug_options list. For example, this line adds level 5 debugging for the FTP server-side code:
debug_options ALL,1 9,5
As with other configuration directives, you can change debug_options, then send Squid the reconfigure signal:
% squid -k reconfigure
Note that the debug_options parameters are processed sequentially, and a later value can override an earlier one. This is of particular concern if you use the ALL keyword. Consider this example:
debug_options 9,5 20,9 4,2 ALL,1
In this case, the final value overwrites all of the preceding settings because ALL,1 sets the debugging level to 1 for all sections.
Selecting appropriate debugging sections and levels is sometimes quite difficult, especially for novice Squid users. Many of the more detailed debugging messages are meaningful only to developers and those familiar with the source code. Inexperienced Squid users are likely to find many of the debugging messages meaningless and overwhelming. Furthermore, you may have difficulty isolating the debugging for a particular request or event if Squid is relatively busy. The higher debugging levels are often more useful if you can test Squid with one request at a time.
You must also be particularly careful about running Squid with high debugging levels for a long amount of time. If Squid is busy, the cache.log file grows very quickly and may eventually consume all free space on its partition. If this happens, Squid exits with a fatal message. Another concern is that performance may degrade significantly. Due to the high number of debugging messages, Squid devotes a lot of CPU resources to formatting and printing strings. It also consumes a lot of disk bandwidth writing them all to cache.log.