Partager via


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

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.

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

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.

Capture d'écran du suivi distribué d'une requête de partitions croisées Azure Cosmos DB dans la recherche de transaction d'Application Insights.

Étapes suivantes