Mercurial > hg > nginx-site
comparison xml/en/docs/nginx_dtrace_pid_provider.xml @ 699:8205c2fcde2f
Fixed long lines, apostrophes used, etc.
author | Ruslan Ermilov <ru@nginx.com> |
---|---|
date | Wed, 03 Oct 2012 10:20:50 +0000 |
parents | 5182e655d055 |
children | 25584379a968 |
comparison
equal
deleted
inserted
replaced
698:5182e655d055 | 699:8205c2fcde2f |
---|---|
3 <!-- | 3 <!-- |
4 Copyright (C) Nginx, Inc. | 4 Copyright (C) Nginx, Inc. |
5 --> | 5 --> |
6 | 6 |
7 <!DOCTYPE article SYSTEM "../../../dtd/article.dtd"> | 7 <!DOCTYPE article SYSTEM "../../../dtd/article.dtd"> |
8 | |
9 | 8 |
10 <article name="Debugging nginx with DTrace pid provider" | 9 <article name="Debugging nginx with DTrace pid provider" |
11 link="/en/docs/nginx_dtrace_pid_provider.html" | 10 link="/en/docs/nginx_dtrace_pid_provider.html" |
12 lang="en" | 11 lang="en" |
13 rev="1" | 12 rev="1" |
14 toc="no"> | 13 toc="no"> |
15 | 14 |
16 <section> | 15 <section> |
17 | 16 |
18 <para> | 17 <para> |
19 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 |
20 <link id="see_also">DTrace</link>. | 19 <link id="see_also">DTrace</link>. |
21 </para> | 20 </para> |
22 | 21 |
23 <para> | 22 <para> |
24 Although nginx build with <link doc="debugging_log.xml">--with-debug</link> option | 23 Although nginx build with <link doc="debugging_log.xml">--with-debug</link> |
25 already provides a lot of information about request processing, it is sometimes desirable | 24 option already provides a lot of information about request processing, |
26 to trace particular parts of code path more thoroughly and at the same time | 25 it is sometimes desirable to trace particular parts of code path more |
27 omit the rest of debug output. DTrace pid provider (available on Solaris, OS X) is a useful | 26 thoroughly and at the same time omit the rest of debug output. |
28 tool to explore userland programs internals, since it doesn't require any code changes and | 27 DTrace pid provider (available on Solaris, OS X) is a useful tool to |
29 it can help with the task. E.g. a simple DTrace script to trace and print nginx | 28 explore userland programs internals, since it doesn’t require any code |
30 functions calls may look like: | 29 changes and it can help with the task. |
30 E.g. a simple DTrace script to trace and print nginx functions calls | |
31 may look like: | |
31 | 32 |
32 <programlisting> | 33 <programlisting> |
33 #pragma D option flowindent | 34 #pragma D option flowindent |
34 | 35 |
35 pid$target:nginx::entry { | 36 pid$target:nginx::entry { |
41 | 42 |
42 </para> | 43 </para> |
43 | 44 |
44 <para> | 45 <para> |
45 DTrace capabilities for function calls tracing provide only a limited amount | 46 DTrace capabilities for function calls tracing provide only a limited amount |
46 of useful information, though. Real-time inspection of function arguments | 47 of useful information, though. |
47 is typically more interesting, but also a bit more complicated. Examples below | 48 Real-time inspection of function arguments is typically more interesting, |
48 are intended to help the reader become more familiar with DTrace and the | 49 but also a bit more complicated. |
49 process of analyzing nginx behavior using DTrace. | 50 Examples below are intended to help the reader become more familiar with |
51 DTrace and the process of analyzing nginx behavior using DTrace. | |
50 </para> | 52 </para> |
51 | 53 |
52 <para> | 54 <para> |
53 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: |
54 attach to the nginx worker to log request lines and request start times. | 56 attach to the nginx worker to log request lines and request start times. |
62 pid$target::*ngx_http_process_request:entry | 64 pid$target::*ngx_http_process_request:entry |
63 { | 65 { |
64 this->request = (ngx_http_request_t *)copyin(arg0, sizeof(ngx_http_request_t)); | 66 this->request = (ngx_http_request_t *)copyin(arg0, sizeof(ngx_http_request_t)); |
65 this->request_line = stringof(copyin((uintptr_t)this->request->request_line.data, | 67 this->request_line = stringof(copyin((uintptr_t)this->request->request_line.data, |
66 this->request->request_line.len)); | 68 this->request->request_line.len)); |
67 printf("request line = %s\n", this->request_line); | 69 printf("request line = %s\n", this->request_line); |
68 printf("request start sec = %d\n", this->request->start_sec); | 70 printf("request start sec = %d\n", this->request->start_sec); |
69 } | 71 } |
70 | 72 |
71 </programlisting> | 73 </programlisting> |
72 </para> | 74 </para> |
73 | 75 |
74 <para> | 76 <para> |
75 It should be noted that in the example above DTrace requires some knowledge about | 77 It should be noted that in the example above DTrace requires some knowledge |
76 <literal>ngx_http_process_request</literal> structure. | 78 about <literal>ngx_http_process_request</literal> structure. |
77 Unfortunately while it is possible to use a specific <literal>#include</literal> | 79 Unfortunately while it is possible to use a specific <literal>#include</literal> |
78 directive in the DTrace script and then pass it to a C preprocessor | 80 directive in the DTrace script and then pass it to a C preprocessor |
79 (with -C flag), that doesn't really work. Due to a lot of cross dependencies almost | 81 (with -C flag), that doesn’t really work. |
80 all nginx header files have to be included. In turn, based on configure script | 82 Due to a lot of cross dependencies almost all nginx header files |
81 settings, nginx headers will include PCRE, OpenSSL and a variety of system header | 83 have to be included. |
82 files. While in theory all those header files related to a specific nginx build | 84 In turn, based on configure script settings, nginx headers will include PCRE, |
85 OpenSSL and a variety of system header files. | |
86 While in theory all those header files related to a specific nginx build | |
83 might be included in DTrace script preprocessing and compilation, in reality | 87 might be included in DTrace script preprocessing and compilation, in reality |
84 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 |
85 some header files. | 89 some header files. |
86 </para> | 90 </para> |
87 | 91 |
88 <para> | 92 <para> |
89 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 |
90 necessary structures and types definitions in the DTrace script. DTrace has to know | 94 necessary structures and types definitions in the DTrace script. |
91 sizes of structures, types, and fields offsets. Thus dependencies can be further | 95 DTrace has to know sizes of structures, types, and fields offsets. |
92 reduced by manually optimizing structure definitions for use with DTrace. | 96 Thus dependencies can be further reduced by manually optimizing |
97 structure definitions for use with DTrace. | |
93 </para> | 98 </para> |
94 | 99 |
95 <para> | 100 <para> |
96 Let's use DTrace script example above and see what structure definitions it needs | 101 Let’s use DTrace script example above and see what structure definitions |
97 to work properly. | 102 it needs to work properly. |
98 </para> | 103 </para> |
99 | 104 |
100 <para> | 105 <para> |
101 First of all <literal>objs/ngx_auto_config.h</literal> file generated by configure | 106 First of all <literal>objs/ngx_auto_config.h</literal> file generated by |
102 should be included, because it defines a number of constants affecting various | 107 configure should be included, because it defines a number of constants |
103 <literal>#ifdef's</literal>. After that there's some basic types and definitions | 108 affecting various <literal>#ifdef’s</literal>. |
109 After that there’s some basic types and definitions | |
104 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>, |
105 <literal>ngx_uint_t</literal> etc. should be put at the beginning of DTrace script. | 111 <literal>ngx_uint_t</literal> etc. should be put at the beginning of |
106 These definitions are compact, commonly used and unlikely to be frequently changed. | 112 DTrace script. |
113 These definitions are compact, commonly used and unlikely to be | |
114 frequently changed. | |
107 </para> | 115 </para> |
108 | 116 |
109 <para> | 117 <para> |
110 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 which |
111 contains a lot of pointers to other structures. Because these pointers are | 119 contains a lot of pointers to other structures. |
112 really irrelevant to this script, and because they have the same size, | 120 Because these pointers are really irrelevant to this script, and because they |
113 it is possible to just replace them with void pointers. Instead of changing | 121 have the same size, it is possible to just replace them with void pointers. |
114 definitions, it is better to add appropriate typedefs, though: | 122 Instead of changing definitions, it is better to add appropriate typedefs, |
123 though: | |
115 | 124 |
116 <programlisting> | 125 <programlisting> |
117 typedef ngx_http_upstream_t void; | 126 typedef ngx_http_upstream_t void; |
118 typedef ngx_http_request_body_t void; | 127 typedef ngx_http_request_body_t void; |
119 </programlisting> | 128 </programlisting> |
123 <literal>ngx_http_headers_out_t</literal>, callback functions | 132 <literal>ngx_http_headers_out_t</literal>, callback functions |
124 declarations and constants definitions. | 133 declarations and constants definitions. |
125 </para> | 134 </para> |
126 | 135 |
127 <para> | 136 <para> |
128 Final DTrace script can be downloaded | 137 Final DTrace script can be downloaded |
129 <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>. |
130 </para> | 139 </para> |
131 | 140 |
132 <para> | 141 <para> |
133 The example below shows the output of the DTrace script: | 142 The example below shows the output of the DTrace script: |
149 nginx functions calls. | 158 nginx functions calls. |
150 </para> | 159 </para> |
151 | 160 |
152 </section> | 161 </section> |
153 | 162 |
163 | |
154 <section id="see_also" | 164 <section id="see_also" |
155 name="See also"> | 165 name="See also"> |
156 | 166 |
157 <para> | 167 <para> |
158 <list type="bullet"> | 168 <list type="bullet"> |