Klientbibliotek för Azure Monitor-frågeloggar för JavaScript – version 1.0.0

2025-07-31

Klientbiblioteket Azure Monitor Query Logs används för att köra skrivskyddade frågor mot Azure Monitor dataplattform för loggar:

Loggar – Samlar in och organiserar logg- och prestandadata från övervakade resurser. Data från olika källor, till exempel plattformsloggar från Azure-tjänster, logg- och prestandadata från agenter för virtuella datorer samt användnings- och prestandadata från appar kan konsolideras till en enda Azure Log Analytics-arbetsyta. De olika datatyperna kan analyseras tillsammans med hjälp av Kusto-frågespråk.

Migrera från @azure/monitor-query rådgivande ⚠️

Kolla in migreringsguiden för detaljerade instruktioner om hur du uppdaterar programkoden från det ursprungliga @azure/monitor-query paketet till @azure/monitor-query-logs biblioteket.

Resurser:

Komma igång

Miljöer som stöds

LTS-versioner av Node.js
De senaste versionerna av Safari, Chrome, Microsoft Edge och Firefox

Mer information finns i vår supportpolicy.

Förutsättningar

En prenumeration på Azure
En TokenCredential- implementering, till exempel en autentiseringstyp för Azure Identity-biblioteket.
För att köra frågor mot loggar behöver du något av följande:
- En Azure Log Analytics-arbetsyta
- En Azure-resurs av något slag (lagringskonto, Key Vault, Cosmos DB osv.)

Installera paketet

Installera Azure Monitor Query-klientbiblioteket för JavaScript med npm:

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

Skapa klienten

En autentiserad klient krävs för att fråga loggar. För att autentisera använder följande exempel DefaultAzureCredential från @azure/identity paketet.

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

const credential = new DefaultAzureCredential();

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

Konfigurera klienten för Azures nationella moln

Som standard är bibliotekets klienter konfigurerade för att använda det offentliga Azure-molnet. Om du vill använda ett nationellt moln i stället anger du rätt slutpunkts- och målgruppsvärde när du instansierar en klient. Till exempel:

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

Köra frågan

Exempel på loggfrågor finns i avsnittet Exempel .

Viktiga begrepp

Loggar frågefrekvensgränser och begränsning

Log Analytics-tjänsten tillämpar begränsningar när begärandefrekvensen är för hög. Gränser, till exempel det maximala antalet rader som returneras, tillämpas också på Kusto-frågorna. Mer information finns i Fråge-API.

Exempel

Loggar fråga
Fråga för batchloggar
- Hantera loggar batchfrågesvar
Avancerade frågescenarier för loggar

Loggfråga

kan LogsQueryClient användas för att fråga en Log Analytics-arbetsyta med hjälp av Kusto-frågespråk. kan timespan.duration anges som en sträng i ett ISO 8601-varaktighetsformat. Du kan använda konstanterna Durations för vissa vanliga ISO 8601-varaktigheter.

Du kan köra frågor mot loggar via Log Analytics-arbetsyte-ID eller Azure-resurs-ID. Resultatet returneras som en tabell med en samling rader.

Fråga om arbetsytecentrerade loggar

Om du LogsQueryClient.queryWorkspace vill fråga efter arbetsyte-ID använder du metoden:

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

Fråga om resurscentrerade loggar

I följande exempel visas hur du frågar efter loggar direkt från en Azure-resurs. queryResource Här används metoden och ett Azure-resurs-ID skickas. Till exempel /subscriptions/{subscription-id}/resourceGroups/{resource-group-name}/providers/{resource-provider}/{resource-type}/{resource-name}.

Så här hittar du resurs-ID:t:

Gå till resurssidan i Azure-portalen.
På bladet Översikt väljer du länken JSON-vy .
I den resulterande JSON-filen kopierar du värdet för egenskapen id .

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

Hantera loggfrågesvar

Funktionen queryWorkspace för LogsQueryClient returnerar ett LogsQueryResult objekt. Objekttypen kan vara LogsQuerySuccessfulResult eller LogsQueryPartialResult. Här är en hierarki med svaret:

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

Till exempel för att hantera ett svar med tabeller:

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

Ett fullständigt exempel finns här.

Fråga om Batch-loggar

I följande exempel visas hur du skickar flera frågor samtidigt med hjälp av BATCH-fråge-API:et. Frågorna kan representeras som en lista med BatchQuery objekt.

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

Hantera batchfrågesvar för loggar

Funktionen queryBatch för LogsQueryClient returnerar ett LogsQueryBatchResult objekt. LogsQueryBatchResult Innehåller en lista över objekt med följande möjliga typer:

LogsQueryPartialResult
LogsQuerySuccessfulResult
LogsQueryError

Här är en hierarki med svaret:

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

Följande kod hanterar till exempel ett frågesvar för batchloggar:

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

Ett fullständigt exempel finns här.

Frågescenarier för avancerade loggar

Ange tidsgräns för loggfrågor

Vissa loggfrågor tar längre tid än 3 minuter att köra. Standardtidsgränsen för servern är 3 minuter. Du kan öka tidsgränsen för servern till högst 10 minuter. I följande exempel LogsQueryOptions används objektets egenskap för att öka serverns serverTimeoutInSeconds tidsgräns till 10 minuter:

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;

Sök i flera arbetsytor

Samma loggfråga kan köras på flera Log Analytics-arbetsytor. Förutom Kusto-frågan krävs följande parametrar:

workspaceId - Det första (primära) arbetsyte-ID:t.
additionalWorkspaces - En lista över arbetsytor, exklusive den arbetsyta som anges i parametern workspaceId . Parameterns listobjekt kan bestå av följande identifierarformat:
- Namn på kvalificerade arbetsytor
- Arbetsyte-ID:t
- Azure-resurs-ID:t

Följande fråga körs till exempel på tre arbetsytor:

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;

Om du vill visa resultaten för varje arbetsyta använder du kolumnen TenantId för att antingen ordna resultaten eller filtrera dem i Kusto-frågan.

Orderresultat efter TenantId

AppEvents | order by TenantId

Filtrera resultat efter TenantId

AppEvents | filter TenantId == "<workspace2>"

Ett fullständigt exempel finns här.

Ta med statistik

Så här hämtar du körningsstatistik för loggar, till exempel processor- och minnesförbrukning:

Ange egenskapen LogsQueryOptions.includeQueryStatistics till true.
statistics Öppna fältet inuti LogsQueryResult objektet.

I följande exempel skrivs frågekörningstiden ut:

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

Eftersom nyttolastens statistics struktur varierar beroende på fråga används en Record<string, unknown> returtyp. Den innehåller det råa JSON-svaret. Statistiken query finns i egenskapen för JSON. Till exempel:

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

Inkludera visualisering

Så här hämtar du visualiseringsdata för loggfrågor med hjälp av renderingsoperatorn:

Ange egenskapen LogsQueryOptions.includeVisualization till true.
visualization Öppna fältet inuti LogsQueryResult objektet.

Till exempel:

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

Eftersom nyttolastens visualization struktur varierar beroende på fråga används en Record<string, unknown> returtyp. Den innehåller det råa JSON-svaret. Till exempel:

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

Felsökning

Information om hur du diagnostiserar olika felscenarier finns i felsökningsguiden.

Nästa steg

Mer information om Azure Monitor finns i dokumentationen för Azure Monitor-tjänsten.

Bidrag

Om du vill bidra till det här biblioteket kan du läsa bidragsguide för att lära dig mer om hur du skapar och testar koden.

Den här modulens tester är en blandning av live- och enhetstester, som kräver att du har en Azure Monitor-instans. Om du vill köra testerna måste du köra:

rush update
rush build -t @azure/monitor-query-logs
cd into sdk/monitor/monitor-query
Kopiera filen sample.env till .env
.env Öppna filen i en redigerare och fyll i värdena.
npm run test.

För mer information, se vår testmapp .

Feedback

Var den här sidan till hjälp?

Dela via

Klientbibliotek för Azure Monitor-frågeloggar för JavaScript – version 1.0.0

Migrera från @azure/monitor-query rådgivande ⚠️

Komma igång

Miljöer som stöds

Förutsättningar

Installera paketet

Skapa klienten

Konfigurera klienten för Azures nationella moln

Köra frågan

Viktiga begrepp

Loggar frågefrekvensgränser och begränsning

Exempel

Loggfråga

Fråga om arbetsytecentrerade loggar

Fråga om resurscentrerade loggar

Hantera loggfrågesvar

Fråga om Batch-loggar

Hantera batchfrågesvar för loggar

Frågescenarier för avancerade loggar

Ange tidsgräns för loggfrågor

Sök i flera arbetsytor

Ta med statistik

Inkludera visualisering

Felsökning

Nästa steg

Bidrag

Relaterade projekt

Feedback

Ytterligare resurser