Trace Class

Trace object for collecting diagnostic and performance related information from the Microsoft Analysis Services Tabular server.

Python wrapper around Microsoft Analysis Services Trace

NOTE: This feature is only intended for exploratory use. Due to the asynchronous communication required between the Microsoft Analysis Services (AS) Server and other AS clients, trace events are registered on a best-effort basis where timings are dependent on server load.

Inheritance

object

Trace

Constructor

Trace(server, event_schema: Dict[str, List[str]], name: str | None = None, filter_predicate: Callable[[...], bool] | None = None, stop_event: str | None = None)

Parameters

Name	Description
server Required	<xref:Microsoft.AnalysisServices.Tabular.Server> Server object to add trace to.
event_schema Required	dict Dictionary containing event types as keys and list of column names for that event as values. Both event and column names must be specified as strings, either in Space Delimited Case or PascalCase.
name	str Name identifying trace. If None, the trace name will be "SemanticLinkTrace_%GUID%". default value: None
filter_predicate	Callable Function that takes in TraceEventArgs and returns a boolean based on whether or not the trace with those args should be recorded. default value: None
stop_event	str Event class that signals the end of the trace. trace.stop() will wait for this event (with specified timeout) before returning logs. default value: None

Methods

add_event_handler	Add a custom handler for trace events.
add_events	Add events and their corresponding columns to the trace. The trace must be stopped in order to add events.
drop	Remove the current trace from its parent Server connection.
get_default_query_trace_schema	Get a default event schema for DAX Query Tracing. Default event classes: "QueryBegin", "QueryEnd", "VertiPaqSEQueryBegin", "VertiPaqSEQueryEnd", "VertiPaqSEQueryCacheMatch", "DirectQueryBegin", "DirectQueryEnd" Default event columns: "EventClass", "EventSubclass", "CurrentTime", "TextData", "SessionID", "StartTime", "EndTime", "Duration", "CpuTime", "Success"
get_trace_logs	Retrieve the trace logs as a DataFrame. This can be executed while the trace is still running.
set_filter	Set a custom filter predicate for event preprocessing.
start	Start the trace. Note: After starting the trace, there may be a slight delay as the engine registers and subscribes to trace events. The exact time of this delay may vary, but if you see that no trace events are being logged, you can increase the delay parameter.
stop	Stop the trace and retrieve the trace logs.

add_event_handler

Add a custom handler for trace events.

add_event_handler(on_event_func: Callable) -> None

Parameters

Name	Description
on_event_func Required	Callable Function to execute on every event.

add_events

Add events and their corresponding columns to the trace.

The trace must be stopped in order to add events.

add_events(event_schema: Dict[str, List[str]]) -> None

Parameters

Name	Description
event_schema Required	dict Dictionary containing event types as keys and list of column names for that event as values. Both event and column names must be specified as strings, either in Space Delimited Case or PascalCase.

drop

Remove the current trace from its parent Server connection.

drop() -> None

get_default_query_trace_schema

Get a default event schema for DAX Query Tracing.

Default event classes: "QueryBegin", "QueryEnd", "VertiPaqSEQueryBegin", "VertiPaqSEQueryEnd", "VertiPaqSEQueryCacheMatch", "DirectQueryBegin", "DirectQueryEnd" Default event columns: "EventClass", "EventSubclass", "CurrentTime", "TextData", "SessionID", "StartTime", "EndTime", "Duration", "CpuTime", "Success"

static get_default_query_trace_schema() -> Dict[str, List[str]]

Returns

Type	Description
dict	Dictionary containing event types as keys and list of column names for that event as values.

get_trace_logs

Retrieve the trace logs as a DataFrame.

This can be executed while the trace is still running.

get_trace_logs() -> DataFrame

Returns

Type	Description
DataFrame	DataFrame where every row is data from the events added to the trace.

set_filter

Set a custom filter predicate for event preprocessing.

set_filter(filter_predicate: Callable[[...], bool]) -> None

Parameters

Name	Description
filter_predicate Required	Callable Function that takes in TraceEventArgs, and returns a boolean based on whether or not the trace with those args should be recorded.

start

Start the trace.

Note: After starting the trace, there may be a slight delay as the engine registers and subscribes to trace events. The exact time of this delay may vary, but if you see that no trace events are being logged, you can increase the delay parameter.

start(delay: int = 3) -> None

Parameters

Name	Description
delay	int Number of seconds to sleep for after starting the trace to allow engine to subscribe to added trace events. default value: 3

stop

Stop the trace and retrieve the trace logs.

stop(timeout: int = 5) -> DataFrame

Parameters

Name	Description
timeout	int Number of seconds to wait for stop event (specified in constructor) to register. If stop event is not reached in this time frame, the collected trace logs will still be returned but may be incomplete. default value: 5

Returns

Type	Description
DataFrame	DataFrame where every row is data from the events added to the trace.

Attributes

is_started

Whether or not this trace is currently started.

name

Name of the trace.