msticpy.data.drivers.azure_monitor_driver module

Azure monitor/Log Analytics KQL Driver class.

See also

Azure, Azure, azure

class msticpy.data.drivers.azure_monitor_driver.AzureMonitorDriver(connection_str: str | None = None, **kwargs)

Bases: DriverBase

KqlDriver class to execute kql queries.

Instantiate KqlDriver and optionally connect.

Parameters:

  • connection_str (str, optional) – Connection string

  • debug (bool) – print out additional diagnostic information.

  • timeout (int (seconds)) – Specify a timeout for queries. Default is 300 seconds. (can be set here or in connect and overridden in query methods)

  • proxies (Dict[str, str]) – Proxy settings for log analytics queries. Dictionary format is {protocol: proxy_url} Where protocol is https, http, etc. and proxy_url can contain optional authentication information in the format “https://username:password@proxy_host:port” If you have a proxy configuration in msticpyconfig.yaml and you do not want to use it, set this to an empty dictionary. (can be overridden in connect method)

add_query_filter(name: str, query_filter: str | Iterable)

Add an expression to the query attach filter.

connect(connection_str: str | None = None, **kwargs)

Connect to data source.

Parameters:

  • connection_str (Union[str, WorkspaceConfig, None]) – Connection string or WorkspaceConfig for the Sentinel Workspace.

  • auth_types (Iterable [str]) – Authentication (credential) types to use. By default the values configured in msticpyconfig.yaml are used. If not set, it will use the msticpy defaults.

  • mp_az_auth (Union[bool, str, list, None], optional) – Deprecated parameter directing driver to use MSTICPy Azure authentication. Values can be: True or “default”: use the settings in msticpyconfig.yaml ‘Azure’ section str: single auth method name List[str]: list of acceptable auth methods from Use auth_types parameter instead.

  • tenant_id (str, optional) – Optional parameter specifying a Tenant ID for use by MSTICPy Azure authentication. By default, the tenant_id for the workspace.

  • workspace (str, optional) – Alternative to supplying a WorkspaceConfig object as the connection_str parameter. Giving a workspace name will fetch the workspace settings from msticpyconfig.yaml.

  • workspaces (Iterable[str], optional) – List of workspaces to run the queries against, each workspace name must have an entry in msticpyconfig.yaml

  • workspace_ids (Iterable[str], optional) – List of workspace IDs to run the queries against. Must be supplied along with a tenant_id.

  • timeout (int (seconds)) – Specify a timeout for queries. Default is 300 seconds. (can be overridden query method)

  • proxies (Dict[str, str]) – Proxy settings for log analytics queries. Dictionary format is {protocol: proxy_url} Where protocol is https, http, etc. and proxy_url can contain optional authentication information in the format “https://username:password@proxy_host:port” If you have a proxy configuration in msticpyconfig.yaml and you do not want to use it, set this to an empty dictionary.

Notes

When using the workspaces or workspace_ids parameters, some functionality will be reduced - e.g. no schema will be available for the workspaces. As an alternative to using multiple workspaces here you can create multiple workspace connections

property connected: bool

Return true if at least one connection has been made.

Returns:

True if a successful connection has been made.

Return type:

bool

Notes

This does not guarantee that the last data source connection was successful. It is a best effort to track whether the provider has made at least one successful authentication.

property current_connection: str

Return the current connection name.

property driver_queries: Iterable[Dict[str, Any]]

Return queries retrieved from the service after connecting.

Returns:

List of Dictionary of query_name, query_text. Name of container to add queries to.

Return type:

List[Dict[str, str]]

get_driver_property(name: str) → Any

Return value or KeyError from driver properties.

static get_http_timeout(**kwargs)

Get http timeout from settings or kwargs.

property instance: str | None

Return instance name, if one is set.

Returns:

The name of driver instance or None if the driver does not support multiple instances

Return type:

Optional[str]

property loaded: bool

Return true if the provider is loaded.

Returns:

True if the provider is loaded.

Return type:

bool

Notes

This is not relevant for some providers.

query(query: str, query_source: QuerySource | None = None, **kwargs) → DataFrame | Any

Execute query string and return DataFrame of results.

Parameters:

  • query (str) – The query to execute

  • query_source (Optional[QuerySource]) – The query definition object

  • timeout (int (seconds)) – Specify a timeout for the query. Default is 300 seconds.

  • fail_on_partial (bool) – Fail the query if only partial results are returned.

Returns:

A DataFrame (if successful) or the underlying provider result if an error.

Return type:

Union[pd.DataFrame, results.ResultSet]

property query_attach_spec: Dict[str, Set[str]]

Parameters that determine whether a query is relevant for the driver.

query_usable(query_source: QuerySource) → bool

Return True if query should be exposed for this driver.

query_with_results(query: str, **kwargs) → Tuple[DataFrame, Dict[str, Any]]

Execute query string and return DataFrame of results.

Parameters:

query (str) – The kql query to execute

Returns:

A DataFrame (if successful) and Query status dictionary.

Return type:

Tuple[pd.DataFrame, Dict[str, Any]]

property schema: Dict[str, Dict]

Return current data schema of connection.

Returns:

Data schema of current connection.

Return type:

Dict[str, Dict]

property service_queries: Tuple[Dict[str, str], str]

Return queries retrieved from the service after connecting.

Returns:

Dictionary of query_name, query_text. Name of container to add queries to.

Return type:

Tuple[Dict[str, str], str]

set_driver_property(name: str, value: Any)

Set an item in driver properties.

property url_endpoint: str

Return the current URL endpoint for Azure Monitor.