.. _tracing-example:

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 :ref:`callback-example` 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 :func:`!IIapi_getCallbackPtr`
    and :func:`!IIapi_getClosure` helper 
    functions provided by ``pyngres``. They are not part of the 
    Actian OpenAPI.

..  TIP::

    Refer to the ``ctypes`` `documentation <https://docs.python.org/3/library/ctypes.html#callback-functions>`_ for additional explanation of callbacks.
    
:download:`Download <./examples/tracing.py>`

..  LITERALINCLUDE:: ./examples/tracing.py
    :linenos:

:download:`Download <./examples/tracing.py>`