Package: azure-monitor-query
Azure Monitor Query client library for PythonThe Azure Monitor Query client library is used to execute read-only queries againstAzure Monitor's two data platforms:Logs- Collects and organizes log and performance data from monitored resources. Data from different sources such as platform logs from Azure services, log and performance data from virtual machines agents, and usage and performance data from apps can be consolidated into a singleAzure Log Analytics workspace. The various data types can be analyzed together using theKusto Query Language.Metrics- Collects numeric data from monitored resources into a time series database. Metrics are numerical values that are collected at regular intervals and describe some aspect of a system at a particular time. Metrics are lightweight and capable of supporting near real-time scenarios, making them useful for alerting and fast detection of issues.Resources:Source codePackage (PyPI)Package (Conda)API reference documentationService documentationSamplesChange logGetting startedPrerequisitesPython 3.7 or laterAnAzure subscriptionATokenCredentialimplementation, such as anAzure Identity library credential type.To query Logs, you need one of the following things:AnAzure Log Analytics workspaceAn Azure resource of any kind (Storage Account, Key Vault, Cosmos DB, etc.)To query Metrics, you need an Azure resource of any kind (Storage Account, Key Vault, Cosmos DB, etc.).Install the packageInstall the Azure Monitor Query client library for Python withpip:pipinstallazure-monitor-queryCreate the clientAn authenticated client is required to query Logs or Metrics. The library includes both synchronous and asynchronous forms of the clients. To authenticate, create an instance of a token credential. Use that instance when creating aLogsQueryClientorMetricsQueryClient. The following examples useDefaultAzureCredentialfrom theazure-identitypackage.Synchronous clientsConsider the following example, which creates synchronous clients for both Logs and Metrics querying:fromazure.identityimportDefaultAzureCredentialfromazure.monitor.queryimportLogsQueryClient,MetricsQueryClientcredential=DefaultAzureCredential()logs_client=LogsQueryClient(credential)metrics_client=MetricsQueryClient(credential)Asynchronous clientsThe asynchronous forms of the query client APIs are found in the.aio-suffixed namespace. For example:fromazure.identity.aioimportDefaultAzureCredentialfromazure.monitor.query.aioimportLogsQueryClient,MetricsQueryClientcredential=DefaultAzureCredential()async_logs_client=LogsQueryClient(credential)async_metrics_client=MetricsQueryClient(credential)Configure clients for non-public Azure cloudsBy default,LogsQueryClientandMetricsQueryClientare configured to connect to the public Azure cloud. These can be configured to connect to non-public Azure clouds by passing in the correctendpointargument: For example:logs_client=LogsQueryClient(credential,endpoint="https://api.loganalytics.azure.cn/v1")metrics_client=MetricsQueryClient(credential,endpoint="https://management.chinacloudapi.cn")Note: Currently,MetricsQueryClientuses the Azure Resource Manager (ARM) endpoint for querying metrics, so you will need the corresponding management endpoint for your cloud when using this client. This is subject to change in the future.Execute the queryFor examples of Logs and Metrics queries, see theExamplessection.Key conceptsLogs query rate limits and throttlingThe Log Analytics service applies throttling when the request rate is too high. Limits, such as the maximum number of rows returned, are also applied on the Kusto queries. For more information, seeQuery API.If you're executing a batch logs query, a throttled request will return aLogsQueryErrorobject. That object'scodevalue will beThrottledError.Metrics data structureEach set of metric values is a time series with the following characteristics:The time the value was collectedThe resource associated with the valueA namespace that acts like a category for the metricA metric nameThe value itselfSome metrics may have multiple dimensions as described in multi-dimensional metrics. Custom metrics can have up to 10 dimensions.ExamplesLogs querySpecify timespanHandle logs query responseBatch logs queryResource logs queryAdvanced logs query scenariosSet logs query timeoutQuery multiple workspacesInclude statisticsInclude visualizationMetrics queryHandle metrics query responseExample of handling responseLogs queryThis example shows how to query a Log Analytics workspace. To handle the response and view it in a tabular form, thepandaslibrary is used. See thesamplesif you choose not to usepandas.Specify timespanThetimespanparameter specifies the time duration for which to query the data. This value can be one of the following:atimedeltaatimedeltaand a startdatetimea startdatetime/enddatetimeFor example:importosimportpandasaspdfromdatetimeimportdatetime,timezonefromazure.monitor.queryimportLogsQueryClient,LogsQueryStatusfromazure.identityimportDefaultAzureCredentialfromazure.core.exceptionsimportHttpResponseErrorcredential=DefaultAzureCredential()client=LogsQueryClient(credential)query="""AppRequests | take 5"""start_time=datetime(2021,7,2,tzinfo=timezone.utc)end_time=datetime(2021,7,4,tzinfo=timezone.utc)try:response=client.query_workspace(workspace_id=os.environ['LOG_WORKSPACE_ID'],query=query,timespan=(start_time,end_time))ifresponse.status==LogsQueryStatus.PARTIAL:error=response.partial_errordata=response.partial_dataprint(error)elifresponse.status==LogsQueryStatus.SUCCESS:data=response.tablesfortableindata:df=pd.DataFrame(data=table.rows,columns=table.columns)print(df)exceptHttpResponseErroraserr:print("something fatal happened")print(err)Handle logs query responseThequery_workspaceAPI returns either aLogsQueryResultor aLogsQueryPartialResultobject. Thebatch_queryAPI returns a list that may containLogsQueryResult,LogsQueryPartialResult, andLogsQueryErrorobjects. Here's a hierarchy of the response:LogsQueryResult
|---statistics
|---visualization
|---tables (list of `LogsTable` objects)
    |---name
    |---rows
    |---columns
    |---columns_types

LogsQueryPartialResult
|---statistics
|---visualization
|---partial_error (a `LogsQueryError` object)
    |---code
    |---message
    |---details
    |---status
|---partial_data (list of `LogsTable` objects)
    |---name
    |---rows
    |---columns
    |---columns_typesTheLogsQueryResultdirectly iterates over the table as a convenience. For example, to handle a logs query response with tables and display it usingpandas:response=client.query(...)fortableinresponse:df=pd.DataFrame(table.rows,columns=[col.nameforcolintable.columns])A full sample can be foundhere.In a similar fashion, to handle a batch logs query response:forresultinresponse:ifresult.status==LogsQueryStatus.SUCCESS:fortableinresult:df=pd.DataFrame(table.rows,columns=table.columns)print(df)A full sample can be foundhere.Batch logs queryThe following example demonstrates sending multiple queries at the same time using the batch query API. The queries can either be represented as a list ofLogsBatchQueryobjects or a dictionary. This example uses the former approach.importosfromdatetimeimporttimedelta,datetime,timezoneimportpandasaspdfromazure.monitor.queryimportLogsQueryClient,LogsBatchQuery,LogsQueryStatusfromazure.identityimportDefaultAzureCredentialcredential=DefaultAzureCredential()client=LogsQueryClient(credential)requests=[LogsBatchQuery(query="AzureActivity | summarize count()",timespan=timedelta(hours=1),workspace_id=os.environ['LOG_WORKSPACE_ID']),LogsBatchQuery(query="""bad query""",timespan=timedelta(days=1),workspace_id=os.environ['LOG_WORKSPACE_ID']),LogsBatchQuery(query="""let Weight = 92233720368547758;range x from 1 to 3 step 1| summarize percentilesw(x, Weight * 100, 50)""",workspace_id=os.environ['LOG_WORKSPACE_ID'],timespan=(datetime(2021,6,2,tzinfo=timezone.utc),datetime(2021,6,5,tzinfo=timezone.utc)),# (start, end)include_statistics=True),]results=client.query_batch(requests)forresinresults:ifres.status==LogsQueryStatus.FAILURE:# this will be a LogsQueryErrorprint(res.message)elifres.status==LogsQueryStatus.PARTIAL:## this will be a LogsQueryPartialResultprint(res.partial_error)fortableinres.partial_data:df=pd.DataFrame(table.rows,columns=table.columns)print(df)elifres.status==LogsQueryStatus.SUCCESS:## this will be a LogsQueryResulttable=res.tables[0]df=pd.DataFrame(table.rows,columns=table.columns)print(df)Resource logs queryThe following example demonstrates how to query logs directly from an Azure resource without the use of a Log Analytics workspace. Here, thequery_resourcemethod is used instead ofquery_workspace, and instead of a workspace ID, an Azure resource identifier is passed in (e.g./subscriptions/{subscription-id}/resourceGroups/{resource-group-name}/providers/{resource-provider}/{resource-type}/{resource-name}).importosimportpandasaspdfromdatetimeimporttimedeltafromazure.monitor.queryimportLogsQueryClient,LogsQueryStatusfromazure.core.exceptionsimportHttpResponseErrorfromazure.identityimportDefaultAzureCredentialcredential=DefaultAzureCredential()client=LogsQueryClient(credential)query="""AzureActivity | take 5"""try:response=client.query_resource(os.environ['LOGS_RESOURCE_ID'],query,timespan=timedelta(days=1))ifresponse.status==LogsQueryStatus.PARTIAL:error=response.partial_errordata=response.partial_dataprint(error)elifresponse.status==LogsQueryStatus.SUCCESS:data=response.tablesfortableindata:df=pd.DataFrame(data=table.rows,columns=table.columns)print(df)exceptHttpResponseErroraserr:print("something fatal happened")print(err)Advanced logs query scenariosSet logs query timeoutThe following example shows setting a server timeout in seconds. A gateway timeout is raised if the query takes more time than the mentioned timeout. The default is 180 seconds and can be set up to 10 minutes (600 seconds).importosfromdatetimeimporttimedeltafromazure.monitor.queryimportLogsQueryClientfromazure.identityimportDefaultAzureCredentialcredential=DefaultAzureCredential()client=LogsQueryClient(credential)response=client.query_workspace(os.environ['LOG_WORKSPACE_ID'],"range x from 1 to 10000000000 step 1 | count",timespan=timedelta(days=1),server_timeout=600# sets the timeout to 10 minutes)Query multiple workspacesThe same logs query can be executed across multiple Log Analytics workspaces. In addition to the Kusto query, the following parameters are required:workspace_id- The first (primary) workspace ID.additional_workspaces- A list of workspaces, excluding the workspace provided in theworkspace_idparameter. The parameter's list items may consist of the following identifier formats:Qualified workspace namesWorkspace IDsAzure resource IDsFor example, the following query executes in three workspaces:client.query_workspace(<workspace_id>,query,timespan=timedelta(days=1),additional_workspaces=['<workspace 2>','<workspace 3>'])A full sample can be foundhere.Include statisticsTo get logs query execution statistics, such as CPU and memory consumption:Set theinclude_statisticsparameter toTrue.Access thestatisticsfield inside theLogsQueryResultobject.The following example prints the query execution time:query="AzureActivity | top 10 by TimeGenerated"result=client.query_workspace(<workspace_id>,query,timespan=timedelta(days=1),include_statistics=True)execution_time=result.statistics.get("query",{}).get("executionTime")print(f"Query execution time:{execution_time}")Thestatisticsfield is adictthat corresponds to the raw JSON response, and its structure can vary by query. The statistics are found within thequeryproperty. For example:{"query":{"executionTime":0.0156478,"resourceUsage":{...},"inputDatasetStatistics":{...},"datasetStatistics":[{...}]}}Include visualizationTo get visualization data for logs queries using therender operator:Set theinclude_visualizationproperty toTrue.Access thevisualizationfield inside theLogsQueryResultobject.For example:query=("StormEvents""| summarize event_count = count() by State""| where event_count > 10""| project State, event_count""| render columnchart")result=client.query_workspace(<workspace_id>,query,timespan=timedelta(days=1),include_visualization=True)print(f"Visualization result:{result.visualization}")Thevisualizationfield is adictthat corresponds to the raw JSON response, and its structure can vary by query. For example:{"visualization":"columnchart","title":"the chart title","accumulate":False,"isQuerySorted":False,"kind":None,"legend":None,"series":None,"yMin":"NaN","yMax":"NaN","xAxis":None,"xColumn":None,"xTitle":"x axis title","yAxis":None,"yColumns":None,"ySplit":None,"yTitle":None,"anomalyColumns":None}Interpretation of the visualization data is left to the library consumer. To use this data with thePlotly graphing library, see thesynchronousorasynchronouscode samples.Metrics queryThe following example gets metrics for an Event Grid subscription. The resource URI is that of an Event Grid topic.The resource URI must be that of the resource for which metrics are being queried. It's normally of the format/subscriptions/<id>/resourceGroups/<rg-name>/providers/<source>/topics/<resource-name>.To find the resource URI:Navigate to your resource's page in the Azure portal.From theOverviewblade, select theJSON Viewlink.In the resulting JSON, copy the value of theidproperty.NOTE: The metrics are returned in the order of the metric_names sent.importosfromdatetimeimporttimedelta,datetimefromazure.monitor.queryimportMetricsQueryClientfromazure.identityimportDefaultAzureCredentialcredential=DefaultAzureCredential()client=MetricsQueryClient(credential)start_time=datetime(2021,5,25)duration=timedelta(days=1)metrics_uri=os.environ['METRICS_RESOURCE_URI']response=client.query_resource(metrics_uri,metric_names=["PublishSuccessCount"],timespan=(start_time,duration))formetricinresponse.metrics:print(metric.name)fortime_series_elementinmetric.timeseries:formetric_valueintime_series_element.data:print(metric_value.time_stamp)Handle metrics query responseThe metrics query API returns aMetricsQueryResultobject. TheMetricsQueryResultobject contains properties such as a list ofMetric-typed objects,granularity,namespace, andtimespan. TheMetricobjects list can be accessed using themetricsparam. EachMetricobject in this list contains a list ofTimeSeriesElementobjects. EachTimeSeriesElementobject containsdataandmetadata_valuesproperties. In visual form, the object hierarchy of the response resembles the following structure:MetricsQueryResult
|---granularity
|---timespan
|---cost
|---namespace
|---resource_region
|---metrics (list of `Metric` objects)
    |---id
    |---type
    |---name
    |---unit
    |---timeseries (list of `TimeSeriesElement` objects)
        |---metadata_values
        |---data (list of data points represented by `MetricValue` objects)Example of handling responseimportosfromazure.monitor.queryimportMetricsQueryClient,MetricAggregationTypefromazure.identityimportDefaultAzureCredentialcredential=DefaultAzureCredential()client=MetricsQueryClient(credential)metrics_uri=os.environ['METRICS_RESOURCE_URI']response=client.query_resource(metrics_uri,metric_names=["MatchedEventCount"],aggregations=[MetricAggregationType.COUNT])formetricinresponse.metrics:print(metric.name)fortime_series_elementinmetric.timeseries:formetric_valueintime_series_element.data:ifmetric_value.count!=0:print("There are{}matched events at{}".format(metric_value.count,metric_value.time_stamp))TroubleshootingSee ourtroubleshooting guidefor details on how to diagnose various failure scenarios.Next stepsTo learn more about Azure Monitor, see theAzure Monitor service documentation.SamplesThe following code samples show common scenarios with the Azure Monitor Query client library.Logs query samplesSend a single query with LogsQueryClient and handle the response as a table(async sample)Send a single query with LogsQueryClient and handle the response in key-value formSend a single query with LogsQueryClient without pandasSend a single query with LogsQueryClient across multiple workspacesSend multiple queries with LogsQueryClientSend a single query with LogsQueryClient using server timeoutMetrics query samplesSend a query using MetricsQueryClient(async sample)Get a list of metric namespaces(async sample)Get a list of metric definitions(async sample)ContributingThis project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visitcla.microsoft.com.When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repositories using our CLA.This project has adopted theMicrosoft Open Source Code of Conduct. For more information see theCode of Conduct FAQor contactopencode@microsoft.comwith any additional questions or comments.Release History1.2.1 (2024-01-31)Bugs FixedFixed certain keyword arguments from being propagated when usingMetricsQueryClient.Other ChangesInternal updates to generated code.Bumped minimum dependency onazure-coreto>=1.28.0.1.3.0b2 (2023-11-20)Other ChangesInternal updates to generated code.Bumped minimum dependency onazure-coreto>=1.28.0.1.3.0b1 (2023-08-16)Features AddedAddedMetricsBatchQueryClientto support batch querying metrics from Azure resources. (#31049)1.2.0 (2023-05-09)Features AddedAdd thequery_resourcemethod toLogsQueryClientto allow users to query Azure resources directly without the context of a workspace. (#29365)Bugs FixedFixed an inconsistent keyword argument name in theLogsTableconstructor, changingcolumn_typestocolumns_types. Note that this is a class that is typically only instantiated internally, and not by users. (#29076)Other ChangesImproved client configuration logic for non-public Azure clouds where credential scope will be determined based on the configured endpoint. (#29602)1.1.1 (2023-02-13)Bugs FixedFixed a bug where the incorrect keytime_stamp(should betimeStamp) was used in the creation ofMetricValueobjects (thanks @jamespic).  (#28777)1.1.0 (2023-02-07)Bugs FixedError details are now propagated inside theLogsQueryErrorobject. (#25137)Other ChangesPython 3.6 is no longer supported. Please use Python version 3.7 or later. For more details, seeAzure SDK for Python version support policy.Removedmsrestdependency.Bumped minimum dependency onazure-coreto>=1.24.0.Added requirement forisodate>=0.6.0(isodatewas required bymsrest).Added requirement fortyping-extensions>=4.0.1.1.0.3 (2022-07-07)Bugs FixedFixed a bug wherequery_resourcein metrics client is throwing an error with unexpectedmetric_namespaceargument.1.0.2 (2022-05-06)This version and all future versions will require Python 3.6+. Python 2.7 is no longer supported.Bugs FixedFixed a bug where having a None value in datetime throws1.0.1 (2021-11-09)Bugs FixedFixed a bug where Metadata values in timestamp don't show up sometimes.1.0.0 (2021-10-06)Features AddedAddedLogsQueryPartialResultandLogsQueryErrorto handle errors.Addedstatusattribute toLogsQueryResult.AddedLogsQueryStatusEnum to describe the status of a result.Added a newLogsTableRowtype that represents a single row in a table.Items inmetricslist inMetricsQueryResultcan now be accessed by metric names.Breaking ChangesLogsQueryResultnow iterates over the tables directly as a convenience.queryAPI in logs is renamed toquery_workspacequeryAPI in metrics is renamed toquery_resourcequery_workspaceAPI now returns a union ofLogsQueryPartialResultandLogsQueryResult.query_batchAPI now returns a union ofLogsQueryPartialResult,LogsQueryErrorandLogsQueryResult.metric_namespaceis renamed tonamespaceand is a keyword-only argument inlist_metric_definitionsAPI.MetricsResultis renamed toMetricsQueryResult.1.0.0b4 (2021-09-09)Features AddedAdded additionaldisplay_descriptionattribute to theMetrictype.Added aMetricClassenum to provide the class of a metric.Added ametric_classattribute to theMetricDefinitiontype.Added aMetricNamespaceClassificationenum to support thenamespace_classificationattribute onMetricNamespacetype.Added aMetricUnitenum to describe the unit of the metric.Breaking ChangesRenamebatch_querytoquery_batch.RenameLogsBatchQueryRequesttoLogsBatchQuery.include_renderis now renamed toinclude_visualizationin the query API.LogsQueryResultnow returnsvisualizationinstead ofrender.start_time,durationandend_timeare now replaced with a single param calledtimespanresourceregionis renamed toresource_regionin the MetricResult type.topis renamed tomax_resultsin the metric'squeryAPI.metric_namespace_nameis renamed tofully_qualified_namespaceis_dimension_requiredis renamed todimension_requiredintervalandtime_grainare renamed togranularityorderbyis renamed toorder_byLogsQueryResultnow returnsdatetimeobjects for a time values.LogsBatchQuerydoesn't accept arequest_idanymore.MetricsMetadataValuesis removed. A dictionary is used instead.time_stampis renamed totimestampinMetricValuetype.AggregationTypeis renamed toMetricAggregationType.RemovedLogsBatchResultErrortype.LogsQueryResultTableis named toLogsTableLogsTableColumnis now removed. Column labels are strings instead.start_timeinlist_metric_namespacesAPI is now a datetime.The order of params inLogsBatchQueryis changed. Also,headersis no longer accepted.timespanis now a required keyword-only argument in logs APIs.batch api now returns a list ofLogsQueryResultobjects.Bugs Fixedinclude_statisticsandinclude_visualizationargs can now work together.1.0.0b3 (2021-08-09)Features AddedAdded enumAggregationTypewhich can be used to specify aggregations in the query API.AddedLogsBatchQueryResultmodel that is returned for a logs batch query.Addederrorattribute toLogsQueryResult.Breaking Changesaggregationparam in the query API is renamed toaggregationsbatch_queryAPI now returns a list of responses.LogsBatchResultsmodel is now removed.LogsQueryRequestis renamed toLogsBatchQueryRequestLogsQueryResultsis now renamed toLogsQueryResultLogsBatchQueryResultnow has 4 additional attributes -tables,error,statisticsandrenderinstead ofbodyattribute.1.0.0b2 (2021-07-06)Breaking Changesworkspaces,workspace_ids,qualified_namesandazure_resource_idsare now merged into a singleadditional_workspaceslist in the query API.TheLogQueryRequestobject now takes in aworkspace_idandadditional_workspacesinstead ofworkspace.aggregationparam is now a list instead of a string in thequerymethod.durationmust now be provided as a timedelta instead of a string.1.0.0b1 (2021-06-10)FeaturesVersion (1.0.0b1) is the first preview of our efforts to create a user-friendly and Pythonic client library for Azure Monitor Query.
For more information about this, and preview releases of other Azure SDK libraries, please visithttps://azure.github.io/azure-sdk/releases/latest/python.html.Added~azure.monitor.query.LogsQueryClientto query log analytics along with~azure.monitor.query.aio.LogsQueryClient.Implements the~azure.monitor.query.MetricsQueryClientfor querying metrics, listing namespaces and metric definitions along with~azure.monitor.query.aio.MetricsQueryClient.