16.2 Debugging via cache.log

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.

Table 16-1. Debugging section numbers for the debug_options directive

Number	Description	Source file(s)
	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 .