Edit File: plugin_trace.h
/* Copyright (c) 2012, 2023, Oracle and/or its affiliates. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License, version 2.0, as published by the Free Software Foundation. This program is also distributed with certain software (including but not limited to OpenSSL) that is licensed under separate terms, as designated in a particular file or component or in included license documentation. The authors of MySQL hereby grant you an additional permission to link the program and your derivative works with the separately licensed software that they have included with MySQL. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License, version 2.0, for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */ #ifndef PLUGIN_TRACE_INCLUDED #define PLUGIN_TRACE_INCLUDED /** @file ======================================================================== Declarations for client-side plugins of type MYSQL_CLIENT_TRACE_PLUGIN ======================================================================== See libmysql/mysql_trace.c for a brief description of the client-side protocol tracing infrastructure. */ #include <mysql/client_plugin.h> #ifdef __cplusplus extern "C" { #endif /* Lists of protocol stages and trace events ========================================= These lists are defined with PROTOCOL_STAGE_LIST() and TRACE_EVENT_LIST(), respectively. Macros accept a disposition name as an argument. For example, to process list of protocol stages using disposition "foo", define protocol_stage_foo(Stage) macro and then put PROTOCOL_STAGE_LIST(foo) in your code. This will expand to sequence of protocol_stage_foo(X) macros where X ranges over the list of protocol stages, and these macros should generate the actual code. See below how this technique is used to generate protocol_stage and trace_events enums. */ /** Protocol stages --------------- A client following the MySQL protocol goes through several stages of it. Each stage determines what packets can be expected from the server or can be send by the client. Upon receiving each trace event, trace plugin will be notified of the current protocol stage so that it can correctly interpret the event. These are the possible protocol stages and the transitions between them. .. digraph:: protocol_stages CONNECTING -> WAIT_FOR_INIT_PACKET; CONNECTING -> DISCONNECTED [ label = "failed connection" ]; WAIT_FOR_INIT_PACKET -> AUTHENTICATE; WAIT_FOR_INIT_PACKET -> SSL_NEGOTIATION -> AUTHENTICATE; AUTHENTICATE -> READY_FOR_COMMAND [ label = "accepted" ]; AUTHENTICATE -> DISCONNECTED [ label = "rejected" ]; READY_FOR_COMMAND -> DISCONNECTED [ label = "COM_QUIT" ]; READY_FOR_COMMAND -> AUTHENTICATE [ label="after change user" ]; READY_FOR_COMMAND -> WAIT_FOR_PACKET [ label="wait for a single packet after, e.g., COM_STATISTICS" ]; READY_FOR_COMMAND -> WAIT_FOR_RESULT; READY_FOR_COMMAND -> WAIT_FOR_PS_DESCRIPTION [ label="after prepare command" ]; WAIT_FOR_PACKET -> READY_FOR_COMAND; WAIT_FOR_RESULT -> READY_FOR_COMMAND [ label="simple reply" ]; WAIT_FOR_RESULT -> WAIT_FOR_FIELD_DEF; WAIT_FOR_RESULT -> FILE_REQUEST; WAIT_FOR_FIELD_DEF -> WAIT_FOR_ROW [ label="in a resultset" ]; WAIT_FOR_FIELD_DEF -> READY_FOR_COMMAND [ label="after describe table or prepare command" ]; WAIT_FOR_ROW -> READY_FOR_COMMAND; WAIT_FOR_ROW -> WAIT_FOR_RESULT [ label="multi-resultset" ]; WAIT_FOR_PS_DESCRIPTION -> WAIT_FOR_PARAM_DEF; WAIT_FOR_PS_DESCRIPTION -> READY_FOR_COMMAND [ label="no params and result" ]; WAIT_FOR_PS_DESCRIPTION -> WAIT_FOR_FIELD_DEF [ label="no params" ]; WAIT_FOR_PARAM_DEF -> WAIT_FOR_FIELD_DEF; WAIT_FOR_PARAM_DEF -> READY_FOR_COMMAND [ label="no result" ]; FILE_REQUEST -> WAIT_FOR_RESULT [label="when whole file sent"]; */ #define PROTOCOL_STAGE_LIST(X) \ protocol_stage_ ## X(CONNECTING) \ protocol_stage_ ## X(WAIT_FOR_INIT_PACKET) \ protocol_stage_ ## X(AUTHENTICATE) \ protocol_stage_ ## X(SSL_NEGOTIATION) \ protocol_stage_ ## X(READY_FOR_COMMAND) \ protocol_stage_ ## X(WAIT_FOR_PACKET) \ protocol_stage_ ## X(WAIT_FOR_RESULT) \ protocol_stage_ ## X(WAIT_FOR_FIELD_DEF) \ protocol_stage_ ## X(WAIT_FOR_ROW) \ protocol_stage_ ## X(FILE_REQUEST) \ protocol_stage_ ## X(WAIT_FOR_PS_DESCRIPTION) \ protocol_stage_ ## X(WAIT_FOR_PARAM_DEF) \ protocol_stage_ ## X(DISCONNECTED) /** Trace events ------------ The following events are generated during the various stages of the client-server conversation. ---------------------- ----------------------------------------------------- Connection events ---------------------- ----------------------------------------------------- CONNECTING Client is connecting to the server. CONNECTED Physical connection has been established. DISCONNECTED Connection with server was broken. ---------------------- ----------------------------------------------------- SSL events ---------------------- ----------------------------------------------------- SEND_SSL_REQUEST Client is sending SSL connection request. SSL_CONNECT Client is initiating SSL handshake. SSL_CONNECTED SSL connection has been established. ---------------------- ----------------------------------------------------- Authentication events ---------------------- ----------------------------------------------------- CHALLENGE_RECEIVED Client received authentication challenge. AUTH_PLUGIN Client selects an authentication plugin to be used in the following authentication exchange. SEND_AUTH_RESPONSE Client sends response to the authentication challenge. SEND_AUTH_DATA Client sends extra authentication data packet. AUTHENTICATED Server has accepted connection. ---------------------- ----------------------------------------------------- Command phase events ---------------------- ----------------------------------------------------- SEND_COMMAND Client is sending a command to the server. SEND_FILE Client is sending local file contents to the server. ---------------------- ----------------------------------------------------- General events ---------------------- ----------------------------------------------------- READ_PACKET Client starts waiting for a packet from server. PACKET_RECEIVED A packet from server has been received. PACKET_SENT After successful sending of a packet to the server. ERROR Client detected an error. ---------------------- ----------------------------------------------------- */ #define TRACE_EVENT_LIST(X) \ trace_event_ ## X(ERROR) \ trace_event_ ## X(CONNECTING) \ trace_event_ ## X(CONNECTED) \ trace_event_ ## X(DISCONNECTED) \ trace_event_ ## X(SEND_SSL_REQUEST) \ trace_event_ ## X(SSL_CONNECT) \ trace_event_ ## X(SSL_CONNECTED) \ trace_event_ ## X(INIT_PACKET_RECEIVED) \ trace_event_ ## X(AUTH_PLUGIN) \ trace_event_ ## X(SEND_AUTH_RESPONSE) \ trace_event_ ## X(SEND_AUTH_DATA) \ trace_event_ ## X(AUTHENTICATED) \ trace_event_ ## X(SEND_COMMAND) \ trace_event_ ## X(SEND_FILE) \ trace_event_ ## X(READ_PACKET) \ trace_event_ ## X(PACKET_RECEIVED) \ trace_event_ ## X(PACKET_SENT) /** Some trace events have additional arguments. These are stored in st_trace_event_args structure. Various events store their arguments in the structure as follows. Unused members are set to 0/NULL. AUTH_PLUGIN ------------- ---------------------------------- plugin_name the name of the plugin ------------- ---------------------------------- SEND_COMMAND ------------- ---------------------------------- cmd the command code hdr pointer to command packet header hdr_len length of the header pkt pointer to command arguments pkt_len length of arguments ------------- ---------------------------------- Other SEND_* and *_RECEIVED events ------------- ---------------------------------- pkt the data sent or received pkt_len length of the data ------------- ---------------------------------- PACKET_SENT ------------- ---------------------------------- pkt_len number of bytes sent ------------- ---------------------------------- */ struct st_trace_event_args { const char *plugin_name; int cmd; const unsigned char *hdr; size_t hdr_len; const unsigned char *pkt; size_t pkt_len; }; /* Definitions of protocol_stage and trace_event enums. */ #define protocol_stage_enum(X) PROTOCOL_STAGE_ ## X, enum protocol_stage { PROTOCOL_STAGE_LIST(enum) PROTOCOL_STAGE_LAST }; #define trace_event_enum(X) TRACE_EVENT_ ## X, enum trace_event { TRACE_EVENT_LIST(enum) TRACE_EVENT_LAST }; /* Trace plugin methods ==================== */ struct st_mysql_client_plugin_TRACE; struct st_mysql; /** Trace plugin tracing_start() method. Called when tracing with this plugin starts on a connection. A trace plugin might want to maintain per-connection information. It can return a pointer to memory area holding such information. It will be stored in a connection handle and passed to other plugin methods. @param self pointer to the plugin instance @param connection_handle @param stage protocol stage in which tracing has started - currently it is always CONNECTING stage. @return A pointer to plugin-specific, per-connection data if any. */ typedef void* (tracing_start_callback)(struct st_mysql_client_plugin_TRACE *self, struct st_mysql *connection_handle, enum protocol_stage stage); /** Trace plugin tracing_stop() method. Called when tracing of the connection has ended. If a plugin allocated any per-connection resources, it should de-allocate them here. @param self pointer to the plugin instance @param connection_handle @param plugin_data pointer to plugin's per-connection data. */ typedef void (tracing_stop_callback)(struct st_mysql_client_plugin_TRACE *self, struct st_mysql *connection_handle, void *plugin_data); /** Trace plugin trace_event() method. Called when a trace event occurs. Plugin can decide to stop tracing this connection by returning non-zero value. @param self pointer to the plugin instance @param plugin_data pointer to plugin's per-connection data @param connection_handle @param stage current protocol stage @param event the trace event @param args trace event arguments @return Non-zero if tracing of the connection should end here. */ typedef int (trace_event_handler)(struct st_mysql_client_plugin_TRACE *self, void *plugin_data, struct st_mysql *connection_handle, enum protocol_stage stage, enum trace_event event, struct st_trace_event_args args); struct st_mysql_client_plugin_TRACE { MYSQL_CLIENT_PLUGIN_HEADER tracing_start_callback *tracing_start; tracing_stop_callback *tracing_stop; trace_event_handler *trace_event; }; /** The global trace_plugin pointer. If it is not NULL, it points at a loaded trace plugin which should be used to trace all connections made to the server. */ extern struct st_mysql_client_plugin_TRACE *trace_plugin; #ifndef NDEBUG /* Functions for getting names of trace events and protocol stages for debugging purposes. */ const char* protocol_stage_name(enum protocol_stage stage); const char* trace_event_name(enum trace_event ev); #endif #ifdef __cplusplus } #endif #endif