Mercurial > hg > nginx-site
annotate xml/en/docs/nginx_dtrace_pid_provider.xml @ 1024:e47971bf6619
Documented output_buffers directive.
author | Maxim Dounin <mdounin@mdounin.ru> |
---|---|
date | Thu, 28 Nov 2013 13:46:45 +0400 |
parents | 7f8e85a50845 |
children | f024ac0ec5c7 |
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" | |
733
7f8e85a50845
Renamed OX X to Mac OS X for uniformity.
Sergey Budnevitch <sb@waeme.net>
parents:
708
diff
changeset
|
12 rev="2" |
698 | 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> | |
708
25584379a968
Slightly revised the DTrace article's text and grammar.
Ruslan Ermilov <ru@nginx.com>
parents:
699
diff
changeset
|
23 Although nginx built with the <link doc="debugging_log.xml">--with-debug</link> |
699
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 |
708
25584379a968
Slightly revised the DTrace article's text and grammar.
Ruslan Ermilov <ru@nginx.com>
parents:
699
diff
changeset
|
26 thoroughly and at the same time omit the rest of debugging output. |
733
7f8e85a50845
Renamed OX X to Mac OS X for uniformity.
Sergey Budnevitch <sb@waeme.net>
parents:
708
diff
changeset
|
27 DTrace pid provider (available on Solaris, Mac OS X) is a useful tool to |
708
25584379a968
Slightly revised the DTrace article's text and grammar.
Ruslan Ermilov <ru@nginx.com>
parents:
699
diff
changeset
|
28 explore userland program’s internals, since it doesn’t require any code |
699
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. |
708
25584379a968
Slightly revised the DTrace article's text and grammar.
Ruslan Ermilov <ru@nginx.com>
parents:
699
diff
changeset
|
30 A simple DTrace script to trace and print nginx function calls |
25584379a968
Slightly revised the DTrace article's text and grammar.
Ruslan Ermilov <ru@nginx.com>
parents:
699
diff
changeset
|
31 may look like this: |
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: | |
708
25584379a968
Slightly revised the DTrace article's text and grammar.
Ruslan Ermilov <ru@nginx.com>
parents:
699
diff
changeset
|
56 attach to the nginx worker process to log request lines and request start times. |
698 | 57 The corresponding function to attach is |
708
25584379a968
Slightly revised the DTrace article's text and grammar.
Ruslan Ermilov <ru@nginx.com>
parents:
699
diff
changeset
|
58 <c-func>ngx_http_process_request</c-func>, and the argument in question |
25584379a968
Slightly revised the DTrace article's text and grammar.
Ruslan Ermilov <ru@nginx.com>
parents:
699
diff
changeset
|
59 is a pointer to the <literal>ngx_http_request_t</literal> structure. |
698 | 60 DTrace script for such request logging can be as simple as: |
61 | |
62 <programlisting> | |
63 pid$target::*ngx_http_process_request:entry | |
64 { | |
65 this->request = (ngx_http_request_t *)copyin(arg0, sizeof(ngx_http_request_t)); | |
66 this->request_line = stringof(copyin((uintptr_t)this->request->request_line.data, | |
67 this->request->request_line.len)); | |
699
8205c2fcde2f
Fixed long lines, apostrophes used, etc.
Ruslan Ermilov <ru@nginx.com>
parents:
698
diff
changeset
|
68 printf("request line = %s\n", this->request_line); |
698 | 69 printf("request start sec = %d\n", this->request->start_sec); |
70 } | |
708
25584379a968
Slightly revised the DTrace article's text and grammar.
Ruslan Ermilov <ru@nginx.com>
parents:
699
diff
changeset
|
71 </programlisting> |
698 | 72 |
73 </para> | |
74 | |
75 <para> | |
699
8205c2fcde2f
Fixed long lines, apostrophes used, etc.
Ruslan Ermilov <ru@nginx.com>
parents:
698
diff
changeset
|
76 It should be noted that in the example above DTrace requires some knowledge |
708
25584379a968
Slightly revised the DTrace article's text and grammar.
Ruslan Ermilov <ru@nginx.com>
parents:
699
diff
changeset
|
77 about the <literal>ngx_http_process_request</literal> structure. |
698 | 78 Unfortunately while it is possible to use a specific <literal>#include</literal> |
79 directive in the DTrace script and then pass it to a C preprocessor | |
708
25584379a968
Slightly revised the DTrace article's text and grammar.
Ruslan Ermilov <ru@nginx.com>
parents:
699
diff
changeset
|
80 (with the <literal>-C</literal> flag), that doesn’t really work. |
25584379a968
Slightly revised the DTrace article's text and grammar.
Ruslan Ermilov <ru@nginx.com>
parents:
699
diff
changeset
|
81 Due to a lot of cross dependencies, almost all nginx header files |
699
8205c2fcde2f
Fixed long lines, apostrophes used, etc.
Ruslan Ermilov <ru@nginx.com>
parents:
698
diff
changeset
|
82 have to be included. |
708
25584379a968
Slightly revised the DTrace article's text and grammar.
Ruslan Ermilov <ru@nginx.com>
parents:
699
diff
changeset
|
83 In turn, based on <command>configure</command> script settings, |
25584379a968
Slightly revised the DTrace article's text and grammar.
Ruslan Ermilov <ru@nginx.com>
parents:
699
diff
changeset
|
84 nginx headers will include PCRE, |
699
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 | |
708
25584379a968
Slightly revised the DTrace article's text and grammar.
Ruslan Ermilov <ru@nginx.com>
parents:
699
diff
changeset
|
94 necessary structure and type definitions in the DTrace script. |
699
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 |
708
25584379a968
Slightly revised the DTrace article's text and grammar.
Ruslan Ermilov <ru@nginx.com>
parents:
699
diff
changeset
|
108 affecting various <literal>#ifdef</literal>’s. |
25584379a968
Slightly revised the DTrace article's text and grammar.
Ruslan Ermilov <ru@nginx.com>
parents:
699
diff
changeset
|
109 After that, some basic types and definitions |
698 | 110 like <literal>ngx_str_t</literal>, <literal>ngx_table_elt_t</literal>, |
708
25584379a968
Slightly revised the DTrace article's text and grammar.
Ruslan Ermilov <ru@nginx.com>
parents:
699
diff
changeset
|
111 <literal>ngx_uint_t</literal> etc. should be put at the beginning of the |
699
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> | |
708
25584379a968
Slightly revised the DTrace article's text and grammar.
Ruslan Ermilov <ru@nginx.com>
parents:
699
diff
changeset
|
118 Then there’s the <literal>ngx_http_process_request_t</literal> structure that |
699
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 | |
708
25584379a968
Slightly revised the DTrace article's text and grammar.
Ruslan Ermilov <ru@nginx.com>
parents:
699
diff
changeset
|
130 Last but not least it is necessary to add definitions of two member structures |
25584379a968
Slightly revised the DTrace article's text and grammar.
Ruslan Ermilov <ru@nginx.com>
parents:
699
diff
changeset
|
131 (<literal>ngx_http_headers_in_t</literal>, |
25584379a968
Slightly revised the DTrace article's text and grammar.
Ruslan Ermilov <ru@nginx.com>
parents:
699
diff
changeset
|
132 <literal>ngx_http_headers_out_t</literal>), |
25584379a968
Slightly revised the DTrace article's text and grammar.
Ruslan Ermilov <ru@nginx.com>
parents:
699
diff
changeset
|
133 declarations of callback functions and definitions of constants. |
698 | 134 </para> |
135 | |
136 <para> | |
708
25584379a968
Slightly revised the DTrace article's text and grammar.
Ruslan Ermilov <ru@nginx.com>
parents:
699
diff
changeset
|
137 The final DTrace script can be downloaded from |
698 | 138 <link url="http://nginx.org/download/trace_process_request.d">here</link>. |
139 </para> | |
140 | |
141 <para> | |
708
25584379a968
Slightly revised the DTrace article's text and grammar.
Ruslan Ermilov <ru@nginx.com>
parents:
699
diff
changeset
|
142 The following example shows the output of running this script: |
698 | 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 | |
708
25584379a968
Slightly revised the DTrace article's text and grammar.
Ruslan Ermilov <ru@nginx.com>
parents:
699
diff
changeset
|
158 nginx function calls. |
698 | 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> |