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

A biblioteca de clientes de Consulta do Azure Monitor é usada para executar consultas somente leitura nas duas plataformas de dados do Azure Monitor:

• Logs – coleta e organiza dados de log e desempenho de recursos monitorados. Dados de diferentes fontes, como logs de plataforma de serviços do Azure, dados de log e desempenho de agentes de máquinas virtuais, e dados de uso e desempenho de aplicativos podem ser consolidados em um único workspace do Log Analytics do Azure. Os vários tipos de dados podem ser analisados juntos usando o Linguagem de Consulta Kusto.
• Métricas – coleta dados numéricos de recursos monitorados em um banco de dados de série temporal. Métricas são valores numéricos que são coletados a intervalos regulares e descrevem algum aspecto de um sistema em um determinado momento. As métricas são leves e capazes de dar suporte a cenários quase em tempo real, tornando-as úteis para alertas e detecção rápida de problemas.

Recursos:

• Código-fonte
• Pacote (PyPI)
• Pacote (Conda)
• Documentação de referência da API
• Documentação do serviço
• Amostras
• Log de alterações

Introdução

Pré-requisitos

• Python 3.7 ou posterior
• Uma assinatura do Azure
• Uma implementação de TokenCredential, como um tipo de credencial de biblioteca de identidade do Azure.
• Para consultar logs, você precisa de um workspace do Log Analytics do Azure.
• Para consultar Métricas, você precisa de um recurso do Azure de qualquer tipo (Conta de Armazenamento, Key Vault, Cosmos DB etc.).

Instalar o pacote

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

pip install azure-monitor-query

Crie o cliente

Um cliente autenticado é necessário para consultar Logs 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. Use essa instância ao criar um LogsQueryClient ou MetricsQueryClient. Os exemplos a seguir usam DefaultAzureCredential do pacote azure-identity .

Clientes síncronos

Considere o exemplo a seguir, que cria clientes síncronos para a consulta de Logs 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 do cliente de consulta são encontradas no .aionamespace -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 nuvens não públicas do Azure

Por padrão, LogsQueryClient e MetricsQueryClient são configurados para se conectar à nuvem pública do Azure. Eles podem ser configurados para se conectar a nuvens não públicas do Azure passando 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")

Observação: atualmente, MetricsQueryClient usa o ponto de extremidade do Azure Resource Manager (ARM) para consultar métricas, portanto, você precisará do ponto de extremidade de gerenciamento correspondente para sua nuvem ao usar esse cliente. Isso está sujeito a alterações no futuro.

Executar a consulta

Para obter exemplos de consultas de Logs e Métricas, consulte a seção Exemplos .

Principais conceitos

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

O serviço log analytics aplica limitação quando a taxa de solicitação é muito alta. Limites, como o número máximo de linhas retornadas, também são aplicados nas consultas Kusto. Para obter mais informações, consulte API de consulta.

Se você estiver executando uma consulta de logs em lotes, uma solicitação limitada retornará um LogsQueryError objeto . O valor desse code objeto será ThrottledError.

Estrutura de dados de métricas

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

• A hora em que o valor foi coletado
• O recurso associado ao valor
• Um namespace que funciona como uma categoria para a métrica
• Um nome de métrica
• O valor em si
• Algumas métricas podem ter várias dimensões, conforme descrito em métricas multidimensionais. As métricas personalizadas podem ter até 10 dimensões.

Exemplos

• Consulta de logs
  • Especificar o período de tempo
  • Lidar com a resposta da consulta de logs
• Consulta de logs do lote
• Consulta de logs de recursos
• Cenários de consulta de logs avançados
  • Definir o tempo limite de consulta de logs
  • Consultar vários workspaces
  • Incluir estatísticas
  • Incluir visualização
• Consulta de métricas
  • Manipular resposta de consulta de métricas
  • Exemplo de tratamento de resposta

Consulta de logs

Este exemplo mostra como consultar um workspace do Log Analytics. Para lidar com a resposta e exibi-la em um formulário tabular, a biblioteca pandas é usada. Consulte os exemplos se você optar por não usar pandas.

Especificar o período de tempo

O timespan parâmetro especifica a duração do tempo para a qual consultar os dados. Este valor pode ser um dos seguintes:

• um timedelta
• a timedelta e um datetime de início
• a datetime/end datetime 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)

Lidar com a resposta da consulta de logs

A query_workspace API retorna um LogsQueryResult ou um LogsQueryPartialResult objeto . A batch_query API retorna uma lista que pode conter LogsQueryResultobjetos , LogsQueryPartialResulte LogsQueryError . Aqui está 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 tabela como uma conveniência. Por exemplo, para manipular uma resposta de consulta de logs com tabelas e exibi-la usando pandas:

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

Um exemplo completo pode ser encontrado aqui.

De maneira semelhante, para lidar com uma resposta de consulta de logs de lote:

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

Um exemplo completo pode ser encontrado aqui.

Consulta de logs do lote

O exemplo a seguir demonstra o envio de várias consultas ao mesmo tempo usando a API de consulta em lote. As consultas podem ser representadas como uma lista de LogsBatchQuery objetos ou um dicionário. Este exemplo usa 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 logs de recursos

O exemplo a seguir demonstra como consultar logs diretamente de um recurso do Azure sem o uso de um workspace do Log Analytics. Aqui, o query_resource método é usado em vez de query_workspacee, em vez de uma ID de workspace, um identificador de recurso do Azure é passado (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 logs avançados

Definir o tempo limite de consulta de logs

O exemplo a seguir mostra a configuração de um tempo limite do servidor em segundos. Um tempo limite do gateway será gerado se a consulta levar mais tempo do que o tempo limite mencionado. O padrão é 180 segundos e pode ser configurado para 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ários workspaces

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

• workspace_id - A primeira ID do workspace (primário).
• additional_workspaces - Uma lista de workspaces, excluindo o workspace fornecido no workspace_id parâmetro . Os itens de lista do parâmetro podem consistir nos seguintes formatos de identificador:
  • Nomes de workspace qualificados
  • Workspace IDs
  • IDs de recursos do Azure

Por exemplo, a consulta a seguir é executada em três workspaces:

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

Um exemplo completo pode ser encontrado aqui.

Incluir estatísticas

Para obter estatísticas de execução de consulta de logs, como consumo de CPU e memória:

1. Defina o parâmetro de include_statistics a True.
2. Acesse o statistics campo dentro do LogsQueryResult objeto .

O exemplo a seguir 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 bruta e sua estrutura pode variar de acordo com a consulta. As estatísticas são encontradas dentro da query propriedade . Por exemplo:

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

Incluir visualização

Para obter dados de visualização para consultas de logs usando o operador de renderização:

1. Defina a propriedade include_visualization como True.
2. Acesse o 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 bruta e sua estrutura pode variar de acordo com 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 a seguir obtém métricas para uma assinatura da Grade de Eventos. O URI do recurso é o de um tópico da Grade de Eventos.

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

Para localizar o URI do recurso:

1. Navegue até a página do recurso no portal do Azure.
2. Na folha Visão geral , selecione o link Modo de Exibição JSON .
3. No JSON resultante, copie o valor da id propriedade .

OBSERVAÇÃO: as métricas são retornadas na 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)

Manipular resposta de consulta de métricas

A API de consulta de métricas retorna um MetricsQueryResult objeto . O MetricsQueryResult objeto contém propriedades como uma lista de Metricobjetos do tipo , granularity, namespacee timespan. A Metric lista de objetos pode ser acessada usando o metrics parâmetro . Cada Metric objeto nesta lista contém uma lista de TimeSeriesElement objetos. Cada TimeSeriesElement objeto contém data propriedades e metadata_values . No formato visual, a hierarquia de objeto da resposta se assemelha à 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 tratamento 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
                    )
                )

Solução de problemas

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

Próximas etapas

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

Exemplos

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

Exemplos de consulta de logs

• Enviar uma única consulta com LogsQueryClient e manipular a resposta como uma tabela (exemplo assíncrono)
• Enviar uma única consulta com LogsQueryClient e manipular a resposta no formulário chave-valor
• Enviar uma única consulta com LogsQueryClient sem pandas
• Enviar uma única consulta com LogsQueryClient em vários workspaces
• Enviar várias consultas com LogsQueryClient
• Enviar uma única consulta com LogsQueryClient usando o tempo limite do servidor

Exemplos de consulta de métricas

• Enviar uma consulta usando MetricsQueryClient (exemplo assíncrono)
• Obter uma lista de namespaces de métrica (exemplo assíncrono)
• Obter uma lista de definições de métrica (exemplo assíncrono)

Contribuição

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder, e de fato concede, os direitos de usar sua contribuição. Para obter detalhes, visite cla.microsoft.com.

Quando você envia uma solicitação de pull, um bot do CLA determina automaticamente se você precisa fornecer um CLA e preencher a PR corretamente (por exemplo, rótulo, comentário). Basta seguir as instruções fornecidas pelo bot. Você só precisará fazer isso uma vez em todos os repositórios usando nosso CLA.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, confira as Perguntas frequentes sobre o Código de Conduta ou contate opencode@microsoft.com para enviar outras perguntas ou comentários.