Setting Up Tracing

Trace messages from the DBMS such as query execution plans (QEPs) or I/O traces arrive at unpredictable times. They need to be handled using callback functions. See Using Callbacks for more information.

Note

A trace -handling callback is installed in the OpenAPI environment. It is not session-specific. If multiple sessions are started by the application it is good to be aware of which session has enabled tracing and to avoid tracing multiple sessions at the same time.

Note

This example makes use of the IIapi_getCallbackPtr() and IIapi_getClosure() helper functions provided by pyngres. They are not part of the Actian OpenAPI.

Tip

Refer to the ctypes documentation for additional explanation of callbacks.

Download

import pyngres as py
from loguru import logger

# initialize the OpenAPI and note the envHandle for use later
inp = py.IIAPI_INITPARM()
inp.in_timeout = -1
inp.in_version = py.IIAPI_VERSION

py.IIapi_initialize(inp)
envHandle = inp.in_envHandle

...

# create iiapi_trace() as the callback for trace messages
@py.IIapi_callback
def iiapi_trace(trace_block,parmBlock=None):
    '''trace-message call-back'''

    # get the trace_block argument as a Python IIAPI_TRACEPARM instance
    trp = py.IIapi_getClosure(trace_block,py.IIAPI_TRACEPARM)
    # extract the tr_message member containing a line of trace info
    tr_message = trp.tr_message.decode().rstrip()
    # do something with the trace-message (in this example, send it to loguru)
    logger.info(tr_message)

...

# install iiapi_trace() as the callback to handle trace-messages
tracer = py.IIapi_getCallbackPtr(iiapi_trace)
sep = py.IIAPI_SETENVPRMPARM()
sep.se_envHandle = envHandle
sep.se_paramID = py.IIAPI_EP_TRACE_FUNC
sep.se_paramValue = tracer
py.IIapi_setEnvParam(sep)

Download