Biblioteca de cliente de Consulta do Azure Monitor para Python – versão 1.2.0

  • Artigo

A biblioteca de cliente de Consulta do Azure Monitor é utilizada para executar consultas só de leitura nas duas plataformas de dados do Azure Monitor:

  • Registos – recolhe e organiza dados de registo e desempenho de recursos monitorizados. Os dados de diferentes origens, como registos de plataformas de serviços do Azure, dados de registo e desempenho de agentes de máquinas virtuais e dados de utilização e desempenho de aplicações, podem ser consolidados numa única área de trabalho do Azure Log Analytics. Os vários tipos de dados podem ser analisados em conjunto com o Linguagem de Pesquisa Kusto.
  • Métricas – recolhe dados numéricos de recursos monitorizados para uma base de dados de série temporal. As métricas são valores numéricos que são recolhidos em intervalos regulares e descrevem alguns aspetos de um sistema num determinado momento. As métricas são leves e capazes de suportar cenários quase em tempo real, tornando-as úteis para alertas e deteção rápida de problemas.

Recursos:

Introdução

Pré-requisitos

Instalar o pacote

Instale a biblioteca de cliente de Consulta do Azure Monitor para Python com pip:

pip install azure-monitor-query

Criar o cliente

É necessário um cliente autenticado para consultar Registos ou Métricas. A biblioteca inclui formas síncronas e assíncronas dos clientes. Para autenticar, crie uma instância de uma credencial de token. Utilize essa instância ao criar um LogsQueryClient ou MetricsQueryClient. Os exemplos seguintes são utilizados DefaultAzureCredential a partir do pacote azure-identity .

Clientes síncronos

Considere o exemplo seguinte, que cria clientes síncronos para consultas de Registos e Métricas:

from azure.identity import DefaultAzureCredential
from azure.monitor.query import LogsQueryClient, MetricsQueryClient

credential = DefaultAzureCredential()
logs_client = LogsQueryClient(credential)
metrics_client = MetricsQueryClient(credential)

Clientes assíncronos

As formas assíncronas das APIs de cliente de consulta encontram-se no .aioespaço de nomes -sufixo. Por exemplo:

from azure.identity.aio import DefaultAzureCredential
from azure.monitor.query.aio import LogsQueryClient, MetricsQueryClient

credential = DefaultAzureCredential()
async_logs_client = LogsQueryClient(credential)
async_metrics_client = MetricsQueryClient(credential)

Configurar clientes para clouds do Azure não públicas

Por predefinição, LogsQueryClient e MetricsQueryClient estão configurados para ligar à cloud pública do Azure. Estas podem ser configuradas para ligar a clouds do Azure não públicas ao transmitir o argumento correto endpoint : Por exemplo:

logs_client = LogsQueryClient(credential, endpoint="https://api.loganalytics.azure.cn/v1")
metrics_client = MetricsQueryClient(credential, endpoint="https://management.chinacloudapi.cn")

Nota: atualmente, MetricsQueryClient utiliza o ponto final do Azure Resource Manager (ARM) para consultar métricas, pelo que precisará do ponto final de gestão correspondente para a sua cloud ao utilizar este cliente. Isto está sujeito a alterações no futuro.

Executar a consulta

Para obter exemplos de consultas de Registos e Métricas, veja a secção Exemplos .

Conceitos-chave

Limites e limitação da taxa de consulta de registos

O serviço Log Analytics aplica limitação quando a taxa de pedidos é demasiado elevada. Os limites, como o número máximo de linhas devolvidas, também são aplicados nas consultas kusto. Para obter mais informações, veja API de Consulta.

Se estiver a executar uma consulta de registos em lote, um pedido limitado devolverá um LogsQueryError objeto. O valor desse code objeto será ThrottledError.

Estrutura de dados de métricas

Cada conjunto de valores de métricas é uma série temporal com as seguintes características:

  • A hora em que o valor foi recolhido
  • O recurso associado ao valor
  • Um espaço de nomes que age como uma categoria para a métrica
  • Um nome de métrica
  • O valor em si
  • Algumas métricas podem ter múltiplas dimensões, conforme descrito em métricas multidimensionais. As métricas personalizadas podem ter até 10 dimensões.

Exemplos

Consulta de registos

Este exemplo mostra como consultar uma área de trabalho do Log Analytics. Para processar a resposta e vê-la num formulário tabular, é utilizada a biblioteca do pandas . Veja os exemplos se optar por não utilizar o pandas.

Especificar intervalo de tempo

O timespan parâmetro especifica a duração da consulta dos dados. Este valor pode ser um dos seguintes:

  • a timedelta
  • a timedelta e uma data de início
  • data/data de fim de início

Por exemplo:

import os
import pandas as pd
from datetime import datetime, timezone
from azure.monitor.query import LogsQueryClient, LogsQueryStatus
from azure.identity import DefaultAzureCredential
from azure.core.exceptions import HttpResponseError

credential = 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)
        )
    if response.status == LogsQueryStatus.PARTIAL:
        error = response.partial_error
        data = response.partial_data
        print(error)
    elif response.status == LogsQueryStatus.SUCCESS:
        data = response.tables
    for table in data:
        df = pd.DataFrame(data=table.rows, columns=table.columns)
        print(df)
except HttpResponseError as err:
    print("something fatal happened")
    print(err)

Processar a resposta da consulta de registos

A query_workspace API devolve um LogsQueryResult ou um LogsQueryPartialResult objeto. A batch_query API devolve uma lista que pode conter LogsQueryResult, LogsQueryPartialResulte LogsQueryError objetos. Segue-se uma hierarquia da resposta:

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_types

O LogsQueryResult itera diretamente sobre a mesa como uma conveniência. Por exemplo, para processar uma resposta de consulta de registos com tabelas e apresentá-la com o pandas:

response = client.query(...)
for table in response:
    df = pd.DataFrame(table.rows, columns=[col.name for col in table.columns])

Pode encontrar um exemplo completo aqui.

De forma semelhante, para processar uma resposta de consulta de registos em lote:

for result in response:
    if result.status == LogsQueryStatus.SUCCESS:
        for table in result:
            df = pd.DataFrame(table.rows, columns=table.columns)
            print(df)

Pode encontrar um exemplo completo aqui.

Consulta de registos do Batch

O exemplo seguinte demonstra o envio de várias consultas ao mesmo tempo através da API de consulta em lote. As consultas podem ser representadas como uma lista de LogsBatchQuery objetos ou um dicionário. Este exemplo utiliza a abordagem anterior.

import os
from datetime import timedelta, datetime, timezone
import pandas as pd
from azure.monitor.query import LogsQueryClient, LogsBatchQuery, LogsQueryStatus
from azure.identity import DefaultAzureCredential

credential = 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)

for res in results:
    if res.status == LogsQueryStatus.FAILURE:
        # this will be a LogsQueryError
        print(res.message)
    elif res.status == LogsQueryStatus.PARTIAL:
        ## this will be a LogsQueryPartialResult
        print(res.partial_error)
        for table in res.partial_data:
            df = pd.DataFrame(table.rows, columns=table.columns)
            print(df)
    elif res.status == LogsQueryStatus.SUCCESS:
        ## this will be a LogsQueryResult
        table = res.tables[0]
        df = pd.DataFrame(table.rows, columns=table.columns)
        print(df)

Consulta de registos de recursos

O exemplo seguinte demonstra como consultar registos diretamente a partir de um recurso do Azure sem a utilização de uma área de trabalho do Log Analytics. Aqui, o query_resource método é utilizado em vez de query_workspacee, em vez de um ID de área de trabalho, é transmitido um identificador de recursos do Azure (por exemplo, /subscriptions/{subscription-id}/resourceGroups/{resource-group-name}/providers/{resource-provider}/{resource-type}/{resource-name}).

import os
import pandas as pd
from datetime import timedelta
from azure.monitor.query import LogsQueryClient, LogsQueryStatus
from azure.core.exceptions import HttpResponseError
from azure.identity import DefaultAzureCredential

credential  = DefaultAzureCredential()
client = LogsQueryClient(credential)

query = """AzureActivity | take 5"""

try:
    response = client.query_resource(os.environ['LOGS_RESOURCE_ID'], query, timespan=timedelta(days=1))
    if response.status == LogsQueryStatus.PARTIAL:
        error = response.partial_error
        data = response.partial_data
        print(error)
    elif response.status == LogsQueryStatus.SUCCESS:
        data = response.tables
    for table in data:
        df = pd.DataFrame(data=table.rows, columns=table.columns)
        print(df)
except HttpResponseError as err:
    print("something fatal happened")
    print(err)

Cenários de consulta de registos avançados

Definir o tempo limite da consulta de registos

O exemplo seguinte mostra a definição de um tempo limite do servidor em segundos. Um tempo limite do gateway é aumentado se a consulta demorar mais tempo do que o tempo limite mencionado. A predefinição é de 180 segundos e pode ser configurada até 10 minutos (600 segundos).

import os
from azure.monitor.query import LogsQueryClient
from azure.identity import DefaultAzureCredential

credential = 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
    )

Consultar várias áreas de trabalho

A mesma consulta de registos pode ser executada em várias áreas de trabalho do Log Analytics. Além da consulta Kusto, são necessários os seguintes parâmetros:

  • workspace_id - O primeiro ID (primário) da área de trabalho.
  • additional_workspaces - Uma lista de áreas de trabalho, excluindo a área de trabalho fornecida no workspace_id parâmetro. Os itens de lista do parâmetro podem consistir nos seguintes formatos de identificador:
    • Nomes de áreas de trabalho qualificados
    • IDs da área de trabalho
    • IDs de recursos do Azure

Por exemplo, a seguinte consulta é executada em três áreas de trabalho:

client.query_workspace(
    <workspace_id>,
    query,
    timespan=timedelta(days=1),
    additional_workspaces=['<workspace 2>', '<workspace 3>']
    )

Pode encontrar um exemplo completo aqui.

Incluir estatísticas

Para obter estatísticas de execução de consultas de registos, como a CPU e o consumo de memória:

  1. Defina o include_statistics parâmetro como True.
  2. Aceda ao statistics campo dentro do LogsQueryResult objeto.

O exemplo seguinte imprime o tempo de execução da consulta:

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}")

O statistics campo é um dict que corresponde à resposta JSON não processada e a sua estrutura pode variar consoante a consulta. As estatísticas encontram-se na query propriedade. Por exemplo:

{
  "query": {
    "executionTime": 0.0156478,
    "resourceUsage": {...},
    "inputDatasetStatistics": {...},
    "datasetStatistics": [{...}]
  }
}

Incluir visualização

Para obter dados de visualização para consultas de registos com o operador de composição:

  1. Defina a include_visualization propriedade como True.
  2. Aceda ao visualization campo dentro do LogsQueryResult objeto.

Por exemplo:

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}")

O visualization campo é um dict que corresponde à resposta JSON não processada e a sua estrutura pode variar consoante a consulta. Por exemplo:

{
  "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
}

Consulta de métricas

O exemplo seguinte obtém métricas para uma subscrição do Event Grid. O URI do recurso é o de um tópico do Event Grid.

O URI do recurso tem de ser o do recurso para o qual as métricas estão a ser consultadas. Normalmente, é do formato /subscriptions/<id>/resourceGroups/<rg-name>/providers/<source>/topics/<resource-name>.

Para localizar o URI do recurso:

  1. Navegue para a página do recurso no portal do Azure.
  2. No painel Descrição geral , selecione a ligação Vista JSON .
  3. No JSON resultante, copie o valor da id propriedade.

NOTA: as métricas são devolvidas pela ordem dos metric_names enviados.

import os
from datetime import timedelta, datetime
from azure.monitor.query import MetricsQueryClient
from azure.identity import DefaultAzureCredential

credential = 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)
    )

for metric in response.metrics:
    print(metric.name)
    for time_series_element in metric.timeseries:
        for metric_value in time_series_element.data:
            print(metric_value.time_stamp)

Processar resposta de consulta de métricas

A API de consulta de métricas devolve um MetricsQueryResult objeto. O MetricsQueryResult objeto contém propriedades como uma lista de Metricobjetos digitados, , granularitynamespacee timespan. A Metric lista de objetos pode ser acedida com o metrics parâmetro. Cada Metric objeto nesta lista contém uma lista de TimeSeriesElement objetos. Cada TimeSeriesElement objeto contém data e metadata_values propriedades. Na forma visual, a hierarquia de objetos da resposta assemelha-se à seguinte estrutura:

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)

Exemplo de processamento de resposta

import os
from azure.monitor.query import MetricsQueryClient, MetricAggregationType
from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()
client = MetricsQueryClient(credential)

metrics_uri = os.environ['METRICS_RESOURCE_URI']
response = client.query_resource(
    metrics_uri,
    metric_names=["MatchedEventCount"],
    aggregations=[MetricAggregationType.COUNT]
    )

for metric in response.metrics:
    print(metric.name)
    for time_series_element in metric.timeseries:
        for metric_value in time_series_element.data:
            if metric_value.count != 0:
                print(
                    "There are {} matched events at {}".format(
                        metric_value.count,
                        metric_value.time_stamp
                    )
                )

Resolução de problemas

Veja o nosso guia de resolução de problemas para obter detalhes sobre como diagnosticar vários cenários de falha.

Passos seguintes

Para saber mais sobre o Azure Monitor, veja a documentação do serviço Azure Monitor.

Amostras

Os exemplos de código seguintes mostram cenários comuns com a biblioteca de cliente de Consulta do Azure Monitor.

Exemplos de consulta de registos

Exemplos de consulta de métricas

Contribuir

Agradecemos todas as contribuições e sugestões para este projeto. A maioria das contribuições requerem que celebre um Contrato de Licença de Contribuição (CLA) no qual se declare que tem o direito de conceder e que, na verdade, concede-nos os direitos para utilizar a sua contribuição. Para obter detalhes, visite cla.microsoft.com.

Quando submete um pedido Pull, um bot do CLA determina automaticamente se tem de fornecer um CLA e decorar o PR de forma adequada (por exemplo, etiqueta, comentário). Só tem de seguir as instruções fornecidas pelo bot. Só terá de o fazer uma vez em todos os repositórios com o nosso CLA.

Este projeto adotou o Microsoft Open Source Code of Conduct (Código de Conduta do Microsoft Open Source). Para obter mais informações, consulte as FAQ do Código de Conduta ou o contacto opencode@microsoft.com com quaisquer perguntas ou comentários adicionais.