Mercurial > hg > nginx-site
annotate xml/en/docs/nginx_dtrace_pid_provider.xml @ 3072:7f493ec56c12
Renamed news page.
| author | Maxim Dounin <mdounin@mdounin.ru> |
|---|---|
| date | Tue, 09 Apr 2024 18:14:16 +0300 |
| parents | cfdc1ba95196 |
| children |
| 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" | |
|
3057
cfdc1ba95196
Free nginx: removed link to the example DTrace script.
Maxim Dounin <mdounin@mdounin.ru>
parents:
2746
diff
changeset
|
12 rev="5" |
| 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> | |
|
3057
cfdc1ba95196
Free nginx: removed link to the example DTrace script.
Maxim Dounin <mdounin@mdounin.ru>
parents:
2746
diff
changeset
|
137 The following example shows the output of running the resulting script: |
| 698 | 138 |
| 139 <programlisting> | |
| 140 # dtrace -C -I ./objs -s trace_process_request.d -p 4848 | |
| 141 dtrace: script 'trace_process_request.d' matched 1 probe | |
| 142 CPU ID FUNCTION:NAME | |
| 143 1 4 .XAbmO.ngx_http_process_request:entry request line = GET / HTTP/1.1 | |
| 144 request start sec = 1349162898 | |
| 145 | |
| 146 0 4 .XAbmO.ngx_http_process_request:entry request line = GET /en/docs/nginx_dtrace_pid_provider.html HTTP/1.1 | |
| 147 request start sec = 1349162899 | |
| 148 </programlisting> | |
| 149 | |
| 150 </para> | |
| 151 | |
| 152 <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
|
153 nginx function calls. |
| 698 | 154 </para> |
| 155 | |
| 156 </section> | |
| 157 | |
|
699
8205c2fcde2f
Fixed long lines, apostrophes used, etc.
Ruslan Ermilov <ru@nginx.com>
parents:
698
diff
changeset
|
158 |
| 698 | 159 <section id="see_also" |
| 160 name="See also"> | |
| 161 | |
| 162 <para> | |
| 163 <list type="bullet"> | |
| 164 | |
| 165 <listitem> | |
| 166 <link url="http://docs.oracle.com/cd/E19253-01/817-6223/index.html"> | |
| 167 Solaris Dynamic Tracing Guide</link> | |
| 168 </listitem> | |
| 169 | |
| 170 <listitem> | |
| 171 <link url="http://dtrace.org/blogs/brendan/2011/02/09/dtrace-pid-provider/"> | |
| 172 Introduction article on DTrace pid provider</link> | |
| 173 </listitem> | |
| 174 | |
| 175 </list> | |
| 176 </para> | |
| 177 | |
| 178 </section> | |
| 179 | |
| 180 </article> |