Mercurial > hg > nginx-site

comparison xml/en/docs/nginx_dtrace_pid_provider.xml @ 699:8205c2fcde2f

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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">