Sdílet prostřednictvím

Konfigurujte OpenTelemetry pro Azure Monitor

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

Poznámka:

Informace o aplikacích Funkcí Azure najdete v tématu Použití OpenTelemetry se službou Azure Functions.

Řetězec připojení

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

Pro nastavení připojovacího stringu použijte jeden ze tří následujících 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ě, dodržujeme následující prioritu:

  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ů distro Služby Azure Monitor OpenTelemetry automaticky rozpozná kontext prostředku a poskytuje výchozí hodnoty pro název cloudové role a vlastnosti instance cloudové role 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, a pokud není service.name nastaven, použije se 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();

Povolení vzorkování

Vzorkování snižuje objem a náklady na příjem telemetrie. Distribuce OpenTelemetry služby Azure Monitor podporuje dvě strategie vzorkování trasování a (volitelně) umožňuje sladit protokoly aplikací s rozhodováním 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é

Rozsah vzorkování

  • Rozhodnutí o vzorkování se vztahují na stopy (rozsahy).
  • Metriky se nikdy nevzorkují.
  • Protokoly nejsou ve výchozím nastavení vzorkovány. Můžete se rozhodnout pro vzorkování založené na trasách pro protokoly tak, aby byly protokoly, které patří k nevzorkovaným trasám, vyřazeny (podrobnosti níže).

Poznámka:

Pokud ve službě Application Insights dochází k neočekávaným poplatkům nebo vysokým nákladům, 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í standardních proměnných prostředí OpenTelemetry vyberte sampler a zadejte jeho argument:

  • OTEL_TRACES_SAMPLER — typ vzorkovníku
    • microsoft.fixed.percentage — vybrat zlomek tras.
    • microsoft.rate_limited — maximální počet stop 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).

Examples

# Fixed percentage (~10%)
export OTEL_TRACES_SAMPLER="microsoft.fixed.percentage"
export OTEL_TRACES_SAMPLER_ARG=0.1

# Rate-limited (~1.5 traces/sec)
export OTEL_TRACES_SAMPLER="microsoft.rate_limited"
export OTEL_TRACES_SAMPLER_ARG=1.5

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í sampleru se může lišit podle jazyka – podívejte se na karty.

Vzorkování pomocí trasování pro záznamy

Pokud je tato možnost povolená, protokolové záznamy patřící k nevzorkovaným trasám se zahodí, aby vaše protokoly byly sladěny s vzorkováním tras.

Chování

  • Záznam protokolu se považuje za součást sledování, pokud má platný SpanId.
  • Pokud přidružené trasování indikuje TraceFlags, že není vzorkováno, záznam protokolu se zahodí.
  • Záznamy protokolu bez kontextu trasování nejsou ovlivněny.
  • Funkce je ve výchozím nastavení zakázaná. Povolení funkce je specifické pro jazyk – viz karty.

Vzorkování můžete nakonfigurovat v kódu nebo pomocí výše uvedených proměnných prostředí.

Konfigurace v kódu

Pevné procento

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

Omezení 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 .

Vzorkování pomocí trasování pro záznamy

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

Návod

Pokud používáte vzorkování s pevným procentem a nevíte, jak nastavit vzorkovací frekvenci, 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 doporučujeme upozorňovat na metriky OpenTelemetry, které nejsou ovlivněné vzorkováním.

Ž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é

Právní podmínky, které platí pro funkce Azure, které jsou ve verzi beta, verzi Preview nebo které zatím nejsou veřejně dostupné, najdete v Dodatečných podmínkách použití pro Microsoft Azure verze Preview.

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

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

Možná budete chtít povolit ověřování Microsoft Entra pro bezpečnější připojení k Azure, které brání neoprávněné telemetrii v ingestování do vašeho předplatného.

Další informace najdete na naší vyhrazené ověřovací stránce Microsoft Entra propojené pro každý podporovaný jazyk.

Informace o konfiguraci ověřování ID Entra najdete v tématu Ověřování Microsoft Entra pro Application Insights.

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

Nabídky založené na OpenTelemetry služby Azure Monitor ukládají telemetrii do mezipaměti, když se aplikace odpojí od Application Insights a opakuje odesílá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
  • Jiné než 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 cannot 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, měli byste nastavit AzureMonitorOptions.DisableOfflineStorage = true.

Povolení vývozce OTLP

Možná budete chtít povolit exportér openTelemetry Protocol (OTLP) společně s exportérem služby Azure Monitor, aby odesílal telemetrická data do dvou umístění.

Poznámka:

Vývozce OTLP se zobrazuje pouze pro usnadnění. Oficiálně nepodporujeme vývozce OTLP ani žádné komponenty nebo zážitky třetích stran, které na něj navazují.

  1. Do projektu nainstalujte balíček OpenTelemetry.Exporter.OpenTelemetryProtocol.
    dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol
  1. 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 příkladu na GitHubu.
// 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

K následujícím konfiguracím OpenTelemetry je možné přistupovat prostřednictvím proměnných prostředí při použití distros openTelemetry služby Azure Monitor.

Proměnná prostředí Popis
APPLICATIONINSIGHTS_CONNECTION_STRING Nastavte jej na připojovací řetězec prostředku Application Insights.
APPLICATIONINSIGHTS_STATSBEAT_DISABLED Nastavte ji na true, aby se zrušil interní sběr metrik.
OTEL_RESOURCE_ATTRIBUTES Páry klíčů a hodnot určené k použití 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, pak OTEL_SERVICE_NAME má přednost.

Redigovat dotazy URL

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

Pokud používáte balíček distribuce Azure.Monitor.OpenTelemetry.AspNetCore , jsou zahrnuty knihovny instrumentace ASP.NET Core i HttpClient . Náš distribuční balíček vypne ve výchozím nastavení redakci řetězce dotazu.

Chcete-li toto chování změnit, je nutné nastavit proměnnou prostředí na true nebo false.

  • ASP.NET základní instrumentace: OTEL_DOTNET_EXPERIMENTAL_ASPNETCORE_DISABLE_URL_QUERY_REDACTION Ve výchozím nastavení je redakce řetězce dotazu zakázaná. 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

Metriky Azure Monitor a pracovní prostor Azure Monitor 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:

  • Last updated on