libxesession

SQL Server Extended Events session driver + ring-buffer XML parser. Builds the CREATE EVENT SESSION DDL, polls the ring_buffer target, turns the payload into typed events.

Maintained by Tirion. Used by Calliper. MIT, zero deps.

Status

1.0. Stable API.

What it does

Three things every SQL Server XEvent tool ends up rewriting:

1. The CREATE EVENT SESSION DDL (with the ADD EVENT list, ring_buffer target sizing, dispatch latency).
2. The poll loop reading sys.dm_xe_session_targets.target_data and tracking totalEventsProcessed for dedup.
3. The XML parser. <data> vs <action>, numeric character refs, CDATA-wrapped showplan, per-event-type column dispatch.

Supported events

• sp_statement_completed
• sql_batch_completed
• rpc_completed
• query_post_execution_showplan
• sqlos.wait_info (filtered by duration)

XeSessionOptions toggles events on/off and tunes the ring buffer plus dispatch latency.

Usage

#include <xesession/xesession.hpp>

class MyConn : public xesession::IConn {
public:
    explicit MyConn(MyOdbcWrapper& c) : conn_(c) {}
    void exec(const std::string& sql) override { conn_.exec(sql); }
    std::string exec_scalar_text(const std::string& sql) override {
        return conn_.exec_scalar_text(sql);
    }
private:
    MyOdbcWrapper& conn_;
};

MyConn ax{my_odbc};
xesession::XeSession session{ax};
session.start();

while (running) {
    auto events = session.poll();
    for (const auto& e : events) {
        if (e.name == "sp_statement_completed") {
            log("stmt {} ms, {} reads, in {}",
                e.duration_us / 1000, e.logical_reads, e.object_name);
        }
    }
    std::this_thread::sleep_for(std::chrono::seconds(2));
}
session.stop();

Building

cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build
ctest --test-dir build

CMake integration:

add_subdirectory(path/to/libxesession)
target_link_libraries(my_app PRIVATE xesession::xesession)

API

All in include/xesession/xesession.hpp:

Type	Purpose
xesession::IConn	Abstract host-provided connection (two methods).
xesession::XeEvent	One parsed event.
xesession::XeSessionOptions	Session knobs.
xesession::XeSession	RAII session + poll loop.
xesession::parse_ring_buffer_xml(xml)	Free function. Test + offline replay.
xesession::parse_ring_buffer_total_processed(xml)	Free function. Dedup high-water mark.

What it doesn't do

• Drive the connection. Bring your own.
• File-target captures (.xel). Ring buffer only.
• Predicate DSL.
• History beyond one XeSession lifetime.

License

MIT. Issues at github.com/tirion-tools/libxesession.