MySQL  8.0.23
Source Code Documentation
mysql_trace.h
Go to the documentation of this file.
1 /* Copyright (c) 2012, 2017, Oracle and/or its affiliates. All rights reserved.
2 
3  This program is free software; you can redistribute it and/or modify
4  it under the terms of the GNU General Public License, version 2.0,
5  as published by the Free Software Foundation.
6 
7  This program is also distributed with certain software (including
8  but not limited to OpenSSL) that is licensed under separate terms,
9  as designated in a particular file or component or in included license
10  documentation. The authors of MySQL hereby grant you an additional
11  permission to link the program and your derivative works with the
12  separately licensed software that they have included with MySQL.
13 
14  This program is distributed in the hope that it will be useful,
15  but WITHOUT ANY WARRANTY; without even the implied warranty of
16  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17  GNU General Public License, version 2.0, for more details.
18 
19  You should have received a copy of the GNU General Public License
20  along with this program; if not, write to the Free Software
21  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */
22 
23 #ifndef MYSQL_TRACE_INCLUDED
24 #define MYSQL_TRACE_INCLUDED
25 /**
26  @file
27 
28  =====================================================
29  Declarations for client-side tracing infrastructure
30  =====================================================
31 
32  See libmysql/mysql_trace.c for a brief description. Trace plugin
33  declarations are in plugin_trace.h header.
34 */
35 
36 #include <stddef.h>
37 
38 #include "my_macros.h"
39 
40 /*
41  Disable trace hooks if the infrastructure is not enabled
42 */
43 #if !defined(CLIENT_PROTOCOL_TRACING) || defined(MYSQL_SERVER)
44 
45 #define MYSQL_TRACE(E, M, ARGS)
46 #define MYSQL_TRACE_STAGE(M, S)
47 
48 #else
49 
50 #include <mysql/plugin_trace.h>
51 #include <stdarg.h>
52 
53 #include "sql_common.h" /* for MYSQL_EXTENSION() */
54 
55 /**
56  Per connection protocol tracing state
57 
58  For each connection which is traced an instance of this structure
59  is pointed by the trace_data member of MYSQL_EXTENSION structure
60  attached to that connection handle.
61 
62  If trace_data is NULL, for an initialized connection, then it means
63  that tracing in this connection is disabled.
64 */
65 
66 struct st_mysql_trace_info {
67  struct st_mysql_client_plugin_TRACE *plugin;
68  void *trace_plugin_data;
69  enum protocol_stage stage;
70 };
71 
72 #define TRACE_DATA(M) (MYSQL_EXTENSION_PTR(M)->trace_data)
73 
74 /*
75  See libmysql/mysql_trace.c for documentation and implementation of
76  these functions.
77 */
78 
80 void mysql_trace_start(MYSQL *);
81 
82 /**
83  The main protocol tracing hook.
84 
85  It is placed in places in the libmysql code where trace events occur.
86  If tracing of the connection is not disabled, it calls
87  mysql_trace_trace() function to report the event to the
88  trace plugin.
89 
90  @param E trace event (without TRACE_EVENT_ prefix)
91  @param M connection handle (pointer to MYSQL structure)
92  @param ARGS event specific arguments
93 
94  Event arguments are processed with appropriate TRACE_ARGS_* macro
95  (see below) to put them inside st_trace_event_args structure.
96 */
97 
98 #define MYSQL_TRACE(E, M, ARGS) \
99  do { \
100  if (NULL == TRACE_DATA(M)) break; \
101  { \
102  struct st_trace_event_args event_args = TRACE_ARGS_##E ARGS; \
103  mysql_trace_trace(M, TRACE_EVENT_##E, event_args); \
104  } \
105  } while (0)
106 
107 /**
108  A hook to set the current protocol stage.
109 
110  @param M connection handle (pointer to MYSQL structure)
111  @param S the current stage (without PROTOCOL_STAGE_ prefix)
112 
113  If tracing is not disabled, the stage is stored in connection's
114  tracing state. A special case is if the current stage is the
115  initial CONNECTING one. In that case function mysql_trace_start()
116  is called to initialize tracing in this connection, provided that
117  a trace plugin is loaded.
118 */
119 
120 #define MYSQL_TRACE_STAGE(M, S) \
121  do { \
122  if (TRACE_DATA(M)) \
123  TRACE_DATA(M)->stage = PROTOCOL_STAGE_##S; \
124  else if (trace_plugin && \
125  (PROTOCOL_STAGE_CONNECTING == PROTOCOL_STAGE_##S)) \
126  mysql_trace_start(M); \
127  } while (0)
128 
129 /*
130  Macros to parse event arguments and initialize the
131  st_trace_event_args structure accordingly. See description of
132  the structure in plugin_trace.h.
133 */
134 
135 #define TRACE_ARGS_SEND_SSL_REQUEST(Size, Packet) \
136  { NULL, 0, NULL, 0, Packet, Size }
137 #define TRACE_ARGS_SEND_AUTH_RESPONSE(Size, Packet) \
138  { NULL, 0, NULL, 0, Packet, Size }
139 #define TRACE_ARGS_SEND_AUTH_DATA(Size, Packet) \
140  { NULL, 0, NULL, 0, Packet, Size }
141 #define TRACE_ARGS_AUTH_PLUGIN(PluginName) \
142  { PluginName, 0, NULL, 0, NULL, 0 }
143 #define TRACE_ARGS_SEND_COMMAND(Command, HdrSize, ArgSize, Header, Args) \
144  { NULL, Command, Header, HdrSize, Args, ArgSize }
145 #define TRACE_ARGS_SEND_FILE(Size, Packet) \
146  { NULL, 0, NULL, 0, Packet, Size }
147 
148 #define TRACE_ARGS_PACKET_SENT(Size) \
149  { NULL, 0, NULL, 0, NULL, Size }
150 #define TRACE_ARGS_PACKET_RECEIVED(Size, Packet) \
151  { NULL, 0, NULL, 0, Packet, Size }
152 #define TRACE_ARGS_INIT_PACKET_RECEIVED(Size, Packet) \
153  { NULL, 0, NULL, 0, Packet, Size }
154 
155 #define TRACE_ARGS_ERROR() \
156  { NULL, 0, NULL, 0, NULL, 0 }
157 #define TRACE_ARGS_READ_PACKET() \
158  { NULL, 0, NULL, 0, NULL, 0 }
159 #define TRACE_ARGS_CONNECTING() \
160  { NULL, 0, NULL, 0, NULL, 0 }
161 #define TRACE_ARGS_CONNECTED() \
162  { NULL, 0, NULL, 0, NULL, 0 }
163 #define TRACE_ARGS_DISCONNECTED() \
164  { NULL, 0, NULL, 0, NULL, 0 }
165 #define TRACE_ARGS_AUTHENTICATED() \
166  { NULL, 0, NULL, 0, NULL, 0 }
167 #define TRACE_ARGS_SSL_CONNECT() \
168  { NULL, 0, NULL, 0, NULL, 0 }
169 #define TRACE_ARGS_SSL_CONNECTED() \
170  { NULL, 0, NULL, 0, NULL, 0 }
171 
172 #endif /* !defined(CLIENT_PROTOCOL_TRACING) || defined(MYSQL_SERVER) */
173 
174 #endif
trace_event
trace_event
Definition: plugin_trace.h:229
sql_common.h
mysql_trace_start
void mysql_trace_start(MYSQL *m)
Initialize tracing in a given connection.
Definition: mysql_trace.cc:84
plugin_trace.h
st_trace_event_args
Some trace events have additional arguments.
Definition: plugin_trace.h:212
st_mysql_client_plugin_TRACE
Definition: plugin_trace.h:297
mysql_trace_trace
void mysql_trace_trace(MYSQL *m, enum trace_event ev, struct st_trace_event_args args)
Report a protocol trace event to trace plugin.
Definition: mysql_trace.cc:137
MYSQL
Definition: mysql.h:296
protocol_stage
protocol_stage
Definition: plugin_trace.h:225
my_macros.h