Delen via

Azure Monitor Query Logs-clientbibliotheek voor JavaScript - versie 1.0.0

De clientbibliotheek van Azure Monitor Query Logs wordt gebruikt om alleen-lezen query's uit te voeren op het Logs-gegevensplatform van Azure Monitor:

  • Logboeken - Verzamelt en organiseert logboek- en prestatiegegevens van bewaakte bronnen. Gegevens uit verschillende bronnen, zoals platformlogboeken van Azure-services, logboek- en prestatiegegevens van agents voor virtuele machines en gebruiks- en prestatiegegevens van apps, kunnen worden geconsolideerd in één Azure Log Analytics-werkruimte. De verschillende gegevenstypen kunnen samen worden geanalyseerd met behulp van de Kusto-querytaal.

Migreren van @azure/monitor-query advies ⚠️

Bekijk de migratiehandleiding voor gedetailleerde instructies over het bijwerken van uw applicatiecode van het oorspronkelijke @azure/monitor-query pakket naar de @azure/monitor-query-logs bibliotheek.

Bronnen:

Aan de slag

Ondersteunde omgevingen

Zie ons ondersteuningsbeleid voor meer informatie.

Vereiste voorwaarden

Installeer het pakket

Installeer de Azure Monitor Query-clientbibliotheek voor JavaScript met npm:

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

De client maken

Een geverifieerde client is vereist om query's uit te voeren op logboeken. Voor verificatie wordt in het volgende voorbeeld DefaultAzureCredential uit het pakket @azure/identity gebruikt.

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

const credential = new DefaultAzureCredential();

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

Client configureren voor onafhankelijke Azure-cloud

De clients van de bibliotheek zijn standaard geconfigureerd voor het gebruik van de openbare Azure-cloud. Als u in plaats daarvan een onafhankelijke cloud wilt gebruiken, geeft u het juiste eindpunt en de doelgroepwaarde op bij het instantiëren van een client. Voorbeeld:

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

De query uitvoeren

Zie de sectie Voorbeelden voor voorbeelden van logboekquery's.

Belangrijke concepten

Logboeken queryfrequentielimieten en bandbreedtebeperking

De Log Analytics-service past beperking toe wanneer de aanvraagsnelheid te hoog is. Limieten, zoals het maximum aantal geretourneerde rijen, worden ook toegepast op de Kusto-query's. Zie Query-API voor meer informatie.

Voorbeelden

Logboekquery

Het LogsQueryClient kan worden gebruikt om een query uit te voeren op een Log Analytics-werkruimte met behulp van de Kusto-querytaal. Het timespan.duration kan worden gespecificeerd als een tekenreeks in een ISO 8601-duurformaat. U kunt de Durations constanten gebruiken die worden gegeven voor een aantal veelgebruikte ISO 8601-duurperioden.

U kunt query's uitvoeren op logboeken op log analytics-werkruimte-id of Azure-resource-id. Het resultaat wordt geretourneerd als een tabel met een verzameling rijen.

Query voor werkruimtegerichte logboeken

Gebruik de LogsQueryClient.queryWorkspace volgende methode om een query uit te voeren op basis van werkruimte-id:

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 voor resourcegerichte logboeken

In het volgende voorbeeld ziet u hoe u logboeken rechtstreeks vanuit een Azure-resource opvraagt. Hier wordt de queryResource methode gebruikt en wordt een Azure-resource-id doorgegeven. Bijvoorbeeld: /subscriptions/{subscription-id}/resourceGroups/{resource-group-name}/providers/{resource-provider}/{resource-type}/{resource-name}.

De resource-id zoeken:

  1. Navigeer naar de pagina van uw resource in Azure Portal.
  2. Selecteer op de blade Overzicht de koppeling JSON-weergave .
  3. Kopieer in de resulterende JSON de waarde van de id eigenschap.
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);
  }
}

Logboekenqueryantwoord verwerken

De queryWorkspace functie van LogsQueryClient geeft een LogsQueryResult object terug. Het objecttype kan of zijn LogsQuerySuccessfulResultLogsQueryPartialResult. Hier volgt een hiërarchie van het antwoord:

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

Als u bijvoorbeeld een antwoord wilt verwerken met tabellen:

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

Een volledig voorbeeld is hier te vinden.

Query voor Batch-logboeken

In het volgende voorbeeld ziet u hoe u meerdere query's tegelijk verzendt met behulp van de batchquery-API. De query's kunnen worden weergegeven als een lijst met BatchQuery objecten.

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

Batchqueryantwoorden verwerken in logboeken

De queryBatch functie van LogsQueryClient geeft een LogsQueryBatchResult object terug. LogsQueryBatchResult Bevat een lijst van objecten met de volgende mogelijke typen:

  • LogsQueryPartialResult
  • LogsQuerySuccessfulResult
  • LogsQueryError

Hier volgt een hiërarchie van het antwoord:

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

Met de volgende code wordt bijvoorbeeld een queryantwoord voor batchlogboeken verwerkt:

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

Een volledig voorbeeld is hier te vinden.

Geavanceerde queryscenario's voor logboeken

Time-out voor logboekquery's instellen

Het uitvoeren van sommige logboekquery's duurt langer dan 3 minuten. De standaardtime-out voor de server is 3 minuten. U kunt de time-out van de server verhogen tot maximaal 10 minuten. In het volgende voorbeeld wordt de eigenschap van LogsQueryOptions het serverTimeoutInSeconds object gebruikt om de time-out van de server te verlengen tot 10 minuten:

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;

Query's uitvoeren op meerdere werkruimten

Dezelfde logboekquery kan worden uitgevoerd in meerdere Log Analytics-werkruimten. Naast de Kusto-query zijn de volgende parameters vereist:

  • workspaceId - De eerste (primaire) werkruimte-ID.
  • additionalWorkspaces - Een lijst met werkruimten, met uitzondering van de werkruimte die in de workspaceId parameter is opgegeven. De lijstitems van de parameter kunnen bestaan uit de volgende id-indelingen:
    • Gekwalificeerde werkruimtenamen
    • Werkruimte-id's
    • Azure-resource-id's

De volgende query wordt bijvoorbeeld uitgevoerd in drie werkruimten:

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;

Als u de resultaten voor elke werkruimte wilt weergeven, gebruikt u de TenantId kolom om de resultaten te ordenen of te filteren in de Kusto-query.

Bestel resultaten op TenantId

AppEvents | order by TenantId

Resultaten filteren op TenantId

AppEvents | filter TenantId == "<workspace2>"

Een volledig voorbeeld is hier te vinden.

Statistieken opnemen

Ga als volgende te werk om statistieken over de uitvoering van logboeken op te halen, zoals CPU en geheugenverbruik:

  1. Stel de eigenschap LogsQueryOptions.includeQueryStatistics in op true.
  2. Open het statistics veld in het LogsQueryResult object.

In het volgende voorbeeld wordt de uitvoeringstijd van de query afgedrukt:

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

Omdat de structuur van de statistics payload per query verschilt, wordt een Record<string, unknown> retourtype gebruikt. Het bevat het onbewerkte JSON-antwoord. De statistieken zijn te vinden binnen het query eigendom van de JSON. Voorbeeld:

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

Visualisatie opnemen

Visualisatiegegevens ophalen voor logboekquery's met behulp van de renderoperator:

  1. Stel de eigenschap LogsQueryOptions.includeVisualization in op true.
  2. Open het visualization veld in het LogsQueryResult object.

Voorbeeld:

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

Omdat de structuur van de visualization payload per query verschilt, wordt een Record<string, unknown> retourtype gebruikt. Het bevat het onbewerkte JSON-antwoord. Voorbeeld:

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

Probleemoplossingsproces

Zie de handleiding voor het oplossen van problemen om verschillende foutscenario's te diagnosticeren.

Volgende stappen

Zie de documentatie van de Azure Monitor-service voor meer informatie over Azure Monitor.

Bijdragen

Als u een bijdrage wilt leveren aan deze bibliotheek, leest u de gids voor bijdragen voor meer informatie over het bouwen en testen van de code.

De tests van deze module zijn een combinatie van live- en eenheidstests, waarvoor u een Azure Monitor-exemplaar moet hebben. Als u de tests wilt uitvoeren, moet u het volgende uitvoeren:

  1. rush update
  2. rush build -t @azure/monitor-query-logs
  3. cd into sdk/monitor/monitor-query
  4. Kopieer het sample.env bestand naar .env
  5. Open het .env bestand in een editor en vul de waarden in.
  6. npm run test.

Bekijk voor meer informatie onze testmap.