Mercurial > hg > nginx-site

comparison xml/en/docs/nginx_dtrace_pid_provider.xml @ 708:25584379a968

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Slightly revised the DTrace article's text and grammar.
author Ruslan Ermilov <ru@nginx.com>
date Fri, 05 Oct 2012 04:15:57 +0000
parents 8205c2fcde2f
children 7f8e85a50845
comparison
equal deleted inserted replaced
707:b133b1f44765 708:25584379a968
18 This article assumes the reader has a general knowledge of nginx internals and 18 This article assumes the reader has a general knowledge of nginx internals and
19 <link id="see_also">DTrace</link>. 19 <link id="see_also">DTrace</link>.
20 </para> 20 </para>
21 21
22 <para> 22 <para>
23 Although nginx build with <link doc="debugging_log.xml">--with-debug</link> 23 Although nginx built with the <link doc="debugging_log.xml">--with-debug</link>
24 option already provides a lot of information about request processing, 24 option already provides a lot of information about request processing,
25 it is sometimes desirable to trace particular parts of code path more 25 it is sometimes desirable to trace particular parts of code path more
26 thoroughly and at the same time omit the rest of debug output. 26 thoroughly and at the same time omit the rest of debugging output.
27 DTrace pid provider (available on Solaris, OS X) is a useful tool to 27 DTrace pid provider (available on Solaris, OS X) is a useful tool to
28 explore userland programs internals, since it doesn’t require any code 28 explore userland program’s internals, since it doesn’t require any code
29 changes and it can help with the task. 29 changes and it can help with the task.
30 E.g. a simple DTrace script to trace and print nginx functions calls 30 A simple DTrace script to trace and print nginx function calls
31 may look like: 31 may look like this:
32 32
33 <programlisting> 33 <programlisting>
34 #pragma D option flowindent 34 #pragma D option flowindent
35 35
36 pid$target:nginx::entry { 36 pid$target:nginx::entry {
51 DTrace and the process of analyzing nginx behavior using DTrace. 51 DTrace and the process of analyzing nginx behavior using DTrace.
52 </para> 52 </para>
53 53
54 <para> 54 <para>
55 One of the common scenarios for using DTrace with nginx is the following: 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. 56 attach to the nginx worker process to log request lines and request start times.
57 The corresponding function to attach is 57 The corresponding function to attach is
58 <literal>ngx_http_process_request</literal>, and the argument in question 58 <c-func>ngx_http_process_request</c-func>, and the argument in question
59 is a pointer to <literal>ngx_http_request_t</literal> structure. 59 is a pointer to the <literal>ngx_http_request_t</literal> structure.
60 DTrace script for such request logging can be as simple as: 60 DTrace script for such request logging can be as simple as:
61 61
62 <programlisting> 62 <programlisting>
63
64 pid$target::*ngx_http_process_request:entry 63 pid$target::*ngx_http_process_request:entry
65 { 64 {
66 this->request = (ngx_http_request_t *)copyin(arg0, sizeof(ngx_http_request_t)); 65 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, 66 this->request_line = stringof(copyin((uintptr_t)this->request->request_line.data,
68 this->request->request_line.len)); 67 this->request->request_line.len));
69 printf("request line = %s\n", this->request_line); 68 printf("request line = %s\n", this->request_line);
70 printf("request start sec = %d\n", this->request->start_sec); 69 printf("request start sec = %d\n", this->request->start_sec);
71 } 70 }
71 </programlisting>
72 72
73 </programlisting>
74 </para> 73 </para>
75 74
76 <para> 75 <para>
77 It should be noted that in the example above DTrace requires some knowledge 76 It should be noted that in the example above DTrace requires some knowledge
78 about <literal>ngx_http_process_request</literal> structure. 77 about the <literal>ngx_http_process_request</literal> structure.
79 Unfortunately while it is possible to use a specific <literal>#include</literal> 78 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 79 directive in the DTrace script and then pass it to a C preprocessor
81 (with -C flag), that doesn’t really work. 80 (with the <literal>-C</literal> flag), that doesn’t really work.
82 Due to a lot of cross dependencies almost all nginx header files 81 Due to a lot of cross dependencies, almost all nginx header files
83 have to be included. 82 have to be included.
84 In turn, based on configure script settings, nginx headers will include PCRE, 83 In turn, based on <command>configure</command> script settings,
84 nginx headers will include PCRE,
85 OpenSSL and a variety of system header files. 85 OpenSSL and a variety of system header files.
86 While in theory all those header files related to a specific nginx build 86 While in theory all those header files related to a specific nginx build
87 might be included in DTrace script preprocessing and compilation, in reality 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 88 DTrace script most probably will fail to compile because of unknown syntax in
89 some header files. 89 some header files.
90 </para> 90 </para>
91 91
92 <para> 92 <para>
93 The problem above can be solved by including only the relevant and 93 The problem above can be solved by including only the relevant and
94 necessary structures and types definitions in the DTrace script. 94 necessary structure and type definitions in the DTrace script.
95 DTrace has to know sizes of structures, types, and fields offsets. 95 DTrace has to know sizes of structures, types, and fields offsets.
96 Thus dependencies can be further reduced by manually optimizing 96 Thus dependencies can be further reduced by manually optimizing
97 structure definitions for use with DTrace. 97 structure definitions for use with DTrace.
98 </para> 98 </para>
99 99
103 </para> 103 </para>
104 104
105 <para> 105 <para>
106 First of all <literal>objs/ngx_auto_config.h</literal> file generated by 106 First of all <literal>objs/ngx_auto_config.h</literal> file generated by
107 configure should be included, because it defines a number of constants 107 configure should be included, because it defines a number of constants
108 affecting various <literal>#ifdef’s</literal>. 108 affecting various <literal>#ifdef</literal>’s.
109 After that there’s some basic types and definitions 109 After that, some basic types and definitions
110 like <literal>ngx_str_t</literal>, <literal>ngx_table_elt_t</literal>, 110 like <literal>ngx_str_t</literal>, <literal>ngx_table_elt_t</literal>,
111 <literal>ngx_uint_t</literal> etc. should be put at the beginning of 111 <literal>ngx_uint_t</literal> etc. should be put at the beginning of the
112 DTrace script. 112 DTrace script.
113 These definitions are compact, commonly used and unlikely to be 113 These definitions are compact, commonly used and unlikely to be
114 frequently changed. 114 frequently changed.
115 </para> 115 </para>
116 116
117 <para> 117 <para>
118 Then there’s the <literal>ngx_http_process_request_t</literal> structure which 118 Then there’s the <literal>ngx_http_process_request_t</literal> structure that
119 contains a lot of pointers to other structures. 119 contains a lot of pointers to other structures.
120 Because these pointers are really irrelevant to this script, and because they 120 Because these pointers are really irrelevant to this script, and because they
121 have the same size, it is possible to just replace them with void pointers. 121 have the same size, it is possible to just replace them with void pointers.
122 Instead of changing definitions, it is better to add appropriate typedefs, 122 Instead of changing definitions, it is better to add appropriate typedefs,
123 though: 123 though:
125 <programlisting> 125 <programlisting>
126 typedef ngx_http_upstream_t void; 126 typedef ngx_http_upstream_t void;
127 typedef ngx_http_request_body_t void; 127 typedef ngx_http_request_body_t void;
128 </programlisting> 128 </programlisting>
129 129
130 Last but not least it is necessary to add definitions of two member structures: 130 Last but not least it is necessary to add definitions of two member structures
131 <literal>ngx_http_headers_in_t</literal> and 131 (<literal>ngx_http_headers_in_t</literal>,
132 <literal>ngx_http_headers_out_t</literal>, callback functions 132 <literal>ngx_http_headers_out_t</literal>),
133 declarations and constants definitions. 133 declarations of callback functions and definitions of constants.
134 </para> 134 </para>
135 135
136 <para> 136 <para>
137 Final DTrace script can be downloaded 137 The final DTrace script can be downloaded from
138 <link url="http://nginx.org/download/trace_process_request.d">here</link>. 138 <link url="http://nginx.org/download/trace_process_request.d">here</link>.
139 </para> 139 </para>
140 140
141 <para> 141 <para>
142 The example below shows the output of the DTrace script: 142 The following example shows the output of running this script:
143 143
144 <programlisting> 144 <programlisting>
145 # dtrace -C -I ./objs -s trace_process_request.d -p 4848 145 # dtrace -C -I ./objs -s trace_process_request.d -p 4848
146 dtrace: script 'trace_process_request.d' matched 1 probe 146 dtrace: script 'trace_process_request.d' matched 1 probe
147 CPU ID FUNCTION:NAME 147 CPU ID FUNCTION:NAME
153 </programlisting> 153 </programlisting>
154 154
155 </para> 155 </para>
156 156
157 <para>Using similar techniques the reader should be able to trace other 157 <para>Using similar techniques the reader should be able to trace other
158 nginx functions calls. 158 nginx function calls.
159 </para> 159 </para>
160 160
161 </section> 161 </section>
162 162
163 163