Mercurial > hg > nginx-site
annotate xml/en/docs/nginx_dtrace_pid_provider.xml @ 702:6b6585577c33
Slightly changed the wording when talking about the "rewrite_log" directive.
author | Ruslan Ermilov <ru@nginx.com> |
---|---|
date | Thu, 04 Oct 2012 08:27:40 +0000 |
parents | 8205c2fcde2f |
children | 25584379a968 |
rev | line source |
---|---|
698 | 1 <?xml version="1.0"?> |
2 | |
3 <!-- | |
4 Copyright (C) Nginx, Inc. | |
5 --> | |
6 | |
7 <!DOCTYPE article SYSTEM "../../../dtd/article.dtd"> | |
8 | |
9 <article name="Debugging nginx with DTrace pid provider" | |
10 link="/en/docs/nginx_dtrace_pid_provider.html" | |
11 lang="en" | |
12 rev="1" | |
13 toc="no"> | |
14 | |
15 <section> | |
16 | |
17 <para> | |
699
8205c2fcde2f
Fixed long lines, apostrophes used, etc.
Ruslan Ermilov <ru@nginx.com>
parents:
698
diff
changeset
|
18 This article assumes the reader has a general knowledge of nginx internals and |
698 | 19 <link id="see_also">DTrace</link>. |
20 </para> | |
21 | |
22 <para> | |
699
8205c2fcde2f
Fixed long lines, apostrophes used, etc.
Ruslan Ermilov <ru@nginx.com>
parents:
698
diff
changeset
|
23 Although nginx build with <link doc="debugging_log.xml">--with-debug</link> |
8205c2fcde2f
Fixed long lines, apostrophes used, etc.
Ruslan Ermilov <ru@nginx.com>
parents:
698
diff
changeset
|
24 option already provides a lot of information about request processing, |
8205c2fcde2f
Fixed long lines, apostrophes used, etc.
Ruslan Ermilov <ru@nginx.com>
parents:
698
diff
changeset
|
25 it is sometimes desirable to trace particular parts of code path more |
8205c2fcde2f
Fixed long lines, apostrophes used, etc.
Ruslan Ermilov <ru@nginx.com>
parents:
698
diff
changeset
|
26 thoroughly and at the same time omit the rest of debug output. |
8205c2fcde2f
Fixed long lines, apostrophes used, etc.
Ruslan Ermilov <ru@nginx.com>
parents:
698
diff
changeset
|
27 DTrace pid provider (available on Solaris, OS X) is a useful tool to |
8205c2fcde2f
Fixed long lines, apostrophes used, etc.
Ruslan Ermilov <ru@nginx.com>
parents:
698
diff
changeset
|
28 explore userland programs internals, since it doesn’t require any code |
8205c2fcde2f
Fixed long lines, apostrophes used, etc.
Ruslan Ermilov <ru@nginx.com>
parents:
698
diff
changeset
|
29 changes and it can help with the task. |
8205c2fcde2f
Fixed long lines, apostrophes used, etc.
Ruslan Ermilov <ru@nginx.com>
parents:
698
diff
changeset
|
30 E.g. a simple DTrace script to trace and print nginx functions calls |
8205c2fcde2f
Fixed long lines, apostrophes used, etc.
Ruslan Ermilov <ru@nginx.com>
parents:
698
diff
changeset
|
31 may look like: |
698 | 32 |
33 <programlisting> | |
34 #pragma D option flowindent | |
35 | |
36 pid$target:nginx::entry { | |
37 } | |
38 | |
39 pid$target:nginx::return { | |
40 } | |
41 </programlisting> | |
42 | |
43 </para> | |
44 | |
45 <para> | |
46 DTrace capabilities for function calls tracing provide only a limited amount | |
699
8205c2fcde2f
Fixed long lines, apostrophes used, etc.
Ruslan Ermilov <ru@nginx.com>
parents:
698
diff
changeset
|
47 of useful information, though. |
8205c2fcde2f
Fixed long lines, apostrophes used, etc.
Ruslan Ermilov <ru@nginx.com>
parents:
698
diff
changeset
|
48 Real-time inspection of function arguments is typically more interesting, |
8205c2fcde2f
Fixed long lines, apostrophes used, etc.
Ruslan Ermilov <ru@nginx.com>
parents:
698
diff
changeset
|
49 but also a bit more complicated. |
8205c2fcde2f
Fixed long lines, apostrophes used, etc.
Ruslan Ermilov <ru@nginx.com>
parents:
698
diff
changeset
|
50 Examples below are intended to help the reader become more familiar with |
8205c2fcde2f
Fixed long lines, apostrophes used, etc.
Ruslan Ermilov <ru@nginx.com>
parents:
698
diff
changeset
|
51 DTrace and the process of analyzing nginx behavior using DTrace. |
698 | 52 </para> |
53 | |
54 <para> | |
55 One of the common scenarios for using DTrace with nginx is the following: | |
56 attach to the nginx worker to log request lines and request start times. | |
57 The corresponding function to attach is | |
58 <literal>ngx_http_process_request</literal>, and the argument in question | |
59 is a pointer to <literal>ngx_http_request_t</literal> structure. | |
60 DTrace script for such request logging can be as simple as: | |
61 | |
62 <programlisting> | |
63 | |
64 pid$target::*ngx_http_process_request:entry | |
65 { | |
66 this->request = (ngx_http_request_t *)copyin(arg0, sizeof(ngx_http_request_t)); | |
67 this->request_line = stringof(copyin((uintptr_t)this->request->request_line.data, | |
68 this->request->request_line.len)); | |
699
8205c2fcde2f
Fixed long lines, apostrophes used, etc.
Ruslan Ermilov <ru@nginx.com>
parents:
698
diff
changeset
|
69 printf("request line = %s\n", this->request_line); |
698 | 70 printf("request start sec = %d\n", this->request->start_sec); |
71 } | |
72 | |
73 </programlisting> | |
74 </para> | |
75 | |
76 <para> | |
699
8205c2fcde2f
Fixed long lines, apostrophes used, etc.
Ruslan Ermilov <ru@nginx.com>
parents:
698
diff
changeset
|
77 It should be noted that in the example above DTrace requires some knowledge |
8205c2fcde2f
Fixed long lines, apostrophes used, etc.
Ruslan Ermilov <ru@nginx.com>
parents:
698
diff
changeset
|
78 about <literal>ngx_http_process_request</literal> structure. |
698 | 79 Unfortunately while it is possible to use a specific <literal>#include</literal> |
80 directive in the DTrace script and then pass it to a C preprocessor | |
699
8205c2fcde2f
Fixed long lines, apostrophes used, etc.
Ruslan Ermilov <ru@nginx.com>
parents:
698
diff
changeset
|
81 (with -C flag), that doesn’t really work. |
8205c2fcde2f
Fixed long lines, apostrophes used, etc.
Ruslan Ermilov <ru@nginx.com>
parents:
698
diff
changeset
|
82 Due to a lot of cross dependencies almost all nginx header files |
8205c2fcde2f
Fixed long lines, apostrophes used, etc.
Ruslan Ermilov <ru@nginx.com>
parents:
698
diff
changeset
|
83 have to be included. |
8205c2fcde2f
Fixed long lines, apostrophes used, etc.
Ruslan Ermilov <ru@nginx.com>
parents:
698
diff
changeset
|
84 In turn, based on configure script settings, nginx headers will include PCRE, |
8205c2fcde2f
Fixed long lines, apostrophes used, etc.
Ruslan Ermilov <ru@nginx.com>
parents:
698
diff
changeset
|
85 OpenSSL and a variety of system header files. |
8205c2fcde2f
Fixed long lines, apostrophes used, etc.
Ruslan Ermilov <ru@nginx.com>
parents:
698
diff
changeset
|
86 While in theory all those header files related to a specific nginx build |
698 | 87 might be included in DTrace script preprocessing and compilation, in reality |
88 DTrace script most probably will fail to compile because of unknown syntax in | |
89 some header files. | |
90 </para> | |
91 | |
92 <para> | |
93 The problem above can be solved by including only the relevant and | |
699
8205c2fcde2f
Fixed long lines, apostrophes used, etc.
Ruslan Ermilov <ru@nginx.com>
parents:
698
diff
changeset
|
94 necessary structures and types definitions in the DTrace script. |
8205c2fcde2f
Fixed long lines, apostrophes used, etc.
Ruslan Ermilov <ru@nginx.com>
parents:
698
diff
changeset
|
95 DTrace has to know sizes of structures, types, and fields offsets. |
8205c2fcde2f
Fixed long lines, apostrophes used, etc.
Ruslan Ermilov <ru@nginx.com>
parents:
698
diff
changeset
|
96 Thus dependencies can be further reduced by manually optimizing |
8205c2fcde2f
Fixed long lines, apostrophes used, etc.
Ruslan Ermilov <ru@nginx.com>
parents:
698
diff
changeset
|
97 structure definitions for use with DTrace. |
698 | 98 </para> |
99 | |
100 <para> | |
699
8205c2fcde2f
Fixed long lines, apostrophes used, etc.
Ruslan Ermilov <ru@nginx.com>
parents:
698
diff
changeset
|
101 Let’s use DTrace script example above and see what structure definitions |
8205c2fcde2f
Fixed long lines, apostrophes used, etc.
Ruslan Ermilov <ru@nginx.com>
parents:
698
diff
changeset
|
102 it needs to work properly. |
698 | 103 </para> |
104 | |
105 <para> | |
699
8205c2fcde2f
Fixed long lines, apostrophes used, etc.
Ruslan Ermilov <ru@nginx.com>
parents:
698
diff
changeset
|
106 First of all <literal>objs/ngx_auto_config.h</literal> file generated by |
8205c2fcde2f
Fixed long lines, apostrophes used, etc.
Ruslan Ermilov <ru@nginx.com>
parents:
698
diff
changeset
|
107 configure should be included, because it defines a number of constants |
8205c2fcde2f
Fixed long lines, apostrophes used, etc.
Ruslan Ermilov <ru@nginx.com>
parents:
698
diff
changeset
|
108 affecting various <literal>#ifdef’s</literal>. |
8205c2fcde2f
Fixed long lines, apostrophes used, etc.
Ruslan Ermilov <ru@nginx.com>
parents:
698
diff
changeset
|
109 After that there’s some basic types and definitions |
698 | 110 like <literal>ngx_str_t</literal>, <literal>ngx_table_elt_t</literal>, |
699
8205c2fcde2f
Fixed long lines, apostrophes used, etc.
Ruslan Ermilov <ru@nginx.com>
parents:
698
diff
changeset
|
111 <literal>ngx_uint_t</literal> etc. should be put at the beginning of |
8205c2fcde2f
Fixed long lines, apostrophes used, etc.
Ruslan Ermilov <ru@nginx.com>
parents:
698
diff
changeset
|
112 DTrace script. |
8205c2fcde2f
Fixed long lines, apostrophes used, etc.
Ruslan Ermilov <ru@nginx.com>
parents:
698
diff
changeset
|
113 These definitions are compact, commonly used and unlikely to be |
8205c2fcde2f
Fixed long lines, apostrophes used, etc.
Ruslan Ermilov <ru@nginx.com>
parents:
698
diff
changeset
|
114 frequently changed. |
698 | 115 </para> |
116 | |
117 <para> | |
699
8205c2fcde2f
Fixed long lines, apostrophes used, etc.
Ruslan Ermilov <ru@nginx.com>
parents:
698
diff
changeset
|
118 Then there’s the <literal>ngx_http_process_request_t</literal> structure which |
8205c2fcde2f
Fixed long lines, apostrophes used, etc.
Ruslan Ermilov <ru@nginx.com>
parents:
698
diff
changeset
|
119 contains a lot of pointers to other structures. |
8205c2fcde2f
Fixed long lines, apostrophes used, etc.
Ruslan Ermilov <ru@nginx.com>
parents:
698
diff
changeset
|
120 Because these pointers are really irrelevant to this script, and because they |
8205c2fcde2f
Fixed long lines, apostrophes used, etc.
Ruslan Ermilov <ru@nginx.com>
parents:
698
diff
changeset
|
121 have the same size, it is possible to just replace them with void pointers. |
8205c2fcde2f
Fixed long lines, apostrophes used, etc.
Ruslan Ermilov <ru@nginx.com>
parents:
698
diff
changeset
|
122 Instead of changing definitions, it is better to add appropriate typedefs, |
8205c2fcde2f
Fixed long lines, apostrophes used, etc.
Ruslan Ermilov <ru@nginx.com>
parents:
698
diff
changeset
|
123 though: |
698 | 124 |
125 <programlisting> | |
126 typedef ngx_http_upstream_t void; | |
127 typedef ngx_http_request_body_t void; | |
128 </programlisting> | |
129 | |
130 Last but not least it is necessary to add definitions of two member structures: | |
131 <literal>ngx_http_headers_in_t</literal> and | |
132 <literal>ngx_http_headers_out_t</literal>, callback functions | |
133 declarations and constants definitions. | |
134 </para> | |
135 | |
136 <para> | |
699
8205c2fcde2f
Fixed long lines, apostrophes used, etc.
Ruslan Ermilov <ru@nginx.com>
parents:
698
diff
changeset
|
137 Final DTrace script can be downloaded |
698 | 138 <link url="http://nginx.org/download/trace_process_request.d">here</link>. |
139 </para> | |
140 | |
141 <para> | |
142 The example below shows the output of the DTrace script: | |
143 | |
144 <programlisting> | |
145 # dtrace -C -I ./objs -s trace_process_request.d -p 4848 | |
146 dtrace: script 'trace_process_request.d' matched 1 probe | |
147 CPU ID FUNCTION:NAME | |
148 1 4 .XAbmO.ngx_http_process_request:entry request line = GET / HTTP/1.1 | |
149 request start sec = 1349162898 | |
150 | |
151 0 4 .XAbmO.ngx_http_process_request:entry request line = GET /en/docs/nginx_dtrace_pid_provider.html HTTP/1.1 | |
152 request start sec = 1349162899 | |
153 </programlisting> | |
154 | |
155 </para> | |
156 | |
157 <para>Using similar techniques the reader should be able to trace other | |
158 nginx functions calls. | |
159 </para> | |
160 | |
161 </section> | |
162 | |
699
8205c2fcde2f
Fixed long lines, apostrophes used, etc.
Ruslan Ermilov <ru@nginx.com>
parents:
698
diff
changeset
|
163 |
698 | 164 <section id="see_also" |
165 name="See also"> | |
166 | |
167 <para> | |
168 <list type="bullet"> | |
169 | |
170 <listitem> | |
171 <link url="http://docs.oracle.com/cd/E19253-01/817-6223/index.html"> | |
172 Solaris Dynamic Tracing Guide</link> | |
173 </listitem> | |
174 | |
175 <listitem> | |
176 <link url="http://dtrace.org/blogs/brendan/2011/02/09/dtrace-pid-provider/"> | |
177 Introduction article on DTrace pid provider</link> | |
178 </listitem> | |
179 | |
180 </list> | |
181 </para> | |
182 | |
183 </section> | |
184 | |
185 </article> |