Konfigurace Azure Monitor OpenTelemetry

Tato příručka vysvětluje, jak nakonfigurovat OpenTelemetry (OTel) v Azure Monitor Application Insights pomocí distribuce Azure Monitor OpenTelemetry. Správná konfigurace zajišťuje konzistentní shromažďování telemetrických dat napříč .NET, Java, Node.jsa Python aplikacemi, což umožňuje spolehlivější monitorování a diagnostiku.

Poznámka:

Pokud pracujete s aplikacemi Azure Functions, přečtěte si téma Použití OpenTelemetry s Azure Functions.

Řetězec připojení

V Application Insights definuje připojovací řetězec cílové umístění pro odesílání telemetrických dat.

Ke konfiguraci připojovací řetězec použijte jeden z následujících tří způsobů:

  • Přidejte UseAzureMonitor() do program.cs souboru.

        var builder = WebApplication.CreateBuilder(args);

    // Add the OpenTelemetry telemetry service to the application.
    // This service will collect and send telemetry data to Azure Monitor.
    builder.Services.AddOpenTelemetry().UseAzureMonitor(options => {
        options.ConnectionString = "<YOUR-CONNECTION-STRING>";
    });

    var app = builder.Build();

    app.Run();

  • Nastavte proměnnou prostředí.

    APPLICATIONINSIGHTS_CONNECTION_STRING=<YOUR-CONNECTION-STRING>

  • Do konfiguračního souboru přidejte následující část appsettings.json .

      {
    "AzureMonitor": {
        "ConnectionString": "<YOUR-CONNECTION-STRING>"
    }
  }

Poznámka:

Pokud nastavíte připojovací řetězec na více než jednom místě, platí následující pořadí priority:

  1. Code
  2. Proměnná prostředí
  3. Konfigurační soubor

Nastavení názvu cloudové role a instance cloudové role

V případě podporovaných jazyků zařízení Azure Monitor OpenTelemetry automaticky rozpozná kontext prostředku a poskytne výchozí hodnoty pro Název role cloudu a vlastnosti instance role v cloudu vaší komponenty. Můžete ale chtít přepsat výchozí hodnoty na něco, co dává vašemu týmu smysl. Hodnota názvu cloudové role se zobrazí na mapě aplikace jako název zobrazený pod uzlem.

Nastavte název cloudové role a instanci cloudové role prostřednictvím atributů prostředků . Název cloudové role používá atributy service.namespace a service.name, ale pokud service.name není nastavený, vrátí se na service.namespace. Cloudová instance role používá hodnotu atributu service.instance.id. Informace o standardních atributech pro prostředky naleznete v tématu sémantické konvence OpenTelemetry.

// Setting role name and role instance

// Create a dictionary of resource attributes.
var resourceAttributes = new Dictionary<string, object> {
    { "service.name", "my-service" },
    { "service.namespace", "my-namespace" },
    { "service.instance.id", "my-instance" }};

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

// Add the OpenTelemetry telemetry service to the application.
// This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry()
    .UseAzureMonitor()
    // Configure the ResourceBuilder to add the custom resource attributes to all signals.
    // Custom resource attributes should be added AFTER AzureMonitor to override the default ResourceDetectors.
    .ConfigureResource(resourceBuilder => resourceBuilder.AddAttributes(resourceAttributes));

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

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

Nastavení atributů prostředků

Automatická instrumentace a distribuce Azure Monitor umožní detekovat prostředky při spuštění v prostředích Azure, která jsou podporována. Další informace najdete v tématu Automatické shromažďování dat a detektory prostředků pro Azure Monitor OpenTelemetry.

Pro ruční nastavení nastavte atributy prostředků přímo pomocí standardních možností OpenTelemetry:

# Applies to .NET (ASP.NET/ASP.NET Core), Java, Node.js, and Python
export OTEL_SERVICE_NAME="my-service"
export OTEL_RESOURCE_ATTRIBUTES="cloud.provider=azure,cloud.region=westus,cloud.resource_id=/subscriptions/<SUB>/resourceGroups/<RG>/providers/Microsoft.Web/sites/<APP>"

V Windows PowerShellu:

$Env:OTEL_SERVICE_NAME="my-service"
$Env:OTEL_RESOURCE_ATTRIBUTES="cloud.provider=azure,cloud.region=westus,cloud.resource_id=/subscriptions/<SUB>/resourceGroups/<RG>/providers/Microsoft.Web/sites/<APP>"

Povolení vzorkování

Vzorkování snižuje objem a náklady na příjem telemetrie. Azure Monitor distribuce OpenTelemetry podporuje dvě strategie vzorkování pro trasování a (volitelně) umožňuje synchronizovat protokoly aplikací s vašimi rozhodnutími o vzorkování trasování. Sampler připojí vybraný poměr vzorkování nebo míru k exportovaným rozsahům, aby Application Insights mohl upravit počty zkušeností přesně. Koncepční přehled najdete v tématu Další informace o vzorkování.

Důležité

  • Rozhodnutí o vzorkování se vztahují na stopy (rozsahy).
  • Logy, které patří k netrasovaným záznamům, se ve výchozím nastavení zahodí, ale můžete deaktivovat vzorkování protokolů založené na trasách.
  • Metriky se nikdy neprovádí vzorkování.

Poznámka:

Pokud se v Application Insights zobrazí neočekávané poplatky nebo vysoké náklady, mezi běžné příčiny patří vysoký objem telemetrie, špičky příjmu dat a chybně nakonfigurované vzorkování. Pokud chcete začít řešit potíže, přečtěte si téma Řešení potíží s vysokým příjmem dat ve službě Application Insights.

Konfigurace vzorkování pomocí proměnných prostředí

Pomocí standardních proměnných prostředí OpenTelemetry vyberte sampler a zadejte jeho argument. Další informace o typech vzorkovníků OpenTelemetry najdete v tématu OTEL_TRACES_SAMPLER.

  • OTEL_TRACES_SAMPLER Typ vzorkovníku

    • microsoft.fixed_percentage odebírejte zlomek stop.
    • microsoft.rate_limited — sledy za sekundu.

  • OTEL_TRACES_SAMPLER_ARG Argument vzorkovníku

    • Pro microsoft.fixed_percentage: hodnota v rozmezí 0,0–1,0 (například 0.1 = ~10%).
    • Pro microsoft.rate_limited: maximální počet trasování za sekundu (například 1.5).

Následující příklady ukazují, jak nakonfigurovat vzorkování pomocí proměnných prostředí.

Poznámka:

Následující příklady nejsou platné pro Java. Pro správné proměnné prostředí se podívejte na předchozí kartu Java.

Vzorkování s pevným procentem (~10%)

export OTEL_TRACES_SAMPLER="microsoft.fixed_percentage"
export OTEL_TRACES_SAMPLER_ARG=0.1

Vzorkování omezené rychlostí (přibližně 1,5 trasování za sekundu)

export OTEL_TRACES_SAMPLER="microsoft.rate_limited"
export OTEL_TRACES_SAMPLER_ARG=1.5

Konfigurace vzorkování v kódu

Poznámka:

Pokud jsou nakonfigurované možnosti na úrovni kódu i proměnné prostředí, mají proměnné prostředí přednost. Výchozí chování vzorkovníku se může lišit podle jazyka.

Pevné procento vzorkování

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOpenTelemetry().UseAzureMonitor(o =>
{
    o.SamplingRatio = 0.1F; // ~10%
});
var app = builder.Build();
app.Run();

Vzorkování s omezením rychlosti

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOpenTelemetry().UseAzureMonitor(o =>
{
    o.TracesPerSecond = 1.5; // ~1.5 traces/sec
});
var app = builder.Build();
app.Run();

Poznámka:

Pokud v kódu nebo prostřednictvím proměnných prostředí nenastavíte sampler, Azure Monitor ve výchozím nastavení použije ApplicationInsightsSampler.

Návod

Při použití vzorkování s pevným procentem a nevíte, jakou hodnotu pro vzorkovací frekvenci nastavíte, začněte na 5% (0.05). Upravte rychlost podle přesnosti operací zobrazených v oknech selhání a výkonu. Jakékoli vzorkování snižuje přesnost, proto sledujte metriky OpenTelemetry, které nejsou ovlivněné vzorkováním.

Konfigurace vzorkování v konfiguračním souboru

Konfigurace vzorkování v konfiguračním souboru není pro ASP.NET Core podporovaná. Ke konfiguraci vzorkování použijte místo toho kód nebo proměnné prostředí.

Konfigurace vzorkování na základě tras pro protokoly

Když tuto funkci povolíte, systém zahodí záznamy protokolu, které patří do nevzorkovaných trasování, aby vaše protokoly zůstaly v souladu s vzorkováním trasování.

  • Záznam protokolu je součástí trasování, pokud má platný SpanId.
  • Pokud přidružené trasování TraceFlags indikuje není vzorkováno, funkce zahodí záznam protokolu.
  • Záznamy protokolu bez kontextu trasování nejsou ovlivněny.
  • Funkce je ve výchozím nastavení povolená.

Pro konfiguraci vzorkování logů založeného na sledování použijte následující nastavení.

builder.Services.AddOpenTelemetry().UseAzureMonitor(o =>
{
    o.EnableTraceBasedLogsSampler = true;
});

Živé metriky

Živé metriky poskytují řídicí panel analýzy v reálném čase pro přehled o aktivitě a výkonu aplikací.

Důležité

Podívejte se na Supplementální podmínky použití pro verze Microsoft Azure Preview pro právní podmínky, které platí pro Azure funkce, které jsou v beta verzi, preview nebo jinak dosud nebyly vydány v obecné dostupnosti.

Tato funkce je ve výchozím nastavení povolena.

Uživatelé můžou při konfiguraci distribuce zakázat živé metriky.

builder.Services.AddOpenTelemetry().UseAzureMonitor(options => {
	// Disable the Live Metrics feature.
    options.EnableLiveMetrics = false;
});

Povolit ověřování Microsoft Entra ID (dříve Azure AD)

Pokud chcete vytvořit bezpečnější připojení k Azure, povolte ověřování Microsoft Entra. Tato metoda ověřování zabraňuje ingestování neautorizované telemetrie do vašeho předplatného.

Další informace najdete na vyhrazené stránce s autentizací Microsoft Entra s odkazem pro každý podporovaný jazyk.

Další informace o konfiguraci ověřování Entra ID naleznete v tématu Ověřování Microsoft Entra pro Application Insights.

Offline úložiště dat a automatické opakování

Azure Monitor nabídky založené na OpenTelemetry ukládají telemetrii do mezipaměti, když se aplikace odpojí od Application Insights a opakují pokus o odeslání po dobu až 48 hodin. Doporučení pro zpracování dat najdete v tématu Export a odstranění privátních dat. Aplikace s vysokým zatížením občas zahazují telemetrii ze dvou důvodů: překročení povolené doby nebo překročení maximální velikosti souboru. V případě potřeby produkt upřednostňuje nedávné události oproti starým událostem.

Balíček Distro obsahuje AzureMonitorExporter, který ve výchozím nastavení používá pro offline úložiště jedno z následujících umístění (v pořadí podle priority):

  • Windows

    • %LOCALAPPDATA%\Microsoft\AzureMonitor
    • %TEMP%\Microsoft\AzureMonitor

  • Bez Windows

    • %TMPDIR%/Microsoft/AzureMonitor
    • /var/tmp/Microsoft/AzureMonitor
    • /tmp/Microsoft/AzureMonitor

Pokud chcete přepsat výchozí adresář, měli byste nastavit AzureMonitorOptions.StorageDirectory.

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

// Add the OpenTelemetry telemetry service to the application.
// This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor(options =>
{
    // Set the Azure Monitor storage directory to "C:\\SomeDirectory".
    // This is the directory where the OpenTelemetry SDK will store any telemetry data that can't be sent to Azure Monitor immediately.
    options.StorageDirectory = "C:\\SomeDirectory";
});

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

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

Chcete-li tuto funkci zakázat, nastavte AzureMonitorOptions.DisableOfflineStorage = true.

Povolení vývozce OTLP

Možná budete chtít povolit Exporter OpenTelemetry Protocol (OTLP) společně s Azure Monitor Exporter, abyste mohli odesílat telemetrii do dvou umístění.

Poznámka:

Vývozce OTLP se zobrazuje pouze pro usnadnění. Microsoft oficiálně nepodporuje exportér OTLP ani žádné komponenty ani zkušenosti třetích stran, které jsou na něm podřízené.

  1. Do projektu nainstalujte balíček OpenTelemetry.Exporter.OpenTelemetryProtocol.

    dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol

  2. Přidejte následující fragment kódu. Tento příklad předpokládá, že máte kolektor OpenTelemetry se spuštěným přijímačem OTLP. Podrobnosti najdete v example na GitHub.

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

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

// Add the OpenTelemetry OTLP exporter to the application.
// This exporter will send telemetry data to an OTLP receiver, such as Prometheus
builder.Services.AddOpenTelemetry().WithTracing(builder => builder.AddOtlpExporter());
builder.Services.AddOpenTelemetry().WithMetrics(builder => builder.AddOtlpExporter());

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

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

Konfigurace OpenTelemetry

Při použití distros Azure Monitor OpenTelemetry můžete přistupovat k následujícím konfiguracím OpenTelemetry prostřednictvím proměnných prostředí.

Proměnná prostředí Popis
APPLICATIONINSIGHTS_CONNECTION_STRING Nastavte tuto proměnnou na připojovací řetězec prostředku Application Insights.
APPLICATIONINSIGHTS_STATSBEAT_DISABLED Nastavte tuto proměnnou na true pro vypnutí interního shromažďování metrik.
OTEL_RESOURCE_ATTRIBUTES Páry klíčů a hodnot, které se použijí jako atributy prostředků. Další informace o atributech prostředků najdete ve specifikaci Resource SDK.
OTEL_SERVICE_NAME Nastaví hodnotu atributu service.name prostředku. Pokud service.name je také uveden v OTEL_RESOURCE_ATTRIBUTES, OTEL_SERVICE_NAME má přednost.

Redigovat řetězce dotazu adresy URL

Pokud chcete odstranit řetězce dotazů v adresách URL, vypněte sběr řetězců dotazů. Toto nastavení se doporučuje, pokud voláte Azure úložiště pomocí tokenu SAS.

Při použití Azure.Monitor.OpenTelemetry.AspNetCore distribučního balíčku jsou zahrnuty knihovny instrumentace ASP.NET Core a HttpClient. Balíček distribuce ve výchozím nastavení vypíná redakci řetězce dotazu.

Chcete-li toto chování změnit, nastavte proměnnou prostředí buď na hodnotu true, nebo false.

  • Instrumentace ASP.NET Core: redakce řetězce dotazu je ve výchozím nastavení zakázána OTEL_DOTNET_EXPERIMENTAL_ASPNETCORE_DISABLE_URL_QUERY_REDACTION. Chcete-li tuto proměnnou prostředí povolit, nastavte ji na falsehodnotu .

  • Instrumentace klienta HTTP: OTEL_DOTNET_EXPERIMENTAL_HTTPCLIENT_DISABLE_URL_QUERY_REDACTION Redigování řetězce dotazu je standardně zakázáno. Chcete-li tuto proměnnou prostředí povolit, nastavte ji na falsehodnotu .

Interval exportu metriky

Interval exportu metrik můžete nakonfigurovat pomocí proměnné prostředí OTEL_METRIC_EXPORT_INTERVAL.

OTEL_METRIC_EXPORT_INTERVAL=60000

Výchozí hodnota je 60000 milisekundy (60 sekund). Toto nastavení určuje, jak často sada OpenTelemetry SDK exportuje metriky.

Návod

Azure Monitor Metriky a Azure Monitor Pracovní prostor ingestují vlastní metriky v pevném 60sekundovém intervalu. Metriky odeslané častěji se ukládají do vyrovnávací paměti a zpracovávají se jednou za 60 sekund. Log Analytics zaznamenává metriky v intervalu, v jakém se odesílají, což může zvýšit náklady v kratších intervalech a zpozdit viditelnost u delších.

Referenční informace najdete v následujících specifikacích OpenTelemetry:

Řešení potíží, zpětná vazba a podpora

Návod

Následující části jsou k dispozici ve všech článcích o distribuci OpenTelemetry.

Troubleshooting

Zpětná vazba k OpenTelemetry

Poskytnutí zpětné vazby:

Podpora

Vyberte kartu pro jazyk podle vašeho výběru a objevte možnosti podpory.

  • V případě problémů s podporou Azure otevřete podpora Azure ticket.
  • V případě problémů s OpenTelemetry se obraťte přímo na komunitu OpenTelemetry .NET.
  • Seznam otevřených problémů souvisejících s vývozcem Azure Monitor najdete na stránce GitHub Problémy.

Další kroky

  • Last updated on