Biblioteka klienta pozyskiwania usługi Azure Monitor dla środowiska JS

  • Artykuł

Biblioteka klienta pozyskiwania usługi Azure Monitor służy do wysyłania dzienników niestandardowych do usługi Azure Monitor przy użyciu interfejsu API pozyskiwania dzienników.

Ta biblioteka umożliwia wysyłanie danych z praktycznie dowolnego źródła do obsługiwanych wbudowanych tabel lub tabel niestandardowych tworzonych w obszarze roboczym usługi Log Analytics. Można nawet rozszerzyć schemat wbudowanych tabel za pomocą kolumn niestandardowych.

Zasoby:

Wprowadzenie

Wymagania wstępne

Instalowanie pakietu

Zainstaluj bibliotekę klienta pozyskiwania usługi Azure Monitor dla środowiska JS za pomocą narzędzia npm:

npm install @azure/monitor-ingestion

Uwierzytelnianie klienta

Uwierzytelniony klient jest wymagany do pozyskiwania danych. Aby przeprowadzić uwierzytelnianie, utwórz wystąpienie klasy TokenCredential (zobacz @azure/tożsamość i DefaultAzureCredential inne TokenCredential implementacje). Przekaż go do konstruktora klasy klienta.

Do uwierzytelnienia użyjemy następującego przykładu DefaultAzureCredential z pakietu @azure/tożsamości :

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

Kluczowe pojęcia

Punkt końcowy zbierania danych

Punkty końcowe zbierania danych (DCE) umożliwiają unikatowe konfigurowanie ustawień pozyskiwania dla usługi Azure Monitor. Ten artykuł zawiera omówienie punktów końcowych zbierania danych, w tym ich zawartości i struktury oraz sposobu ich tworzenia i pracy z nimi.

Reguła zbierania danych

Reguły zbierania danych (DCR) definiują dane zbierane przez usługę Azure Monitor i określają, jak i gdzie mają być wysyłane lub przechowywane te dane. Wywołanie interfejsu API REST musi określać kontroler domeny do użycia. Pojedynczy kontroler domeny może obsługiwać wiele kontrolerów DCR, dzięki czemu można określić różne kontrolery domeny dla różnych źródeł i tabel docelowych.

Kontroler domeny musi zrozumieć strukturę danych wejściowych i strukturę tabeli docelowej. Jeśli te dwa nie są zgodne, może użyć przekształcenia, aby przekonwertować dane źródłowe w celu dopasowania do tabeli docelowej. Możesz również użyć przekształcenia do filtrowania danych źródłowych i wykonywania innych obliczeń lub konwersji.

Aby uzyskać więcej informacji, zobacz Reguły zbierania danych w usłudze Azure Monitor. Aby uzyskać informacje na temat pobierania identyfikatora DCR, zobacz ten samouczek.

Tabele obszarów roboczych usługi Log Analytics

Dzienniki niestandardowe mogą wysyłać dane do dowolnej utworzonej tabeli niestandardowej i do niektórych wbudowanych tabel w obszarze roboczym usługi Log Analytics. Tabela docelowa musi istnieć przed wysłaniem do niej danych. Obecnie obsługiwane są następujące wbudowane tabele:

Przykłady

Możesz zapoznać się z różnymi interfejsami API przy użyciu przykładów.

Przekazywanie dzienników niestandardowych

Możesz utworzyć klienta i wywołać metodę klienta Upload . Zanotuj limity pozyskiwania danych.

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

Weryfikowanie dzienników

Możesz sprawdzić, czy dane zostały prawidłowo przekazane przy użyciu biblioteki @azure/monitor-query . Uruchom przykład Przekazywanie dzienników niestandardowych najpierw przed zweryfikowaniem dzienników.

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

Przekazywanie dużych partii dzienników

Podczas przekazywania więcej niż 1 MB dzienników w jednym wywołaniu metody upload w systemie LogsIngestionClientprzekazywanie zostanie podzielone na kilka mniejszych partii, każdy nie większy niż 1 MB. Domyślnie te partie zostaną przekazane równolegle z maksymalnie 5 partiami przekazywanymi jednocześnie. Może być pożądane zmniejszenie maksymalnej współbieżności, jeśli użycie pamięci jest problemem. Maksymalną liczbę współbieżnych operacji przekazywania można kontrolować przy użyciu maxConcurrency opcji, jak pokazano w tym przykładzie:

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

Pobieranie dzienników

Dzienniki przekazane przy użyciu biblioteki klienta pozyskiwania monitora można pobrać przy użyciu biblioteki klienta Monitor Query.

Rozwiązywanie problemów

Rejestrowanie

Włączenie rejestrowania może pomóc odkryć przydatne informacje o błędach. Aby wyświetlić dziennik żądań HTTP i odpowiedzi, ustaw zmienną AZURE_LOG_LEVEL środowiskową na info. Możesz też włączyć rejestrowanie w czasie wykonywania, wywołując polecenie w elemecie setLogLevel@azure/logger:

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

setLogLevel("info");

Aby uzyskać szczegółowe instrukcje dotyczące włączania dzienników, zobacz dokumentację pakietu @azure/rejestratora.

Następne kroki

Aby dowiedzieć się więcej na temat usługi Azure Monitor, zobacz dokumentację usługi Azure Monitor. Zapoznaj się z katalogiem samples, aby uzyskać szczegółowe przykłady dotyczące sposobu korzystania z tej biblioteki.

Współtworzenie

Jeśli chcesz współtworzyć tę bibliotekę, przeczytaj przewodnik współtworzenia , aby dowiedzieć się więcej na temat sposobu kompilowania i testowania kodu.

Wrażenia