Observabilité du Kit de développement logiciel (SDK) Azure Cosmos DB

Article
03/10/2024

S’APPLIQUE À : NoSQL

Les Kits de développement logiciel (SDK) .NET et Java Azure Cosmos DB prennent en charge le suivi distribué pour vous aider à surveiller vos applications. Le suivi du flux de requêtes est utile pour le débogage, l’analyse de la latence et des performances et la collecte de diagnostics. Suivi d’instruments pour vos applications à l’aide d’OpenTelemetry, qui est indépendant du fournisseur et a un ensemble de conventions sémantiques pour garantir un format de données standardisé, quel que soit l’exportateur que vous avez choisi, ou utiliser le Kit de développement logiciel (SDK) Application Insights ou la distribution OpenTelemetry d’Azure Monitor.

Bien démarrer

Le suivi distribué est disponible dans les kits SDK suivants :

Kit SDK	Version prise en charge	Notes
SDK .NET v3	>= `3.36.0`	Cette fonctionnalité est disponible dans les versions préliminaires et non préliminaires. Elle est désactivée par défaut pour les versions non préliminaires. Vous pouvez désactiver le suivi en définissant `DisableDistributedTracing = false` dans `CosmosClientOptions.CosmosClientTelemetryOptions`.
Version préliminaire du Kit de développement logiciel (SDK) .NET v3	>= `3.33.0-preview`	Cette fonctionnalité est disponible dans les versions préliminaires et non préliminaires. Elle est activée par défaut pour les versions préliminaires. Vous pouvez désactiver le suivi en définissant `DisableDistributedTracing = true` dans `CosmosClientOptions.CosmosClientTelemetryOptions`.
SDK Java v4	>= `4.43.0`

Traces (attributs)

Les traces Azure Cosmos DB suivent la spécification de la base de données OpenTelemetry et fournissent également plusieurs attributs personnalisés. Vous pouvez voir différents attributs en fonction de l’opération de votre demande, et ces attributs sont des attributs principaux pour toutes les requêtes.

Attribut	Type	Description
`net.peer.name`	string	Nom d’hôte Azure Cosmos DB.
`db.name`	string	Nom de la base de données Azure Cosmos DB.
`db.system`	string	Identificateur pour le service de la base de données. Est `cosmosdb` pour toutes les requêtes.
`db.operation`	string	Nom de l’opération, ex. `CreateItemAsync`.
`db.cosmosdb.container`	string	Nom de conteneur Azure Cosmos DB.
`db.cosmosdb.client_id`	string	Identificateur représentant une instance client unique.
`db.cosmosdb.operation_type`	string	Type d’opération, ex. `Create`.
`db.cosmosdb.connection_mode`	string	Mode de connexion client. `direct` ou `gateway`.
`db.cosmosdb.status_code`	int	Le code d'état pour la demande.
`db.cosmosdb.sub_status_code`	int	Le code de sous-état pour la demande.
`db.cosmosdb.request_charge`	double	Unités de requête consommées pour l’opération.
`db.cosmosdb.regions_contacted`	string	Liste des régions contactées dans le compte Azure Cosmos DB.
`user_agent.original`	string	Chaîne d’agent utilisateur complète générée par le Kit de développement logiciel (SDK) Azure Cosmos DB.

Collecter des diagnostics

Si vous avez configuré des journaux dans votre fournisseur de trace, vous pouvez obtenir automatiquement des diagnostics pour les requêtes Azure Cosmos DB ayant échoué ou qui ont eu une latence élevée. Ces journaux peuvent vous aider à diagnostiquer les demandes ayant échoué et lentes sans nécessiter de code personnalisé pour les capturer.

.NET
Java

En plus d’obtenir des journaux de diagnostic pour les demandes ayant échoué, vous pouvez configurer différents seuils de latence pour le moment auquel collecter des diagnostics à partir des demandes réussies. Les valeurs par défaut sont 100 ms pour les opérations de point et 500 ms pour les opérations non point. Ces seuils peuvent être ajustés via les options du client.

CosmosClientOptions options = new CosmosClientOptions()
{
    CosmosClientTelemetryOptions = new CosmosClientTelemetryOptions()
    {
        DisableDistributedTracing = false,
        CosmosThresholdOptions = new CosmosThresholdOptions()
        {
            PointOperationLatencyThreshold = TimeSpan.FromMilliseconds(100),
            NonPointOperationLatencyThreshold = TimeSpan.FromMilliseconds(500)
        }
    },
};

Vous pouvez configurer le niveau de journalisation pour contrôler les diagnostics journaux que vous recevez.

Niveau du journal	Description
Error	Journaux pour les erreurs uniquement.
Avertissement	Journaux pour les erreurs et les requêtes à latence élevée en fonction des seuils configurés.
Information	Il n’existe aucun journal d’information spécifique. Les journaux de ce niveau sont identiques à l’utilisation d’Avertissement.

Selon votre environnement d’application, il existe différentes façons de configurer le niveau de journalisation. Voici un exemple de configuration dans appSettings.json :

{ 
    "Logging": {
        "LogLevel": {
            "Azure-Cosmos-Operation-Request-Diagnostics": "Information"
        }
    }
}

En plus d’obtenir des journaux de diagnostic pour les demandes ayant échoué, vous pouvez configurer différentes conditions pour collecter des diagnostics à partir des demandes réussies. Les conditions incluent un seuil de latence pour les opérations de point et les opérations pas de point et un seuil pour les demandes qui dépassent un nombre d’unités de requête. Ces seuils peuvent être définis dans le client Azure Cosmos DB.

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

Configurer OpenTelemetry

Pour utiliser OpenTelemetry avec les kits SDK Azure Cosmos DB, ajoutez la source Azure.Cosmos.Operation à votre fournisseur de traces. OpenTelemetry est compatible avec de nombreux exportateurs qui peuvent ingérer vos données. L’exemple suivant utilise le Azure Monitor OpenTelemetry Exporter, mais vous pouvez choisir de configurer n’importe quel exportateur de votre choix. En fonction de l’exportateur que vous avez choisi, vous pouvez constater un délai d’ingestion des données pouvant aller jusqu’à quelques minutes.

Conseil

Si vous utilisez le package Azure.Monitor.OpenTelemetry.Exporter, vérifiez que vous utilisez la version >= 1.0.0-beta.11. Si vous utilisez ASP.NET Core et Azure Monitor, nous vous recommandons d’utiliser la distribution OpenTelemetry d’Azure Monitor à la place.

Cet exemple montre comment configurer OpenTelemetry pour une application console .NET. Consultez l’exemple complet sur 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();

Configurer le SDK Application Insights

Il existe de nombreuses façons de configurer Application Insights en fonction de la langue dans laquelle votre application est écrite et de votre environnement de calcul. Pour plus d’informations, consultez la documentation Application Insights. L’ingestion des données dans Application Insights peut prendre jusqu’à quelques minutes.

Remarque

Utilisez la version >= 2.22.0-beta2 du package Application Insights pour votre environnement .NET cible.

L’exemple suivant montre comment configurer Application Insights pour une application console .NET. Consultez l’exemple complet sur GitHub.

IServiceCollection services = new ServiceCollection();
services.AddApplicationInsightsTelemetryWorkerService((ApplicationInsightsServiceOptions options) => options.ConnectionString = aiConnectionString);

IServiceProvider serviceProvider = services.BuildServiceProvider();
telemetryClient = serviceProvider.GetRequiredService<TelemetryClient>();

Une fois les données de trace ingérées dans Application Insights, vous pouvez les visualiser dans le portail Azure pour comprendre le flux de demandes dans votre application. Voici un exemple de données de trace provenant d’une requête de partitions croisées dans la recherche de transaction dans la navigation de gauche du portail Azure.