Waarneembaarheid van Azure Cosmos DB SDK
VAN TOEPASSING OP: 
NoSQL
De Azure Cosmos DB .NET- en Java SDK's ondersteunen gedistribueerde tracering om u te helpen uw toepassingen te bewaken. Het traceren van de stroom van aanvragen is handig bij het opsporen van fouten, het analyseren van latentie en prestaties en het verzamelen van diagnostische gegevens. Instrumenttracering voor uw toepassingen met behulp van OpenTelemetry, die leverancierneutraal is en een reeks semantische conventies heeft om een gestandaardiseerde gegevensindeling te garanderen, ongeacht uw gekozen exporteur, of gebruik de Application Insights SDK of Azure Monitor OpenTelemetry Distro.
Aan de slag
Gedistribueerde tracering is beschikbaar in de volgende SDK's:
| SDK | Ondersteunde versie | Opmerkingen |
|---|---|---|
| .NET v3 SDK | >= 3.36.0 |
Deze functie is beschikbaar in zowel preview- als niet-preview-versies. Voor niet-preview-versies is deze standaard uitgeschakeld. U kunt tracering inschakelen door de instelling in CosmosClientOptions.CosmosClientTelemetryOptionste stellenDisableDistributedTracing = false. |
| .NET v3 SDK Preview | >= 3.33.0-preview |
Deze functie is beschikbaar in zowel preview- als niet-preview-versies. Voor preview-versies is deze standaard ingeschakeld. U kunt tracering uitschakelen door de instelling in CosmosClientOptions.CosmosClientTelemetryOptionste stellenDisableDistributedTracing = true. |
| Java v4 SDK | >= 4.43.0 |
Kenmerken traceren
Azure Cosmos DB-traceringen volgen de specificatie van de OpenTelemetry-database en bieden ook verschillende aangepaste kenmerken. U kunt verschillende kenmerken zien, afhankelijk van de werking van uw aanvraag en deze kenmerken zijn kernkenmerken voor alle aanvragen.
| Kenmerk | Type | Omschrijving |
|---|---|---|
net.peer.name |
tekenreeks | Azure Cosmos DB-hostnaam. |
db.name |
tekenreeks | Azure Cosmos DB-databasenaam. |
db.system |
tekenreeks | Id voor de databaseservice. Is cosmosdb voor alle aanvragen. |
db.operation |
tekenreeks | Naam van bewerking, bijvoorbeeld. CreateItemAsync. |
db.cosmosdb.container |
tekenreeks | Azure Cosmos DB-containernaam. |
db.cosmosdb.client_id |
tekenreeks | Id die een uniek clientexemplaren vertegenwoordigt. |
db.cosmosdb.operation_type |
tekenreeks | Bewerkingstype, bijvoorbeeld. Create. |
db.cosmosdb.connection_mode |
tekenreeks | Clientverbindingsmodus. direct of gateway. |
db.cosmosdb.status_code |
int | Statuscode voor de aanvraag. |
db.cosmosdb.sub_status_code |
int | Substatuscode voor de aanvraag. |
db.cosmosdb.request_charge |
dubbel | RU's die worden gebruikt voor de bewerking. |
db.cosmosdb.regions_contacted |
tekenreeks | Lijst met regio's die zijn opgenomen in het Azure Cosmos DB-account. |
user_agent.original |
tekenreeks | Volledige tekenreeks voor de gebruikersagent die is gegenereerd door de Azure Cosmos DB SDK. |
Diagnostische gegevens verzamelen
Als u logboeken in uw traceringsprovider hebt geconfigureerd, kunt u automatisch diagnostische gegevens ophalen voor Azure Cosmos DB-aanvragen die zijn mislukt of een hoge latentie hadden. Deze logboeken kunnen u helpen bij het diagnosticeren van mislukte en trage aanvragen zonder dat u aangepaste code nodig hebt om ze vast te leggen.
Naast het ophalen van diagnostische logboeken voor mislukte aanvragen, kunt u verschillende latentiedrempels configureren voor het verzamelen van diagnostische gegevens van geslaagde aanvragen. De standaardwaarden zijn 100 ms voor puntbewerkingen en 500 ms voor niet-puntbewerkingen. Deze drempelwaarden kunnen worden aangepast via clientopties.
CosmosClientOptions options = new CosmosClientOptions()
{
CosmosClientTelemetryOptions = new CosmosClientTelemetryOptions()
{
DisableDistributedTracing = false,
CosmosThresholdOptions = new CosmosThresholdOptions()
{
PointOperationLatencyThreshold = TimeSpan.FromMilliseconds(100),
NonPointOperationLatencyThreshold = TimeSpan.FromMilliseconds(500)
}
},
};
U kunt het logboekniveau configureren om te bepalen welke diagnostische logboeken u ontvangt.
| Logboekniveau | Beschrijving |
|---|---|
| Error | Alleen logboeken voor fouten. |
| Waarschuwing | Logboeken voor fouten en aanvragen met hoge latentie op basis van geconfigureerde drempelwaarden. |
| Gegevens | Er zijn geen specifieke logboeken op informatieniveau. Logboeken op dit niveau zijn hetzelfde als het gebruik van Waarschuwing. |
Afhankelijk van uw toepassingsomgeving zijn er verschillende manieren om het logboekniveau te configureren. Hier volgt een voorbeeldconfiguratie in appSettings.json:
{
"Logging": {
"LogLevel": {
"Azure-Cosmos-Operation-Request-Diagnostics": "Information"
}
}
}
OpenTelemetry configureren
Als u OpenTelemetry wilt gebruiken met de Azure Cosmos DB SDK's, voegt u de Azure.Cosmos.Operation bron toe aan uw traceringsprovider. OpenTelemetry is compatibel met veel exporteurs die uw gegevens kunnen opnemen. In het volgende voorbeeld wordt de Azure Monitor OpenTelemetry Exporter, maar u kunt ervoor kiezen om elke gewenste exporteur te configureren. Afhankelijk van de door u gekozen exporteur ziet u mogelijk een vertraging bij het opnemen van gegevens van maximaal een paar minuten.
Tip
Als u het Azure.Monitor.OpenTelemetry.Exporter pakket gebruikt, controleert u of u versie >= 1.0.0-beta.11gebruikt.
Als u ASP.NET Core en Azure Monitor gebruikt, raden we u aan in plaats daarvan azure Monitor OpenTelemetry Distro te gebruiken.
In dit voorbeeld ziet u hoe u OpenTelemetry configureert voor een .NET-console-app. Bekijk het volledige voorbeeld op GitHub.
ResourceBuilder resource = ResourceBuilder.CreateDefault().AddService(
serviceName: serviceName,
serviceVersion: "1.0.0");
// Set up logging to forward logs to chosen exporter
using ILoggerFactory loggerFactory
= LoggerFactory.Create(builder => builder
.AddConfiguration(configuration.GetSection("Logging"))
.AddOpenTelemetry(options =>
{
options.IncludeFormattedMessage = true;
options.SetResourceBuilder(resource);
options.AddAzureMonitorLogExporter(o => o.ConnectionString = aiConnectionString); // Set up exporter of your choice
}));
/*.AddFilter(level => level == LogLevel.Error) // Filter is irrespective of event type or event name*/
AzureEventSourceLogForwarder logforwader = new AzureEventSourceLogForwarder(loggerFactory);
logforwader.Start();
// Configure OpenTelemetry trace provider
AppContext.SetSwitch("Azure.Experimental.EnableActivitySource", true);
_traceProvider = Sdk.CreateTracerProviderBuilder()
.AddSource("Azure.Cosmos.Operation", // Cosmos DB source for operation level telemetry
"Sample.Application")
.AddAzureMonitorTraceExporter(o => o.ConnectionString = aiConnectionString) // Set up exporter of your choice
.AddHttpClientInstrumentation() // Added to capture HTTP telemetry
.SetResourceBuilder(resource)
.Build();
De Application Insights-SDK configureren
Er zijn veel verschillende manieren om Application Insights te configureren, afhankelijk van de taal waarin uw toepassing is geschreven en uw rekenomgeving. Zie de Application Insights-documentatie voor meer informatie. Het opnemen van gegevens in Application Insights kan enkele minuten duren.
Notitie
Gebruik versie >= 2.22.0-beta2 van het Application Insights-pakket voor uw .NET-doelomgeving.
In het volgende voorbeeld ziet u hoe u Application Insights configureert voor een .NET-console-app. Bekijk het volledige voorbeeld op GitHub.
IServiceCollection services = new ServiceCollection();
services.AddApplicationInsightsTelemetryWorkerService((ApplicationInsightsServiceOptions options) => options.ConnectionString = aiConnectionString);
IServiceProvider serviceProvider = services.BuildServiceProvider();
telemetryClient = serviceProvider.GetRequiredService<TelemetryClient>();
Zodra traceringsgegevens zijn opgenomen in Application Insights, kunt u deze visualiseren in Azure Portal om inzicht te krijgen in de aanvraagstroom in uw toepassing. Hier volgt een voorbeeld van traceringsgegevens uit een query voor meerdere partities in de transactiezoekopdracht in de linkernavigatiebalk van Azure Portal.
