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

Klientská knihovna pro příjem dat služby Azure Monitor slouží 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 prakticky z libovolného zdroje do podporovaných předdefinovaný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 vaší klientské třídy.

K ověření použije DefaultAzureCredential následující příklad 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);

Konfigurace klienta pro suverénní cloud Azure

Ve výchozím nastavení je klient nakonfigurovaný tak, aby používal veřejný cloud Azure. Pokud chcete místo toho použít suverénní cloud, při vytváření instance klienta zadejte správnou hodnotu koncového bodu a cílové skupiny. Příklad:

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, {
  audience: "https://api.loganalytics.azure.cn/.default",
});

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 toho, jak je můžete vytvářet a pracovat s nimi.

Pravidlo shromažďování dat

Pravidla shromažďování dat (DCR) definují data shromažďovaná 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. Jedna DCE může podporovat více dcr, takže můžete zadat jiné 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 k převodu zdrojových dat tak, aby odpovídala cílové tabulce. Transformaci můžete také použít 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ích prostorů 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ávnost 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 v LogsIngestionClientsystému se nahrávání rozdělí do několika menších dávek, z nichž každá nesmí být 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 je využití paměti problém, 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čítání protokolů

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

Poradce při potížích

Podrobnosti o diagnostice různých scénářů selhání najdete v našem průvodci odstraňováním potíží.

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 samples.

Přispívání

Pokud chcete přispívat do této knihovny, přečtěte si prosím průvodce přispívání , kde se dozvíte více o tom, jak sestavit a otestovat kód.