Mercurial > hg > nginx-site
comparison xml/en/docs/nginx_dtrace_pid_provider.xml @ 708:25584379a968
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 |