MySQL 8.3.0
Source Code Documentation
plugin_trace.h
Go to the documentation of this file.
1/* Copyright (c) 2012, 2023, Oracle and/or its affiliates.
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 PLUGIN_TRACE_INCLUDED
24#define PLUGIN_TRACE_INCLUDED
25/**
26 @file include/mysql/plugin_trace.h
27
28 Declarations for client-side plugins of type MYSQL_CLIENT_TRACE_PLUGIN.
29
30 See libmysql/mysql_trace.c for a brief description of the client-side
31 protocol tracing infrastructure.
32*/
33
34#include <mysql/client_plugin.h>
35
36/*
37 Lists of protocol stages and trace events
38 =========================================
39
40 These lists are defined with PROTOCOL_STAGE_LIST() and TRACE_EVENT_LIST(),
41 respectively. Macros accept a disposition name as an argument.
42
43 For example, to process list of protocol stages using disposition "foo",
44 define protocol_stage_foo(Stage) macro and then put
45
46 PROTOCOL_STAGE_LIST(foo)
47
48 in your code. This will expand to sequence of protocol_stage_foo(X)
49 macros where X ranges over the list of protocol stages, and these macros
50 should generate the actual code. See below how this technique is used
51 to generate protocol_stage and trace_events enums.
52*/
53
54/**
55 Protocol stages
56 ---------------
57
58 A client following the MySQL protocol goes through several stages of it. Each
59 stage determines what packets can be expected from the server or can be send
60 by the client.
61
62 Upon receiving each trace event, trace plugin will be notified of the current
63 protocol stage so that it can correctly interpret the event.
64
65 These are the possible protocol stages and the transitions between them.
66
67 .. digraph:: protocol_stages
68
69 CONNECTING -> WAIT_FOR_INIT_PACKET;
70 CONNECTING -> DISCONNECTED [ label = "failed connection" ];
71
72 WAIT_FOR_INIT_PACKET -> AUTHENTICATE;
73 WAIT_FOR_INIT_PACKET -> SSL_NEGOTIATION -> AUTHENTICATE;
74
75 AUTHENTICATE -> READY_FOR_COMMAND [ label = "accepted" ];
76 AUTHENTICATE -> DISCONNECTED [ label = "rejected" ];
77
78 READY_FOR_COMMAND -> DISCONNECTED [ label = "COM_QUIT" ];
79 READY_FOR_COMMAND -> AUTHENTICATE [ label="after change user" ];
80 READY_FOR_COMMAND -> WAIT_FOR_PACKET
81 [ label="wait for a single packet after, e.g., COM_STATISTICS" ];
82 READY_FOR_COMMAND -> WAIT_FOR_RESULT;
83 READY_FOR_COMMAND -> WAIT_FOR_PS_DESCRIPTION
84 [ label="after prepare command" ];
85
86 WAIT_FOR_PACKET -> READY_FOR_COMAND;
87
88 WAIT_FOR_RESULT -> READY_FOR_COMMAND [ label="simple reply" ];
89 WAIT_FOR_RESULT -> WAIT_FOR_FIELD_DEF;
90 WAIT_FOR_RESULT -> FILE_REQUEST;
91
92 WAIT_FOR_FIELD_DEF -> WAIT_FOR_ROW [ label="in a resultset" ];
93 WAIT_FOR_FIELD_DEF -> READY_FOR_COMMAND
94 [ label="after describe table or prepare command" ];
95
96 WAIT_FOR_ROW -> READY_FOR_COMMAND;
97 WAIT_FOR_ROW -> WAIT_FOR_RESULT [ label="multi-resultset" ];
98
99 WAIT_FOR_PS_DESCRIPTION -> WAIT_FOR_PARAM_DEF;
100 WAIT_FOR_PS_DESCRIPTION -> READY_FOR_COMMAND
101 [ label="no params and result" ];
102 WAIT_FOR_PS_DESCRIPTION -> WAIT_FOR_FIELD_DEF [ label="no params" ];
103
104 WAIT_FOR_PARAM_DEF -> WAIT_FOR_FIELD_DEF;
105 WAIT_FOR_PARAM_DEF -> READY_FOR_COMMAND [ label="no result" ];
106
107 FILE_REQUEST -> WAIT_FOR_RESULT [label="when whole file sent"];
108*/
109
110#define PROTOCOL_STAGE_LIST(X) \
111 protocol_stage_##X(CONNECTING) protocol_stage_##X(WAIT_FOR_INIT_PACKET) \
112 protocol_stage_##X(AUTHENTICATE) protocol_stage_##X(SSL_NEGOTIATION) \
113 protocol_stage_##X(READY_FOR_COMMAND) \
114 protocol_stage_##X(WAIT_FOR_PACKET) \
115 protocol_stage_##X(WAIT_FOR_RESULT) \
116 protocol_stage_##X(WAIT_FOR_FIELD_DEF) \
117 protocol_stage_##X(WAIT_FOR_ROW) \
118 protocol_stage_##X(FILE_REQUEST) \
119 protocol_stage_##X(WAIT_FOR_PS_DESCRIPTION) \
120 protocol_stage_##X(WAIT_FOR_PARAM_DEF) \
121 protocol_stage_##X(DISCONNECTED)
122
123/**
124 Trace events
125 ------------
126
127 The following events are generated during the various stages of the
128 client-server conversation.
129
130 ---------------------- -----------------------------------------------------
131 Connection events
132 ---------------------- -----------------------------------------------------
133 CONNECTING Client is connecting to the server.
134 CONNECTED Physical connection has been established.
135 DISCONNECTED Connection with server was broken.
136 ---------------------- -----------------------------------------------------
137 SSL events
138 ---------------------- -----------------------------------------------------
139 SEND_SSL_REQUEST Client is sending SSL connection request.
140 SSL_CONNECT Client is initiating SSL handshake.
141 SSL_CONNECTED SSL connection has been established.
142 ---------------------- -----------------------------------------------------
143 Authentication events
144 ---------------------- -----------------------------------------------------
145 CHALLENGE_RECEIVED Client received authentication challenge.
146 AUTH_PLUGIN Client selects an authentication plugin to be used
147 in the following authentication exchange.
148 SEND_AUTH_RESPONSE Client sends response to the authentication
149 challenge.
150 SEND_AUTH_DATA Client sends extra authentication data packet.
151 AUTHENTICATED Server has accepted connection.
152 ---------------------- -----------------------------------------------------
153 Command phase events
154 ---------------------- -----------------------------------------------------
155 SEND_COMMAND Client is sending a command to the server.
156 SEND_FILE Client is sending local file contents to the server.
157 ---------------------- -----------------------------------------------------
158 General events
159 ---------------------- -----------------------------------------------------
160 READ_PACKET Client starts waiting for a packet from server.
161 PACKET_RECEIVED A packet from server has been received.
162 PACKET_SENT After successful sending of a packet to the server.
163 ERROR Client detected an error.
164 ---------------------- -----------------------------------------------------
165*/
166
167#define TRACE_EVENT_LIST(X) \
168 trace_event_##X(ERROR) trace_event_##X(CONNECTING) trace_event_##X( \
169 CONNECTED) trace_event_##X(DISCONNECTED) \
170 trace_event_##X(SEND_SSL_REQUEST) trace_event_##X(SSL_CONNECT) \
171 trace_event_##X(SSL_CONNECTED) trace_event_##X(INIT_PACKET_RECEIVED) \
172 trace_event_##X(AUTH_PLUGIN) trace_event_##X(SEND_AUTH_RESPONSE) \
173 trace_event_##X(SEND_AUTH_DATA) \
174 trace_event_##X(AUTHENTICATED) \
175 trace_event_##X(SEND_COMMAND) \
176 trace_event_##X(SEND_FILE) \
177 trace_event_##X(READ_PACKET) \
178 trace_event_##X(PACKET_RECEIVED) \
179 trace_event_##X(PACKET_SENT)
180
181/**
182 Some trace events have additional arguments. These are stored in
183 st_trace_event_args structure. Various events store their arguments in the
184 structure as follows. Unused members are set to 0/NULL.
185
186 AUTH_PLUGIN
187 ------------- ----------------------------------
188 plugin_name the name of the plugin
189 ------------- ----------------------------------
190
191 SEND_COMMAND
192 ------------- ----------------------------------
193 cmd the command code
194 hdr pointer to command packet header
195 hdr_len length of the header
196 pkt pointer to command arguments
197 pkt_len length of arguments
198 ------------- ----------------------------------
199
200 Other SEND_* and *_RECEIVED events
201 ------------- ----------------------------------
202 pkt the data sent or received
203 pkt_len length of the data
204 ------------- ----------------------------------
205
206 PACKET_SENT
207 ------------- ----------------------------------
208 pkt_len number of bytes sent
209 ------------- ----------------------------------
210*/
211
213 const char *plugin_name;
214 int cmd;
215 const unsigned char *hdr;
216 size_t hdr_len;
217 const unsigned char *pkt;
218 size_t pkt_len;
219};
220
221/* Definitions of protocol_stage and trace_event enums. */
222
223#define protocol_stage_enum(X) PROTOCOL_STAGE_##X,
224
225enum protocol_stage { PROTOCOL_STAGE_LIST(enum) PROTOCOL_STAGE_LAST };
226
227#define trace_event_enum(X) TRACE_EVENT_##X,
228
229enum trace_event { TRACE_EVENT_LIST(enum) TRACE_EVENT_LAST };
230
231/*
232 Trace plugin methods
233 ====================
234*/
235
237struct MYSQL;
238
239/**
240 Trace plugin tracing_start() method.
241
242 Called when tracing with this plugin starts on a connection. A trace
243 plugin might want to maintain per-connection information. It can
244 return a pointer to memory area holding such information. It will be
245 stored in a connection handle and passed to other plugin methods.
246
247 @param self pointer to the plugin instance
248 @param connection_handle Session
249 @param stage protocol stage in which tracing has started - currently
250 it is always CONNECTING stage.
251
252 @return A pointer to plugin-specific, per-connection data if any.
253*/
254
256 struct st_mysql_client_plugin_TRACE *self, MYSQL *connection_handle,
257 enum protocol_stage stage);
258
259/**
260 Trace plugin tracing_stop() method.
261
262 Called when tracing of the connection has ended. If a plugin
263 allocated any per-connection resources, it should de-allocate them
264 here.
265
266 @param self pointer to the plugin instance
267 @param connection_handle Session
268 @param plugin_data pointer to plugin's per-connection data.
269*/
270
272 MYSQL *connection_handle,
273 void *plugin_data);
274
275/**
276 Trace plugin trace_event() method.
277
278 Called when a trace event occurs. Plugin can decide to stop tracing
279 this connection by returning non-zero value.
280
281 @param self pointer to the plugin instance
282 @param plugin_data pointer to plugin's per-connection data
283 @param connection_handle Session
284 @param stage current protocol stage
285 @param event the trace event
286 @param args trace event arguments
287
288 @return Non-zero if tracing of the connection should end here.
289*/
290
292 void *plugin_data, MYSQL *connection_handle,
293 enum protocol_stage stage,
294 enum trace_event event,
295 struct st_trace_event_args args);
296
302};
303
304/**
305 The global trace_plugin pointer. If it is not NULL, it points at a
306 loaded trace plugin which should be used to trace all connections made
307 to the server.
308*/
310
311#ifndef NDEBUG
312
313/*
314 Functions for getting names of trace events and protocol
315 stages for debugging purposes.
316*/
317const char *protocol_stage_name(enum protocol_stage stage);
318const char *trace_event_name(enum trace_event ev);
319
320#endif
321
322#endif
MySQL Client Plugin API.
#define MYSQL_CLIENT_PLUGIN_HEADER
Definition: client_plugin.h:99
int() trace_event_handler(struct st_mysql_client_plugin_TRACE *self, void *plugin_data, MYSQL *connection_handle, enum protocol_stage stage, enum trace_event event, struct st_trace_event_args args)
Trace plugin trace_event() method.
Definition: plugin_trace.h:291
struct st_mysql_client_plugin_TRACE * trace_plugin
The global trace_plugin pointer.
Definition: mysql_trace.cc:68
const char * trace_event_name(enum trace_event ev)
Definition: mysql_trace.cc:208
#define TRACE_EVENT_LIST(X)
Definition: plugin_trace.h:167
const char * protocol_stage_name(enum protocol_stage stage)
Definition: mysql_trace.cc:196
trace_event
Definition: plugin_trace.h:229
protocol_stage
Definition: plugin_trace.h:225
void *() tracing_start_callback(struct st_mysql_client_plugin_TRACE *self, MYSQL *connection_handle, enum protocol_stage stage)
Trace plugin tracing_start() method.
Definition: plugin_trace.h:255
void() tracing_stop_callback(struct st_mysql_client_plugin_TRACE *self, MYSQL *connection_handle, void *plugin_data)
Trace plugin tracing_stop() method.
Definition: plugin_trace.h:271
#define PROTOCOL_STAGE_LIST(X)
Definition: plugin_trace.h:110
required string event
Definition: replication_group_member_actions.proto:31
T plugin_data(st_plugin_int **ref)
Definition: sql_plugin_ref.h:91
Definition: mysql.h:297
Definition: plugin_trace.h:297
tracing_stop_callback * tracing_stop
Definition: plugin_trace.h:300
trace_event_handler * trace_event
Definition: plugin_trace.h:301
MYSQL_CLIENT_PLUGIN_HEADER tracing_start_callback * tracing_start
Definition: plugin_trace.h:299
Some trace events have additional arguments.
Definition: plugin_trace.h:212
const unsigned char * hdr
Definition: plugin_trace.h:215
size_t hdr_len
Definition: plugin_trace.h:216
const unsigned char * pkt
Definition: plugin_trace.h:217
int cmd
Definition: plugin_trace.h:214
size_t pkt_len
Definition: plugin_trace.h:218
const char * plugin_name
Definition: plugin_trace.h:213