Mercurial > hg > nginx-site
annotate xml/en/docs/nginx_dtrace_pid_provider.xml @ 2846:fdf1464e1977
Moved banner to the external file to make partial rollout possible.
An idea is to have several banners and show them with different probability
specified by split directive in the nginx.conf
author | Sergey Budnevitch <sb@waeme.net> |
---|---|
date | Tue, 10 May 2022 18:07:27 +0400 |
parents | 438e5c551d67 |
children | cfdc1ba95196 |
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" | |
2746
438e5c551d67
Fixed name of the ngx_http_request_t structure in DTrace article.
Maxim Dounin <mdounin@mdounin.ru>
parents:
1911
diff
changeset
|
12 rev="4" |
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. |
1911
f024ac0ec5c7
Apple rebranded Mac OS X to macOS.
Sergey Kandaurov <pluknet@nginx.com>
parents:
733
diff
changeset
|
27 DTrace pid provider (available on Solaris, macOS) 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 |
2746
438e5c551d67
Fixed name of the ngx_http_request_t structure in DTrace article.
Maxim Dounin <mdounin@mdounin.ru>
parents:
1911
diff
changeset
|
77 about the <literal>ngx_http_request_t</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> | |
2746
438e5c551d67
Fixed name of the ngx_http_request_t structure in DTrace article.
Maxim Dounin <mdounin@mdounin.ru>
parents:
1911
diff
changeset
|
118 Then there’s the <literal>ngx_http_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> |