Biblioteca cliente de registros de consultas de Azure Monitor para JavaScript: versión 1.0.0

La biblioteca cliente de registros de consultas de Azure Monitor se usa para ejecutar consultas de solo lectura en la plataforma de datos de registros 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 una única área de trabajo de Azure Log Analytics. Los distintos tipos de datos se pueden analizar juntos mediante el lenguaje de consulta Kusto.

Migración desde @azure/monitor-query el ⚠aviso ️

Consulte la Guía de migración para obtener instrucciones detalladas sobre cómo actualizar el código de la aplicación del paquete original @azure/monitor-query a la @azure/monitor-query-logs biblioteca.

Recursos:

• Código fuente
• Paquete (npm)
• Documentación de referencia de API
• Documentación del servicio
• Muestras
• Registro de cambios

Cómo empezar

Entornos soportados

• Versiones de LTS de Node.js
• Versiones más recientes de Safari, Chrome, Microsoft Edge y Firefox

Para obtener más información, consulte nuestra política de soporte.

Prerrequisitos

• Una suscripción de Azure
• Una implementación de TokenCredential, como un tipo de credencial de la biblioteca de Azure Identity.
• Para consultar registros, necesita una de las siguientes cosas:
  • Un área de trabajo de Azure Log Analytics
  • Un recurso de Azure de cualquier tipo (cuenta de almacenamiento, Key Vault, Cosmos DB, etcetera).

Instalación del paquete

Instale la biblioteca cliente de consultas de Azure Monitor para JavaScript con npm:

npm install --save @azure/monitor-query-logs

Creación del cliente

Se requiere un cliente autenticado para consultar los registros. Para autenticarse, en el ejemplo siguiente se usa DefaultAzureCredential del paquete @azure/identity .

import { DefaultAzureCredential } from "@azure/identity";
import { LogsQueryClient } from "@azure/monitor-query-logs";

const credential = new DefaultAzureCredential();

// Create a LogsQueryClient
const logsQueryClient = new LogsQueryClient(credential);

Configuración del cliente para la nube soberana de Azure

De forma predeterminada, los clientes de la biblioteca están configurados para usar la nube pública de Azure. Para usar una nube soberana en su lugar, proporcione el punto de conexión y el valor de audiencia correctos al crear una instancia de un cliente. Por ejemplo:

import { DefaultAzureCredential } from "@azure/identity";
import { LogsQueryClient } from "@azure/monitor-query-logs";

const credential = new DefaultAzureCredential();

// Create a LogsQueryClient
const logsQueryClient: LogsQueryClient = new LogsQueryClient(credential, {
  endpoint: "https://api.loganalytics.azure.cn/v1",
  audience: "https://api.loganalytics.azure.cn/.default",
});

Ejecución de la consulta

Para obtener ejemplos de consultas de registros, consulte la sección Ejemplos .

Conceptos clave

Registra los límites y los límites de frecuencia de consulta

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 obtener más información, consulte API de consulta.

Ejemplos

• Consulta de registros
  • Consulta de registros centrados en el área de trabajo
  • Consulta de registros centrados en recursos
  • Respuesta a la consulta de control de registros
• Consulta de registros por lotes
  • Respuesta a consulta por lotes de registros de control
• Escenarios avanzados de consulta de registros
  • Establecer el tiempo de espera de consulta de registros
  • Consulta de varias áreas de trabajo
  • Incluir estadísticas
  • Incluir visualización

Consulta de registros

Se LogsQueryClient puede usar para consultar un área de trabajo de Log Analytics mediante el lenguaje de consulta Kusto. Se timespan.duration puede especificar como una cadena en un formato de duración ISO 8601. Puede utilizar las Durations constantes proporcionadas para algunas duraciones ISO 8601 de uso común.

Puede consultar los registros mediante el identificador del área de trabajo de Log Analytics o el identificador de recurso de Azure. El resultado se devuelve como una tabla con una colección de filas.

Consulta de registros centrados en el área de trabajo

Para consultar por ID de área de trabajo, use el LogsQueryClient.queryWorkspace método:

import { LogsQueryClient, Durations, LogsQueryResultStatus } from "@azure/monitor-query-logs";
import { DefaultAzureCredential } from "@azure/identity";

const azureLogAnalyticsWorkspaceId = "<workspace_id>";
const logsQueryClient = new LogsQueryClient(new DefaultAzureCredential());

const kustoQuery = "AppEvents | limit 1";
const result = await logsQueryClient.queryWorkspace(azureLogAnalyticsWorkspaceId, kustoQuery, {
  duration: Durations.twentyFourHours,
});

if (result.status === LogsQueryResultStatus.Success) {
  const tablesFromResult = result.tables;

  if (tablesFromResult.length === 0) {
    console.log(`No results for query '${kustoQuery}'`);
    return;
  }
  console.log(`This query has returned table(s) - `);
  processTables(tablesFromResult);
} else {
  console.log(`Error processing the query '${kustoQuery}' - ${result.partialError}`);
  if (result.partialTables.length > 0) {
    console.log(`This query has also returned partial data in the following table(s) - `);
    processTables(result.partialTables);
  }
}

Consulta de registros centrados en recursos

En el ejemplo siguiente se muestra cómo consultar registros directamente desde un recurso de Azure. Aquí, se usa el queryResource método y se pasa un identificador de recurso de Azure. Por ejemplo: /subscriptions/{subscription-id}/resourceGroups/{resource-group-name}/providers/{resource-provider}/{resource-type}/{resource-name}.

Para buscar el identificador de recurso:

1. Vaya a la página del recurso en 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.

import { DefaultAzureCredential } from "@azure/identity";
import { LogsQueryClient, Durations, LogsQueryResultStatus } from "@azure/monitor-query-logs";

const logsResourceId = "<the Resource Id for your logs resource>";

const tokenCredential = new DefaultAzureCredential();
const logsQueryClient = new LogsQueryClient(tokenCredential);

const kustoQuery = `MyTable_CL | summarize count()`;

console.log(`Running '${kustoQuery}' over the last One Hour`);
const queryLogsOptions = {
  // explicitly control the amount of time the server can spend processing the query.
  serverTimeoutInSeconds: 600, // sets the timeout to 10 minutes
  // optionally enable returning additional statistics about the query's execution.
  // (by default, this is off)
  includeQueryStatistics: true,
};

const result = await logsQueryClient.queryResource(
  logsResourceId,
  kustoQuery,
  { duration: Durations.sevenDays },
  queryLogsOptions,
);

console.log(`Results for query '${kustoQuery}'`);

if (result.status === LogsQueryResultStatus.Success) {
  const tablesFromResult = result.tables;

  if (tablesFromResult.length === 0) {
    console.log(`No results for query '${kustoQuery}'`);
    return;
  }
  console.log(`This query has returned table(s) - `);
  processTables(tablesFromResult);
} else {
  console.log(`Error processing the query '${kustoQuery}' - ${result.partialError}`);
  if (result.partialTables.length > 0) {
    console.log(`This query has also returned partial data in the following table(s) - `);
    processTables(result.partialTables);
  }
}

Control de la respuesta de consulta de registros

La queryWorkspace función de LogsQueryClient devuelve un LogsQueryResult objeto. El tipo de objeto puede ser LogsQuerySuccessfulResult o LogsQueryPartialResult. Esta es una jerarquía de la respuesta:

LogsQuerySuccessfulResult
|---statistics
|---visualization
|---status ("Success")
|---tables (list of `LogsTable` objects)
    |---name
    |---rows
    |---columnDescriptors (list of `LogsColumn` objects)
        |---name
        |---type

LogsQueryPartialResult
|---statistics
|---visualization
|---status ("PartialFailure")
|---partialError
    |--name
    |--code
    |--message
    |--stack
|---partialTables (list of `LogsTable` objects)
    |---name
    |---rows
    |---columnDescriptors (list of `LogsColumn` objects)
        |---name
        |---type

Por ejemplo, para controlar una respuesta con tablas:

function processTables(tablesFromResult) {
  for (const table of tablesFromResult) {
    const columnHeaderString = table.columnDescriptors
      .map((column) => `${column.name}(${column.type}) `)
      .join("| ");
    console.log("| " + columnHeaderString);
    for (const row of table.rows) {
      const columnValuesString = row.map((columnValue) => `'${columnValue}' `).join("| ");
      console.log("| " + columnValuesString);
    }
  }
}

Puede encontrar una muestra completa 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 BatchQuery objetos.

import { DefaultAzureCredential } from "@azure/identity";
import { LogsQueryClient, LogsQueryResultStatus } from "@azure/monitor-query-logs";

const monitorWorkspaceId = "<workspace_id>";

const tokenCredential = new DefaultAzureCredential();
const logsQueryClient = new LogsQueryClient(tokenCredential);

const kqlQuery = "AppEvents | project TimeGenerated, Name, AppRoleInstance | limit 1";
const queriesBatch = [
  {
    workspaceId: monitorWorkspaceId,
    query: kqlQuery,
    timespan: { duration: "P1D" },
  },
  {
    workspaceId: monitorWorkspaceId,
    query: "AzureActivity | summarize count()",
    timespan: { duration: "PT1H" },
  },
  {
    workspaceId: monitorWorkspaceId,
    query:
      "AppRequests | take 10 | summarize avgRequestDuration=avg(DurationMs) by bin(TimeGenerated, 10m), _ResourceId",
    timespan: { duration: "PT1H" },
  },
  {
    workspaceId: monitorWorkspaceId,
    query: "AppRequests | take 2",
    timespan: { duration: "PT1H" },
    includeQueryStatistics: true,
  },
];

const result = await logsQueryClient.queryBatch(queriesBatch);

if (result == null) {
  throw new Error("No response for query");
}

let i = 0;
for (const response of result) {
  console.log(`Results for query with query: ${queriesBatch[i]}`);
  if (response.status === LogsQueryResultStatus.Success) {
    console.log(
      `Printing results from query '${queriesBatch[i].query}' for '${queriesBatch[i].timespan}'`,
    );
    processTables(response.tables);
  } else if (response.status === LogsQueryResultStatus.PartialFailure) {
    console.log(
      `Printing partial results from query '${queriesBatch[i].query}' for '${queriesBatch[i].timespan}'`,
    );
    processTables(response.partialTables);
    console.log(
      ` Query had errors:${response.partialError.message} with code ${response.partialError.code}`,
    );
  } else {
    console.log(`Printing errors from query '${queriesBatch[i].query}'`);
    console.log(` Query had errors:${response.message} with code ${response.code}`);
  }
  // next query
  i++;
}

Control de la respuesta de consulta por lotes de registros

La queryBatch función de LogsQueryClient devuelve un LogsQueryBatchResult objeto. LogsQueryBatchResult Contiene una lista de objetos con los siguientes tipos posibles:

• LogsQueryPartialResult
• LogsQuerySuccessfulResult
• LogsQueryError

Esta es una jerarquía de la respuesta:

LogsQuerySuccessfulResult
|---statistics
|---visualization
|---status ("Success")
|---tables (list of `LogsTable` objects)
    |---name
    |---rows
    |---columnDescriptors (list of `LogsColumn` objects)
        |---name
        |---type

LogsQueryPartialResult
|---statistics
|---visualization
|---status ("PartialFailure")
|---partialError
    |--name
    |--code
    |--message
    |--stack
|---partialTables (list of `LogsTable` objects)
    |---name
    |---rows
    |---columnDescriptors (list of `LogsColumn` objects)
        |---name
        |---type

LogsQueryError
|--name
|--code
|--message
|--stack
|--status ("Failure")

Por ejemplo, el código siguiente controla una respuesta de consulta de registros por lotes:

import { LogsQueryResultStatus } from "@azure/monitor-query-logs";

async function processBatchResult(result, queriesBatch) {
  let i = 0;
  for (const response of result) {
    console.log(`Results for query with query: ${queriesBatch[i]}`);
    if (response.status === LogsQueryResultStatus.Success) {
      console.log(
        `Printing results from query '${queriesBatch[i].query}' for '${queriesBatch[i].timespan}'`,
      );
      processTables(response.tables);
    } else if (response.status === LogsQueryResultStatus.PartialFailure) {
      console.log(
        `Printing partial results from query '${queriesBatch[i].query}' for '${queriesBatch[i].timespan}'`,
      );
      processTables(response.partialTables);
      console.log(
        ` Query had errors:${response.partialError.message} with code ${response.partialError.code}`,
      );
    } else {
      console.log(`Printing errors from query '${queriesBatch[i].query}'`);
      console.log(` Query had errors:${response.message} with code ${response.code}`);
    }
    // next query
    i++;
  }
}
function processTables(tablesFromResult) {
  for (const table of tablesFromResult) {
    const columnHeaderString = table.columnDescriptors
      .map((column) => `${column.name}(${column.type}) `)
      .join("| ");
    console.log("| " + columnHeaderString);
    for (const row of table.rows) {
      const columnValuesString = row.map((columnValue) => `'${columnValue}' `).join("| ");
      console.log("| " + columnValuesString);
    }
  }
}

Puede encontrar una muestra completa aquí.

Escenarios de consulta de registros avanzados

Establecimiento del tiempo de espera de consulta de registros

Algunas consultas de registros tardan más de 3 minutos en ejecutarse. El tiempo de espera predeterminado del servidor es de 3 minutos. Puede aumentar el tiempo de espera del servidor a un máximo de 10 minutos. En el ejemplo siguiente, la propiedad del LogsQueryOptions objeto se utiliza para aumentar el tiempo de serverTimeoutInSeconds espera del servidor a 10 minutos:

import { DefaultAzureCredential } from "@azure/identity";
import { LogsQueryClient, Durations } from "@azure/monitor-query-logs";

const azureLogAnalyticsWorkspaceId = "<workspace_id>";

const tokenCredential = new DefaultAzureCredential();
const logsQueryClient = new LogsQueryClient(tokenCredential);

const kqlQuery = "AppEvents | project TimeGenerated, Name, AppRoleInstance | limit 1";

// setting optional parameters
const queryLogsOptions = {
  // explicitly control the amount of time the server can spend processing the query.
  serverTimeoutInSeconds: 600, // 600 seconds = 10 minutes
};

const result = await logsQueryClient.queryWorkspace(
  azureLogAnalyticsWorkspaceId,
  kqlQuery,
  { duration: Durations.twentyFourHours },
  queryLogsOptions,
);

const status = result.status;

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:

• workspaceId - El primer ID de área de trabajo (principal).
• additionalWorkspaces - Una lista de espacios de trabajo, excluyendo el espacio de trabajo proporcionado en el workspaceId parámetro. Los elementos de lista del parámetro pueden constar de los siguientes formatos de identificador:
  • Nombres de área de trabajo calificados
  • Identificadores del área de trabajo
  • Identificadores de recursos de Azure

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

import { DefaultAzureCredential } from "@azure/identity";
import { LogsQueryClient, Durations } from "@azure/monitor-query-logs";

const azureLogAnalyticsWorkspaceId = "<workspace_id>";

const tokenCredential = new DefaultAzureCredential();
const logsQueryClient = new LogsQueryClient(tokenCredential);

const kqlQuery = "AppEvents | project TimeGenerated, Name, AppRoleInstance | limit 1";

// setting optional parameters
const queryLogsOptions = {
  additionalWorkspaces: ["<workspace2>", "<workspace3>"],
};

const result = await logsQueryClient.queryWorkspace(
  azureLogAnalyticsWorkspaceId,
  kqlQuery,
  { duration: Durations.twentyFourHours },
  queryLogsOptions,
);

const status = result.status;

Para ver los resultados de cada área de trabajo, use la TenantId columna para ordenar los resultados o filtrarlos en la consulta de Kusto.

Ordenar resultados por TenantId

AppEvents | order by TenantId

Filtrar resultados por TenantId

AppEvents | filter TenantId == "<workspace2>"

Puede encontrar una muestra completa 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 la propiedad LogsQueryOptions.includeQueryStatistics 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:

import { LogsQueryClient, Durations } from "@azure/monitor-query-logs";
import { DefaultAzureCredential } from "@azure/identity";

const monitorWorkspaceId = "<workspace_id>";
const logsQueryClient = new LogsQueryClient(new DefaultAzureCredential());
const kustoQuery = "AzureActivity | top 10 by TimeGenerated";

const result = await logsQueryClient.queryWorkspace(
  monitorWorkspaceId,
  kustoQuery,
  { duration: Durations.oneDay },
  {
    includeQueryStatistics: true,
  },
);

console.log(`Results for query '${kustoQuery}'`);

Dado que la estructura de la carga varía según la statistics consulta, se utiliza un Record<string, unknown> tipo de valor devuelto. Contiene la respuesta JSON sin procesar. Las estadísticas se encuentran dentro de la query propiedad del JSON. Por ejemplo:

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

Incluir visualización

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

1. Establezca la propiedad LogsQueryOptions.includeVisualization en true.
2. Acceda al visualization campo dentro del LogsQueryResult objeto.

Por ejemplo:

import { LogsQueryClient, Durations } from "@azure/monitor-query-logs";
import { DefaultAzureCredential } from "@azure/identity";

const monitorWorkspaceId = "<workspace_id>";
const logsQueryClient = new LogsQueryClient(new DefaultAzureCredential());

const result = await logsQueryClient.queryWorkspace(
  monitorWorkspaceId,
  `StormEvents
        | summarize event_count = count() by State
        | where event_count > 10
        | project State, event_count
        | render columnchart`,
  { duration: Durations.oneDay },
  {
    includeVisualization: true,
  },
);

console.log("visualization result:", result.visualization);

Dado que la estructura de la carga varía según la visualization consulta, se utiliza un Record<string, unknown> tipo de valor devuelto. Contiene la respuesta JSON sin procesar. Por ejemplo:

{
  "visualization": "columnchart",
  "title": "the chart title",
  "accumulate": false,
  "isQuerySorted": false,
  "kind": null,
  "legend": null,
  "series": null,
  "yMin": "NaN",
  "yMax": "NaN",
  "xAxis": null,
  "xColumn": null,
  "xTitle": "x axis title",
  "yAxis": null,
  "yColumns": null,
  "ySplit": null,
  "yTitle": null,
  "anomalyColumns": null
}

Solución de problemas

Para diagnosticar varios escenarios de error, consulte la guía de solución de problemas.

Pasos siguientes

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

Contribución

Si desea contribuir a esta biblioteca, lea la guía de contribución de para obtener más información sobre cómo compilar y probar el código.

Las pruebas de este módulo son una combinación de pruebas dinámicas y unitarias, que requieren que tenga una instancia de Azure Monitor. Para ejecutar las pruebas, deberá ejecutar:

1. rush update
2. rush build -t @azure/monitor-query-logs
3. cd into sdk/monitor/monitor-query
4. Copie el sample.env archivo en .env
5. Abra el .env archivo en un editor y rellene los valores.
6. npm run test.

Para obtener más detalles, consulte nuestra carpeta de pruebas .

Proyectos relacionados

• SDK de Microsoft Azure para JavaScript
• Azure Monitor