Klientská knihovna pro příjem dat služby Azure Monitor pro JS

Klientská knihovna pro příjem dat služby Azure Monitor se používá k odesílání vlastních protokolů do služby Azure Monitor pomocí rozhraní API pro příjem protokolů.

Tato knihovna umožňuje odesílat data z prakticky libovolného zdroje do podporovaných integrovaných tabulek nebo do vlastních tabulek, které vytvoříte v pracovním prostoru služby Log Analytics. Schéma předdefinovaných tabulek můžete dokonce rozšířit o vlastní sloupce.

Zdroje a prostředky:

• Zdrojový kód
• Balíček (NPM)
• Dokumentace ke službě
• Protokol změn

Začínáme

Požadavky

• Předplatné Azure
• Koncový bod shromažďování dat
• Pravidlo shromažďování dat
• Pracovní prostor služby Log Analytics

Instalace balíčku

Nainstalujte klientskou knihovnu pro příjem dat služby Azure Monitor pro JS pomocí npm:

npm install @azure/monitor-ingestion

Ověření klienta

K ingestování dat se vyžaduje ověřený klient. Pokud chcete provést ověření, vytvořte instanci třídy TokenCredential (viz @azure/identity pro DefaultAzureCredential a další TokenCredential implementace). Předejte ho konstruktoru třídy klienta.

K ověření použije následující příklad DefaultAzureCredential balíček @azure/identity :

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

Klíčové koncepty

Koncový bod shromažďování dat

Koncové body shromažďování dat (DCE) umožňují jedinečnou konfiguraci nastavení příjmu dat pro Azure Monitor. Tento článek obsahuje přehled koncových bodů shromažďování dat včetně jejich obsahu a struktury a způsobu jejich vytváření a práce s nimi.

Pravidlo shromažďování dat

Pravidla shromažďování dat (DCR) definují data shromážděná službou Azure Monitor a určují, jak a kam se mají tato data odesílat nebo ukládat. Volání rozhraní REST API musí určovat DCR, které se má použít. Jeden DCE může podporovat více dcr, takže můžete zadat různé DCR pro různé zdroje a cílové tabulky.

DCR musí rozumět struktuře vstupních dat a struktuře cílové tabulky. Pokud se neshoduje, může použít transformaci a převést zdrojová data tak, aby odpovídala cílové tabulce. Transformaci můžete použít také k filtrování zdrojových dat a provádění dalších výpočtů nebo převodů.

Další podrobnosti najdete v tématu Pravidla shromažďování dat ve službě Azure Monitor. Informace o tom, jak načíst ID DCR, najdete v tomto kurzu.

Tabulky pracovního prostoru služby Log Analytics

Vlastní protokoly můžou odesílat data do libovolné vlastní tabulky, kterou vytvoříte, a do určitých předdefinovaných tabulek v pracovním prostoru služby Log Analytics. Cílová tabulka musí existovat, abyste do ní mohli odesílat data. V současné době jsou podporovány následující předdefinované tabulky:

• CommonSecurityLog
• SecurityEvents
• Syslog
• WindowsEvents

Příklady

• Nahrání vlastních protokolů
• Ověření protokolů

Pomocí ukázek se můžete seznámit s různými rozhraními API.

Nahrání vlastních protokolů

Můžete vytvořit klienta a volat metodu klienta Upload . Poznamenejte si limity příjmu dat.

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

Ověření protokolů

Správné nahrání dat můžete ověřit pomocí knihovny @azure/monitor-query . Před ověřením protokolů nejprve spusťte ukázku nahrát vlastní protokoly .

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

Nahrávání velkých dávek protokolů

Při nahrání více než 1 MB protokolů v jednom volání upload metody na LogsIngestionClientse nahrávání rozdělí do několika menších dávek, z nichž každá nebude větší než 1 MB. Ve výchozím nastavení se tyto dávky nahrají paralelně a současně se nahraje maximálně 5 dávek. Pokud se jedná o využití paměti, může být žádoucí snížit maximální souběžnost. Maximální počet souběžných nahrávání lze řídit pomocí maxConcurrency možnosti , jak je znázorněno v tomto příkladu:

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

Načtení protokolů

Protokoly nahrané pomocí klientské knihovny Monitorování příjmu dat je možné načíst pomocí klientské knihovny Monitor Query.

Řešení potíží

protokolování

Povolení protokolování může pomoct odhalit užitečné informace o selháních. Pokud chcete zobrazit protokol požadavků a odpovědí HTTP, nastavte proměnnou AZURE_LOG_LEVEL prostředí na info. Případně je možné protokolování povolit za běhu voláním setLogLevel v :@azure/logger

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

setLogLevel("info");

Podrobné pokyny k povolení protokolů najdete v dokumentaci k balíčkům @azure/logger.

Další kroky

Další informace o službě Azure Monitor najdete v dokumentaci ke službě Azure Monitor. Podrobné příklady použití této knihovny najdete v adresáři ukázek.

Přispívání

Pokud chcete přispívat do této knihovny, přečtěte si příručku pro přispívání , kde najdete další informace o tom, jak sestavit a otestovat kód.