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