Megosztás a következőn keresztül:

Azure Monitor OpenTelemetria hozzáadása és módosítása .NET-, Java-, Node.js- és Python-alkalmazásokhoz

  • Cikk

Ez a cikk útmutatást nyújt az OpenTelemetria alkalmazásokhoz való hozzáadásához és módosításához az Azure Monitor Application Insights használatával.

Az OpenTelemetry fogalmaival kapcsolatos további információkért tekintse meg az OpenTelemetria áttekintését vagy az OpenTelemetria gyiket.

Automatikus adatgyűjtés

A disztribúciók automatikusan gyűjtenek adatokat az OpenTelemetry-eszközkódtárak összekapcsolásával.

Belefoglalt rendszerállapot-kódtárak

Kérelmek

Függőségek

Logging

  • ILogger

További információ: ILoggerNaplózás c# és .NET nyelven, valamint kód példák.

Lábjegyzetek

  • ¹: Támogatja a nem kezelt/nem kezelt kivételek automatikus jelentését
  • ²: Támogatja az OpenTelemetry-metrikákat
  • ³: Alapértelmezés szerint a naplózás csak infoszinten vagy magasabb szinten történik. A beállítás módosításához tekintse meg a konfigurációs beállításokat.
  • ⁴: Alapértelmezés szerint a naplózás csak akkor lesz összegyűjtve, ha a naplózás a FIGYELMEZTETÉS vagy magasabb szinten történik.

Feljegyzés

Az Azure Monitor OpenTelemetry Distros egyéni leképezést és logikát tartalmaz az Application Insights standard metrikák automatikus kibocsájtásához.

Tipp.

A rendszerállapot-kódtárakból automatikusan gyűjtött vagy az egyéni kódolásból manuálisan gyűjtött OpenTelemetry-metrikák jelenleg az Application Insights "egyéni mérőszámainak" számítanak számlázási célokra. További információ.

Közösségi rendszerállapot-kódtár hozzáadása

Az OpenTelemetry-közösség rendszerállapot-kódtárainak felvételekor automatikusan további adatokat gyűjthet.

Figyelemfelhívás

Nem támogatjuk és nem garantáljuk a közösségi eszközkódtárak minőségét. Javasoljuk, hogy egy a mi disztribúció, post vagy up-vote a mi visszajelzési közösség. Vegye figyelembe, hogy egyes adatok kísérleti OpenTelemetria-specifikációkon alapulnak, és jövőbeli kompatibilitástörő változásokat eredményezhetnek.

Közösségi kódtár hozzáadásához használja azokat vagy ConfigureOpenTelemetryMeterProvider ConfigureOpenTelemetryTracerProvider metódusokat, miután hozzáadta a NuGet-csomagot a tárhoz.

Az alábbi példa bemutatja, hogyan adható hozzá a futtatókörnyezeti rendszerállapot a további metrikák gyűjtéséhez:

dotnet add package OpenTelemetry.Instrumentation.Runtime 

// Create a new ASP.NET Core web application builder.
var builder = WebApplication.CreateBuilder(args);

// Configure the OpenTelemetry meter provider to add runtime instrumentation.
builder.Services.ConfigureOpenTelemetryMeterProvider((sp, builder) => builder.AddRuntimeInstrumentation());

// Add the Azure Monitor telemetry service to the application.
// This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor();

// Build the ASP.NET Core web application.
var app = builder.Build();

// Start the ASP.NET Core web application.
app.Run();

Egyéni telemetriai adatok gyűjtése

Ez a szakasz bemutatja, hogyan gyűjthet egyéni telemetriát az alkalmazásból.

A nyelvtől és a jeltípustól függően különböző módokon gyűjthet egyéni telemetriát, például:

  • OpenTelemetry API
  • Nyelvspecifikus naplózási/metrikakódtárak
  • Klasszikus Application Insights API

Az alábbi táblázat a jelenleg támogatott egyéni telemetriai típusokat jelöli:

Nyelv Egyéni események Egyéni metrikák Függőségek Kivételek Lapmegtekintések Kérelmek Hívásláncok
ASP.NET Core
   OpenTelemetry API Igen Igen Igen Igen
   ILogger API Igen
   Klasszikus AI API
Java
   OpenTelemetry API Igen Igen Igen Igen
   Logback, Log4j, JUL Igen Igen
   Mikrométeres metrikák Igen
   Klasszikus AI API Igen Igen Igen Igen Igen Igen Igen
Node.js
   OpenTelemetry API Igen Igen Igen Igen
Python
   OpenTelemetry API Igen Igen Igen Igen
   Python-naplózási modul Igen
   Eseménybővítmény Igen Igen

Feljegyzés

Az Application Insights Java 3.x figyeli a klasszikus Application Insights API-nak küldött telemetriát. Hasonlóképpen, az Application Insights Node.js 3.x gyűjti a klasszikus Application Insights API-val létrehozott eseményeket. Ez megkönnyíti a frissítést, és betölt egy rést az egyéni telemetriai támogatásban, amíg az OpenTelemetry API nem támogatja az összes egyéni telemetriai típust.

Egyéni metrikák hozzáadása

Ebben az összefüggésben az egyéni metrikák kifejezés a kód manuális rendszerezésére vonatkozik, hogy további metrikákat gyűjtsön az OpenTelemetry Instrumentation Libraries automatikusan gyűjtött adatain túl.

Az OpenTelemetry API hat metrika "eszközt" kínál a különböző metrikaforgatókönyvek lefedéséhez, és a metrikák vizualizációja során a megfelelő "Aggregációs típust" kell választania. Ez a követelmény akkor érvényes, ha az OpenTelemetry Metric API használatával metrikákat küld, és rendszerállapot-kódtárat használ.

Az alábbi táblázat az Egyes OpenTelemetry Metric Instruments ajánlott összesítési típusait mutatja be.

OpenTelemetry Instrument Azure Monitor aggregáció típusa
Számláló Sum
Aszinkron számláló Sum
Hisztogram Min, Max, Average, Sum és Count
Aszinkron mérőműszer Átlag
UpDownCounter Sum
Aszinkron UpDownCounter Sum

Figyelemfelhívás

A táblázatban láthatónál több aggregációtípus általában nem értelmezhető.

Az OpenTelemetria specifikációja ismerteti az eszközöket, és példákat tartalmaz arra, hogy mikor használhatja az egyes eszközöket.

Tipp.

A hisztogram a legsokoldalúbb és legszorosabb egyenértékű az Application Insights GetMetric classic API-val. Az Azure Monitor jelenleg az öt támogatott összesítési típusba simítja a hisztogram-eszközt, és a percentilisek támogatása folyamatban van. Bár kevésbé sokoldalú, más OpenTelemetry-eszközök kevésbé befolyásolják az alkalmazás teljesítményét.

Példa hisztogramra

Az alkalmazásindításnak elő kell fizetnie egy meter név szerint:

// Create a new ASP.NET Core web application builder.
var builder = WebApplication.CreateBuilder(args);

// Configure the OpenTelemetry meter provider to add a meter named "OTel.AzureMonitor.Demo".
builder.Services.ConfigureOpenTelemetryMeterProvider((sp, builder) => builder.AddMeter("OTel.AzureMonitor.Demo"));

// Add the Azure Monitor telemetry service to the application.
// This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor();

// Build the ASP.NET Core web application.
var app = builder.Build();

// Start the ASP.NET Core web application.
app.Run();

Ezt Meter a nevet kell inicializálni:

// Create a new meter named "OTel.AzureMonitor.Demo".
var meter = new Meter("OTel.AzureMonitor.Demo");

// Create a new histogram metric named "FruitSalePrice".
Histogram<long> myFruitSalePrice = meter.CreateHistogram<long>("FruitSalePrice");

// Create a new Random object.
var rand = new Random();

// Record a few random sale prices for apples and lemons, with different colors.
myFruitSalePrice.Record(rand.Next(1, 1000), new("name", "apple"), new("color", "red"));
myFruitSalePrice.Record(rand.Next(1, 1000), new("name", "lemon"), new("color", "yellow"));
myFruitSalePrice.Record(rand.Next(1, 1000), new("name", "lemon"), new("color", "yellow"));
myFruitSalePrice.Record(rand.Next(1, 1000), new("name", "apple"), new("color", "green"));
myFruitSalePrice.Record(rand.Next(1, 1000), new("name", "apple"), new("color", "red"));
myFruitSalePrice.Record(rand.Next(1, 1000), new("name", "lemon"), new("color", "yellow"));

Példa számlálóra

Az alkalmazásindításnak elő kell fizetnie egy meter név szerint:

// Create a new ASP.NET Core web application builder.
var builder = WebApplication.CreateBuilder(args);

// Configure the OpenTelemetry meter provider to add a meter named "OTel.AzureMonitor.Demo".
builder.Services.ConfigureOpenTelemetryMeterProvider((sp, builder) => builder.AddMeter("OTel.AzureMonitor.Demo"));

// Add the Azure Monitor telemetry service to the application.
// This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor();

// Build the ASP.NET Core web application.
var app = builder.Build();

// Start the ASP.NET Core web application.
app.Run();

Ezt Meter a nevet kell inicializálni:

// Create a new meter named "OTel.AzureMonitor.Demo".
var meter = new Meter("OTel.AzureMonitor.Demo");

// Create a new counter metric named "MyFruitCounter".
Counter<long> myFruitCounter = meter.CreateCounter<long>("MyFruitCounter");

// Record the number of fruits sold, grouped by name and color.
myFruitCounter.Add(1, new("name", "apple"), new("color", "red"));
myFruitCounter.Add(2, new("name", "lemon"), new("color", "yellow"));
myFruitCounter.Add(1, new("name", "lemon"), new("color", "yellow"));
myFruitCounter.Add(2, new("name", "apple"), new("color", "green"));
myFruitCounter.Add(5, new("name", "apple"), new("color", "red"));
myFruitCounter.Add(4, new("name", "lemon"), new("color", "yellow"));

Példa mérőműszerre

Az alkalmazásindításnak elő kell fizetnie egy meter név szerint:

// Create a new ASP.NET Core web application builder.
var builder = WebApplication.CreateBuilder(args);

// Configure the OpenTelemetry meter provider to add a meter named "OTel.AzureMonitor.Demo".
builder.Services.ConfigureOpenTelemetryMeterProvider((sp, builder) => builder.AddMeter("OTel.AzureMonitor.Demo"));

// Add the Azure Monitor telemetry service to the application.
// This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor();

// Build the ASP.NET Core web application.
var app = builder.Build();

// Start the ASP.NET Core web application.
app.Run();

Ezt Meter a nevet kell inicializálni:

// Get the current process.
var process = Process.GetCurrentProcess();

// Create a new meter named "OTel.AzureMonitor.Demo".
var meter = new Meter("OTel.AzureMonitor.Demo");

// Create a new observable gauge metric named "Thread.State".
// This metric will track the state of each thread in the current process.
ObservableGauge<int> myObservableGauge = meter.CreateObservableGauge("Thread.State", () => GetThreadState(process));

private static IEnumerable<Measurement<int>> GetThreadState(Process process)
{
    // Iterate over all threads in the current process.
    foreach (ProcessThread thread in process.Threads)
    {
        // Create a measurement for each thread, including the thread state, process ID, and thread ID.
        yield return new((int)thread.ThreadState, new("ProcessId", process.Id), new("ThreadId", thread.Id));
    }
}

Egyéni kivételek hozzáadása

A rendszerállapot-kódtárak kiválasztása automatikusan jelenti az Application Insights kivételeit. Előfordulhat azonban, hogy manuálisan szeretné jelenteni a kivételeket a rendszerállapot-kódtárak jelentéseien túl. A kód által észlelt kivételeket például általában nem jelenti a rendszer. Előfordulhat, hogy fel szeretné őket jelenteni, hogy felhívják a figyelmet a releváns élményekre, beleértve a hibák szakaszt és a végpontok közötti tranzakciónézeteket.

  • Kivétel naplózása tevékenység használatával:

    // Start a new activity named "ExceptionExample".
using (var activity = activitySource.StartActivity("ExceptionExample"))
{
    // Try to execute some code.
    try
    {
        throw new Exception("Test exception");
    }
    // If an exception is thrown, catch it and set the activity status to "Error".
    catch (Exception ex)
    {
        activity?.SetStatus(ActivityStatusCode.Error);
        activity?.RecordException(ex);
    }
}

  • Kivétel naplózása a következővel ILogger:

    // Create a logger using the logger factory. The logger category name is used to filter and route log messages.
var logger = loggerFactory.CreateLogger(logCategoryName);

// Try to execute some code.
try
{
    throw new Exception("Test Exception");
}
catch (Exception ex)
{
    // Log an error message with the exception. The log level is set to "Error" and the event ID is set to 0.
    // The log message includes a template and a parameter. The template will be replaced with the value of the parameter when the log message is written.
    logger.Log(
        logLevel: LogLevel.Error,
        eventId: 0,
        exception: ex,
        message: "Hello {name}.",
        args: new object[] { "World" });
}

Egyéni spanok hozzáadása

Előfordulhat, hogy két forgatókönyvben szeretne egyéni tartományt hozzáadni. Először is, ha van egy olyan függőségi kérés, amelyet még nem gyűjtött össze egy eszközkódtár. Másodszor, ha egy alkalmazásfolyamatot szeretne modellezni a teljes körű tranzakciós nézetben.

Feljegyzés

A Activity névtérből származó System.Diagnostics osztályok és ActivitySource osztályok az OpenTelemetry fogalmaitSpan, illetve Tracerazokat jelölik. Közvetlenül a konstruktor használatával hozhat létre ActivitySource , nem pedig a használatával TracerProvider. Minden ActivitySource osztályhoz explicit módon kell kapcsolódni TracerProvider a használatával AddSource(). Ennek az az oka, hogy az OpenTelemetry tracing API egyes részei közvetlenül a .NET-futtatókörnyezetbe vannak beépítve. További információ: Bevezetés az OpenTelemetry .NET Tracing API használatába.

// Define an activity source named "ActivitySourceName". This activity source will be used to create activities for all requests to the application.
internal static readonly ActivitySource activitySource = new("ActivitySourceName");

// Create an ASP.NET Core application builder.
var builder = WebApplication.CreateBuilder(args);

// Configure the OpenTelemetry tracer provider to add a source named "ActivitySourceName". This will ensure that all activities created by the activity source are traced.
builder.Services.ConfigureOpenTelemetryTracerProvider((sp, builder) => builder.AddSource("ActivitySourceName"));

// Add the Azure Monitor telemetry service to the application. This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor();

// Build the ASP.NET Core application.
var app = builder.Build();

// Map a GET request to the root path ("/") to the specified action.
app.MapGet("/", () =>
{
    // Start a new activity named "CustomActivity". This activity will be traced and the trace data will be sent to Azure Monitor.
    using (var activity = activitySource.StartActivity("CustomActivity"))
    {
        // your code here
    }

    // Return a response message.
    return $"Hello World!";
});

// Start the ASP.NET Core application.
app.Run();

StartActivity alapértelmezett érték, ActivityKind.Internalde bármely más ActivityKindelemet megadhat. ActivityKind.Client, ActivityKind.Producerés ActivityKind.Internal az Application Insightsra dependenciesvan leképezve. ActivityKind.Server és ActivityKind.Consumer az Application Insightsra requestsvan leképezve.

Egyéni telemetriai adatok küldése a Klasszikus Application Insights API használatával

Javasoljuk, hogy amikor csak lehetséges, használja az OpenTelemetry API-kat, de előfordulhatnak forgatókönyvek, amikor a klasszikus Application Insights API-t kell használnia.

Események

  1. Adja hozzá Microsoft.ApplicationInsights az alkalmazáshoz.

  2. Példány létrehozása TelemetryClient :

    Feljegyzés

    Fontos, hogy alkalmazásonként csak egyszer hozzon létre TelemetryClient-példányt.

    var telemetryConfiguration = new TelemetryConfiguration { ConnectionString = "" };
var telemetryClient = new TelemetryClient(telemetryConfiguration);

  3. Egyéni telemetriai adatok küldése az ügyfél használatával:

    telemetryClient.TrackEvent("testEvent");

Telemetria módosítása

Ez a szakasz bemutatja, hogyan módosíthatja a telemetriát.

Span attribútumok hozzáadása

Ezek az attribútumok közé tartozhat egy egyéni tulajdonság hozzáadása a telemetriához. Attribútumokkal is beállíthat választható mezőket az Application Insights-sémában, például az ügyfél IP-címében.

Egyéni tulajdonság hozzáadása spanhoz

A spanokhoz hozzáadott attribútumok egyéni tulajdonságokként lesznek exportálva. Feltöltik a customDimensions mezőt a kérések, függőségek, nyomkövetések vagy kivételek táblában.

Span attribútumok hozzáadásához használja az alábbi két módszer egyikét:

Tipp.

A rendszerállapot-kódtárak által biztosított lehetőségek használatának előnye, hogy ha elérhetők, a teljes környezet elérhető. Ennek eredményeképpen a felhasználók további attribútumokat adhatnak hozzá vagy szűrhetnek. A HttpClient-eszköztár bővítési lehetősége például hozzáférést biztosít a felhasználóknak a HttpRequestMessage-hez és magához a HttpResponseMessage-hez . Bármit kiválaszthatnak belőle, és attribútumként tárolhatják.

  1. Számos rendszerállapot-kódtár kínál bővítési lehetőséget. Útmutatásért tekintse meg az egyes eszközkódtárak olvasási fájljait:

  2. Egyéni processzor használata:

    Tipp.

    Az Azure Monitor hozzáadása előtt adja hozzá az itt látható processzort.

    // Create an ASP.NET Core application builder.
var builder = WebApplication.CreateBuilder(args);

// Configure the OpenTelemetry tracer provider to add a new processor named ActivityEnrichingProcessor.
builder.Services.ConfigureOpenTelemetryTracerProvider((sp, builder) => builder.AddProcessor(new ActivityEnrichingProcessor()));

// Add the Azure Monitor telemetry service to the application. This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor();

// Build the ASP.NET Core application.
var app = builder.Build();

// Start the ASP.NET Core application.
app.Run();

    Adja hozzá ActivityEnrichingProcessor.cs a projekthez a következő kóddal:

    public class ActivityEnrichingProcessor : BaseProcessor<Activity>
{
    public override void OnEnd(Activity activity)
    {
        // The updated activity will be available to all processors which are called after this processor.
        activity.DisplayName = "Updated-" + activity.DisplayName;
        activity.SetTag("CustomDimension1", "Value1");
        activity.SetTag("CustomDimension2", "Value2");
    }
}

A felhasználói IP-cím beállítása

A kérések client_IP mezőjét feltöltheti egy attribútum beállításával. Az Application Insights az IP-cím használatával hoz létre felhasználói helyattribútumokat, majd alapértelmezés szerint elveti.

Használja az egyéni tulajdonság példáját, de cserélje le a következő kódsorokat a következőben ActivityEnrichingProcessor.cs:

// Add the client IP address to the activity as a tag.
// only applicable in case of activity.Kind == Server
activity.SetTag("client.address", "<IP Address>");

A felhasználói azonosító vagy a hitelesített felhasználói azonosító beállítása

A kérések user_Id vagy user_AuthenticatedId mezőjét az alábbi útmutató segítségével töltheti fel. A felhasználói azonosító névtelen felhasználói azonosító. A hitelesített felhasználói azonosító egy ismert felhasználói azonosító.

Fontos

A hitelesített felhasználói azonosító beállítása előtt tekintse meg a vonatkozó adatvédelmi jogszabályokat.

Használja az egyéni tulajdonság példáját:

// Add the user ID to the activity as a tag, but only if the activity is not null.
activity?.SetTag("enduser.id", "<User Id>");

Naplóattribútumok hozzáadása

Az OpenTelemetry a . NET's ILogger. Az egyéni dimenziók naplókhoz való csatolása üzenetsablon használatával végezhető el.

A nyomkövetési azonosító vagy a span azonosítójának lekérése

A jelenleg aktív span és Span ID az aktuális span az alábbi lépések végrehajtásával szerezhető beTrace ID.

Feljegyzés

A Activity névtérből származó System.Diagnostics osztályok és ActivitySource osztályok az OpenTelemetry fogalmaitSpan, illetve Tracerazokat jelölik. Ennek az az oka, hogy az OpenTelemetry tracing API egyes részei közvetlenül a .NET-futtatókörnyezetbe vannak beépítve. További információ: Bevezetés az OpenTelemetry .NET Tracing API használatába.

// Get the current activity.
Activity activity = Activity.Current;
// Get the trace ID of the activity.
string traceId = activity?.TraceId.ToHexString();
// Get the span ID of the activity.
string spanId = activity?.SpanId.ToHexString();

Következő lépések