Libreria client di inserimento di Monitoraggio di Azure per JS

Articolo
06/12/2024

La libreria client di inserimento di Monitoraggio di Azure viene usata per inviare log personalizzati a Monitoraggio di Azure usando l'API Inserimento log.

Questa libreria consente di inviare dati da qualsiasi origine a tabelle predefinite supportate o a tabelle personalizzate create nell'area di lavoro Log Analytics. È anche possibile aggiungere colonne personalizzate per estendere lo schema delle tabelle predefinite.

Risorse:

Introduzione

Prerequisiti

Installare il pacchetto

Installare la libreria client di inserimento di Monitoraggio di Azure per JS con npm:

npm install @azure/monitor-ingestion

Autenticare il client

È necessario un client autenticato per inserire i dati. Per eseguire l'autenticazione, creare un'istanza di una classe TokenCredential (vedere @azure/identity per DefaultAzureCredential e altre TokenCredential implementazioni). Passalo al costruttore della classe client.

Per eseguire l'autenticazione, nell'esempio seguente viene usato DefaultAzureCredential il pacchetto @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);

Configurare il client per il cloud sovrano di Azure

Per impostazione predefinita, il client è configurato per l'uso del cloud pubblico di Azure. Per usare invece un cloud sovrano, specificare il valore corretto dell'endpoint e del pubblico quando si crea un'istanza del client. Ad esempio:

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

Concetti chiave

Endpoint di raccolta dati

Gli endpoint di raccolta dati consentono di configurare in modo univoco le impostazioni di inserimento per Monitoraggio di Azure. Questo articolo offre una panoramica degli endpoint di raccolta dati, inclusi il contenuto e la struttura e come creare e usare tali endpoint.

Regola raccolta dati

Le regole di raccolta dati definiscono i dati raccolti da Monitoraggio di Azure e specificano come e dove i dati devono essere inviati o archiviati. La chiamata API REST deve specificare un registro di dominio da usare. Un singolo controller di dominio può supportare più controller di dominio di dominio, in modo da poter specificare un DCR diverso per diverse origini e tabelle di destinazione.

Il DCR deve comprendere la struttura dei dati di input e la struttura della tabella di destinazione. Se i due non corrispondono, può usare una trasformazione per convertire i dati di origine in modo che corrispondano alla tabella di destinazione. È anche possibile usare la trasformazione per filtrare i dati di origine ed eseguire eventuali altri calcoli o conversioni.

Per altre informazioni, vedere Regole di raccolta dati in Monitoraggio di Azure. Per informazioni su come recuperare un ID DCR, vedere questa esercitazione.

Tabelle dell'area di lavoro Log Analytics

I log personalizzati possono inviare dati a qualsiasi tabella personalizzata creata e a determinate tabelle predefinite nell'area di lavoro Log Analytics. La tabella di destinazione deve esistere prima di poter inviare dati. Le tabelle predefinite seguenti sono attualmente supportate:

È possibile acquisire familiarità con diverse API usando esempi.

Caricare log personalizzati

È possibile creare un client e chiamare il metodo del Upload client. Prendere nota dei limiti di inserimento dei dati.

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

Verificare i log

È possibile verificare che i dati siano stati caricati correttamente usando la libreria @azure/monitor-query . Eseguire l'esempio Carica log personalizzati prima di verificare i log.

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

Caricamento di batch di log di grandi dimensioni

Quando si caricano più di 1 MB di log in una singola chiamata al upload metodo in LogsIngestionClient, il caricamento verrà suddiviso in diversi batch più piccoli, ognuno non più grande di 1 MB. Per impostazione predefinita, questi batch verranno caricati in parallelo, con un massimo di 5 batch caricati simultaneamente. Potrebbe essere consigliabile ridurre la concorrenza massima se l'utilizzo della memoria è un problema. Il numero massimo di caricamenti simultanei può essere controllato usando l'opzione maxConcurrency , come illustrato in questo esempio:

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

Recuperare i log

I log caricati usando la libreria client monitoraggio inserimento possono essere recuperati usando la libreria client di Query di monitoraggio.

Risoluzione dei problemi

Per informazioni dettagliate sulla diagnosi di vari scenari di errore, vedere la guida alla risoluzione dei problemi.

Passaggi successivi

Per altre informazioni su Monitoraggio di Azure, vedere la documentazione del servizio Monitoraggio di Azure. Per esempi dettagliati su come usare questa libreria, vedere la directory degli esempi .

Contributo

Per contribuire a questa libreria, leggere la guida ai contributi per altre informazioni su come compilare e testare il codice.

Impression

Condividi tramite