مكتبة عميل Azure Monitor Ingestion ل JS

مقالة
04/05/2023

تستخدم مكتبة عميل استيعاب Azure Monitor لإرسال سجلات مخصصة إلى Azure Monitor باستخدام واجهة برمجة تطبيقات استيعاب السجلات.

تسمح لك هذه المكتبة بإرسال البيانات من أي مصدر تقريبا إلى الجداول المضمنة المدعومة أو إلى الجداول المخصصة التي تقوم بإنشائها في مساحة عمل Log Analytics. يمكنك حتى توسيع مخطط الجداول المضمنة باستخدام أعمدة مخصصة.

الموارد:

الشروع في العمل

المتطلبات الأساسية

تثبيت الحِزَمة

قم بتثبيت مكتبة عميل Azure Monitor Ingestion ل JS مع npm:

npm install @azure/monitor-ingestion

مصادقة العميل

مطلوب عميل مصادق عليه لاستيعاب البيانات. للمصادقة، أنشئ مثيلا لفئة TokenCredential (راجع @azure/الهوية للتطبيقات DefaultAzureCredential الأخرى TokenCredential ). مررها إلى الدالة الإنشائية لفئة العميل.

للمصادقة، يستخدم DefaultAzureCredential المثال التالي من حزمة @azure/الهوية :

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

import * as dotenv from "dotenv";
dotenv.config();

const logsIngestionEndpoint = process.env.LOGS_INGESTION_ENDPOINT || "logs_ingestion_endpoint";

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

المفاهيم الرئيسية

نقطة نهاية جمع البيانات

تسمح لك نقاط نهاية تجميع البيانات (DCEs) بتكوين إعدادات الاستيعاب بشكل فريد لـ Azure Monitor. توفر هذه المقالة نظرة عامة على نقاط نهاية جمع البيانات بما في ذلك محتوياتها وبنيتها وكيفية إنشائها والعمل معها.

قاعدة جمع البيانات

تحدد قواعد جمع البيانات (DCR) البيانات التي تم جمعها بواسطة Azure Monitor وتحدد كيفية ومكان إرسال تلك البيانات أو تخزينها. يجب أن يحدد استدعاء REST API DCR لاستخدامه. يمكن أن يدعم DCE واحد عدة DCRs، بحيث يمكنك تحديد DCR مختلف لمصادر مختلفة وجداول الهدف.

يجب أن يفهم DCR بنية بيانات الإدخال وبنية الجدول الهدف. إذا لم يتطابق الاثنان، فيمكنه استخدام تحويل لتحويل البيانات المصدر لمطابقة الجدول الهدف. يمكنك أيضًا استخدام التحويل لتصفية بيانات المصدر وإجراء أي حسابات أو تحويلات أخرى.

لمزيد من التفاصيل، راجع قواعد جمع البيانات في Azure Monitor. للحصول على معلومات حول كيفية استرداد معرف DCR، راجع هذا البرنامج التعليمي.

جداول مساحة عمل Log Analytics

يمكن للسجلات المخصصة إرسال البيانات إلى أي جدول مخصص تقوم بإنشائه وإلى جداول مضمنة معينة في مساحة عمل Log Analytics. يجب أن يكون الجدول الهدف موجودًا قبل أن تتمكن من إرسال البيانات إليه. الجداول المضمنة التالية مدعومة حاليًا:

يمكنك التعرف على واجهات برمجة التطبيقات المختلفة باستخدام عينات.

تحميل سجلات مخصصة

يمكنك إنشاء عميل واستدعاء أسلوب العميل Upload . لاحظ حدود استيعاب البيانات.

const { isAggregateLogsUploadError, DefaultAzureCredential } = require("@azure/identity");
const { LogsIngestionClient } = require("@azure/monitor-ingestion");

require("dotenv").config();

async function main() {
  const logsIngestionEndpoint = process.env.LOGS_INGESTION_ENDPOINT || "logs_ingestion_endpoint";
  const ruleId = process.env.DATA_COLLECTION_RULE_ID || "data_collection_rule_id";
  const streamName = process.env.STREAM_NAME || "data_stream_name";
  const credential = new DefaultAzureCredential();
  const client = 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 client.upload(ruleId, streamName, logs);
  }
  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);
    }
  }
}

main().catch((err) => {
  console.error("The sample encountered an error:", err);
  process.exit(1);
});

module.exports = { main };

التحقق من السجلات

يمكنك التحقق من تحميل بياناتك بشكل صحيح باستخدام مكتبة @azure/monitor-query . قم بتشغيل عينة تحميل السجلات المخصصة أولا قبل التحقق من السجلات.

// Copyright (c) Microsoft Corporation.
// Licensed under the MIT license.

/**
 * @summary Demonstrates how to run query against a Log Analytics workspace to verify if the logs were uploaded
 */

const { DefaultAzureCredential } = require("@azure/identity");
const { LogsQueryClient } = require("@azure/monitor-query");

const monitorWorkspaceId = process.env.MONITOR_WORKSPACE_ID || "workspace_id";
const tableName = process.env.TABLE_NAME || "table_name";
require("dotenv").config();

async function main() {
  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])
    );
  }
}

main().catch((err) => {
  console.error("The sample encountered an error:", err);
  process.exit(1);
});

module.exports = { main };

تحميل دفعات كبيرة من السجلات

عند تحميل أكثر من 1 ميغابايت من السجلات في استدعاء واحد للأسلوب upload على LogsIngestionClient، سيتم تقسيم التحميل إلى عدة دفعات أصغر، لا يزيد كل منها عن 1 ميغابايت. بشكل افتراضي، سيتم تحميل هذه الدفعات بالتوازي، مع تحميل 5 دفعات كحد أقصى بشكل متزامن. قد يكون من المستحسن تقليل الحد الأقصى للتزامن إذا كان استخدام الذاكرة مصدر قلق. يمكن التحكم في الحد الأقصى لعدد التحميلات المتزامنة maxConcurrency باستخدام الخيار ، كما هو موضح في هذا المثال:

const { DefaultAzureCredential } = require("@azure/identity");
const { isAggregateLogsUploadError, LogsIngestionClient } = require("@azure/monitor-ingestion");

require("dotenv").config();

async function main() {
  const logsIngestionEndpoint = process.env.LOGS_INGESTION_ENDPOINT || "logs_ingestion_endpoint";
  const ruleId = process.env.DATA_COLLECTION_RULE_ID || "data_collection_rule_id";
  const streamName = process.env.STREAM_NAME || "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);
    }
  }
}
main().catch((err) => {
  console.error("The sample encountered an error:", err);
  process.exit(1);
});

module.exports = { main };

استرداد السجلات

يمكن استرداد السجلات التي تم تحميلها باستخدام مكتبة عميل Monitor Ingestion باستخدام مكتبة عميل Monitor Query.

استكشاف الأخطاء وإصلاحها

قد يساعد تمكين التسجيل في الكشف عن معلومات مفيدة حول حالات الفشل. لمشاهدة سجل لطلبات واستجابات HTTP، قم بتعيين AZURE_LOG_LEVEL متغير البيئة إلى info. بدلًا من ذلك، يمكن تمكين التسجيل في وقت التشغيل عن طريق الاتصال setLogLevelبـ @azure/logger:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

للحصول على إرشادات مفصلة حول كيفية تمكين السجلات، راجع مستندات حزمة @azure/المسجل.

الخطوات التالية

لمعرفة المزيد حول Azure Monitor، راجع وثائق خدمة Azure Monitor. يرجى إلقاء نظرة على دليل العينات للحصول على أمثلة مفصلة حول كيفية استخدام هذه المكتبة.

المساهمة

إذا كنت ترغب في المساهمة في هذه المكتبة، يرجى قراءة دليل المساهمة لمعرفة المزيد حول كيفية إنشاء التعليمات البرمجية واختبارها.

مرات الظهور

Share via