Activez Azure Monitor OpenTelemetry pour les applications .NET, Node.js et Python (préversion)
Article
37 minutes de lecture
Azure Monitor OpenTelemetry Exporter est un composant qui envoie des traces et des métriques (et éventuellement toute la télémétrie d’application) à Azure Monitor Application Insights. Pour en savoir plus sur les concepts OpenTelemetry, consultez la vue d’ensemble d’OpenTelemetry ou les questions fréquentes (FAQ).
Cet article explique comment activer et configurer l’offre en préversion Azure Monitor basée sur OpenTelemetry. Après avoir suivi les instructions de cet article, vous pourrez envoyer des traces et des métriques OpenTelemetry à Azure Monitor Application Insights.
Important
L’offre Azure Monitor basée sur OpenTelemetry Azure pour les applications .NET, Node.js et Python est actuellement en préversion.
Pour connaître les conditions juridiques qui s’appliquent aux fonctionnalités Azure en version bêta, en préversion ou plus généralement non encore en disponibilité générale, consultez l’Avenant aux conditions d’utilisation des préversions de Microsoft Azure.
Etat prend en charge statuscode(unset,ok,error) et status-description. La « Description de l’état » est ignorée par les Exportateurs Azure Monitor.
Si vous avez besoin d’une expérience complète,utilisez le Kit de développement logiciel (SDK) ASP.NET ou ASP.NET Core Application Insights existant jusqu’à ce que l’offre basée sur OpenTelemetry gagne en maturité.
Déterminez si cette préversion vous convient. Elle active le suivi distribué, les métriques et , mais exclut les éléments suivants :
Possibilité de définir manuellement l’ID utilisateur ou l’ID utilisateur authentifié
Propagation du nom de l’opération à la télémétrie des dépendances
Etat prend uniquement en charge statuscode(unset,ok,error) et status-description. La « Description de l’état » est ignorée par les Exportateurs Azure Monitor.
Si vous avez besoin d’une expérience complète, utilisez le SDK Node.js Application Insights existant jusqu’à ce que l’offre OpenTelemetry ne soit plus en préversion.
Avertissement
À l’heure actuelle, cet outil d’exportation ne fonctionne que pour les environnements Node.js. Utilisez le SDK JavaScript Application Insights pour les scénarios web et navigateur.
Déterminez si cette préversion vous convient. Elle active le suivi distribué, les métriques et , mais exclut les éléments suivants :
Possibilité de définir manuellement l’ID utilisateur ou l’ID utilisateur authentifié
Propagation du nom de l’opération à la télémétrie des dépendances
Etat prend uniquement en charge statuscode(unset,ok,error) et status-description. La « Description de l’état » est ignorée par les Exportateurs Azure Monitor.
Si vous avez besoin d’une expérience complète, utilisez le SDK Node.js Application Insights existant jusqu’à ce que l’offre OpenTelemetry ne soit plus en préversion.
Avertissement
À l’heure actuelle, cet outil d’exportation ne fonctionne que pour les environnements Node.js. Utilisez le SDK JavaScript Application Insights pour les scénarios web et navigateur.
Déterminez si cette préversion vous convient. Elle active le suivi distribué, les métriques et , mais exclut les éléments suivants :
Etat prend uniquement en charge statuscode(unset,ok,error) et status-description. La « Description de l’état » est ignorée par les Exportateurs Azure Monitor.
Si vous avez besoin d’une expérience complète, utilisez le SDK Python-OpenCensus Application Insights existant jusqu’à ce que l’offre OpenTelemetry ne soit plus en préversion.
Bien démarrer
Suivez les étapes de cette section pour instrumenter votre application avec OpenTelemetry.
Si vous recevez une erreur de type « Aucune version n’est disponible pour le package 'Azure.Monitor.OpenTelemetry.Exporter' », cela est probablement dû au fait qu’il manque le paramètre des sources du package NuGet. Vous pouvez essayer de spécifier la source avec l’option -s :
# Install the latest package with the NuGet package source specified.
dotnet add package --prerelease Azure.Monitor.OpenTelemetry.Exporter -s https://api.nuget.org/v3/index.json
Le code suivant illustre l’activation d’OpenTelemetry dans une application console C# en configurant OpenTelemetry TracerProvider. Ce code doit être présent au démarrage de l’application. Pour ASP.NET Core, nous utilisons généralement la méthode ConfigureServices de la classe Startup de l’application. Pour les applications ASP.NET, nous utilisons généralement Global.asax.cs.
using System.Diagnostics;
using Azure.Monitor.OpenTelemetry.Exporter;
using OpenTelemetry;
using OpenTelemetry.Trace;
public class Program
{
private static readonly ActivitySource MyActivitySource = new ActivitySource(
"OTel.AzureMonitor.Demo");
public static void Main()
{
using var tracerProvider = Sdk.CreateTracerProviderBuilder()
.AddSource("OTel.AzureMonitor.Demo")
.AddAzureMonitorTraceExporter(o =>
{
o.ConnectionString = "<Your Connection String>";
})
.Build();
using (var activity = MyActivitySource.StartActivity("TestActivity"))
{
activity?.SetTag("CustomTag1", "Value1");
activity?.SetTag("CustomTag2", "Value2");
}
System.Console.WriteLine("Press Enter key to exit.");
System.Console.ReadLine();
}
}
Notes
Les classes Activity et ActivitySource de l’espace de noms System.Diagnostics représentent les concepts OpenTelemetry de Span et Tracer respectivement. Vous créez ActivitySource directement à l’aide de son constructeur à la place de TracerProvider. Chaque classe ActivitySource doit être explicitement connectée àTracerProvider à l’aide de AddSource() . Cela est dû au fait que des parties de l’API de suivi OpenTelemetry sont incorporées directement dans le runtime .NET. Pour plus d’informations, consultez Présentation de l’API de suivi .NET OpenTelemetry.
Le code suivant illustre l’activation d’OpenTelemetry dans une application JavaScript simple :
const { AzureMonitorTraceExporter } = require("@azure/monitor-opentelemetry-exporter");
const { BatchSpanProcessor } = require("@opentelemetry/sdk-trace-base");
const { NodeTracerProvider } = require("@opentelemetry/sdk-trace-node");
const { context, trace } = require("@opentelemetry/api")
const provider = new NodeTracerProvider();
provider.register();
// Create an exporter instance.
const exporter = new AzureMonitorTraceExporter({
connectionString: "<Your Connection String>"
});
// Add the exporter to the provider.
provider.addSpanProcessor(
new BatchSpanProcessor(exporter)
);
// Create a tracer.
const tracer = trace.getTracer("example-basic-tracer-node");
// Create a span. A span must be closed.
const parentSpan = tracer.startSpan("main");
for (let i = 0; i < 10; i += 1) {
doWork(parentSpan);
}
// Be sure to end the span.
parentSpan.end();
function doWork(parent) {
// Start another span. In this example, the main method already started a
// span, so that will be the parent span, and this will be a child span.
const ctx = trace.setSpan(context.active(), parent);
// Set attributes to the span.
// Check the SpanOptions interface for more options that can be set into the span creation
const spanOptions = {
attributes: {
"key": "value"
}
};
const span = tracer.startSpan("doWork", spanOptions, ctx);
// Simulate some random work.
for (let i = 0; i <= Math.floor(Math.random() * 40000000); i += 1) {
// empty
}
// Annotate our span to capture metadata about our operation.
span.addEvent("invoking doWork");
// Mark the end of span execution.
span.end();
}
Le code suivant illustre l’activation d’OpenTelemetry dans une application TypeScript simple :
import { AzureMonitorTraceExporter } from "@azure/monitor-opentelemetry-exporter";
import { BatchSpanProcessor} from "@opentelemetry/sdk-trace-base";
import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
import { Context, context, Span, SpanOptions, trace, Tracer } from "@opentelemetry/api";
const provider = new NodeTracerProvider();
provider.register();
// Create an exporter instance.
const exporter = new AzureMonitorTraceExporter({
connectionString: "<Your Connection String>"
});
// Add the exporter to the provider.
provider.addSpanProcessor(
new BatchSpanProcessor(exporter)
);
// Create a tracer.
const tracer: Tracer = trace.getTracer("example-basic-tracer-node");
// Create a span. A span must be closed.
const parentSpan: Span = tracer.startSpan("main");
for (let i = 0; i < 10; i += 1) {
doWork(parentSpan);
}
// Be sure to end the span.
parentSpan.end();
function doWork(parent: Span) {
// Start another span. In this example, the main method already started a
// span, so that will be the parent span, and this will be a child span.
const ctx: Context = trace.setSpan(context.active(), parent);
// Set attributes to the span.
// Check the SpanOptions interface for more options that can be set into the span creation
const options: SpanOptions = {
attributes: {
"key": "value"
}
};
// Create a span and attach the span options and parent span context.
const span: Span = tracer.startSpan("doWork", options, ctx);
// Simulate some random work.
for (let i = 0; i <= Math.floor(Math.random() * 40000000); i += 1) {
// empty
}
// Annotate our span to capture metadata about our operation.
span.addEvent("invoking doWork");
// Mark the end of span execution.
span.end();
}
Le code suivant illustre l’activation d’OpenTelemetry dans une application Python simple.
import os
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from azure.monitor.opentelemetry.exporter import AzureMonitorTraceExporter
exporter = AzureMonitorTraceExporter(connection_string="<Your Connection String>")
trace.set_tracer_provider(TracerProvider())
tracer = trace.get_tracer(__name__)
span_processor = BatchSpanProcessor(exporter)
trace.get_tracer_provider().add_span_processor(span_processor)
with tracer.start_as_current_span("hello"):
print("Hello, World!")
Conseil
Ajoutez des bibliothèques d’instrumentation pour collecter automatiquement les données de télémétrie dans les frameworks et bibliothèques populaires.
Définir la chaîne de connexion Application Insights
Remplacez l’espace réservé <Your Connection String> dans le code ci-dessus par la chaîne de connexion de votre ressource Application Insights.
Confirmer le déplacement des données
Exécutez votre application et ouvrez votre onglet Ressource Application Insights dans le portail Azure. L’affichage des données dans le portail peut prendre plusieurs minutes.
Notes
Si vous n’êtes pas en mesure d’exécuter l’application ou si vous n’obtenez pas de données comme prévu, accédez à la section Résolution des problèmes.
Important
Si vous avez deux ou plusieurs services émettant de la télémétrie vers la même ressource Application Insights, vous devez définir les noms des rôles cloud pour les représenter correctement sur la cartographie d’application.
Dans le cadre de l’utilisation de l’instrumentation Application Insights, nous collectons et envoyons des données de diagnostic à Microsoft. Ces données nous permettent d’exécuter et d’améliorer Application Insights. Vous pouvez désactiver la collecte de données non essentielles. Pour en savoir plus, consultez Statsbeat dans Azure Application Insights.
Définir le nom du rôle cloud et l’instance de rôle cloud
Vous pouvez définir le nom du rôle cloud et l’instance de rôle cloud via les attributs Ressource. Cela remplace la valeur par défaut du nom du rôle cloud et de l’instance de rôle cloud par quelque chose qui a un sens pour votre équipe. Cela s’affiche sur la cartographie d’application en tant que nom sous un nœud. Le nom du rôle cloud utilise les attributs service.namespace et service.name, mais il retourne à la valeur service.name si service.namespace n’est pas défini. L’instance de rôle cloud utilise la valeur d’attribut service.instance.id.
// Setting role name and role instance
var resourceAttributes = new Dictionary<string, object> {
{ "service.name", "my-service" },
{ "service.namespace", "my-namespace" },
{ "service.instance.id", "my-instance" }};
var resourceBuilder = ResourceBuilder.CreateDefault().AddAttributes(resourceAttributes);
// Done setting role name and role instance
// Set ResourceBuilder on the provider.
var tracerProvider = Sdk.CreateTracerProviderBuilder()
.SetResourceBuilder(resourceBuilder)
.AddSource("OTel.AzureMonitor.Demo")
.AddAzureMonitorTraceExporter(o =>
{
o.ConnectionString = "<Your Connection String>";
})
.Build();
...
const { Resource } = require("@opentelemetry/resources");
const { SemanticResourceAttributes } = require("@opentelemetry/semantic-conventions");
const { NodeTracerProvider } = require("@opentelemetry/sdk-trace-node");
const { MeterProvider } = require("@opentelemetry/sdk-metrics")
// ----------------------------------------
// Setting role name and role instance
// ----------------------------------------
const testResource = new Resource({
[SemanticResourceAttributes.SERVICE_NAME]: "my-helloworld-service",
[SemanticResourceAttributes.SERVICE_NAMESPACE]: "my-namespace",
[SemanticResourceAttributes.SERVICE_INSTANCE_ID]: "my-instance",
});
// ----------------------------------------
// Done setting role name and role instance
// ----------------------------------------
const tracerProvider = new NodeTracerProvider({
resource: testResource
});
const meterProvider = new MeterProvider({
resource: testResource
});
import { Resource } from "@opentelemetry/resources";
import { SemanticResourceAttributes } from "@opentelemetry/semantic-conventions";
import { NodeTracerConfig, NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
import { MeterProvider, MeterProviderOptions } from "@opentelemetry/sdk-metrics";
// ----------------------------------------
// Setting role name and role instance
// ----------------------------------------
const testResource = new Resource({
[SemanticResourceAttributes.SERVICE_NAME]: "my-helloworld-service",
[SemanticResourceAttributes.SERVICE_NAMESPACE]: "my-namespace",
[SemanticResourceAttributes.SERVICE_INSTANCE_ID]: "my-instance",
});
const tracerProviderConfig: NodeTracerConfig = {
resource: testResource
};
const meterProviderConfig: MeterProviderOptions = {
resource: testResource
};
// ----------------------------------------
// Done setting role name and role instance
// ----------------------------------------
const tracerProvider = new NodeTracerProvider(tracerProviderConfig);
const meterProvider = new MeterProvider(meterProviderConfig);
...
...
from opentelemetry.sdk.resources import SERVICE_NAME, SERVICE_NAMESPACE, SERVICE_INSTANCE_ID, Resource
trace.set_tracer_provider(
TracerProvider(
resource=Resource.create(
{
SERVICE_NAME: "my-helloworld-service",
# ----------------------------------------
# Setting role name and role instance
# ----------------------------------------
SERVICE_NAMESPACE: "my-namespace",
SERVICE_INSTANCE_ID: "my-instance",
# ----------------------------------------------
# Done setting role name and role instance
# ----------------------------------------------
}
)
)
)
...
Vous pouvez activer l’échantillonnage pour réduire votre volume d’ingestion de données, ce qui réduit vos coûts. Azure Monitor fournit un échantillonneur à taux fixe personnalisé qui remplit les événements avec un « ratio d’échantillonnage », qu’Application Insights convertit en « ItemCount ». L’échantillonneur à taux fixe garantit des expériences et des comptes d’événements précis. L’échantillonneur est conçu pour préserver vos traces entre les services, et il est interopérable avec des Kits de développement logiciel (SDK) Application Insights plus anciens. L’échantillonneur s’attend à un taux d’échantillonnage compris entre 0 et 1 inclus. Un taux de 0,1 signifie qu’environ 10 % de vos traces seront envoyées. Pour plus d’informations, consultez En savoir plus sur l’échantillonnage.
Notes
Les métriques ne sont pas affectées par l’échantillonnage.
Dans cet exemple, nous utilisons le ApplicationInsightsSampler, qui offre une compatibilité avec les Kits de développement logiciel (SDK) Application Insights.
const { BasicTracerProvider, SimpleSpanProcessor } = require("@opentelemetry/sdk-trace-base");
const { ApplicationInsightsSampler, AzureMonitorTraceExporter } = require("@azure/monitor-opentelemetry-exporter");
// Sampler expects a sample rate of between 0 and 1 inclusive
// A rate of 0.1 means approximately 10% of your traces are sent
const aiSampler = new ApplicationInsightsSampler(0.75);
const provider = new BasicTracerProvider({
sampler: aiSampler
});
const exporter = new AzureMonitorTraceExporter({
connectionString: "<Your Connection String>"
});
provider.addSpanProcessor(new SimpleSpanProcessor(exporter));
provider.register();
import { BasicTracerProvider, SimpleSpanProcessor } from "@opentelemetry/sdk-trace-base";
import { ApplicationInsightsSampler, AzureMonitorTraceExporter } from "@azure/monitor-opentelemetry-exporter";
// Sampler expects a sample rate of between 0 and 1 inclusive
// A rate of 0.1 means approximately 10% of your traces are sent
const aiSampler = new ApplicationInsightsSampler(0.75);
const provider = new BasicTracerProvider({
sampler: aiSampler
});
const exporter = new AzureMonitorTraceExporter({
connectionString: "<Your Connection String>"
});
provider.addSpanProcessor(new SimpleSpanProcessor(exporter));
provider.register();
Dans cet exemple, nous utilisons le ApplicationInsightsSampler, qui offre une compatibilité avec les Kits de développement logiciel (SDK) Application Insights.
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from azure.monitor.opentelemetry.exporter import (
ApplicationInsightsSampler,
AzureMonitorTraceExporter,
)
# Sampler expects a sample rate of between 0 and 1 inclusive
# 0.1 means approximately 10% of your traces are sent
sampler = ApplicationInsightsSampler(0.1)
trace.set_tracer_provider(TracerProvider(sampler=sampler))
tracer = trace.get_tracer(__name__)
exporter = AzureMonitorTraceExporter(connection_string="<your-connection-string>")
span_processor = BatchSpanProcessor(exporter)
trace.get_tracer_provider().add_span_processor(span_processor)
for i in range(100):
# Approximately 90% of these spans should be sampled out
with tracer.start_as_current_span("hello"):
print("Hello, World!")
Conseil
Si vous ne savez pas où définir le taux d’échantillonnage, commencez à 5 % (c’est-à-dire 0,05 du taux d’échantillonnage) et ajustez le taux en fonction de la précision des opérations affichées dans les volets d’échecs et de performances. Un taux plus élevé entraîne généralement une plus grande précision. Toutefois, l’échantillonnage ANY affecte la précision. Nous vous recommandons donc de générer des alertes sur les métriques OpenTelemetry, lesquelles ne sont pas affectées par l’échantillonnage.
Bibliothèques d’instrumentation
Les bibliothèques suivantes sont validées pour fonctionner avec la Préversion :
Avertissement
Les bibliothèques d’instrumentation sont basées sur des spécifications OpenTelemetry expérimentales. L’engagement de prise en charge de la préversion par Microsoft permet de s’assurer que les bibliothèques listées ci-dessous émettent des données pour Azure Monitor Application Insights, mais il est possible que des modifications avec rupture ou qu’un mappage expérimental bloquent certains éléments de données.
Les offres Basées sur OpenTelemetry émettent actuellement toutes les métriques en tant que Métriques personnalisées dans Metrics Explorer. Tout ce que vous définissez comme nom du compteur devient l’espace de noms des métriques.
Modifier la télémétrie
Cette section explique comment modifier la télémétrie.
Ajouter des attributs d’étendue
Pour ajouter des attributs span, utilisez l’une des deux méthodes suivantes :
Ces attributs peuvent inclure l’ajout d’une propriété personnalisée à votre télémétrie. Vous pouvez également utiliser des attributs pour définir des champs facultatifs dans le schéma Application Insights, comme une adresse IP de client.
Conseil
L’avantage de l’utilisation des options fournies par les bibliothèques d’instrumentation, lorsqu’elles sont disponibles, est que tout le contexte est disponible. Par conséquent, les utilisateurs peuvent choisir d’ajouter ou de filtrer davantage d’attributs. Par exemple, l’option enrichir de la bibliothèque d’instrumentation HttpClient permet aux utilisateurs d’accéder au httpRequestMessage lui-même. Ils peuvent sélectionner n’importe quoi et le stocker en tant qu’attribut.
Ajoutez une propriété personnalisée à une Trace
Tous les attributs que vous ajoutez aux étendues sont exportés en tant que propriétés personnalisées. Ils remplissent le champ customDimensions dans les tables de requêtes ou de dépendances dans Application Insights.
De nombreuses bibliothèques d’instrumentation fournissent une option enrichir. Pour obtenir de l’aide, consultez les fichiers Lisez-moi des bibliothèques d’instrumentation individuelles :
Ajoutez le processeur indiqué ci-dessous avant Azure Monitor Exporter.
using var tracerProvider = Sdk.CreateTracerProviderBuilder()
.AddSource("OTel.AzureMonitor.Demo")
.AddProcessor(new ActivityEnrichingProcessor())
.AddAzureMonitorTraceExporter(o =>
{
o.ConnectionString = "<Your Connection String>"
})
.Build();
Ajoutez ActivityEnrichingProcessor.cs à votre projet avec le code ci-dessous :
using System.Diagnostics;
using OpenTelemetry;
using OpenTelemetry.Trace;
public class ActivityEnrichingProcessor : BaseProcessor<Activity>
{
public override void OnEnd(Activity activity)
{
// The updated activity will be available to all processors which are called after this processor.
activity.DisplayName = "Updated-" + activity.DisplayName;
activity.SetTag("CustomDimension1", "Value1");
activity.SetTag("CustomDimension2", "Value2");
}
}
Utilisation d’un processeur personnalisé :
Conseil
Ajoutez le processeur indiqué ci-dessous avant Azure Monitor Exporter.
Ajoutez le processeur indiqué ci-dessous avant Azure Monitor Exporter.
...
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
trace.set_tracer_provider(TracerProvider())
span_processor = BatchSpanProcessor(exporter)
span_enrich_processor = SpanEnrichingProcessor()
trace.get_tracer_provider().add_span_processor(span_enrich_processor)
trace.get_tracer_provider().add_span_processor(span_processor)
...
Ajoutez SpanEnrichingProcessor.py à votre projet avec le code ci-dessous :
from opentelemetry.sdk.trace import SpanProcessor
class SpanEnrichingProcessor(SpanProcessor):
def on_end(self, span):
span._name = "Updated-" + span.name
span._attributes["CustomDimension1"] = "Value1"
span._attributes["CustomDimension2"] = "Value2"
Définir l’IP utilisateur
Vous pouvez renseigner le champ client_IP pour les requêtes en définissant l’attribut http.client_ip sur l’étendue. Application Insights utilise l’adresse IP pour générer des attributs d’emplacement utilisateur, puis la supprime par défaut.
De nombreuses bibliothèques d’instrumentation fournissent une option de filtre. Pour obtenir de l’aide, consultez les fichiers Lisez-moi des bibliothèques d’instrumentation individuelles :
using var tracerProvider = Sdk.CreateTracerProviderBuilder()
.AddSource("OTel.AzureMonitor.Demo")
.AddProcessor(new ActivityFilteringProcessor())
.AddAzureMonitorTraceExporter(o =>
{
o.ConnectionString = "<Your Connection String>"
})
.Build();
Ajoutez ActivityFilteringProcessor.cs à votre projet avec le code ci-dessous :
using System.Diagnostics;
using OpenTelemetry;
using OpenTelemetry.Trace;
public class ActivityFilteringProcessor : BaseProcessor<Activity>
{
public override void OnStart(Activity activity)
{
// prevents all exporters from exporting internal activities
if (activity.Kind == ActivityKind.Internal)
{
activity.IsAllDataRequested = false;
}
}
}
Si une source particulière n’est pas explicitement ajoutée à l’aide de AddSource("ActivitySourceName"), alors aucune des activités créées à l’aide de cette source n’est exportée.
Option d’exclusion d’URL fournie par de nombreuses bibliothèques d’instrumentation HTTP.
Utiliser un processeur personnalisé. Vous pouvez utiliser un processeur d’étendues personnalisé pour exclure certaines étendues de l’exportation. Pour marquer des étendues à ne pas exporter, définissez leur TraceFlag sur DEFAULT.
Utilisez l’exemple d’ajout d’une propriété personnalisée, mais changez les lignes de code suivantes :
import { IncomingMessage } from "http";
import { RequestOptions } from "https";
import { registerInstrumentations } from "@opentelemetry/instrumentation";
import { HttpInstrumentation, HttpInstrumentationConfig } from "@opentelemetry/instrumentation-http";
import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
const httpInstrumentationConfig: HttpInstrumentationConfig = {
ignoreIncomingRequestHook: (request: IncomingMessage) => {
// Ignore OPTIONS incoming requests
if (request.method === 'OPTIONS') {
return true;
}
return false;
},
ignoreOutgoingRequestHook: (options: RequestOptions) => {
// Ignore outgoing requests with /test path
if (options.path === '/test') {
return true;
}
return false;
}
};
const httpInstrumentation = new HttpInstrumentation(httpInstrumentationConfig);
const provider = new NodeTracerProvider();
provider.register();
registerInstrumentations({
instrumentations: [
httpInstrumentation,
]
});
Utiliser un processeur personnalisé. Vous pouvez utiliser un processeur d’étendues personnalisé pour exclure certaines étendues de l’exportation. Pour marquer des étendues à ne pas exporter, définissez leur TraceFlag sur DEFAULT.
Utilisez l’exemple d’ajout d’une propriété personnalisée, mais changez les lignes de code suivantes :
Option d’exclusion d’URL fournie par de nombreuses bibliothèques d’instrumentation HTTP.
Vous trouverez ci-dessous un exemple de la façon d’exclure une URL d’un suivi à l’aide de l’instrumentation Flask.
...
import flask
from opentelemetry.instrumentation.flask import FlaskInstrumentor
# You might also populate OTEL_PYTHON_FLASK_EXCLUDED_URLS env variable
# List will consist of comma delimited regexes representing which URLs to exclude
excluded_urls = "client/.*/info,healthcheck"
FlaskInstrumentor().instrument(excluded_urls=excluded_urls) # Do this before flask.Flask
app = flask.Flask(__name__)
...
Utiliser un processeur personnalisé. Vous pouvez utiliser un processeur d’étendues personnalisé pour exclure certaines étendues de l’exportation. Pour marquer des étendues à ne pas exporter, définissez leur TraceFlag sur DEFAULT.
...
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
trace.set_tracer_provider(TracerProvider())
span_processor = BatchSpanProcessor(exporter)
span_filter_processor = SpanFilteringProcessor()
trace.get_tracer_provider().add_span_processor(span_filter_processor)
trace.get_tracer_provider().add_span_processor(span_processor)
...
Ajoutez SpanFilteringProcessor.py à votre projet avec le code ci-dessous :
from opentelemetry.trace import SpanContext, SpanKind, TraceFlags
from opentelemetry.sdk.trace import SpanProcessor
class SpanFilteringProcessor(SpanProcessor):
# prevents exporting spans from internal activities
def on_start(self, span):
if span._kind is SpanKind.INTERNAL:
span._context = SpanContext(
span.context.trace_id,
span.context.span_id,
span.context.is_remote,
TraceFlags.DEFAULT,
span.context.trace_state,
)
Télémétrie personnalisée
Cette section explique comment collecter des données de télémétrie personnalisées à partir de votre application.
Ajoutez des métriques personnalisées
Notes
Les métriques personnalisées sont en préversion dans Azure Monitor Application Insights. Les métriques personnalisées sans dimensions sont disponibles par défaut. Pour afficher et générer des alertes sur les dimensions, vous devez vous inscrire.
L’API OpenTelemetry propose six « instruments » de métrique pour couvrir différents scénarios de métrique et vous devez choisir le « Type d’agrégation » correct lors de la visualisation des métriques dans Metrics Explorer. Cette exigence est vraie lors de l’utilisation de l’API de métrique OpenTelemetry pour envoyer des métriques et lors de l’utilisation d’une bibliothèque d’instrumentation.
Le tableau suivant présente les types d’agrégation recommandés pour chacun des instruments de métriques OpenTelemetry.
Instrumentation OpenTelemetry
Type d’agrégation Azure Monitor
Compteur
Sum
Compteur asynchrone
Sum
Histogramme
Min, Max, Average, Sum et Count
Jauge asynchrone
Moyenne
UpDownCounter
Sum
UpDownCounter asynchrone
Sum
Attention
Les types d’agrégation au-delà des éléments affichés dans le tableau ne sont généralement pas significatifs.
La Spécification OpenTelemetry décrit les instruments et fournit des exemples de cas où vous pouvez utiliser chacun d’eux.
Conseil
L’histogramme est l’équivalent le plus versatile et le plus proche de l’API Application Insights Track Metric précédente. Azure Monitor aplatit actuellement l’instrumentation de l’histogramme dans nos cinq types d’agrégation pris en charge. La prise en charge des centiles est en cours. Bien que moins polyvalents, les autres instruments OpenTelemetry ont un impact moindre sur les performances de votre application.
using System.Diagnostics.Metrics;
using Azure.Monitor.OpenTelemetry.Exporter;
using OpenTelemetry;
using OpenTelemetry.Metrics;
public class Program
{
private static readonly Meter meter = new("OTel.AzureMonitor.Demo");
public static void Main()
{
using var meterProvider = Sdk.CreateMeterProviderBuilder()
.AddMeter("OTel.AzureMonitor.Demo")
.AddAzureMonitorMetricExporter(o =>
{
o.ConnectionString = "<Your Connection String>";
})
.Build();
var process = Process.GetCurrentProcess();
ObservableGauge<int> myObservableGauge = meter.CreateObservableGauge("Thread.State", () => GetThreadState(process));
System.Console.WriteLine("Press Enter key to exit.");
System.Console.ReadLine();
}
private static IEnumerable<Measurement<int>> GetThreadState(Process process)
{
foreach (ProcessThread thread in process.Threads)
{
yield return new((int)thread.ThreadState, new("ProcessId", process.Id), new("ThreadId", thread.Id));
}
}
}
const {
MeterProvider,
PeriodicExportingMetricReader
} = require("@opentelemetry/sdk-metrics");
const { AzureMonitorMetricExporter } = require("@azure/monitor-opentelemetry-exporter");
const provider = new MeterProvider();
const exporter = new AzureMonitorMetricExporter({
connectionString:
connectionString: "<Your Connection String>",
});
const metricReader = new PeriodicExportingMetricReader({
exporter: exporter
});
provider.addMetricReader(metricReader);
const meter = provider.getMeter("OTel.AzureMonitor.Demo");
let gauge = meter.createObservableGauge("gauge");
gauge.addCallback((observableResult) => {
let randomNumber = Math.floor(Math.random() * 100);
observableResult.observe(randomNumber, {"testKey": "testValue"});
});
import {
MeterProvider,
PeriodicExportingMetricReader,
PeriodicExportingMetricReaderOptions
} from "@opentelemetry/sdk-metrics";
import { AzureMonitorMetricExporter } from "@azure/monitor-opentelemetry-exporter";
const provider = new MeterProvider();
const exporter = new AzureMonitorMetricExporter({
connectionString: "<Your Connection String>",
});
const metricReaderOptions: PeriodicExportingMetricReaderOptions = {
exporter: exporter,
};
const metricReader = new PeriodicExportingMetricReader(metricReaderOptions);
provider.addMetricReader(metricReader);
const meter = provider.getMeter("OTel.AzureMonitor.Demo");
let gauge = meter.createObservableGauge("gauge");
gauge.addCallback((observableResult: ObservableResult) => {
let randomNumber = Math.floor(Math.random() * 100);
observableResult.observe(randomNumber, {"testKey": "testValue"});
});
from typing import Iterable
from opentelemetry import metrics
from opentelemetry.metrics import CallbackOptions, Observation
from opentelemetry.sdk.metrics import MeterProvider
from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
from azure.monitor.opentelemetry.exporter import AzureMonitorMetricExporter
exporter = AzureMonitorMetricExporter(connection_string="<your-connection-string")
reader = PeriodicExportingMetricReader(exporter)
metrics.set_meter_provider(MeterProvider(metric_readers=[reader]))
meter = metrics.get_meter_provider().get_meter("otel_azure_monitor_gauge_demo")
def observable_gauge_generator(options: CallbackOptions) -> Iterable[Observation]:
yield Observation(9, {"test_key": "test_value"})
def observable_gauge_sequence(options: CallbackOptions) -> Iterable[Observation]:
observations = []
for i in range(10):
observations.append(
Observation(9, {"test_key": i})
)
return observations
gauge = meter.create_observable_gauge("gauge", [observable_gauge_generator])
gauge2 = meter.create_observable_gauge("gauge2", [observable_gauge_sequence])
input()
Ajoutez des exceptions personnalisées
Sélectionnez des bibliothèques d’instrumentation qui prennent automatiquement en charge les exceptions à Application Insights.
Toutefois, vous pouvez signaler manuellement des exceptions au-delà du rapport des bibliothèques d’instrumentation.
Par exemple, les exceptions interceptées par votre code ne sont généralement pas* signalées. Vous pouvez les signaler pour attirer l’attention sur les expériences pertinentes, notamment la section échecs et les vues de transaction de bout en bout.
import * as opentelemetry from "@opentelemetry/api";
import { BasicTracerProvider, SimpleSpanProcessor } from "@opentelemetry/sdk-trace-base";
import { AzureMonitorTraceExporter } from "@azure/monitor-opentelemetry-exporter";
const provider = new BasicTracerProvider();
const exporter = new AzureMonitorTraceExporter({
connectionString: "<Your Connection String>",
});
provider.addSpanProcessor(new SimpleSpanProcessor(exporter as any));
provider.register();
const tracer = opentelemetry.trace.getTracer("example-basic-tracer-node");
let span = tracer.startSpan("hello");
try{
throw new Error("Test Error");
}
catch(error){
span.recordException(error);
}
Le Kit de développement logiciel (SDK) Python OpenTelemetry est implémenté de telle sorte que les exceptions levées soient capturées et enregistrées automatiquement. Consultez ci-dessous pour obtenir un exemple de ceci.
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from azure.monitor.opentelemetry.exporter import AzureMonitorTraceExporter
exporter = AzureMonitorTraceExporter(connection_string="<your-connection-string>")
trace.set_tracer_provider(TracerProvider())
tracer = trace.get_tracer("otel_azure_monitor_exception_demo")
span_processor = BatchSpanProcessor(exporter)
trace.get_tracer_provider().add_span_processor(span_processor)
# Exception events
try:
with tracer.start_as_current_span("hello") as span:
# This exception will be automatically recorded
raise Exception("Custom exception message.")
except Exception:
print("Exception raised")
Si vous souhaitez enregistrer manuellement des exceptions, vous pouvez désactiver cette option lors de la création de l’étendue comme indiqué ci-dessous.
...
with tracer.start_as_current_span("hello", record_exception=False) as span:
try:
raise Exception("Custom exception message.")
except Exception as ex:
# Manually record exception
span.record_exception(ex)
...
Activer l’exportateur OTLP
Vous pouvez activer OpenTelemetry Protocol (OTLP) Exporter en plus d’Azure Monitor Exporter pour envoyer vos données de télémétrie à deux emplacements.
Notes
OTLP Exporter est illustré pour des raisons pratiques uniquement. Nous ne prenons pas officiellement en charge OTLP Exporter ni les composants ou les expériences tierces qui en découlent. Nous vous suggérons de signaler le problème auprès de OpenTelemetry-Collector pour les problèmes OpenTelemetry qui ne relèvent pas du Support Azure.
Ajoutez l’extrait de code suivant : Cet exemple suppose que vous disposez d’un OpenTelemetry Collector avec un récepteur OTLP en cours d’exécution. Pour plus d’informations, consultez l' exemple relatif à GitHub.
// Sends data to Application Insights as well as OTLP
using var tracerProvider = Sdk.CreateTracerProviderBuilder()
.AddSource("OTel.AzureMonitor.Demo")
.AddAzureMonitorTraceExporter(o =>
{
o.ConnectionString = "<Your Connection String>"
})
.AddOtlpExporter()
.Build();
Ajoutez l’extrait de code suivant : Cet exemple suppose que vous disposez d’un OpenTelemetry Collector avec un récepteur OTLP en cours d’exécution. Pour plus d’informations, consultez l' exemple relatif à GitHub.
Ajoutez l’extrait de code suivant : Cet exemple suppose que vous disposez d’un OpenTelemetry Collector avec un récepteur OTLP en cours d’exécution. Pour plus d’informations, consultez l' exemple relatif à GitHub.
import { BasicTracerProvider, SimpleSpanProcessor } from '@opentelemetry/sdk-trace-base';
import { OTLPTraceExporter } from '@opentelemetry/exporter-otlp-http';
import { AzureMonitorTraceExporter } from '@azure/monitor-opentelemetry-exporter';
const provider = new BasicTracerProvider();
const azureMonitorExporter = new AzureMonitorTraceExporter({
connectionString: "<Your Connection String>",
});
const otlpExporter = new OTLPTraceExporter();
provider.addSpanProcessor(new SimpleSpanProcessor(azureMonitorExporter));
provider.addSpanProcessor(new SimpleSpanProcessor(otlpExporter));
provider.register();
Ajoutez l’extrait de code suivant : Cet exemple suppose que vous disposez d’un OpenTelemetry Collector avec un récepteur OTLP en cours d’exécution. Pour plus d’informations, consultez ce fichier Lisez-moi.
from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from azure.monitor.opentelemetry.exporter import AzureMonitorTraceExporter
trace.set_tracer_provider(TracerProvider())
tracer = trace.get_tracer(__name__)
exporter = AzureMonitorTraceExporter(connection_string="<your-connection-string>")
otlp_exporter = OTLPSpanExporter(endpoint="http://localhost:4317")
span_processor = BatchSpanProcessor(otlp_exporter)
trace.get_tracer_provider().add_span_processor(span_processor)
with tracer.start_as_current_span("test"):
print("Hello world!")
Configuration
Stockage hors connexion et nouvelles tentatives automatiques
Pour améliorer la fiabilité et la résilience, les offres Azure Monitor basées sur OpenTelemetry écrivent dans un stockage hors connexion/local par défaut lorsqu’une application perd sa connexion avec Application Insights. Il enregistre la télémétrie de l’application pendant 48 heures et tente régulièrement de l’envoyer à nouveau. En plus de dépasser le temps autorisé, les données de télémétrie sont parfois supprimées dans des applications à charge élevée lorsque la taille maximale du fichier est dépassée ou que le Kit de développement logiciel (SDK) n’a pas la possibilité d’effacer le fichier. Si nous devons choisir, le produit enregistre les événements les plus récents sur les anciens. Dans certains cas, vous pouvez désactiver cette fonctionnalité pour optimiser les performances de l’application. En savoir plus
Azure Monitor Exporter utilise EventSource pour sa propre journalisation interne. Les journaux de l’outil d’exportation sont disponibles pour n’importe quel EventListener en vous abonnant à la source nommée « OpenTelemetry-AzureMonitor-Exporter ». Pour obtenir les étapes de dépannage, consultez Résolution des problèmes OpenTelemetry.
Azure Monitor exporter utilise l’enregistreur d’API OpenTelemetry pour les journaux internes. Pour ce faire, utilisez le code suivant :
Azure Monitor exporter utilise l’enregistreur d’API OpenTelemetry pour les journaux internes. Pour ce faire, utilisez le code suivant :
import { diag, DiagConsoleLogger, DiagLogLevel } from "@opentelemetry/api";
import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
const provider = new NodeTracerProvider();
diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.ALL);
provider.register();
Azure Monitor Exporter utilise la bibliothèque de journalisation standard Python pour sa propre journalisation interne. Les journaux de l’API OpenTelemetry et de l’Exportateur Azure Monitor sont généralement journalisés au niveau de gravité AVERTISSEMENT ou ERREUR pour une activité irrégulière. Le niveau de gravité INFO est utilisé pour une activité normale ou réussie. Par défaut, le niveau de gravité de la bibliothèque de journalisation Python est AVERTISSEMENT. Vous devez donc modifier le niveau de gravité pour afficher les journaux sous cette gravité. L'exemple suivant montre comment sortir les journaux de tous les niveaux de gravité vers la console et un fichier :
Les problèmes connus pour Azure Monitor OpenTelemetry Exporters incluent :
Le nom de l’opération est manquant sur la télémétrie des dépendances, ce qui a un impact négatif sur l’expérience de l’onglet des échecs et des performances.
Le modèle d’appareil est manquant sur la télémétrie de la demande et de la dépendance, ce qui a un impact négatif sur l’analyse de la cohorte d’appareils.
Le nom du serveur de base de données ne figure pas dans le nom de la dépendance, ce qui agrège de manière incorrecte les tables portant le même nom sur des serveurs différents.
Tester la connectivité entre votre hôte d’application et le service d’ingestion
Les SDK et les agents Application Insights envoient de la télémétrie à ingérer en tant qu’appels REST à nos points de terminaison d’ingestion. Vous pouvez tester la connectivité de votre serveur web ou de votre machine hôte d’application vers les points de terminaison de service d’ingestion en utilisant des clients du Representational State Transfer (REST) bruts à partir de commandes PowerShell ou curl. Consultez Résoudre les problèmes de télémétrie d’application manquante dans Azure Monitor Application Insights.
Support
Pour bénéficier du support technique :
Passez en revue les étapes de résolution des problèmes décrites dans cet article.
Pour installer le package NuGet, recherchez les mises à jour ou affichez les notes de publication, visitez la page Package NuGet Azure Monitor Exporter.