Partilhar via

Biblioteca de cliente de Logs de Consulta do Azure Monitor para JavaScript - versão 1.0.0

A biblioteca de cliente de Logs de Consulta do Azure Monitor é usada para executar consultas somente leitura na plataforma de dados de Logs 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 espaço de trabalho do Azure Log Analytics. Os vários tipos de dados podem ser analisados em conjunto usando a Kusto Query Language.

Migrando de @azure/monitor-query advisory ⚠️

Confira o Guia de Migração para obter instruções detalhadas sobre como atualizar o código do aplicativo do pacote original @azure/monitor-query para a @azure/monitor-query-logs biblioteca.

Recursos:

Como Começar

Ambientes suportados

Para mais informações, consulte a nossa política de suporte.

Pré-requisitos

  • Uma assinatura do Azure
  • Uma implementação de TokenCredential, como um tipo de credencial da biblioteca Azure Identity do .
  • Para consultar Logs, você precisa de uma das seguintes coisas:

Instale o pacote

Instale a biblioteca de cliente do Azure Monitor Query para JavaScript com npm:

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

Criar o cliente

Um cliente autenticado é necessário para consultar Logs. Para autenticar, o exemplo a seguir usa DefaultAzureCredential do pacote @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);

Configurar o cliente para a nuvem soberana do Azure

Por padrão, os clientes da biblioteca são configurados para usar a Nuvem Pública do Azure. Para usar uma nuvem soberana em vez disso, forneça o valor correto de ponto de extremidade e audiência ao instanciar um cliente. Por exemplo:

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

Executar a consulta

Para obter exemplos de consultas Logs, consulte a seção Exemplos .

Conceitos-chave

Registra limites de taxa de consulta e limitação

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.

Exemplos

Consulta de logs

O LogsQueryClient pode ser usado para consultar um espaço de trabalho do Log Analytics usando a Kusto Query Language. O timespan.duration pode ser especificado como uma cadeia de caracteres em um formato de duração ISO 8601. Você pode usar as Durations constantes fornecidas para algumas durações ISO 8601 comumente usadas.

Você pode consultar logs pela ID do espaço de trabalho do Log Analytics ou pela ID do recurso do Azure. O resultado é retornado como uma tabela com uma coleção de linhas.

Consulta de logs centrada no espaço de trabalho

Para consultar por ID de espaço de trabalho, use o 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 logs centrada em recursos

O exemplo a seguir demonstra como consultar logs diretamente de um recurso do Azure. Aqui, o queryResource método é usado e uma ID de recurso do Azure é passada. Por exemplo, /subscriptions/{subscription-id}/resourceGroups/{resource-group-name}/providers/{resource-provider}/{resource-type}/{resource-name}.

Para encontrar o ID do recurso:

  1. Navegue até a página do seu recurso no portal do Azure.
  2. Na folha Visão geral , selecione o link Exibição JSON .
  3. No JSON resultante, copie o id valor da propriedade.
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);
  }
}

Manipular a resposta da consulta de logs

A queryWorkspace função de LogsQueryClient retorna um LogsQueryResult objeto. O tipo de objeto pode ser LogsQuerySuccessfulResult ou LogsQueryPartialResult. Aqui está uma hierarquia da resposta:

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 exemplo, para manipular uma resposta com tabelas:

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

Uma amostra completa pode ser encontrada aqui.

Consulta de logs em 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 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++;
}

Manipular logs de resposta de consulta em lote

A queryBatch função de LogsQueryClient retorna um LogsQueryBatchResult objeto. LogsQueryBatchResult Contém uma lista de objetos com os seguintes tipos possíveis:

  • LogsQueryPartialResult
  • LogsQuerySuccessfulResult
  • LogsQueryError

Aqui está uma hierarquia da resposta:

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 exemplo, o código a seguir manipula uma resposta de consulta de logs em lote:

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

Uma amostra completa pode ser encontrada aqui.

Cenários avançados de consulta de logs

Definir tempo limite de consulta de logs

Algumas consultas de logs levam mais de 3 minutos para serem executadas. O tempo limite padrão do servidor é de 3 minutos. Você pode aumentar o tempo limite do servidor para um máximo de 10 minutos. No exemplo a seguir, a LogsQueryOptions propriedade do serverTimeoutInSeconds objeto é usada para aumentar o tempo limite do servidor para 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;

Consultar vários espaços de trabalho

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

  • workspaceId - O primeiro ID de espaço de trabalho (principal).
  • additionalWorkspaces - Uma lista de espaços de trabalho, excluindo o espaço de trabalho fornecido no workspaceId parâmetro. Os itens da lista do parâmetro podem consistir nos seguintes formatos de identificador:
    • Nomes de espaços de trabalho qualificados
    • IDs do espaço de trabalho
    • IDs de recursos do Azure

Por exemplo, a consulta a seguir é executada em três espaços de trabalho:

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 exibir os resultados de cada espaço de trabalho, use a TenantId coluna para ordenar os resultados ou filtrá-los na consulta Kusto.

Resultados da encomenda por TenantId

AppEvents | order by TenantId

Filtrar resultados por TenantId

AppEvents | filter TenantId == "<workspace2>"

Uma amostra completa pode ser encontrada aqui.

Incluir estatísticas

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

  1. Defina a propriedade LogsQueryOptions.includeQueryStatistics como true.
  2. Acesse o statistics campo dentro do LogsQueryResult objeto.

O exemplo a seguir imprime o tempo de execução da 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}'`);

Como a estrutura da carga varia de acordo com a statistics consulta, um Record<string, unknown> tipo de retorno é usado. Ele contém a resposta JSON bruta. As estatísticas são encontradas dentro da query propriedade do JSON. 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 LogsQueryOptions.includeVisualization como true.
  2. Acesse o visualization campo dentro do LogsQueryResult objeto.

Por exemplo:

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

Como a estrutura da carga varia de acordo com a visualization consulta, um Record<string, unknown> tipo de retorno é usado. Ele contém a resposta JSON bruta. Por exemplo:

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

Solução de problemas

Para diagnosticar vários cenários de falha, consulte o guia de solução de problemas.

Próximos passos

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

Contribuir

Se você quiser contribuir para esta biblioteca, leia o guia de contribuição para saber mais sobre como criar e testar o código.

Os testes deste módulo são uma mistura de testes ao vivo e de unidade, que exigem que você tenha uma instância do Azure Monitor. Para executar os testes, você precisará executar:

  1. rush update
  2. rush build -t @azure/monitor-query-logs
  3. cd into sdk/monitor/monitor-query
  4. Copie o sample.env ficheiro para .env
  5. Abra o .env arquivo em um editor e preencha os valores.
  6. npm run test.

Para mais detalhes, consulte a nossa pasta de testes .

  • Last updated on