Eseguire la migrazione dagli SDK di .NET Application Insights ad OpenTelemetry di Monitoraggio di Azure
Questa guida fornisce istruzioni dettagliate per eseguire la migrazione di varie applicazioni .NET dall'uso dei kit di sviluppo software (SDK) di Application Insights ad OpenTelemetry di Monitoraggio di Azure.
Con la strumentazione OpenTelemetry di Monitoraggio di Azure si può prevedere un'esperienza simile a quella con gli SDK di Application Insights. Per altre informazioni e un confronto funzionalità per funzionalità, vedere lo stato di rilascio delle funzionalità.
- Eseguire la migrazione di ASP.NET Core alla distribuzione OpenTelemetry di Monitoraggio di Azure. (Pacchetto NuGet
Azure.Monitor.OpenTelemetry.AspNetCore
) - ASP.NET, console e migrazione di WorkerService all'utilità di esportazione OpenTelemetry di Monitoraggio di Azure. (Pacchetto NuGet
Azure.Monitor.OpenTelemetry.Exporter
)
Se si è in fase di attività iniziali con Application Insights e non è necessario eseguire la migrazione dall'API classica, vedere Abilitare OpenTelemetry di Monitoraggio di Azure.
Prerequisiti
- Un'applicazione Web ASP.NET Core già instrumentata con Application Insights senza alcuna personalizzazione
- Una versione attivamente supportata di .NET
Suggerimento
Si sta cercando attivamente di ottenere commenti e suggerimenti su questa documentazione per il nostro gruppo di prodotti. Inviare commenti e suggerimenti a otel@microsoft.com o consultare la sezione Assistenza clienti.
Rimuovere Application Insights SDK
Nota
Prima di procedere con questi passaggi, è necessario verificare se si è in possesso di un backup corrente dell'applicazione.
Rimuovere i pacchetti NuGet
Rimuovere il pacchetto
Microsoft.ApplicationInsights.AspNetCore
dacsproj
.dotnet remove package Microsoft.ApplicationInsights.AspNetCore
Rimuovere il codice di inizializzazione e le personalizzazioni
Rimuovere qualsiasi riferimento ai tipi di Application Insights nella codebase.
Suggerimento
Una volto rimosso il pacchetto di Application Insights, è possibile ricompilare l'applicazione per ottenere un elenco dei riferimenti che devono essere rimossi.
Rimuovere Application Insights da
ServiceCollection
eliminando la riga seguente:builder.Services.AddApplicationInsightsTelemetry();
Rimuovere la sezione
ApplicationInsights
daappsettings.json
.{ "ApplicationInsights": { "ConnectionString": "<Your Connection String>" } }
Eseguire la pulizia e la compilazione
Ispezionare la directory bin per verificare che tutti i riferimenti a
Microsoft.ApplicationInsights.*
siano stati rimossi.Testare l'applicazione
Verificare che non vi siano conseguenze impreviste per l'applicazione.
Suggerimento
Si sta cercando attivamente di ottenere commenti e suggerimenti su questa documentazione per il nostro gruppo di prodotti. Inviare commenti e suggerimenti a otel@microsoft.com o consultare la sezione Assistenza clienti.
Abilitare OpenTelemetry
Quando si seguono queste istruzioni, è consigliabile creare una risorsa di sviluppo e usare la stringa di connessione.
Pianificare l'aggiornamento della stringa di connessione per inviare i dati di telemetria alla risorsa originale dopo la conferma dell'esito positivo della migrazione.
Installare la distribuzione di Monitoraggio di Azure
La distribuzione di Monitoraggio di Azure abilita la telemetria automatica includendo librerie di strumentazione OpenTelemetry per raccogliere tracce, metriche, log ed eccezioni, inoltre consente di raccogliere dati di telemetria personalizzati.
L'installazione della distribuzione di Monitoraggio di Azure introduce OpenTelemetry SDK come dipendenza.
dotnet add package Azure.Monitor.OpenTelemetry.AspNetCore
Aggiungere e configurare OpenTelemetry e Monitoraggio di Azure
OpenTelemery SDK deve essere configurato all'avvio dell'applicazione come parte di
ServiceCollection
, generalmente inProgram.cs
.Il concetto di OpenTelemetry ha tre segnali; Tracce, Metriche e Log. La distribuzione di Monitoraggio di Azure configura ciascuno di questi segnali.
Program.cs
Nell'esempio di codice riportato di seguito sono illustrati i dati principali.
using Azure.Monitor.OpenTelemetry.AspNetCore;
using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.DependencyInjection;
public class Program
{
public static void Main(string[] args)
{
var builder = WebApplication.CreateBuilder(args);
// Call AddOpenTelemetry() to add OpenTelemetry to your ServiceCollection.
// Call UseAzureMonitor() to fully configure OpenTelemetry.
builder.Services.AddOpenTelemetry().UseAzureMonitor();
var app = builder.Build();
app.MapGet("/", () => "Hello World!");
app.Run();
}
}
È consigliabile impostare la stringa di connessione in una variabile di ambiente:
APPLICATIONINSIGHTS_CONNECTION_STRING=<Your Connection String>
Altre opzioni per configurare la stringa di connessione sono descritte in dettaglio qui: Configurare la stringa di connessione di Application Insights.
Suggerimento
Si sta cercando attivamente di ottenere commenti e suggerimenti su questa documentazione per il nostro gruppo di prodotti. Inviare commenti e suggerimenti a otel@microsoft.com o consultare la sezione Assistenza clienti.
Installare e configurare le librerie di strumentazione
Le librerie di strumentazione possono essere aggiunte al progetto per raccogliere automaticamente i dati di telemetria su componenti o dipendenze specifici.
Le librerie seguenti sono incluse nella distribuzione.
Personalizzazione delle librerie di strumentazione
La distribuzione di Monitoraggio di Azure include la strumentazione OpenTelemetry .NET per ASP.NET Core, HttpClient e SQLClient. È possibile personalizzare le strumentazioni incluse o aggiungere manualmente e autonomamente strumentazione aggiuntiva tramite l'API OpenTelemetry.
Di seguito sono riportati alcuni esempi di personalizzazione della strumentazione:
Customizing AspNetCoreTraceInstrumentationOptions
builder.Services.AddOpenTelemetry().UseAzureMonitor();
builder.Services.Configure<AspNetCoreTraceInstrumentationOptions>(options =>
{
options.RecordException = true;
options.Filter = (httpContext) =>
{
// only collect telemetry about HTTP GET requests
return HttpMethods.IsGet(httpContext.Request.Method);
};
});
Customizing HttpClientTraceInstrumentationOptions
builder.Services.AddOpenTelemetry().UseAzureMonitor();
builder.Services.Configure<HttpClientTraceInstrumentationOptions>(options =>
{
options.RecordException = true;
options.FilterHttpRequestMessage = (httpRequestMessage) =>
{
// only collect telemetry about HTTP GET requests
return HttpMethods.IsGet(httpRequestMessage.Method.Method);
};
});
Customizing SqlClientInstrumentationOptions
Microsoft fornisce la strumentazione SQLClient con il pacchetto finché è in versione beta. Quando la versione rilasciata è stabile, viene inclusa come riferimento al pacchetto standard. Fino ad allora, per personalizzare la strumentazione SQLClient, aggiungere il riferimento OpenTelemetry.Instrumentation.SqlClient
al pacchetto del progetto e usare la relativa API pubblica.
dotnet add package --prerelease OpenTelemetry.Instrumentation.SqlClient
builder.Services.AddOpenTelemetry().UseAzureMonitor().WithTracing(builder =>
{
builder.AddSqlClientInstrumentation(options =>
{
options.SetDbStatementForStoredProcedure = false;
});
});
Configurare Monitoraggio di Azure
Application Insights offriva molte altre opzioni di configurazione tramite ApplicationInsightsServiceOptions
.
Impostazione di Application Insights | Alternativa a OpenTelemetry |
---|---|
AddAutoCollectedMetricExtractor | N/D |
ApplicationVersion | Impostare "service.version" su Risorsa |
ConnectionString | Vedere le istruzioni sulla configurazione della stringa di connessione. |
DependencyCollectionOptions | N/D. Per personalizzare le dipendenze, esaminare le opzioni di configurazione disponibili per le librerie di strumentazione applicabili. |
DeveloperMode | N/D |
EnableActiveTelemetryConfigurationSetup | N/D |
EnableAdaptiveSampling | N/D. È supportato solo il campionamento a frequenza fissa. |
EnableAppServicesHeartbeatTelemetryModule | N/D |
EnableAuthenticationTrackingJavaScript | N/D |
EnableAzureInstanceMetadataTelemetryModule | N/D |
EnableDependencyTrackingTelemetryModule | Vedere le istruzioni per filtrare le Tracce. |
EnableDiagnosticsTelemetryModule | N/D |
EnableEventCounterCollectionModule | N/D |
EnableHeartbeat | N/D |
EnablePerformanceCounterCollectionModule | N/D |
EnableQuickPulseMetricStream | AzureMonitorOptions.EnableLiveMetrics |
EnableRequestTrackingTelemetryModule | Vedere le istruzioni per filtrare le Tracce. |
EndpointAddress | Utilizzare ConnectionString. |
InstrumentationKey | Utilizzare ConnectionString. |
RequestCollectionOptions | N/D. Vedere OpenTelemetry.Instrumentation.AspNetCore options. |
Rimuovere le configurazioni personalizzate
Gli scenari seguenti sono facoltativi e si applicano solo agli utenti avanzati.
Se sono presenti altri riferimenti a
TelemetryClient
che potrebbe essere usato per registrare manualmente i dati di telemetria, dovranno essere rimossi.Se sono stati aggiunti filtri o arricchimenti personalizzati sotto forma di
TelemetryProcessor
oTelemetryInitializer
personalizzati, dovranno essere rimossi. Essi sono disponibili inServiceCollection
.builder.Services.AddSingleton<ITelemetryInitializer, MyCustomTelemetryInitializer>();
builder.Services.AddApplicationInsightsTelemetryProcessor<MyCustomTelemetryProcessor>();
Rimuovere il frammento di codice JavaScript
Se è stato usato il frammento di codice fornito da Application Insights .NET SDK, dovrà essere rimosso anch’esso. Per gli esempi di codice completi sugli elementi da rimuovere, vedere la guida per abilitare i dati di telemetria sul lato client per le applicazioni Web.
Se è stato aggiunto un JavaScript SDK per raccogliere i dati di telemetria lato client, è possibile rimuoverlo sebbene continui a funzionare senza .NET SDK. Per esempi di codice completi sugli elementi da rimuovere, vedere la Guida all'onboarding per JavaScript SDK.
Rimuovere tutti gli artefatti di Visual Studio
Se è stato usato Visual Studio per eseguire l'onboarding ad Application Insights, è possibile che siano rimasti altri file nel progetto.
- Nella directory
Properties/ServiceDependencies
potrebbe essere presente un riferimento alla risorsa di Application Insights.
- Nella directory
Suggerimento
Si sta cercando attivamente di ottenere commenti e suggerimenti su questa documentazione per il nostro gruppo di prodotti. Inviare commenti e suggerimenti a otel@microsoft.com o consultare la sezione Assistenza clienti.
Domande frequenti
Questa sezione si rivolge ai clienti che usano inizializzatori o processori di telemetria oppure scrivono codice personalizzato in base all'API classica di Application Insights per creare dati di telemetria personalizzati.
Come viene eseguito il mapping dell'API SDK per i concetti di OpenTelemetry?
OpenTelemetry è un framework di osservabilità indipendente dal fornitore. Non esistono API di Application Insights negli SDK o nelle librerie di OpenTelemetry. Prima della migrazione, è importante conoscere alcuni concetti di OpenTelemetry.
In Application Insights, tutti i dati di telemetria sono stati gestiti tramite un singolo
TelemetryClient
eTelemetryConfiguration
. In OpenTelemetry ciascuno dei tre segnali di telemetria (Tracce, Metriche e Log) ha una propria configurazione. È possibile creare manualmente i dati di telemetria tramite il runtime .NET senza librerie esterne. Per altre informazioni, vedere le guide .NET su traccia distribuita, metriche e registrazione.Application Insights ha usato
TelemetryModules
per raccogliere automaticamente i dati di telemetria per l'applicazione. Al contrario, OpenTelemetry usa le librerie di strumentazione per raccogliere i dati di telemetria da componenti specifici, ad esempio AspNetCore per le richieste e HttpClient per le dipendenze.Application Insights ha utilizzato
TelemetryInitializers
per arricchire i dati di telemetria con informazioni aggiuntive o per eseguire l'override delle proprietà. Con OpenTelemetry è possibile scrivere un Processore per personalizzare un segnale specifico. Inoltre, molte librerie di strumentazione di OpenTelemetry offrono un metodoEnrich
per personalizzare i dati di telemetria generati da tale componente specifico.Application Insights ha utilizzato
TelemetryProcessors
per filtrare i dati di telemetria. È anche possibile utilizzare un Processore di OpenTelemetry per applicare le regole di filtro su un segnale specifico.
In che modo i tipi di dati di telemetria di Application Insights eseguono il mapping su OpenTelemetry?
Questa tabella esegue il mapping dei tipi di dati di Application Insights in base ai concetti di OpenTelemetry e alle relative implementazioni .NET.
Tabella di Monitoraggio di Azure | DataType di Application Insights | DataType di OpenTelemetry | Implementazione di .NET |
---|---|---|---|
customEvents | EventTelemetry | N/D | N/D |
customMetrics | MetricTelemetry | Metrica | System.Diagnostics.Metrics.Meter |
dipendenze | DependencyTelemetry | Intervalli (Client, Interno, Consumer) | System.Diagnostics.Activity |
exceptions | ExceptionTelemetry | Eccezioni | System.Exception |
requests | RequestTelemetry | Intervalli (Server, Producer) | System.Diagnostics.Activity |
traces | TraceTelemetry | Registri | Microsoft.Extensions.Logging.ILogger |
I documenti seguenti forniscono maggiori informazioni.
- Dati principali sulla raccolta dati di Application Insights per Monitoraggio di Azure
- Modello di dati di Application Insights Telemetry
- Concetti di OpenTelemetry
In che modo viene eseguito il mapping dei concetti di campionamento di Application Insights su OpenTelemetry?
Sebbene Application Insights offrisse più opzioni per configurare il campionamento, l'utilità di esportazione di Monitoraggio di Azure o la distribuzione di Monitoraggio di Azure offre solo il campionamento a frequenza fissa. È possibile campionare solo le Richieste e le Dipendenze (Tracce OpenTelemetry).
Per gli esempi di codice che illustrano in dettaglio come configurare il campionamento, vedere la guida Abilitare il campionamento
In che modo i processori e gli inizializzatori di telemetria eseguono il mapping su OpenTelemetry?
In Application Insights .NET SDK usare i processori di telemetria per filtrare e modificare o rimuovere i dati di telemetria. Usare gli inizializzatori di telemetria per aggiungere o modificare proprietà personalizzate. Per altre informazioni, vedere la Documentazione di Monitoraggio di Azure. OpenTelemetry sostituisce questi concetti con processori di attività o log, che arricchiscono e filtrano i dati di telemetria.
Filtri per le Tracce
Per filtrare i dati di telemetria in OpenTelemetry, è possibile implementare un processore di attività. Questo esempio equivale all'esempio di Application Insights relativo al filtraggio dei dati di telemetria come descritto nella Documentazione di Monitoraggio di Azure. Nell'esempio si illustra dove vengono filtrate le chiamate di dipendenza non riuscite.
using System.Diagnostics;
using OpenTelemetry;
internal sealed class SuccessfulDependencyFilterProcessor : BaseProcessor<Activity>
{
public override void OnEnd(Activity activity)
{
if (!OKtoSend(activity))
{
activity.ActivityTraceFlags &= ~ActivityTraceFlags.Recorded;
}
}
private bool OKtoSend(Activity activity)
{
return activity.Kind == ActivityKind.Client && activity.Status == ActivityStatusCode.Ok;
}
}
Per utilizzare questo processore, è necessario creare un TracerProvider
e aggiungere il processore prima di AddAzureMonitorTraceExporter
.
using OpenTelemetry.Trace;
public static void Main()
{
var tracerProvider = Sdk.CreateTracerProviderBuilder()
.AddProcessor(new SuccessfulDependencyFilterProcessor())
.AddAzureMonitorTraceExporter()
.Build();
}
Filtri per i Log
Le implementazioni ILogger
hanno un meccanismo integrato per applicare il filtro dei log.
Questo filtro consente di controllare i log inviati a ogni provider registrato, incluso OpenTelemetryLoggerProvider
. "OpenTelemetry" è l'alias di OpenTelemetryLoggerProvider
, che viene utilizzato per la configurazione delle regole dei filtri.
L'esempio seguente definisce "Error" come LogLevel
predefinito, inoltre definisce "Warning" come LogLevel
minimo per una categoria definita dall'utente.
Queste regole definite si applicano solo all'oggetto OpenTelemetryLoggerProvider
.
builder.AddFilter<OpenTelemetryLoggerProvider>("*", LogLevel.Error);
builder.AddFilter<OpenTelemetryLoggerProvider>("MyProduct.MyLibrary.MyClass", LogLevel.Warning);
Per altre informazioni, leggere la Documentazione di OpenTelemetry .NET sui log.
Aggiunta di proprietà personalizzate alle Tracce
In OpenTelemetry è possibile usare i processori di attività per arricchire i dati di telemetria con altre proprietà. Questa è un'operazione simile all'uso degli inizializzatori di telemetria in Application Insights, dove è possibile modificare le proprietà di telemetria.
Per impostazione predefinita, l'utilità di esportazione di Monitoraggio di Azure contrassegna qualsiasi richiesta HTTP con un codice di risposta pari o superiore a 400 come non riuscita. Tuttavia, se si vuole considerare 400 come esito della richiesta riuscito, è possibile aggiungere un processore di attività di arricchimento che imposta l'esito positivo dell'attività e aggiunge un tag per includere altre proprietà di telemetria. Questa operazione è simile all'aggiunta o alla modifica di proprietà mediante un inizializzatore in Application Insights, come descritto nella Documentazione di Monitoraggio di Azure.
Di seguito è riportato un esempio relativo all'aggiunta di proprietà personalizzate e a come eseguire l'override del comportamento predefinito per determinati codici di risposta:
using System.Diagnostics;
using OpenTelemetry;
/// <summary>
/// Custom Processor that overrides the default behavior of treating response codes >= 400 as failed requests.
/// </summary>
internal class MyEnrichingProcessor : BaseProcessor<Activity>
{
public override void OnEnd(Activity activity)
{
if (activity.Kind == ActivityKind.Server)
{
int responseCode = GetResponseCode(activity);
if (responseCode >= 400 && responseCode < 500)
{
// If we set the Success property, the SDK won't change it
activity.SetStatus(ActivityStatusCode.Ok);
// Allow to filter these requests in the portal
activity.SetTag("Overridden400s", "true");
}
// else leave the SDK to set the Success property
}
}
private int GetResponseCode(Activity activity)
{
foreach (ref readonly var tag in activity.EnumerateTagObjects())
{
if (tag.Key == "http.response.status_code" && tag.Value is int value)
{
return value;
}
}
return 0;
}
}
Per utilizzare questo processore, è necessario creare un TracerProvider
e aggiungere il processore prima di AddAzureMonitorTraceExporter
.
using OpenTelemetry.Trace;
public static void Main()
{
var tracerProvider = Sdk.CreateTracerProviderBuilder()
.AddSource("Company.Product.Name")
.AddProcessor(new MyEnrichingProcessor())
.AddAzureMonitorTraceExporter()
.Build();
}
Come è possibile tenere traccia manualmente dei dati di telemetria con OpenTelemetry?
Invio di Tracce - Manuale
Le tracce in Application Insights vengono archiviate come RequestTelemetry
e DependencyTelemetry
. In OpenTelemetry le tracce vengono modellate come Span
usando la classe Activity
.
OpenTelemetry .NET si avvale delle classi ActivitySource
e Activity
per le tracce, che fanno parte del runtime .NET. Questo approccio si distingue perché l'implementazione di .NET integra l'API di traccia direttamente nel runtime. Il pacchetto System.Diagnostics.DiagnosticSource
consente agli sviluppatori di usare ActivitySource
per creare e gestire le istanze di tipo Activity
. Questo metodo offre un modo semplice per aggiungere le tracce alle applicazioni .NET senza affidarsi a librerie esterne e applicando le funzionalità integrate dell'ecosistema .NET. Per informazioni più dettagliate, consultare le Procedure dettagliate della strumentazione della traccia distribuita.
Di seguito si illustra come eseguire la migrazione della traccia manuale:
Nota
In Application Insights il nome del ruolo e l'istanza del ruolo possono essere impostati a livello di telemetria. Tuttavia, con l'utilità di esportazione di Monitoraggio di Azure non è possibile eseguire la personalizzazione al livello dei singoli dati di telemetria. Il nome del ruolo e l'istanza del ruolo vengono estratti dalla risorsa OpenTelemetry e applicati a tutti i dati di telemetria. Leggere questo documento per altre informazioni: Impostare il nome del ruolo cloud e l'istanza del ruolo cloud.
DependencyTelemetry
DependencyTelemetry
di Application Insights consente di modellare le richieste in uscita. Di seguito si riporta il metodo per eseguire la conversione a OpenTelemetry:
Esempio di Application Insights:
DependencyTelemetry dep = new DependencyTelemetry
{
Name = "DependencyName",
Data = "https://www.example.com/",
Type = "Http",
Target = "www.example.com",
Duration = TimeSpan.FromSeconds(10),
ResultCode = "500",
Success = false
};
dep.Context.Cloud.RoleName = "MyRole";
dep.Context.Cloud.RoleInstance = "MyRoleInstance";
dep.Properties["customprop1"] = "custom value1";
client.TrackDependency(dep);
Esempio di OpenTelemetry:
var activitySource = new ActivitySource("Company.Product.Name");
var resourceAttributes = new Dictionary<string, object>
{
{ "service.name", "MyRole" },
{ "service.instance.id", "MyRoleInstance" }
};
var resourceBuilder = ResourceBuilder.CreateDefault().AddAttributes(resourceAttributes);
using var tracerProvider = Sdk.CreateTracerProviderBuilder()
.SetResourceBuilder(resourceBuilder)
.AddSource(activitySource.Name)
.AddAzureMonitorTraceExporter()
.Build();
// Emit traces
using (var activity = activitySource.StartActivity("DependencyName", ActivityKind.Client))
{
activity?.SetTag("url.full", "https://www.example.com/");
activity?.SetTag("server.address", "www.example.com");
activity?.SetTag("http.request.method", "GET");
activity?.SetTag("http.response.status_code", "500");
activity?.SetTag("customprop1", "custom value1");
activity?.SetStatus(ActivityStatusCode.Error);
activity?.SetEndTime(activity.StartTimeUtc.AddSeconds(10));
}
RequestTelemetry
RequestTelemetry
di Application Insights esegue la modellazione delle richieste in ingresso. Ecco come eseguirne la migrazione a OpenTelemetry:
Esempio di Application Insights:
RequestTelemetry req = new RequestTelemetry
{
Name = "RequestName",
Url = new Uri("http://example.com"),
Duration = TimeSpan.FromSeconds(10),
ResponseCode = "200",
Success = true,
Properties = { ["customprop1"] = "custom value1" }
};
req.Context.Cloud.RoleName = "MyRole";
req.Context.Cloud.RoleInstance = "MyRoleInstance";
client.TrackRequest(req);
Esempio di OpenTelemetry:
var activitySource = new ActivitySource("Company.Product.Name");
var resourceAttributes = new Dictionary<string, object>
{
{ "service.name", "MyRole" },
{ "service.instance.id", "MyRoleInstance" }
};
var resourceBuilder = ResourceBuilder.CreateDefault().AddAttributes(resourceAttributes);
using var tracerProvider = Sdk.CreateTracerProviderBuilder()
.SetResourceBuilder(resourceBuilder)
.AddSource(activitySource.Name)
.AddAzureMonitorTraceExporter()
.Build();
// Emit traces
using (var activity = activitySource.StartActivity("RequestName", ActivityKind.Server))
{
activity?.SetTag("url.scheme", "https");
activity?.SetTag("server.address", "www.example.com");
activity?.SetTag("url.path", "/");
activity?.SetTag("http.response.status_code", "200");
activity?.SetTag("customprop1", "custom value1");
activity?.SetStatus(ActivityStatusCode.Ok);
}
Rilevamento di operazioni personalizzate
In Application Insights, tenere traccia delle operazioni personalizzate usando i metodi StartOperation
e StopOperation
. Per ottenere questo risultato, usare ActivitySource
e Activity
in OpenTelemetry .NET. Per le operazioni con ActivityKind.Server
e ActivityKind.Consumer
, l'utilità di esportazione di Monitoraggio di Azure genera RequestTelemetry
. Per ActivityKind.Client
, ActivityKind.Producer
e ActivityKind.Internal
genera DependencyTelemetry
. Per altre informazioni sul rilevamento di operazioni personalizzate, vedere la Documentazione di Monitoraggio di Azure. Per altre informazioni sull'uso di ActivitySource
e Activity
in .NET, vedere le Procedure dettagliate sulla strumentazione della traccia distribuita .NET.
Di seguito si riporta un esempio relativo all'avviamento e all'arresto di un'attività per le operazioni personalizzate:
using System.Diagnostics;
using OpenTelemetry;
var activitySource = new ActivitySource("Company.Product.Name");
using var tracerProvider = Sdk.CreateTracerProviderBuilder()
.AddSource(activitySource.Name)
.AddAzureMonitorTraceExporter()
.Build();
// Start a new activity
using (var activity = activitySource.StartActivity("CustomOperation", ActivityKind.Server))
{
activity?.SetTag("customTag", "customValue");
// Perform your custom operation logic here
// No need to explicitly call Activity.Stop() because the using block automatically disposes the Activity object, which stops it.
}
Invio di Log
I Log in Application Insights vengono archiviati come TraceTelemetry
e ExceptionTelemetry
.
TraceTelemetry
In OpenTelemetry la registrazione viene integrata tramite l'interfaccia ILogger
. Ecco come eseguire la migrazione di TraceTelemetry
:
Esempio di Application Insights:
TraceTelemetry traceTelemetry = new TraceTelemetry
{
Message = "hello from tomato 2.99",
SeverityLevel = SeverityLevel.Warning,
};
traceTelemetry.Context.Cloud.RoleName = "MyRole";
traceTelemetry.Context.Cloud.RoleInstance = "MyRoleInstance";
client.TrackTrace(traceTelemetry);
Esempio di OpenTelemetry:
var resourceAttributes = new Dictionary<string, object>
{
{ "service.name", "MyRole" },
{ "service.instance.id", "MyRoleInstance" }
};
var resourceBuilder = ResourceBuilder.CreateDefault().AddAttributes(resourceAttributes);
using var loggerFactory = LoggerFactory.Create(builder => builder
.AddOpenTelemetry(loggerOptions =>
{
loggerOptions.SetResourceBuilder(resourceBuilder);
loggerOptions.AddAzureMonitorLogExporter();
}));
// Create a new instance `ILogger` from the above LoggerFactory
var logger = loggerFactory.CreateLogger<Program>();
// Use the logger instance to write a new log
logger.FoodPrice("tomato", 2.99);
internal static partial class LoggerExtensions
{
[LoggerMessage(LogLevel.Warning, "Hello from `{name}` `{price}`.")]
public static partial void FoodPrice(this ILogger logger, string name, double price);
}
ExceptionTelemetry
Application Insights usa ExceptionTelemetry
per registrare le eccezioni. Ecco come eseguire la migrazione a OpenTelemetry:
Esempio di Application Insights:
ExceptionTelemetry exceptionTelemetry = new ExceptionTelemetry(new Exception("Test exception"))
{
SeverityLevel = SeverityLevel.Error
};
exceptionTelemetry.Context.Cloud.RoleName = "MyRole";
exceptionTelemetry.Context.Cloud.RoleInstance = "MyRoleInstance";
exceptionTelemetry.Properties["customprop1"] = "custom value1";
client.TrackException(exceptionTelemetry);
Esempio di OpenTelemetry:
var resourceAttributes = new Dictionary<string, object>
{
{ "service.name", "MyRole" },
{ "service.instance.id", "MyRoleInstance" }
};
var resourceBuilder = ResourceBuilder.CreateDefault().AddAttributes(resourceAttributes);
using var loggerFactory = LoggerFactory.Create(builder => builder
.AddOpenTelemetry(loggerOptions =>
{
loggerOptions.SetResourceBuilder(resourceBuilder);
loggerOptions.AddAzureMonitorLogExporter();
}));
// Create a new instance `ILogger` from the above LoggerFactory.
var logger = loggerFactory.CreateLogger<Program>();
try
{
// Simulate exception
throw new Exception("Test exception");
}
catch (Exception ex)
{
logger?.LogError(ex, "An error occurred");
}
Invio di Metriche
Le Metriche in Application Insights vengono archiviate come MetricTelemetry
. In OpenTelemetry le metriche vengono modellate come Meter
dal pacchetto System.Diagnostics.DiagnosticSource
.
Application Insights include API metriche di preaggregazione (TrackMetric()
) e non preaggregazione (GetMetric().TrackValue()
). A differenza di OpenTelemetry, Application Insights non ha alcuna nozione di Strumenti. Application Insights ha la stessa API per tutti gli scenari relativi alla metrica.
D'altro canto, OpenTelemetry prima di tutto chiede agli utenti di scegliere lo strumento di metrica corretto in base alla semantica effettiva della metrica. Ad esempio, se l'obiettivo è effettuare un conteggio (ad esempio il numero totale di richieste server ricevute, ecc.), si consiglia di utilizzare il Contatore di OpenTelemetry. Se l'obiettivo è calcolare i diversi percentili (ad esempio, il valore P99 della latenza server), in questo caso si consiglia si utilizzare lo strumento Istogramma di OpenTelemetry. A causa di questa fondamentale differenza tra Application Insights e OpenTelemetry, non si opera alcun confronto diretto tra loro.
Diversamente da Application Insights, OpenTelemetry non fornisce meccanismi incorporati per arricchire o filtrare le metriche. In Application Insights i processori e gli inizializzatori dei dati telemetria possono essere usati per modificare o rimuovere le metriche, ma questa funzionalità non è disponibile in OpenTelemetry.
Inoltre, OpenTelemetry non supporta l'invio diretto di metriche non elaborate, perché non è disponibile alcun equivalente della funzionalità TrackMetric()
in Application Insights.
La migrazione da Application Insights a OpenTelemetry comporta la sostituzione di tutti gli utilizzi dell'API di metrica di Application Insights con l'API di OpenTelemetry. Ciò richiede la conoscenza dei vari Strumenti OpenTelemetry e della relativa semantica.
Suggerimento
L'istogramma è l'equivalente più versatile e simile all'API GetMetric().TrackValue()
di Application Insights. Per ottenere lo stesso scopo, è possibile sostituire le API di metrica di Application Insights con l'Istogramma.
Altri tipi di dati di telemetria
CustomEvents
Non supportato in OpenTelemetry.
Esempio di Application Insights:
TelemetryClient.TrackEvent()
AvailabilityTelemetry
Non supportato in OpenTelemetry.
Esempio di Application Insights:
TelemetryClient.TrackAvailability()
PageViewTelemetry
Non supportato in OpenTelemetry.
Esempio di Application Insights:
TelemetryClient.TrackPageView()
Passaggi successivi
Suggerimento
Si sta cercando attivamente di ottenere commenti e suggerimenti su questa documentazione per il nostro gruppo di prodotti. Inviare commenti e suggerimenti a otel@microsoft.com o consultare la sezione Assistenza clienti.
Supporto tecnico
- Per i problemi relativi al supporto di Azure, aprire un ticket di supporto tecnico di Azure.
- Per i problemi relativi a OpenTelemetry, contattare direttamente la community .NET di OpenTelemetry.
- Per un elenco dei problemi aperti relativi all'utilità di esportazione di Monitoraggio di Azure, vedere la pagina Problemi di GitHub.