Azure Monitor-klientbibliotek för inmatning för JS

Azure Monitor Ingestion-klientbiblioteket används för att skicka anpassade loggar till Azure Monitor med hjälp av LOGS Ingestion-API:et.

Med det här biblioteket kan du skicka data från praktiskt taget alla källor till inbyggda tabeller som stöds eller till anpassade tabeller som du skapar på Log Analytics-arbetsytan. Du kan även utöka schemat för inbyggda tabeller med anpassade kolumner.

Resurser:

• Källkod
• Paket (NPM)
• Tjänstdokumentation
• Ändringslogg

Komma igång

Förutsättningar

• En Azure-prenumeration
• En slutpunkt för datainsamling
• En datainsamlingsregel
• En Log Analytics-arbetsyta

Installera paketet

Installera Azure Monitor Ingestion-klientbiblioteket för JS med npm:

npm install @azure/monitor-ingestion

Autentisera klienten

En autentiserad klient krävs för att mata in data. Om du vill autentisera skapar du en instans av en TokenCredential-klass (se @azure/identitet för DefaultAzureCredential och andra TokenCredential implementeringar). Skicka den till konstruktorn för klientklassen.

För att autentisera använder DefaultAzureCredential följande exempel från paketet @azure/identitet :

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

Konfigurera klienten för Azures nationella moln

Som standard är klienten konfigurerad för att använda det offentliga Azure-molnet. Om du vill använda ett nationellt moln i stället anger du rätt slutpunkts- och målgruppsvärde när du instansierar klienten. Exempel:

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

Viktiga begrepp

Slutpunkt för datainsamling

Med datainsamlingsslutpunkter (DCE) kan du unikt konfigurera inmatningsinställningar för Azure Monitor. Den här artikeln innehåller en översikt över slutpunkter för datainsamling, inklusive deras innehåll och struktur samt hur du kan skapa och arbeta med dem.

Datainsamlingsregel

Datainsamlingsregler (DCR) definierar data som samlas in av Azure Monitor och anger hur och var dessa data ska skickas eller lagras. REST API-anropet måste ange en DCR som ska användas. En enskild domänkontrollant kan ha stöd för flera domänkontrollanter, så du kan ange en annan DCR för olika källor och måltabeller.

DCR måste förstå strukturen för indata och måltabellens struktur. Om de två inte matchar kan den använda en transformering för att konvertera källdata till att matcha måltabellen. Du kan också använda transformeringen för att filtrera källdata och utföra andra beräkningar eller konverteringar.

Mer information finns i Datainsamlingsregler i Azure Monitor. Information om hur du hämtar ett DCR-ID finns i den här självstudien.

Log Analytics-arbetsytetabeller

Anpassade loggar kan skicka data till alla anpassade tabeller som du skapar och till vissa inbyggda tabeller på Log Analytics-arbetsytan. Måltabellen måste finnas innan du kan skicka data till den. Följande inbyggda tabeller stöds för närvarande:

• CommonSecurityLog
• SecurityEvents
• Syslog
• WindowsEvents

Exempel

• Ladda upp anpassade loggar
• Verifiera loggar

Du kan bekanta dig med olika API:er med hjälp av exempel.

Ladda upp anpassade loggar

Du kan skapa en klient och anropa klientens Upload -metod. Anteckna datainmatningsgränserna.

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

Verifiera loggar

Du kan kontrollera att dina data har laddats upp korrekt med hjälp av biblioteket @azure/monitor-query . Kör exemplet Ladda upp anpassade loggar först innan du verifierar loggarna.

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

Ladda upp stora batchar med loggar

När du laddar upp mer än 1 MB loggar i ett enda anrop till metoden på uploadLogsIngestionClientdelas uppladdningen upp i flera mindre batchar, var och en inte större än 1 MB. Som standard laddas dessa batchar upp parallellt, med högst 5 batchar som laddas upp samtidigt. Det kan vara önskvärt att minska den maximala samtidigheten om minnesanvändningen är ett problem. Det maximala antalet samtidiga uppladdningar kan styras med hjälp av maxConcurrency alternativet, som du ser i det här exemplet:

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

Hämta loggar

Loggar som laddas upp med klientbiblioteket Övervaka inmatning kan hämtas med hjälp av klientbiblioteket För övervakningsfråga.

Felsökning

Mer information om hur du diagnostiserar olika felscenarier finns i vår felsökningsguide.

Nästa steg

Mer information om Azure Monitor finns i dokumentationen för Azure Monitor-tjänsten. Ta en titt på exempelkatalogen för detaljerade exempel på hur du använder det här biblioteket.

Bidra

Om du vill bidra till det här biblioteket kan du läsa bidragsguiden för att lära dig mer om hur du skapar och testar koden.