Co je distribuovaná korelace trasování a telemetrie?

Článek
11/12/2023

Poznámka:

Následující dokumentace se spoléhá na rozhraní API Přehledy Application Přehledy Classic. Dlouhodobým plánem pro application Přehledy je shromažďovat data pomocí OpenTelemetry. Další informace najdete v tématu Povolení OpenTelemetry služby Azure Monitor pro aplikace .NET, Node.js, Python a Java.

Moderní architektury cloudových a mikroslužeb umožňují jednoduché a nezávisle nasaditelné služby, které snižují náklady a zvyšují dostupnost a propustnost. Celkový systém ale ztěžuje zdůvodnění a ladění. Distribuované trasování tento problém řeší tím, že poskytuje profiler výkonu, který funguje jako zásobníky volání pro architektury cloudových a mikroslužeb.

Azure Monitor poskytuje dvě prostředí pro využívání distribuovaných dat trasování: zobrazení diagnostiky transakcí pro jednu transakci nebo požadavek a zobrazení mapy aplikace, které ukazuje, jak systémy komunikují.

Aplikační Přehledy může monitorovat každou komponentu samostatně a zjišťovat, která komponenta zodpovídá za selhání nebo snížení výkonu pomocí distribuované korelace telemetrie. Tento článek vysvětluje datový model, techniky šíření kontextu, protokoly a implementaci taktik korelace na různých jazycích a platformách používaných aplikací Přehledy.

Povolení distribuovaného trasování

Pokud chcete povolit distribuované trasování pro aplikaci, přidejte do každé služby správnou agenta, sadu SDK nebo knihovnu na základě jejího programovacího jazyka.

Povolení prostřednictvím aplikačního Přehledy prostřednictvím automatického zatěžování nebo sad SDK

Agenti a sady SDK pro aplikace Přehledy pro .NET, .NET Core, Javu, Node.js a JavaScript podporují distribuované trasování nativně. Pokyny pro instalaci a konfiguraci jednotlivých sad Application Přehledy SDK jsou k dispozici pro:

Když je nainstalovaná a nakonfigurovaná správná sada Application Přehledy SDK, automaticky se shromažďují informace o trasování pro oblíbené architektury, knihovny a technologie pomocí automatických kolektorů závislostí sady SDK. Úplný seznam podporovaných technologií je k dispozici v dokumentaci k autocollection závislostí.

Libovolnou technologii lze také sledovat ručně pomocí volání TrackDependency v TelemetryClient.

Povolení prostřednictvím OpenTelemetry

Aplikační Přehledy teď podporuje distribuované trasování prostřednictvím OpenTelemetry. OpenTelemetry poskytuje instrumentaci neutrální dodavatele pro odesílání trasování, metrik a protokolů do Přehledy aplikace. Na začátku se komunita OpenTelemetry vzala na distribuované trasování. Metriky a protokoly stále probíhají.

Kompletní pozorovatelnost zahrnuje všechny tři pilíře. Podívejte se na stav nabídek založených na OpenTelemetry služby Azure Monitor a podívejte se na nejnovější stav zahrnutých nabídek, které nabídky jsou obecně dostupné, a možnosti podpory.

Následující stránky se skládají z jazykových pokynů pro povolení a konfiguraci nabídek založených na OpenTelemetry od Microsoftu. Důležité je, že sdílíme dostupné funkce a omezení jednotlivých nabídek, abyste mohli určit, jestli je OpenTelemetry pro váš projekt správný.

Povolení prostřednictvím OpenCensus

Kromě sad SDK Přehledy application Přehledy podporuje také distribuované trasování prostřednictvím OpenCensus. OpenCensus je opensourcová, nezávislá na dodavateli, která poskytuje shromažďování metrik a distribuované trasování služeb. Umožňuje také opensourcové komunitě povolit distribuované trasování s oblíbenými technologiemi, jako jsou Redis, Memcached nebo MongoDB. Microsoft spolupracuje na OpenCensus s několika dalšími monitorovacími a cloudovými partnery.

Další informace o OpenCensus pro Python najdete v tématu Nastavení služby Azure Monitor pro vaši aplikaci v Pythonu.

Web OpenCensus udržuje referenční dokumentaci k rozhraní API pro Python, Go a různé příručky pro použití OpenCensus.

Datový model pro korelaci telemetrie

Aplikační Přehledy definuje datový model pro distribuovanou korelaci telemetrie. Chcete-li přidružit telemetrii k logické operaci, má každá položka telemetrie kontextové pole s názvem operation_Id. Každý telemetrický údaj v distribuovaném trasování sdílí tento identifikátor. I když tedy ztratíte telemetrii z jedné vrstvy, můžete i nadále přidružit telemetrii hlášenou jinými komponentami.

Distribuovaná logická operace se obvykle skládá ze sady menších operací, které jsou požadavky zpracovávané jednou z komponent. Žádost o telemetrii definuje tyto operace. Každá položka telemetrie požadavku má vlastní id , která ji jednoznačně a globálně identifikuje. A všechny položky telemetrie (například trasování a výjimky), které jsou přidružené k požadavku, by měly nastavit operation_parentId na hodnotu požadavku id.

Telemetrie závislostí představuje každou odchozí operaci, například volání HTTP do jiné komponenty. Definuje také vlastní, id která je globálně jedinečná. Žádost o telemetrii, iniciovaná tímto voláním závislosti, používá tuto id funkci jako její operation_parentId.

Můžete vytvořit zobrazení distribuované logické operace pomocí , operation_Idoperation_parentIda request.id s dependency.id. Tato pole také definují pořadí kauzality volání telemetrie.

V prostředí mikroslužeb můžou trasování ze součástí přecházet do různých položek úložiště. Každá komponenta může mít v aplikačním Přehledy vlastní připojovací řetězec. Pokud chcete získat telemetrii pro logickou operaci, aplikace Přehledy dotazuje data ze všech položek úložiště.

Pokud je počet položek úložiště velký, potřebujete nápovědu, kde se má další vzhled. Datový model aplikace Přehledy definuje dvě pole pro vyřešení tohoto problému: request.source a dependency.target. První pole identifikuje komponentu, která iniciovala požadavek na závislost. Druhé pole určuje, která komponenta vrátila odpověď volání závislosti.

Informace o dotazování z několika různorodých instancí pomocí výrazu app dotazu najdete v dotazu azure Monitoru ve výrazu app().

Příklad

Podívejme se na příklad. Aplikace s názvem Stock Prices (Ceny akcií) zobrazuje aktuální tržní cenu akcií pomocí externího rozhraní API s názvem Akcie. Aplikace Stock Prices má stránku s názvem Stock page, kterou klient webový prohlížeč otevře pomocí GET /Home/Stock. Aplikace se dotazuje na burzovní rozhraní API pomocí volání GET /api/stock/valueHTTP .

Výslednou telemetrii můžete analyzovat spuštěním dotazu:

(requests | union dependencies | union pageViews)
| where operation_Id == "STYz"
| project timestamp, itemType, name, id, operation_ParentId, operation_Id

Ve výsledcích všechny položky telemetrie sdílejí kořen operation_Id. Při volání Ajax ze stránky se k telemetrii závislostí přiřadí nové jedinečné ID (qJSXU) a ID objektu pageView se použije jako operation_ParentId. Požadavek serveru pak použije ID Ajax jako operation_ParentId.

Itemtype	name	ID	operation_ParentId	operation_Id
pageView	Stock page	`STYz`		`STYz`
Závislost	GET /Home/Stock	`qJSXU`	`STYz`	`STYz`
request	GET Home/Stock	`KqKwlrSt9PA=`	`qJSXU`	`STYz`
Závislost	GET /api/stock/value	`bBrf2L7mm2g=`	`KqKwlrSt9PA=`	`STYz`

Při volání GET /api/stock/value do externí služby potřebujete znát identitu tohoto serveru, abyste mohli pole správně nastavit dependency.target . Pokud externí služba nepodporuje monitorování, target nastaví se na název hostitele služby. Příklad: stock-prices-api.com. Pokud se ale služba identifikuje vrácením předdefinované hlavičky HTTP, obsahuje identitu služby, target která umožňuje aplikaci Přehledy sestavit distribuované trasování dotazováním telemetrie z této služby.

Hlavičky korelace pomocí W3C TraceContext

Aplikační Přehledy přechází na kontext trasování W3C, který definuje:

traceparent: Nese globálně jedinečné ID operace a jedinečný identifikátor volání.
tracestate: Přenáší kontext trasování specifické pro systém.

Nejnovější verze sady Application Přehledy SDK podporuje protokol Trace-Context, ale možná se k němu budete muset přihlásit. (Zpětnou kompatibilitu s předchozím korelačním protokolem podporovaným sadou Application Přehledy SDK je zachována.)

Protokol HTTP korelace, označovaný také jako ID požadavku, je zastaralý. Tento protokol definuje dvě hlavičky:

Request-Id: Přenáší globálně jedinečné ID volání.
Correlation-Context: Nese kolekci párů name-value distribuovaných vlastností trasování.

Aplikační Přehledy také definuje rozšíření pro protokol HTTP korelace. Pomocí Request-Context párů name-value rozšíří kolekci vlastností používaných bezprostředním volajícím nebo volanou. Sada Application Přehledy SDK používá tuto hlavičku dependency.target k nastavení polí a request.source polí.

Kontext trasování W3C a aplikační Přehledy datové modely mapují následujícím způsobem:

Application Insights	W3C TraceContext
`Id`a `RequestDependency`	parent-id
`Operation_Id`	trace-id
`Operation_ParentId`	parent-id nadřazeného rozsahu tohoto rozsahu. Toto pole musí být prázdné, pokud se jedná o kořenové rozpětí.

Další informace najdete v tématu Aplikační Přehledy datového modelu telemetrie.

Povolení podpory distribuovaného trasování W3C pro aplikace .NET

Distribuované trasování založené na W3C TraceContext je ve výchozím nastavení povolené ve všech nedávných sadách .NET Framework/.NET Core SDK spolu s zpětnou kompatibilitou se starší verzí protokolu REQUEST-ID.

Povolení podpory distribuovaného trasování W3C pro aplikace v Javě

Agent Java 3.0

Agent Java 3.0 podporuje technologii W3C a nevyžaduje se žádná další konfigurace.

Java SDK

Příchozí konfigurace

V případě aplikací Java EE přidejte do <TelemetryModules> značky v aplikaci následující kód Přehledy.xml:
```
<Add type="com.microsoft.applicationinsights.web.extensibility.modules.WebRequestTrackingTelemetryModule>
   <Param name = "W3CEnabled" value ="true"/>
   <Param name ="enableW3CBackCompat" value = "true" />
</Add>
```
Pro aplikace Spring Boot přidejte tyto vlastnosti:
- azure.application-insights.web.enable-W3C=true
- azure.application-insights.web.enable-W3C-backcompat-mode=true
Odchozí konfigurace

Do AI-Agent.xml přidejte následující kód:
```
<Instrumentation>
  <BuiltIn enabled="true">
    <HTTP enabled="true" W3C="true" enableW3CBackCompat="true"/>
  </BuiltIn>
</Instrumentation>
```
Poznámka:

Režim zpětné kompatibility je ve výchozím nastavení povolený a enableW3CBackCompat parametr je volitelný. Používejte ho jenom v případech, kdy chcete zpětnou kompatibilitu vypnout.

V ideálním případě tento režim vypnete, když se všechny vaše služby aktualizují na novější verze sad SDK, které podporují protokol W3C. Důrazně doporučujeme co nejdříve přejít na tyto novější sady SDK.

Je důležité zajistit, aby příchozí a odchozí konfigurace byly úplně stejné.

Povolení podpory distribuovaného trasování W3C pro webové aplikace

Tato funkce je ve výchozím nastavení povolená pro JavaScript a hlavičky se automaticky zahrnou, když je doména hostitelské stránky stejná jako doména, na kterou se požadavky odesílají (například hostující stránka je example.com a požadavky Ajax se odesílají).example.com Pokud chcete změnit režim distribuovaného trasování, použijte distributedTracingMode konfigurační pole. AI_AND_W3C poskytuje ve výchozím nastavení zpětnou kompatibilitu se staršími službami instrumentovanými Přehledy aplikací.

Nastavení na základě npm

Přidejte následující konfiguraci:
```
  distributedTracingMode: DistributedTracingModes.W3C
```
Nastavení skriptu založeného na skriptech sady JavaScript (Web) SDK

Přidejte následující konfiguraci:
```
    distributedTracingMode: 2 // DistributedTracingModes.W3C
```

Pokud se požadavky XMLHttpRequest nebo Fetch Ajax posílají jinému hostiteli domény, včetně subdomén, hlavičky korelace se ve výchozím nastavení nezahrnou. Chcete-li tuto funkci povolit, nastavte enableCorsCorrelation konfigurační pole na truehodnotu . Pokud nastavíte hodnotu enableCorsCorrelationtrue, všechny požadavky XMLHttpRequest a Fetch Ajax zahrnují hlavičky korelace. V důsledku toho se může stát, že pokud aplikace na volaném serveru nepodporuje hlavičku traceparent , požadavek může selhat v závislosti na tom, jestli prohlížeč nebo verze může požadavek ověřit na základě toho, které hlavičky server přijímá. Konfigurační pole můžete použít correlationHeaderExcludedDomains k vyloučení domény serveru z injektáže hlaviček korelace mezi komponentou. Můžete například použít correlationHeaderExcludedDomains: ['*.auth0.com'] k vyloučení hlaviček korelace z požadavků odeslaných zprostředkovateli identity Auth0.

Důležité

Pokud chcete zobrazit všechny konfigurace potřebné k povolení korelace, prohlédněte si dokumentaci k korelaci JavaScriptu.

Korelace telemetrie v Pythonu OpenCensus

OpenCensus Python podporuje kontext trasování W3C bez nutnosti další konfigurace.

Pro referenci najdete datový model OpenCensus na této stránce GitHubu.

Korelace příchozích požadavků

OpenCensus Python koreluje hlavičky trasování W3C z příchozích požadavků na rozsahy vygenerované z samotných požadavků. OpenCensus koreluje automaticky s integracemi těchto oblíbených architektur webových aplikací: Flask, Django a Pyramid. Stačí naplnit hlavičky trasování W3C správným formátem a odeslat je požadavkem.

Prozkoumejte tuto ukázkovou aplikaci Flask. Nainstalujte Flask, OpenCensus a rozšíření pro Flask a Azure.


pip install flask opencensus opencensus-ext-flask opencensus-ext-azure

Do proměnné prostředí je potřeba přidat Přehledy připojovací řetězec aplikace.

APPLICATIONINSIGHTS_CONNECTION_STRING=<appinsights-connection-string>

Ukázková aplikace Flask

from flask import Flask
from opencensus.ext.azure.trace_exporter import AzureExporter
from opencensus.ext.flask.flask_middleware import FlaskMiddleware
from opencensus.trace.samplers import ProbabilitySampler

app = Flask(__name__)
middleware = FlaskMiddleware(
    app,
    exporter=AzureExporter(
        connection_string='<appinsights-connection-string>', # or set environment variable APPLICATION_INSIGHTS_CONNECTION_STRING
    ), 
    sampler=ProbabilitySampler(rate=1.0),
)

@app.route('/')
def hello():
    return 'Hello World!'

if __name__ == '__main__':
    app.run(host='localhost', port=8080, threaded=True)

Tento kód spustí ukázkovou aplikaci Flask na místním počítači a naslouchá portu 8080. Pokud chcete korelovat kontext trasování, odešlete do koncového bodu požadavek. V tomto příkladu curl můžete použít příkaz:

curl --header "traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01" localhost:8080

Když se podíváte na formát záhlaví Trace-Context, můžete odvodit následující informace:

version: 00

trace-id: 4bf92f3577b34da6a3ce929d0e0e4736

parent-id/span-id: 00f067aa0ba902b7

trace-flags: 01

Pokud se podíváte na položku požadavku, která byla odeslána do služby Azure Monitor, zobrazí se pole naplněná informacemi hlavičky trasování. Data najdete v části Protokoly (Analytics) v prostředku Přehledy aplikací služby Azure Monitor.

Pole id je ve formátu <trace-id>.<span-id>, kde trace-id je převzato z hlavičky trasování, které bylo předáno v požadavku a span-id je vygenerované pole 8 bajtů pro toto rozpětí.

Pole operation_ParentId je ve formátu <trace-id>.<parent-id>, kde obě trace-id a parent-id jsou převzaty z hlavičky trasování, která byla předána v požadavku.

Korelace protokolů

OpenCensus Python umožňuje korelovat protokoly přidáním ID trasování, ID rozsahu a příznaku vzorkování pro protokolování záznamů. Tyto atributy přidáte instalací integrace protokolování OpenCensus. Do objektů Pythonu LogRecord se přidají následující atributy: traceId, spanIda traceSampled (platí pouze pro protokolovací nástroje vytvořené po integraci).

Nainstalujte integraci protokolování OpenCensus:

python -m pip install opencensus-ext-logging

Ukázková aplikace

import logging

from opencensus.trace import config_integration
from opencensus.trace.samplers import AlwaysOnSampler
from opencensus.trace.tracer import Tracer

config_integration.trace_integrations(['logging'])
logging.basicConfig(format='%(asctime)s traceId=%(traceId)s spanId=%(spanId)s %(message)s')
tracer = Tracer(sampler=AlwaysOnSampler())

logger = logging.getLogger(__name__)
logger.warning('Before the span')
with tracer.span(name='hello'):
    logger.warning('In the span')
logger.warning('After the span')

Po spuštění tohoto kódu se v konzole vytiskne následující kód:

2019-10-17 11:25:59,382 traceId=c54cb1d4bbbec5864bf0917c64aeacdc spanId=0000000000000000 Before the span
2019-10-17 11:25:59,384 traceId=c54cb1d4bbbec5864bf0917c64aeacdc spanId=70da28f5a4831014 In the span
2019-10-17 11:25:59,385 traceId=c54cb1d4bbbec5864bf0917c64aeacdc spanId=0000000000000000 After the span

Všimněte si, že je spanId k dispozici zpráva protokolu, která je v rozsahu. Je spanId stejný jako ten, který patří do rozsahu s názvem hello.

Data protokolu můžete exportovat pomocí .AzureLogHandler Další informace najdete v tématu Nastavení služby Azure Monitor pro vaši aplikaci v Pythonu.

Pro správnou korelaci můžeme také předat informace o trasování z jedné komponenty do druhé. Představte si například scénář, ve kterém jsou dvě komponenty a module1module2. Modul 1 volá funkce v modulu 2. K získání protokolů z jednoho module1 trasování a module2 z jednoho trasování můžeme použít následující přístup:

# module1.py
import logging

from opencensus.trace import config_integration
from opencensus.trace.samplers import AlwaysOnSampler
from opencensus.trace.tracer import Tracer
from module_2 import function_1

config_integration.trace_integrations(["logging"])
logging.basicConfig(
    format="%(asctime)s traceId=%(traceId)s spanId=%(spanId)s %(message)s"
)
tracer = Tracer(sampler=AlwaysOnSampler())

logger = logging.getLogger(__name__)
logger.warning("Before the span")

with tracer.span(name="hello"):
    logger.warning("In the span")
    function_1(logger, tracer)
logger.warning("After the span")

# module_2.py
import logging

from opencensus.trace import config_integration
from opencensus.trace.samplers import AlwaysOnSampler
from opencensus.trace.tracer import Tracer

config_integration.trace_integrations(["logging"])
logging.basicConfig(
    format="%(asctime)s traceId=%(traceId)s spanId=%(spanId)s %(message)s"
)
logger = logging.getLogger(__name__)
tracer = Tracer(sampler=AlwaysOnSampler())


def function_1(logger=logger, parent_tracer=None):
    if parent_tracer is not None:
        tracer = Tracer(
            span_context=parent_tracer.span_context,
            sampler=AlwaysOnSampler(),
        )
    else:
        tracer = Tracer(sampler=AlwaysOnSampler())

    with tracer.span("function_1"):
        logger.info("In function_1")

Korelace telemetrie v .NET

Korelace se ve výchozím nastavení zpracovává při onboardingu aplikace. Nejsou vyžadovány žádné zvláštní akce.

Modul runtime .NET podporuje distribuovaný pomocí aktivity a diagnostického zdroje.

Sada Application Přehledy .NET SDK používá DiagnosticSource a Activity shromažďuje a koreluje telemetrii.

Korelace telemetrie v Javě

Agent Java podporuje automatickou korelaci telemetrie. Automaticky vyplní operation_id veškerou telemetrii (například trasování, výjimky a vlastní události) vystavené v rámci požadavku. Šíří také hlavičky korelace popsané dříve pro volání mezi službami prostřednictvím protokolu HTTP, pokud je nakonfigurovaný agent sady Java SDK.

Poznámka:

Application Přehledy agent Java autocollects requests and dependencies for JMS, Kafka, Netty/Webflux a další. Pro sadu Java SDK jsou pro funkci korelace podporována pouze volání přes Apache HttpClient. Automatické šíření kontextu mezi technologiemi zasílání zpráv, jako jsou Kafka, RabbitMQ a Azure Service Bus, se v sadě SDK nepodporuje.

Pokud chcete shromažďovat vlastní telemetrii, musíte aplikaci instrumentovat pomocí sady Java SDK 2.6.

Názvy rolí

Možná budete chtít přizpůsobit způsob zobrazení názvů komponent v mapě aplikace. Uděláte to ručně cloud_RoleName tak, že provedete jednu z následujících akcí:

Pro aplikaci Přehledy Javu nastavte název cloudové role následujícím způsobem:
```
{
  "role": {
    "name": "my cloud role name"
  }
}
```
Název cloudové role můžete také nastavit pomocí proměnné APPLICATIONINSIGHTS_ROLE_NAMEprostředí .

Se sadou Application Přehledy Java SDK 2.5.0 a novějším můžete zadat cloud_RoleName přidáním <RoleName> do souboru aplikace Přehledy.xml:

<?xml version="1.0" encoding="utf-8"?>
<ApplicationInsights xmlns="http://schemas.microsoft.com/ApplicationInsights/2013/Settings" schemaVersion="2014-05-30">
   <ConnectionString>InstrumentationKey=00000000-0000-0000-0000-000000000000</ConnectionString>
   <RoleName>** Your role name **</RoleName>
   ...
</ApplicationInsights>

Pokud používáte Spring Boot s aplikací Přehledy Spring Boot Starter, nastavte vlastní název aplikace v souboru application.properties:

spring.application.name=<name-of-app>

Název cloudové role můžete také nastavit prostřednictvím proměnné prostředí nebo systémové vlastnosti. Podrobnosti najdete v tématu Konfigurace názvu cloudové role.

Další kroky

Mapa aplikace
Zápis vlastní telemetrie
Pokročilé scénáře korelace v ASP.NET Core a ASP.NET najdete v tématu Sledování vlastních operací.
Přečtěte si další informace o nastavení cloud_RoleName pro jiné sady SDK.
Onboarding všech komponent mikroslužby v application Přehledy. Projděte si podporované platformy.
Podívejte se na datový model pro typy Přehledy aplikací.
Zjistěte, jak rozšířit a filtrovat telemetrii.
Projděte si referenční informace o konfiguraci Přehledy aplikace.

Co je distribuovaná korelace trasování a telemetrie?

Povolení distribuovaného trasování

Povolení prostřednictvím aplikačního Přehledy prostřednictvím automatického zatěžování nebo sad SDK

Povolení prostřednictvím OpenTelemetry

Povolení prostřednictvím OpenCensus

Datový model pro korelaci telemetrie

Příklad

Hlavičky korelace pomocí W3C TraceContext

Povolení podpory distribuovaného trasování W3C pro aplikace .NET

Povolení podpory distribuovaného trasování W3C pro aplikace v Javě

Agent Java 3.0

Java SDK

Povolení podpory distribuovaného trasování W3C pro webové aplikace

Korelace telemetrie v Pythonu OpenCensus

Korelace příchozích požadavků

Korelace protokolů

Korelace telemetrie v .NET

Korelace telemetrie v Javě

Názvy rolí

Další kroky

Další materiály