Waarneembaarheid van Azure Cosmos DB SDK

Artikel
03/05/2024

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.CosmosClientTelemetryOptions`te stellen`DisableDistributedTracing = 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.CosmosClientTelemetryOptions`te stellen`DisableDistributedTracing = 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.

.NET
Java

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"
        }
    }
}

Naast het ophalen van diagnostische logboeken voor mislukte aanvragen, kunt u verschillende voorwaarden configureren voor het verzamelen van diagnostische gegevens van geslaagde aanvragen. Voorwaarden omvatten een latentiedrempel voor zowel puntbewerkingen als niet-puntbewerkingen en een drempelwaarde voor aanvragen die een aantal RU's overschrijden. Deze drempelwaarden kunnen worden ingesteld in de Azure Cosmos DB-client.

    CosmosAsyncClient client = new CosmosClientBuilder()
            .endpoint("<Your account endpoint>")
            .key("<Your account key>")
            .clientTelemetryConfig(new CosmosClientTelemetryConfig()
                .diagnosticsThresholds(
                    new CosmosDiagnosticsThresholds()
                        .setPointOperationLatencyThreshold(Duration.ofMillis(100))
                        .setNonPointOperationLatencyThreshold(Duration.ofMillis(2000))
                        .setRequestChargeThreshold(100)))
            .buildAsyncClient();

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.