Bagikan melalui

Pustaka klien penyerapan Azure Monitor untuk JS

The Azure Monitor Ingestion client library is used to send custom logs to Azure Monitor using the Logs Ingestion API.

Pustaka ini memungkinkan Anda mengirim data dari hampir semua sumber ke tabel bawaan yang didukung atau ke tabel kustom yang Anda buat di ruang kerja Analitik Log. Anda bahkan dapat memperluas skema tabel bawaan dengan kolom kustom.

Resources:

Getting started

Prerequisites

Pasang paketnya

Install the Azure Monitor Ingestion client library for JS with npm:

npm install @azure/monitor-ingestion

Mengautentikasi klien

Klien yang diautentikasi diperlukan untuk menyerap data. To authenticate, create an instance of a TokenCredential class (see @azure/identity for DefaultAzureCredential and other TokenCredential implementations). Berikan ke konstruktor kelas klien Anda.

To authenticate, the following example uses DefaultAzureCredential from the @azure/identity package:

import { DefaultAzureCredential } from "@azure/identity";
import { LogsIngestionClient } from "@azure/monitor-ingestion";

const logsIngestionEndpoint = "https://<my-endpoint>.azure.com";

const credential = new DefaultAzureCredential();
const logsIngestionClient = new LogsIngestionClient(logsIngestionEndpoint, credential);

Mengonfigurasi klien untuk azure sovereign cloud

Secara default, klien dikonfigurasi untuk menggunakan Azure Public Cloud. Untuk menggunakan cloud berdaulat, berikan nilai titik akhir dan audiens yang benar saat membuat instance klien. For example:

import { DefaultAzureCredential } from "@azure/identity";
import { LogsIngestionClient } from "@azure/monitor-ingestion";

const logsIngestionEndpoint = "https://<my-endpoint>.azure.cn";

const credential = new DefaultAzureCredential();
const logsIngestionClient = new LogsIngestionClient(logsIngestionEndpoint, credential, {
  audience: "https://api.loganalytics.azure.cn/.default",
});

Key concepts

Titik Akhir Pengumpulan Data

Titik Akhir Pengumpulan Data (DCE) memungkinkan Anda mengonfigurasi pengaturan penyerapan secara unik untuk Azure Monitor. This article provides an overview of data collection endpoints including their contents and structure and how you can create and work with them.

Aturan Pengumpulan Data

Aturan pengumpulan data (DCR) menentukan data yang dikumpulkan oleh Azure Monitor dan menentukan bagaimana dan di mana data tersebut harus dikirim atau disimpan. Panggilan REST API harus menentukan DCR yang akan digunakan. Satu DCE dapat mendukung beberapa DCR, sehingga Anda dapat menentukan DCR yang berbeda untuk sumber dan tabel target yang berbeda.

DCR harus memahami struktur data input dan struktur tabel target. Jika keduanya tidak cocok, ia dapat menggunakan transformasi untuk mengonversi data sumber agar sesuai dengan tabel target. Anda juga dapat menggunakan transformasi untuk memfilter data sumber dan melakukan perhitungan atau konversi lainnya.

Untuk detail selengkapnya, lihat Aturan pengumpulan data di Azure Monitor. Untuk informasi tentang cara mengambil ID DCR, lihat tutorial ini.

Tabel ruang kerja Analitik Log

Log kustom dapat mengirim data ke tabel kustom apa pun yang Anda buat dan ke tabel bawaan tertentu di ruang kerja Analitik Log Anda. Tabel target harus ada sebelum Anda dapat mengirim data ke tabel tersebut. Tabel bawaan berikut saat ini didukung:

Examples

You can familiarize yourself with different APIs using Samples.

Mengupload log kustom

Anda dapat membuat klien dan memanggil metode klien Upload . Take note of the data ingestion limits.

import { DefaultAzureCredential } from "@azure/identity";
import { LogsIngestionClient, isAggregateLogsUploadError } from "@azure/monitor-ingestion";

const logsIngestionEndpoint = "https://<my-endpoint>.azure.com";
const ruleId = "data_collection_rule_id";
const streamName = "data_stream_name";

const credential = new DefaultAzureCredential();
const logsIngestionClient = new LogsIngestionClient(logsIngestionEndpoint, credential);

const logs = [
  {
    Time: "2021-12-08T23:51:14.1104269Z",
    Computer: "Computer1",
    AdditionalContext: "context-2",
  },
  {
    Time: "2021-12-08T23:51:14.1104269Z",
    Computer: "Computer2",
    AdditionalContext: "context",
  },
];

try {
  await logsIngestionClient.upload(ruleId, streamName, logs);
} catch (e) {
  const aggregateErrors = isAggregateLogsUploadError(e) ? e.errors : [];
  if (aggregateErrors.length > 0) {
    console.log("Some logs have failed to complete ingestion");
    for (const error of aggregateErrors) {
      console.log(`Error - ${JSON.stringify(error.cause)}`);
      console.log(`Log - ${JSON.stringify(error.failedLogs)}`);
    }
  } else {
    console.log(`An error occurred: ${e}`);
  }
}

Verify logs

You can verify that your data has been uploaded correctly by using the @azure/monitor-query library. Jalankan sampel Unggah log kustom terlebih dahulu sebelum memverifikasi log.

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

const monitorWorkspaceId = "workspace_id";
const tableName = "table_name";

const credential = new DefaultAzureCredential();
const logsQueryClient = new LogsQueryClient(credential);

const queriesBatch = [
  {
    workspaceId: monitorWorkspaceId,
    query: tableName + " | count;",
    timespan: { duration: "P1D" },
  },
];

const result = await logsQueryClient.queryBatch(queriesBatch);
if (result[0].status === "Success") {
  console.log("Table entry count: ", JSON.stringify(result[0].tables));
} else {
  console.log(
    `Some error encountered while retrieving the count. Status = ${result[0].status}`,
    JSON.stringify(result[0]),
  );
}

Mengunggah log dalam jumlah besar

Saat mengunggah lebih dari 1MB log dalam satu panggilan ke upload metode pada LogsIngestionClient, unggahan akan dibagi menjadi beberapa batch yang lebih kecil, masing-masing tidak lebih besar dari 1MB. Secara default, batch ini akan diunggah secara paralel, dengan maksimal 5 batch diunggah secara bersamaan. Mungkin diinginkan untuk mengurangi konkurensi maksimum jika penggunaan memori menjadi perhatian. Jumlah maksimum upload bersamaan dapat dikontrol menggunakan maxConcurrency opsi, seperti yang ditunjukkan dalam contoh ini:

import { DefaultAzureCredential } from "@azure/identity";
import { LogsIngestionClient, isAggregateLogsUploadError } from "@azure/monitor-ingestion";

const logsIngestionEndpoint = "https://<my-endpoint>.azure.com";
const ruleId = "data_collection_rule_id";
const streamName = "data_stream_name";

const credential = new DefaultAzureCredential();
const client = new LogsIngestionClient(logsIngestionEndpoint, credential);

// Constructing a large number of logs to ensure batching takes place
const logs = [];
for (let i = 0; i < 100000; ++i) {
  logs.push({
    Time: "2021-12-08T23:51:14.1104269Z",
    Computer: "Computer1",
    AdditionalContext: `context-${i}`,
  });
}

try {
  // Set the maximum concurrency to 1 to prevent concurrent requests entirely
  await client.upload(ruleId, streamName, logs, { maxConcurrency: 1 });
} catch (e) {
  let aggregateErrors = isAggregateLogsUploadError(e) ? e.errors : [];
  if (aggregateErrors.length > 0) {
    console.log("Some logs have failed to complete ingestion");
    for (const error of aggregateErrors) {
      console.log(`Error - ${JSON.stringify(error.cause)}`);
      console.log(`Log - ${JSON.stringify(error.failedLogs)}`);
    }
  } else {
    console.log(e);
  }
}

Retrieve logs

Log yang diunggah menggunakan pustaka klien Monitor Ingestion dapat diambil menggunakan pustaka klien Monitor Query.

Troubleshooting

For details on diagnosing various failure scenarios, see our troubleshooting guide.

Next steps

Untuk mempelajari selengkapnya tentang Azure Monitor, lihat dokumentasi layanan Azure Monitor. Please take a look at the samples directory for detailed examples on how to use this library.

Contributing

If you'd like to contribute to this library, please read the contributing guide to learn more about how to build and test the code.

  • Last updated on