Building Custom Listeners
To build custom listeners that work with the MariaDB Connector/Net Trace Source, it is necessary to understand the key methods used, and the event data formats used.
The main method involved in passing trace messages is the TraceSource.TraceEvent
method. This has the prototype:
public void TraceEvent( TraceEventType eventType, int id, string format, params Object[] args )
This trace source method will process the list of attached listeners and call the listener's TraceListener.TraceEvent method. The prototype for the TraceListener.TraceEvent
method is as follows:
public virtual void TraceEvent( TraceEventCache eventCache, string source, TraceEventType eventType, int id, string format, params Object[] args )
The first three parameters are used in the standard as defined by Microsoft. The last three parameters contain MySQL-specific trace information. Each of these parameters is now discussed in more detail.
int id
This is a MySQL-specific identifier. It identifies the MariaDB event type that has occurred, resulting in a trace message being generated. This value is defined by the MySqlTraceEventType
public enum contained in the MariaDB Connector/Net code:
public enum MySqlTraceEventType : int { ConnectionOpened = 1, ConnectionClosed, QueryOpened, ResultOpened, ResultClosed, QueryClosed, StatementPrepared, StatementExecuted, StatementClosed, NonQuery, UsageAdvisorWarning, Warning, Error }
The MariaDB event type also determines the contents passed using the parameter params Object[] args
. The nature of the args
parameters are described in further detail in the following material.
string format
This is the format string that contains zero or more format items, which correspond to objects in the args array. This would be used by a listener such as ConsoleTraceListener
to write a message to the output device.
params Object[] args
This is a list of objects that depends on the MariaDB event type, id
. However, the first parameter passed using this list is always the driver id. The driver id is a unique number that is incremented each time the connector is opened. This enables groups of queries on the same connection to be identified. The parameters that follow driver id depend of the MariaDB event id, and are as follows:
MySQL-specific event type | Arguments (params Object[] args) |
---|---|
ConnectionOpened | Connection string |
ConnectionClosed | No additional parameters |
QueryOpened | mysql server thread id, query text |
ResultOpened | field count, affected rows (-1 if select), inserted id (-1 if select) |
ResultClosed | total rows read, rows skipped, size of resultset in bytes |
QueryClosed | No additional parameters |
StatementPrepared | prepared sql, statement id |
StatementExecuted | statement id, mysql server thread id |
StatementClosed | statement id |
NonQuery | Varies |
UsageAdvisorWarning | usage advisor flag. NoIndex = 1, BadIndex = 2, SkippedRows = 3, SkippedColumns = 4, FieldConversion = 5. |
Warning | level, code, message |
Error | error number, error message |
This information will allow you to create custom trace listeners that can actively monitor the MySQL-specific events.