MySQL 8.2.0
Source Code Documentation
mysql_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 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
66struct 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
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
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:138
void mysql_trace_start(MYSQL *m)
Initialize tracing in a given connection.
Definition: mysql_trace.cc:85
Declarations for client-side plugins of type MYSQL_CLIENT_TRACE_PLUGIN.
trace_event
Definition: plugin_trace.h:229
protocol_stage
Definition: plugin_trace.h:225
Definition: mysql.h:299
Definition: plugin_trace.h:297
Some trace events have additional arguments.
Definition: plugin_trace.h:212