Mercurial > hg > nginx-site
annotate xml/en/docs/nginx_dtrace_pid_provider.xml @ 1878:127ae107e5a9
Removed clause about shared memory and Windows versions with ASLR.
Starting with nginx 1.9.0 shared memory can be used on Windows versions
with address space layout randomization.
| author | Maxim Dounin <mdounin@mdounin.ru> |
|---|---|
| date | Mon, 26 Dec 2016 19:38:06 +0300 |
| 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> |