Condividi tramite

Libreria client dei log di query di Monitoraggio di Azure per JavaScript - versione 1.0.0

La libreria client dei log di query di Monitoraggio di Azure viene usata per eseguire query di sola lettura sulla piattaforma dati Logs di Monitoraggio di Azure:

  • Log : raccoglie e organizza i dati di log e le prestazioni dalle risorse monitorate. I dati provenienti da origini diverse, ad esempio i log della piattaforma dai servizi di Azure, i dati di log e prestazioni dagli agenti di macchine virtuali e i dati sull'utilizzo e le prestazioni dalle app possono essere consolidati in un'unica area di lavoro di Azure Log Analytics. I vari tipi di dati possono essere analizzati insieme usando il linguaggio di query Kusto.

Migrazione dall'advisory @azure/monitor-query⚠️

Consulta la Guida alla migrazione per istruzioni dettagliate su come aggiornare il codice dell'applicazione dal pacchetto originale @azure/monitor-query alla @azure/monitor-query-logs libreria.

Risorse:

Come iniziare

Ambienti supportati

Per ulteriori informazioni, consulta la nostra politica di supporto.

Prerequisiti

Installare il pacchetto

Installare la libreria client di query di Monitoraggio di Azure per JavaScript con npm:

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

Creare il client

Per eseguire query sui log è necessario un client autenticato. Per eseguire l'autenticazione, nell'esempio seguente viene usato DefaultAzureCredential dal pacchetto @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);

Configurare il client per il cloud sovrano di Azure

Per impostazione predefinita, i client della libreria sono configurati per l'uso del cloud pubblico di Azure. Per usare invece un cloud sovrano, fornire il valore corretto dell'endpoint e del gruppo di destinatari durante la creazione di un'istanza di un client. Per esempio:

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

Esecuzione della query

Per esempi di query di log, vedere la sezione Esempi .

Concetti chiave

Limiti di frequenza delle query dei log e limitazione

Il servizio Log Analytics applica la limitazione quando la frequenza delle richieste è troppo elevata. I limiti, ad esempio il numero massimo di righe restituite, vengono applicati anche alle query Kusto. Per ulteriori informazioni, vedere API di query.

Esempi

Query dei log

Può LogsQueryClient essere usato per eseguire query su un'area di lavoro Log Analytics usando il linguaggio di query Kusto. Può timespan.duration essere specificato come stringa in un formato di durata ISO 8601. È possibile utilizzare le Durations costanti fornite per alcune durate ISO 8601 di uso comune.

È possibile eseguire query sui log in base all'ID dell'area di lavoro Log Analytics o all'ID risorsa di Azure. Il risultato viene restituito come tabella con un insieme di righe.

Query dei log incentrata sull'area di lavoro

Per eseguire una query in base all'ID dell'area di lavoro, utilizzare il LogsQueryClient.queryWorkspace metodo:

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

Query dei log incentrata sulle risorse

Nell'esempio seguente viene illustrato come eseguire query sui log direttamente da una risorsa di Azure. In questo caso, viene usato il queryResource metodo e viene passato un ID risorsa di Azure. Ad esempio: /subscriptions/{subscription-id}/resourceGroups/{resource-group-name}/providers/{resource-provider}/{resource-type}/{resource-name}.

Per trovare l'ID risorsa:

  1. Passare alla pagina della risorsa nel portale di Azure.
  2. Nel pannello Panoramica selezionare il collegamento Visualizzazione JSON .
  3. Nel codice JSON risultante copiare il valore della id proprietà.
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);
  }
}

Gestire la risposta alle query dei log

La queryWorkspace funzione di LogsQueryClient restituisce un LogsQueryResult oggetto. Il tipo di oggetto può essere LogsQuerySuccessfulResult o LogsQueryPartialResult. Ecco una gerarchia della risposta:

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

Ad esempio, per gestire una risposta con le tabelle:

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

Un esempio completo può essere trovato qui.

Query dei log batch

Nell'esempio seguente viene illustrato l'invio di più query contemporaneamente utilizzando l'API di query batch. Le query possono essere rappresentate come un elenco di BatchQuery oggetti.

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

Gestire la risposta alle query batch dei log

La queryBatch funzione di LogsQueryClient restituisce un LogsQueryBatchResult oggetto. LogsQueryBatchResult Contiene un elenco di oggetti con i seguenti tipi possibili:

  • LogsQueryPartialResult
  • LogsQuerySuccessfulResult
  • LogsQueryError

Ecco una gerarchia della risposta:

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

Ad esempio, il codice seguente gestisce una risposta alla query dei log batch:

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

Un esempio completo può essere trovato qui.

Scenari avanzati di query dei log

Impostare il timeout delle query dei log

L'esecuzione di alcune query di log richiede più di 3 minuti. Il timeout predefinito del server è di 3 minuti. È possibile aumentare il timeout del server fino a un massimo di 10 minuti. Nell'esempio seguente, la proprietà dell'oggetto LogsQueryOptionsserverTimeoutInSeconds viene utilizzata per aumentare il timeout del server a 10 minuti:

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;

Eseguire query su più aree di lavoro

La stessa query di log può essere eseguita in più aree di lavoro Log Analytics. Oltre alla query Kusto, sono necessari i parametri seguenti:

  • workspaceId - Il primo ID dell'area di lavoro (primario).
  • additionalWorkspaces - Un elenco di aree di lavoro, esclusa l'area di lavoro fornita nel workspaceId parametro. Gli elementi dell'elenco del parametro possono essere costituiti dai seguenti formati di identificatore:
    • Nomi completi dell'area di lavoro
    • ID area di lavoro
    • ID risorsa di Azure

Ad esempio, la query seguente viene eseguita in tre aree di lavoro:

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;

Per visualizzare i risultati per ogni area di lavoro, usare la TenantId colonna per ordinare i risultati o filtrarli nella query Kusto.

Risultati dell'ordine in base a TenantId

AppEvents | order by TenantId

Filtrare i risultati in base a TenantId

AppEvents | filter TenantId == "<workspace2>"

Un esempio completo può essere trovato qui.

Includi statistiche

Per ottenere le statistiche di esecuzione delle query sui log, ad esempio il consumo di CPU e memoria:

  1. Impostare la proprietà LogsQueryOptions.includeQueryStatistics su true.
  2. Accedi al statistics campo all'interno dell'oggetto LogsQueryResult .

Nell'esempio seguente viene stampato il tempo di esecuzione della query:

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

Poiché la struttura del payload varia in base alla statistics query, viene utilizzato un Record<string, unknown> tipo restituito. Contiene la risposta JSON non elaborata. Le statistiche si trovano all'interno query della proprietà del JSON. Per esempio:

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

Includi visualizzazione

Per ottenere i dati di visualizzazione per le query di log utilizzando l'operatore render:

  1. Impostare la proprietà LogsQueryOptions.includeVisualization su true.
  2. Accedi al visualization campo all'interno dell'oggetto LogsQueryResult .

Per esempio:

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

Poiché la struttura del payload varia in base alla visualization query, viene utilizzato un Record<string, unknown> tipo restituito. Contiene la risposta JSON non elaborata. Per esempio:

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

Risoluzione dei problemi

Per diagnosticare vari scenari di errore, vedere la guida alla risoluzione dei problemi.

Passaggi successivi

Per altre informazioni su Monitoraggio di Azure, vedere la documentazione del servizio Monitoraggio di Azure.

Contribuire

Per contribuire a questa libreria, leggere la guida contribuire per altre informazioni su come compilare e testare il codice.

I test di questo modulo sono una combinazione di test live e unit test, che richiedono la presenza di un'istanza di Monitoraggio di Azure. Per eseguire i test, è necessario eseguire:

  1. rush update
  2. rush build -t @azure/monitor-query-logs
  3. cd into sdk/monitor/monitor-query
  4. Copia il sample.env file in .env
  5. Aprire il .env file in un editor e inserire i valori.
  6. npm run test.

Per maggiori dettagli, consulta la nostra cartella dei test .

  • Last updated on