Intégration d' OpenTelemetry s aux applications .NET

Modifier en ligne

Vous pouvez utiliser le package d'exportation Instana OTLP pour intégrer OpenTelemetry à Instana dans les applications .NET et .NET Framework. Cet exportateur assure une intégration transparente entre les outils de surveillance d' OpenTelemetry et les fonctionnalités de traçage natives d' Instana. Il établit automatiquement une corrélation entre les traces d' OpenTelemetry. et celles d' Instana. afin d'assurer un traçage distribué unifié dans l'ensemble de vos applications. Il est conçu pour fonctionner avec Instana AutoTracing,, ce qui vous permet de combiner les fonctionnalités d'instrumentation de OpenTelemetry avec les capacités de traçage automatique de Instana.

Vous pouvez également configurer l'exportateur standard OTLP pour qu'il envoie les données directement à l'agent Instana, comme décrit sur la page OpenTelemetry. Toutefois, l'outil « Instana » ( OTLP ) est la méthode recommandée pour les applications .NET et .NET Framework, car il garantit une corrélation correcte des traces.

Présentation
Plateformes prises en charge
Installation de l'exportateur
Configuration de l'exportateur

Présentation

Modifier en ligne

L'exportateur Instana OTLP est un exportateur spécialisé d' OpenTelemetry s qui assure une intégration transparente entre les instruments de OpenTelemetry et Instana. Les fonctions suivantes sont fournies :

Corrélation automatique des traces : établit une corrélation entre les traces d' OpenTelemetry et celles d' Instana
Prise en charge flexible des protocoles : prend en charge à la fois les protocoles gRPC et HTTP -Protobuf
Modes d'exportation configurables : permet de choisir entre un traitement d'exportation simple ou par lots
Configuration via les variables d'environnement : prend en charge la configuration via les variables d'environnement
Prise en charge des en-têtes personnalisés : permet d'ajouter des en-têtes personnalisés aux demandes d'exportation d' OTLP
Options de traitement par lots : permet de configurer la taille des lots, la taille de la file d'attente et les délais de planification pour des performances optimales

L'outil d'exportation d' Instana OTLP offre les avantages suivants :

Traçage unifié : les segments d' OpenTelemetry s sont automatiquement mis en corrélation avec les traces d' Instana, offrant ainsi une vue complète de votre système distribué
Intégration transparente : fonctionne avec les outils d' OpenTelemetry s existants sans nécessiter de modifications du code
Visibilité totale : toutes les données de traçage sont visibles dans l'interface utilisateur d' Instana, avec une corrélation adéquate entre les services
Déploiement flexible : prend en charge plusieurs protocoles et options de configuration pour s'adapter à votre infrastructure

Pour plus d'informations sur l'intégration d' OpenTelemetry, consultez la documentation d' OpenTelemetry.

Plateformes prises en charge

Modifier en ligne

L'outil d'exportation Instana OTLP prend en charge les plateformes .NET suivantes :


Plateforme	Statut de prise en charge
.NET Framework 4.6.2 et plus tard	GA
.NET 2.0 standard	GA
.NET 5.0 et plus tard	GA

Remarque : sur .NET Framework et .NET Standard, seul le protocole HTTP -Protobuf est pris en charge. Le protocole « gRPC » est disponible sur .NET à partir de la version 5.0.

Installation de l'exportateur

Modifier en ligne

Vous pouvez installer le package Instana OTLP Exporter NuGet de l'une des manières suivantes :

Installez dans votre projet.NET :

dotnet add package Instana.OpenTelemetry.Otlp.Exporter

Ajoutez le paquet à votre fichier de projet :

<PackageReference Include="Instana.OpenTelemetry.Otlp.Exporter" Version="<latest-version>" />

Configuration de l'exportateur

Modifier en ligne

Pour configurer l'exportateur Instana OTLP dans votre application, ajoutez-le à votre configuration OpenTelemetryTracerProvider :

Configuration de base

Modifier en ligne

using OpenTelemetry;
using OpenTelemetry.Trace;
using Instana.OpenTelemetry.Otlp.Exporter;

var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .AddSource("MyApplication")
    .AddInstanaOtlpExporter()
    .Build();

Configuration avec options

Modifier en ligne

using OpenTelemetry;
using OpenTelemetry.Trace;
using Instana.OpenTelemetry.Otlp.Exporter;

var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .AddSource("MyApplication")
    .AddInstanaOtlpExporter(options =>
    {
        options.Endpoint = new Uri("http://instana-agent:4317");
        options.Protocol = InstanaOtlpProtocol.Grpc;
    })
    .Build();

La InstanaOtlpExportOptions classe propose les propriétés de configuration suivantes :


Propriété	Type	Par défaut	Description
`Endpoint`	`Uri`	`http://localhost:4317` (À partir de 5 ans) .NET `http://localhost:4318/v1/traces` (Norme .NET Framework ou .NET )	Le point de terminaison de l' OTLP : URL. Remplacer `localhost` avec URL de votre agent Instana. Si elle n'est pas définie, la variable d'environnement ou la valeur par défaut est utilisée.
`Protocol`	`InstanaOtlpProtocol`	`Grpc` (À partir de 5 ans) .NET `HttpProtobuf` (Norme .NET Framework ou .NET )	Le protocole à utiliser : `Grpc` ou `HttpProtobuf`. Si elle n'est pas définie, la variable d'environnement ou la valeur par défaut est utilisée.
`Headers`	`IDictionary<string, string>`	Dictionnaire vide	En-têtes personnalisés à inclure dans les demandes d'exportation.
`TimeoutMilliseconds`	`int`	`10000`	Le délai d'expiration des requêtes d'exportation, en millisecondes.
`ExportProcessorType`	`InstanaExportProcessorType`	`Batch`	Type de processeur d'exportation : `Simple` ou `Batch`.
`MaxQueueSize`	`int`	`2048`	Taille maximale de la file d'attente pour le traitement par lots.
`MaxExportBatchSize`	`int`	`512`	Taille maximale des lots pour le traitement par lots.
`ScheduledDelayMilliseconds`	`int`	`5000`	Délai entre les exportations par lots, en millisecondes.

Remarque : lorsque vous configurez la Endpoint propriété, remplacez localhost par le nom d'hôte ou l'adresse IP de votre agent Instana. Par exemple, utilisez http://instana-agent:4317 pour .NET 5+ avec gRPC, ou http://instana-agent:4318/v1/traces pour .NET Framework ou .NET Standard avec HTTP -Protobuf.

Options de protocole

L'énumération InstanaOtlpProtocol propose les valeurs suivantes :

Grpc: Utilisez le protocole gRPC (disponible sur .NET à partir de la version 5.0 )
HttpProtobuf: Utilisez HTTP avec l'encodage Protobuf (disponible sur toutes les plateformes)

Remarque : sur les versions Standard d'.NET Framework et d'.NET, l'exportateur utilise HttpProtobuf automatiquement même si Grpc est spécifié.

Types de processeurs d'exportation

L'énumération InstanaExportProcessorType propose les valeurs suivantes :

Simple: Les exportations sont effectuées dès qu'elles sont terminées
Batch: Traite les lots par lots et les exporte périodiquement (recommandé pour l'environnement de production)

Configuration via des variables d'environnement

Modifier en ligne

L'exportateur Instana OTLP prend en charge la configuration via des variables d'environnement :


Variable d"environnement	Description	Exemple
INSTANA_EXPORTER_OTLP_ENDPOINT	Le point de terminaison de l' OTLP : URL	`http://instana-agent:4317`
INSTANA_EXPORTER_OTLP_PROTOCOL	Le protocole à utiliser : `grpc` ou `http/protobuf`	`grpc`

Remarque : les variables d'environnement ne sont prises en compte que si l'option correspondante n'est pas explicitement définie dans le code. Les options configurées explicitement ont priorité sur les variables d'environnement.

Exemple : utilisation des variables d'environnement

Définissez les variables d'environnement avant de lancer votre application :

Windows (PowerShell):

$env:INSTANA_EXPORTER_OTLP_ENDPOINT = "http://instana-agent:4317"
$env:INSTANA_EXPORTER_OTLP_PROTOCOL = "grpc"

Linux/macOS:

export INSTANA_EXPORTER_OTLP_ENDPOINT=http://instana-agent:4317
export INSTANA_EXPORTER_OTLP_PROTOCOL=grpc

Configurer l'exportateur sans options explicites :

var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .AddSource("MyApplication")
    .AddInstanaOtlpExporter()
    .Build();