Service Interface

This interface is provided to plugins/components, using which they can receive notifications related to statement lifetime events.

Event notifications are obtained by registering a set of function pointers (callbacks).

Each callback in a collection handles the single notification event:

• m_tel_session_create
  Telemetry session has been started. Telemetry session concept contains a single THD session executing statements with telemetry component installed (telemetry active). Telemetry session will be destroyed when a client session (or an internal session like worker thread) ends or when we detect that the telemetry component itself has been uninstalled/reinstalled.
• m_tel_session_destroy
  Telemetry session has been destroyed. Session callbacks can be used for bookkeeping the statements executing within the current session.
• m_tel_stmt_start
  This callback is called when the new statement has started. Function returns pointer to opaque telemetry_locker_t structure, used by the component itself to store the data needed to trace/filter the respective statement. Returning nullptr from this function will cause the tracing of this statement to be aborted, i.e. subsequent notification handlers (m_tel_stmt_notify_qa, m_tel_stmt_end) will not be called for this statement. The component itself is responsible for disposing of the memory used to store data for this statement, before returning the nullptr (in order to stop tracing the statement).
• m_tel_stmt_notify_qa
  This callback is called when the query attributes for the statement become available. This event is useful if the component that implements telemetry tracing uses filtering based on query attributes attached to each statement. Function returns pointer to opaque telemetry_locker_t structure, used by the component itself to store the data needed to trace/filter the respective statement. Returning nullptr from this function will cause the tracing of this statement to be aborted, i.e. subsequent notification handlers (m_tel_stmt_end) will not be called for this statement. The component itself is responsible for disposing of the memory used to store data for this statement, before returning the nullptr (in order to stop tracing the statement).
• m_tel_stmt_end
  This callback is called when the statement has ended. At this point, the component that implements the telemetry tracing will need to decide if to emit the telemetry for this statement or not. The component itself is responsible for disposing of the memory used to store data for this statement, before exiting this callback.
• m_tel_stmt_abort
  This callback is being called for a statement when we detect that the telemetry session has ended (such statement won't be emitted by the telemetry code). The component itself is responsible for disposing of the memory used to store data for this statement, before exiting this callback.

Note that, at any given time, there can be only one user of this service. There is no support for multiple collections of telemetry callbacks being registered at the same time.

Query Flow Diagram

Following flow diagram shows the execution of query statement with the matching sequence of telemetry notification callback calls being triggered.