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.
