Compartir a través de

Biblioteca cliente de consultas de Azure Monitor para Python: versión 1.2.0

  • Artículo

La biblioteca cliente de consultas de Azure Monitor se usa para ejecutar consultas de solo lectura en las dos plataformas de datos de Azure Monitor:

  • Registros: recopila y organiza los datos de registro y rendimiento de los recursos supervisados. Los datos de diferentes orígenes, como los registros de plataforma de los servicios de Azure, los datos de registro y rendimiento de los agentes de máquinas virtuales, y los datos de uso y rendimiento de las aplicaciones se pueden consolidar en un único área de trabajo de Azure Log Analytics. Los distintos tipos de datos se pueden analizar conjuntamente mediante el Lenguaje de consulta Kusto.
  • Métricas : recopila datos numéricos de recursos supervisados en una base de datos de serie temporal. Las métricas son valores numéricos que se recopilan a intervalos regulares y describen algún aspecto de un sistema en un momento determinado. Las métricas son ligeras y capaces de admitir escenarios casi en tiempo real, lo que hace que sean útiles para alertar y detectar rápidamente problemas.

Recursos:

Introducción

Requisitos previos

Instalar el paquete

Instale la biblioteca cliente de consultas de Azure Monitor para Python con pip:

pip install azure-monitor-query

Creación del cliente

Se requiere un cliente autenticado para consultar registros o métricas. La biblioteca incluye formas sincrónicas y asincrónicas de los clientes. Para autenticarse, cree una instancia de una credencial de token. Use esa instancia al crear o LogsQueryClientMetricsQueryClient. En los ejemplos siguientes se usa DefaultAzureCredential el paquete azure-identity .

Clientes sincrónicos

Considere el ejemplo siguiente, que crea clientes sincrónicos para consultas de registros y 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 asincrónicos

Las formas asincrónicas de las API de cliente de consulta se encuentran en el .aioespacio de nombres -sufijo. Por ejemplo:

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)

Configuración de clientes para nubes de Azure no públicas

De forma predeterminada, LogsQueryClient y MetricsQueryClient están configurados para conectarse a la nube pública de Azure. Se pueden configurar para conectarse a nubes de Azure no públicas pasando el argumento correcto endpoint : por ejemplo:

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

Nota: Actualmente, MetricsQueryClient usa el punto de conexión de Azure Resource Manager (ARM) para consultar métricas, por lo que necesitará el punto de conexión de administración correspondiente para la nube al usar este cliente. Esto está sujeto a cambios en el futuro.

Ejecute la consulta.

Para obtener ejemplos de consultas de registros y métricas, consulte la sección Ejemplos .

Conceptos clave

Registra los límites de frecuencia de consulta y la limitación

El servicio Log Analytics aplica la limitación cuando la tasa de solicitudes es demasiado alta. Los límites, como el número máximo de filas devueltas, también se aplican en las consultas de Kusto. Para más información, consulte Query API.

Si está ejecutando una consulta de registros por lotes, una solicitud limitada devolverá un LogsQueryError objeto . El valor del code objeto será ThrottledError.

Estructura de datos de métricas

Cada conjunto de valores de métricas es una serie temporal con las siguientes características:

  • Hora en que se recopiló el valor.
  • Recurso asociado al valor
  • Espacio de nombres que actúa como una categoría para la métrica.
  • Nombre de la métrica.
  • El propio valor.
  • Algunas métricas pueden tener varias dimensiones, como se describe en métricas multidimensionales. Las métricas personalizadas pueden tener hasta 10 dimensiones.

Ejemplos

consulta de registros

En este ejemplo se muestra cómo consultar un área de trabajo de Log Analytics. Para controlar la respuesta y verlo en un formato tabular, se usa la biblioteca pandas . Consulte los ejemplos si decide no usar Pandas.

Especificar intervalo de tiempo

El timespan parámetro especifica la duración del tiempo durante el que se van a consultar los datos. Este valor puede ser uno de los siguientes:

  • a timedelta
  • a timedelta y una fecha y hora de inicio
  • un valor datetime/end datetime de inicio

Por ejemplo:

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)

Control de la respuesta de consulta de registros

La query_workspace API devuelve un LogsQueryResult objeto o LogsQueryPartialResult . La batch_query API devuelve una lista que puede contener LogsQueryResultobjetos , LogsQueryPartialResulty LogsQueryError . Esta es una jerarquía de la respuesta:

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

La LogsQueryResult iteración directa sobre la tabla como una comodidad. Por ejemplo, para controlar una respuesta de consulta de registros con tablas y mostrarla mediante pandas:

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

Puede encontrar un ejemplo completo aquí.

De forma similar, para controlar una respuesta de consulta de registros por lotes:

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

Puede encontrar un ejemplo completo aquí.

Consulta de registros de Batch

En el ejemplo siguiente se muestra cómo enviar varias consultas al mismo tiempo mediante la API de consulta por lotes. Las consultas se pueden representar como una lista de LogsBatchQuery objetos o un diccionario. En este ejemplo se usa el enfoque 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 registros de recursos

En el ejemplo siguiente se muestra cómo consultar registros directamente desde un recurso de Azure sin usar un área de trabajo de Log Analytics. Aquí, el query_resource método se usa en lugar de query_workspacey, en lugar de un identificador de área de trabajo, se pasa un identificador de recurso de Azure (por ejemplo, /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)

Escenarios de consulta de registros avanzados

Establecimiento del tiempo de espera de la consulta de registros

En el ejemplo siguiente se muestra cómo establecer un tiempo de espera del servidor en segundos. Se genera un tiempo de espera de puerta de enlace si la consulta tarda más tiempo que el tiempo de espera mencionado. El valor predeterminado es 180 segundos y se puede configurar hasta 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
    )

Consulta de varias áreas de trabajo

La misma consulta de registros se puede ejecutar en varias áreas de trabajo de Log Analytics. Además de la consulta de Kusto, se requieren los parámetros siguientes:

  • workspace_id : el primer identificador del área de trabajo (principal).
  • additional_workspaces - Una lista de áreas de trabajo, excepto el área de trabajo proporcionada en el workspace_id parámetro . Los elementos de lista del parámetro pueden constar de los siguientes formatos de identificador:
    • Nombres de área de trabajo calificados
    • Identificadores de área de trabajo
    • Identificadores de recursos de Azure

Por ejemplo, la siguiente consulta se ejecuta en tres áreas de trabajo:

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

Puede encontrar un ejemplo completo aquí.

Incluir estadísticas

Para obtener las estadísticas de ejecución de consultas de registros, como el consumo de CPU y memoria:

  1. Establezca el parámetro include_statistics en True.
  2. Acceda al statistics campo dentro del LogsQueryResult objeto .

En el ejemplo siguiente se imprime el tiempo de ejecución de la 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}")

El statistics campo es un dict que corresponde a la respuesta JSON sin formato y su estructura puede variar según la consulta. Las estadísticas se encuentran dentro de la query propiedad . Por ejemplo:

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

Incluir visualización

Para obtener datos de visualización de consultas de registros mediante el operador render:

  1. Establezca la propiedad include_visualization en True.
  2. Acceda al visualization campo dentro del LogsQueryResult objeto .

Por ejemplo:

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

El visualization campo es un dict que corresponde a la respuesta JSON sin formato y su estructura puede variar según la consulta. Por ejemplo:

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

En el ejemplo siguiente se obtienen métricas de una suscripción de Event Grid. El URI del recurso es el de un tema de Event Grid.

El URI del recurso debe ser el del recurso para el que se consultan las métricas. Normalmente es del formato /subscriptions/<id>/resourceGroups/<rg-name>/providers/<source>/topics/<resource-name>.

Para buscar el URI del recurso:

  1. Vaya a la página del recurso en el Azure Portal.
  2. En la hoja Información general , seleccione el vínculo Vista JSON .
  3. En el JSON resultante, copie el valor de la id propiedad .

NOTA: Las métricas se devuelven en el orden del metric_names enviado.

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)

Control de la respuesta de consulta de métricas

La API de consulta de métricas devuelve un MetricsQueryResult objeto . El MetricsQueryResult objeto contiene propiedades como una lista de Metricobjetos con tipo , granularitynamespace, y timespan. Se Metric puede tener acceso a la lista de objetos mediante el metrics parámetro . Cada Metric objeto de esta lista contiene una lista de TimeSeriesElement objetos . Cada TimeSeriesElement objeto contiene data propiedades y metadata_values . En forma visual, la jerarquía de objetos de la respuesta es similar a la estructura siguiente:

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)

Ejemplo de control de la respuesta

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

Solución de problemas

Consulte nuestra guía de solución de problemas para obtener más información sobre cómo diagnosticar varios escenarios de error.

Pasos siguientes

Para más información sobre Azure Monitor, consulte la documentación del servicio Azure Monitor.

Ejemplos

Los ejemplos de código siguientes muestran escenarios comunes con la biblioteca cliente de consultas de Azure Monitor.

Ejemplos de consultas de registros

Ejemplos de consultas de métricas

Contribuciones

Este proyecto agradece las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia para el colaborador (CLA) que declara que tiene el derecho a concedernos y nos concede los derechos para usar su contribución. Para obtener más información, visite cla.microsoft.com.

Cuando se envía una solicitud de incorporación de cambios, un bot de CLA determinará de forma automática si tiene que aportar un CLA y completar la PR adecuadamente (por ejemplo, la etiqueta, el comentario). Solo siga las instrucciones que le dará el bot. Solo tendrá que hacerlo una vez en todos los repositorios mediante nuestro CLA.

Este proyecto ha adoptado el Código de conducta de Microsoft Open Source. Para más información, consulte las preguntas más frecuentes del código de conducta o póngase en contacto con opencode@microsoft.com si tiene cualquier otra pregunta o comentario.