Bagikan melalui

Pustaka klien Log Kueri Azure Monitor untuk JavaScript - versi 1.0.0

Pustaka klien Log Kueri Azure Monitor digunakan untuk menjalankan kueri baca-saja terhadap platform data Log Azure Monitor:

  • Log - Mengumpulkan dan mengatur data log dan performa dari sumber daya yang dipantau. Data dari sumber yang berbeda seperti log platform dari layanan Azure, data log dan performa dari agen komputer virtual, serta data penggunaan dan performa dari aplikasi dapat dikonsolidasikan ke dalam satu ruang kerja Azure Log Analytics. Berbagai tipe data dapat dianalisis bersama menggunakan Kusto Query Language.

Bermigrasi dari @azure/monitor-query penasihat ⚠️

Lihat Panduan Migrasi untuk petunjuk terperinci tentang cara memperbarui kode aplikasi Anda dari paket asli @azure/monitor-query ke @azure/monitor-query-logs pustaka.

Sumber daya:

Memulai Langkah Pertama

Lingkungan yang didukung

Untuk informasi selengkapnya, lihat kebijakan dukungan kami.

Prasyarat

Pasang paketnya

Instal pustaka klien Azure Monitor Query untuk JavaScript dengan npm:

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

Membuat klien

Klien yang diautentikasi diperlukan untuk mengkueri Log. Untuk mengautentikasi, contoh berikut menggunakan DefaultAzureCredential dari paket @azure/identitas .

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

const credential = new DefaultAzureCredential();

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

Mengonfigurasi klien untuk azure sovereign cloud

Secara default, klien pustaka dikonfigurasi untuk menggunakan Azure Public Cloud. Untuk menggunakan sovereign cloud, berikan nilai titik akhir dan audiens yang benar saat membuat instans klien. Contohnya:

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

Menjalankan kueri

Untuk contoh kueri Log, lihat bagian Contoh .

Konsep utama

Mencatat batas laju kueri dan pembatasan

Layanan Analitik Log menerapkan pembatasan saat tingkat permintaan terlalu tinggi. Batas, seperti jumlah maksimum baris yang dikembalikan, juga diterapkan pada kueri Kusto. Untuk informasi selengkapnya, lihat API Kueri.

Contoh

Kueri log

Ini LogsQueryClient dapat digunakan untuk mengkueri ruang kerja Analitik Log menggunakan Bahasa Kueri Kusto. Dapat timespan.duration ditentukan sebagai string dalam format durasi ISO 8601. Anda dapat menggunakan Durations konstanta yang disediakan untuk beberapa durasi ISO 8601 yang umum digunakan.

Anda dapat mengkueri log menurut ID ruang kerja Log Analytics atau ID sumber daya Azure. Hasilnya dikembalikan sebagai tabel dengan kumpulan baris.

Kueri log yang berentrik ruang kerja

Untuk mengkueri berdasarkan ID ruang kerja, gunakan LogsQueryClient.queryWorkspace metode:

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

Kueri log yang bersentrik sumber daya

Contoh berikut menunjukkan cara mengkueri log langsung dari sumber daya Azure. Di sini, metode digunakan queryResource dan ID sumber daya Azure diteruskan. Contohnya, /subscriptions/{subscription-id}/resourceGroups/{resource-group-name}/providers/{resource-provider}/{resource-type}/{resource-name}.

Untuk menemukan ID sumber daya:

  1. Navigasi ke halaman sumber daya Anda di portal Microsoft Azure.
  2. Dari bilah Gambaran Umum, pilih tautan JSON View .
  3. Dalam JSON yang dihasilkan, salin nilai id properti.
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);
  }
}

Menangani respons kueri log

Fungsi queryWorkspace mengembalikan LogsQueryClientLogsQueryResult objek. Jenis objek dapat berupa LogsQuerySuccessfulResult atau LogsQueryPartialResult. Berikut adalah hierarki respons:

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

Misalnya, untuk menangani respons dengan tabel:

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

Sampel lengkapnya dapat ditemukan di sini.

Kueri log batch

Contoh berikut menunjukkan pengiriman beberapa kueri secara bersamaan menggunakan API kueri batch. Kueri dapat direpresentasikan sebagai daftar BatchQuery objek.

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

Menangani respons kueri batch log

Fungsi queryBatch mengembalikan LogsQueryClientLogsQueryBatchResult objek. LogsQueryBatchResult berisi daftar objek dengan kemungkinan jenis berikut:

  • LogsQueryPartialResult
  • LogsQuerySuccessfulResult
  • LogsQueryError

Berikut adalah hierarki respons:

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

Misalnya, kode berikut menangani respons kueri 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);
    }
  }
}

Sampel lengkapnya dapat ditemukan di sini.

Skenario kueri log tingkat lanjut

Mengatur batas waktu kueri log

Beberapa kueri log membutuhkan waktu lebih dari 3 menit untuk dijalankan. Batas waktu server default adalah 3 menit. Anda dapat meningkatkan batas waktu server hingga maksimum 10 menit. Dalam contoh berikut, LogsQueryOptions properti objek serverTimeoutInSeconds digunakan untuk meningkatkan batas waktu server menjadi 10 menit:

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;

Menelusuri beberapa ruang kerja

Kueri log yang sama dapat dijalankan di beberapa ruang kerja Analitik Log. Selain kueri Kusto, parameter berikut diperlukan:

  • workspaceId - ID ruang kerja (utama) pertama.
  • additionalWorkspaces - Daftar ruang kerja, tidak termasuk ruang kerja yang disediakan dalam workspaceId parameter. Item daftar parameter dapat terdiri dari format pengidentifikasi berikut:
    • Nama ruang kerja yang memenuhi syarat
    • ID Ruang Kerja
    • ID sumber daya Azure

Misalnya, kueri berikut dijalankan di tiga ruang kerja:

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;

Untuk melihat hasil untuk setiap ruang kerja, gunakan TenantId kolom untuk mengurutkan hasil atau memfilternya dalam kueri Kusto.

Hasil pesanan berdasarkan TenantId

AppEvents | order by TenantId

Memfilter hasil berdasarkan TenantId

AppEvents | filter TenantId == "<workspace2>"

Sampel lengkapnya dapat ditemukan di sini.

Sertakan statistik

Untuk mendapatkan statistik eksekusi kueri log, seperti konsumsi CPU dan memori:

  1. Atur properti LogsQueryOptions.includeQueryStatistics ke true.
  2. Akses bidang di statistics dalam LogsQueryResult objek.

Contoh berikut mencetak waktu eksekusi kueri:

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

Karena struktur statistics muatan bervariasi menurut kueri, Record<string, unknown> jenis pengembalian digunakan. Ini berisi respons JSON mentah. Statistik ditemukan dalam query properti JSON. Contohnya:

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

Sertakan visualisasi

Untuk mendapatkan data visualisasi untuk kueri log menggunakan operator render:

  1. Atur properti LogsQueryOptions.includeVisualization ke true.
  2. Akses bidang di visualization dalam LogsQueryResult objek.

Contohnya:

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

Karena struktur visualization muatan bervariasi menurut kueri, Record<string, unknown> jenis pengembalian digunakan. Ini berisi respons JSON mentah. Contohnya:

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

Penyelesaian Masalah

Untuk mendiagnosis berbagai skenario kegagalan, lihat panduan pemecahan masalah.

Langkah selanjutnya

Untuk mempelajari selengkapnya tentang Azure Monitor, lihat dokumentasi layanan Azure Monitor.

Berpartisipasi

Jika Anda ingin berkontribusi pada pustaka ini, baca panduan berkontribusi untuk mempelajari selengkapnya tentang cara membuat dan menguji kode.

Pengujian modul ini adalah campuran pengujian langsung dan unit, yang mengharuskan Anda memiliki instans Azure Monitor. Untuk menjalankan pengujian, Anda harus menjalankan:

  1. rush update
  2. rush build -t @azure/monitor-query-logs
  3. cd into sdk/monitor/monitor-query
  4. Salin sample.env file ke .env
  5. Buka .env file di editor dan isi nilainya.
  6. npm run test.

Untuk detail selengkapnya, lihat folder pengujian kami.

  • Last updated on