plugin_trace.h File Reference

Declarations for client-side plugins of type MYSQL_CLIENT_TRACE_PLUGIN. More...

#include <mysql/client_plugin.h>

Go to the source code of this file.

Classes
struct	st_trace_event_args
	Some trace events have additional arguments. More...
struct	st_mysql_client_plugin_TRACE

Macros
#define	PROTOCOL_STAGE_LIST(X)
#define	TRACE_EVENT_LIST(X)
#define	protocol_stage_enum(X)   PROTOCOL_STAGE_##X,
#define	trace_event_enum(X)   TRACE_EVENT_##X,

Typedefs
typedef void *()	tracing_start_callback(struct st_mysql_client_plugin_TRACE *self, MYSQL *connection_handle, enum protocol_stage stage)
	Trace plugin tracing_start() method. More...
typedef void()	tracing_stop_callback(struct st_mysql_client_plugin_TRACE *self, MYSQL *connection_handle, void *plugin_data)
	Trace plugin tracing_stop() method. More...
typedef 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. More...

Enumerations
enum	protocol_stage { PROTOCOL_STAGE_LIST =(enum) PROTOCOL_STAGE_LAST }
enum	trace_event { TRACE_EVENT_LIST =(enum) TRACE_EVENT_LAST }

Functions
const char *	protocol_stage_name (enum protocol_stage stage)
const char *	trace_event_name (enum trace_event ev)

Variables
struct st_mysql_client_plugin_TRACE *	trace_plugin
	The global trace_plugin pointer. More...

Detailed Description

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.

Macro Definition Documentation

protocol_stage_enum

#define protocol_stage_enum

(

X

)

PROTOCOL_STAGE_##X,

PROTOCOL_STAGE_LIST

#define PROTOCOL_STAGE_LIST

(

X

)

Value:

  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)

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"];

trace_event_enum

#define trace_event_enum

(

X

)

TRACE_EVENT_##X,

TRACE_EVENT_LIST

#define TRACE_EVENT_LIST

(

X

)

Value:

  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)

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.

---

Typedef Documentation

trace_event_handler

typedef 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.

Called when a trace event occurs. Plugin can decide to stop tracing this connection by returning non-zero value.

Parameters

self	pointer to the plugin instance
plugin_data	pointer to plugin's per-connection data
connection_handle	Session
stage	current protocol stage
event	the trace event
args	trace event arguments

Returns

Non-zero if tracing of the connection should end here.

tracing_start_callback

typedef void *() tracing_start_callback(struct st_mysql_client_plugin_TRACE *self, MYSQL *connection_handle, enum protocol_stage stage)

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.

Parameters

self	pointer to the plugin instance
connection_handle	Session
stage	protocol stage in which tracing has started - currently it is always CONNECTING stage.

Returns

A pointer to plugin-specific, per-connection data if any.

tracing_stop_callback

typedef void() tracing_stop_callback(struct st_mysql_client_plugin_TRACE *self, MYSQL *connection_handle, void *plugin_data)

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.

Parameters

self	pointer to the plugin instance
connection_handle	Session
plugin_data	pointer to plugin's per-connection data.

Enumeration Type Documentation

protocol_stage

enum protocol_stage

Enumerator
PROTOCOL_STAGE_LIST

trace_event

enum trace_event

Enumerator
TRACE_EVENT_LIST

Function Documentation

protocol_stage_name()

const char * protocol_stage_name

(

enum protocol_stage

stage

)

trace_event_name()

const char * trace_event_name

(

enum trace_event

ev

)

Variable Documentation

trace_plugin

struct st_mysql_client_plugin_TRACE* trace_plugin

extern

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.