Meilleures pratiques pour le traçage personnalisé

Pour surveiller de manière optimale vos applications et votre infrastructure, Instana exécute un traitement et une analyse avancés sur toutes les données entrantes. Cela inclut tous les spans entrants provenant de toutes les sources.

Pour tirer le meilleur parti de l'analyse et du traitement automatiques d'Instana, l'ajout des balises appropriées aux spans permet à Instana d'analyser et d'agir de manière optimale sur les spans entrants.

Par exemple, le code suivant Python OpenTracing fournit moins d'informations.

import opentracing

with opentracing.tracer.start_active_span('vanilla') as pscope:
  # ...
  # do something that takes 50ms
  # ...
  pscope.span.log_kv({"foo": "bar"})
 

A partir de ce code, nous savons seulement que c'est un intervalle nommé vanilla qui a pris 50 ms de temps. Nous ne connaissons pas son type : HTTP, RPC ou un Messagerie. Nous ne savons pas ce qui s'est passé au cours de cette période, par exemple, communication avec d'autres composants de votre infrastructure.

Si vous fournissez les balises contextuelles OpenTracing appropriées, Instana analyse et extrait des informations du span pour agir dessus.

import opentracing
import opentracing.ext.tags as ext

with opentracing.tracer.start_active_span('webserver') as pscope:
    pscope.span.set_tag(ext.SPAN_KIND, "entry")
    pscope.span.set_tag(ext.PEER_HOSTNAME, "localhost")
    pscope.span.set_tag(ext.HTTP_URL, "/python/simple/two")
    pscope.span.set_tag(ext.HTTP_METHOD, "POST")
    pscope.span.log_kv({"foo": "bar"})

    # ...
    # work that took 50ms
    # ...

    pscope.span.set_tag(ext.HTTP_STATUS_CODE, 204)
 

Ce span bien annoté fournit à Instana beaucoup plus d'informations sur ce qui s'est passé dans son contexte. À partir des balises fournies, nous savons qu'il s'agit d'une demande de serveur Web entrant à /python/simple/two et que le code d'état HTTP résultant est 204.

Un segment correctement annoté, comme l'extrait ci-dessus, permet à Instana d'extraire les services, de surveiller les connexions et leur état de santé, ce qui enrichit l'expérience offerte par votre tableau de bord.

Pour plus de détails sur cet exemple, consultez la spécification « OpenTracing », qui définit la liste officielle de toutes les balises « OpenTracing » prises en charge. La liste complète des balises prise en charge par Instana (qui est un superset des balises OpenTracing) est disponible à la fin de cette page.

Dans le traçage distribué, il existe trois grands types de plages:

• Entrée : annote la réception d'une demande, le début d'une nouvelle tâche ou la consommation d'un message
• Intermédiaire: Annote le travail interne qui n'effectue pas ou ne reçoit pas d'appels (par exemple, affichage)
• Exit: Annote le travail qui effectue un appel à un service distant ou qui publie un message dans une file d'attente

La balise span.kind marque le type de span signalé. Pour plus de détails, consultez span.kind le tableau à la fin de cette page ou le cahier des charges de l' OpenTracing.

Lorsque vous démarrez de nouvelles traces, commencez par un span d'entrée. Si vous ne spécifiez pas la balise span.kind, le span est un span d'entrée. En affectant à cette balise la valeur appropriée, vous améliorez le traitement, l'extraction des appels backend de visualisation et le mappage dans Instana.

Consultez l'exemple Go suivant :

// Start a new entry span and set 'kind' to Consumer (entry)
entrySpan := ot.StartSpan("RPCJobRunner")
entrySpan.SetTag(string(ext.SpanKind), string(ext.SpanKindConsumerEnum))

// Now the RPC exit span
spanName := fmt.Sprintf("%s %s", request.Service, request.Method)
clientSpan := ot.StartSpan(spanName, ot.ChildOf(entrySpan.Context()))
clientSpan.SetTag(string(ext.SpanKind), string(ext.SpanKindRPCClientEnum))
clientSpan.SetTag("rpc.call", request.Method)

// Make the RPC call

clientSpan.Finish()
entrySpan.Finish()
 

Les spans qui représentent un travail contenant une erreur, telle qu'une exception, doivent contenir les balises error et message. Pour les définitions de ces balises, voir la définition dans le tableau comme suit.

Pour transmettre le contexte dans les limites, telles que les hôtes, les files d'attente et les services, le traçage distribué inclut une méthode. Cela se fait généralement avec des transporteurs tels que des en-têtes HTTP ou des en-têtes de file d'attente de messages.

Pour plus de détails, voir notre documentation sur les en-têtesHTTP.

Cela est facultatif. Les noms de service sont des noms appliqués aux processus d'application surveillés. Dans la plupart des langages, le nom du meilleur service peut être automatiquement détecté en fonction du framework en cours d'utilisation ou à partir de la ligne de commande du processus.

Pour changer cela, vous pouvez définir un nom de service par traceur. Consultez l'exemple suivant pour le langage Go.

serviceName := "default"
if *isServer {
    serviceName = "rpc-client"
} else {
    serviceName = "rpc-server"
}

opts := instana.Options{Service: serviceName})
opentracing.InitGlobalTracer(instana.NewTracerWithOptions(&opts)
 

Tous les traceurs Instana OpenTracing prennent également en charge cette configuration via une variable d'environnement. Si vous définissez la variable d'environnement INSTANA_SERVICE_NAME pour le processus, la valeur est utilisée comme nom de service pour le processus. Cette option remplace la configuration de nom de service de niveau du code.

Voir également la documentation sur les techniques et les règles générales d'extraction de services d' Instana.

Cela est facultatif. Dans de nombreux langages, les noms de nœud final et d'appel sont automatiquement détectés en fonction du type de service.

Si vous souhaitez changer cela, vous pouvez définir des noms de nœud final et d'appel par traceur. Consultez l'exemple suivant pour le langage Java.

SpanSupport.annotate(Span.Type.ENTRY, "my-custom-span", "endpoint", "endpoint-name");
SpanSupport.annotate(Span.Type.ENTRY, "my-custom-span", "call.name", "call-name");
 

Pour plus d'informations sur les techniques et les règles générales d'extraction des terminaux d' Instana, consultez notre documentation sur les terminaux.

Le kit SDK de traçage calcule automatiquement la durée de span depuis le début et la fin du span.

Il représente généralement ce que vous souhaitez mesurer mais, lorsque ce n'est pas le cas, vous pouvez le remplacer à l'aide de la balise duration.

Le format attendu est en millisecondes.

// Overwrite the span duration with 15 milliseconds.
SpanSupport.annotate(Span.Type.ENTRY, "my-custom-span", "duration", "15");
 

Instana prend en charge le regroupement automatique des nœuds finaux avec des modèles de chemin. Cette fonction est prise en charge en standard avec le traçage Instana pour la plupart des frameworks. Avec OpenTracing,, une étape supplémentaire est nécessaire, comme décrit ci-dessous.

Des frameworks disposent généralement d'un modèle de chemin REST similaire à ce qui suit :

/api/query/1956-01-31/Guido-van-Rossum
/api/query/1976-04-18/Andrew-Ng
/api/query/1912-06-23/Alan-Turing
 

Ces points de terminaison similaires peuvent être regroupés en indiquant une http.path_tpl clé dans vos segments d' HTTP, avec la valeur /api/query/{birthdate}/{name}« Instana ». Ce modèle permet de regrouper automatiquement les points de terminaison qui correspondent au modèle fourni. Dans votre tableau de bord Instana, les points de terminaison HTTP seront alors regroupés en un seul point de terminaison :

/api/query/{birthdate}/{name}
 

Consultez ce qui suit pour un exemple en Go :

span := ot.GlobalTracer().StartSpan("myTemplatedSpan", ext.RPCServerOption(incomingContext))
span.SetTag("http.path_tpl", "/api/query/{birthdate}/{name}")
span.SetTag(string(ext.SpanKind), string(ext.SpanKindRPCServerEnum))
span.SetTag(string(ext.HTTPUrl), req.URL.Path)
span.SetTag(string(ext.HTTPMethod), req.Method)
span.SetTag(string(ext.HTTPStatusCode), 200)
 

Notez que cette fonction est spécifique à Instana et n'est pas compatible avec OpenTracing.

Cette section répertorie les balises spécifiques qu'Instana recherche lors de l'identification et du traitement des spans. Lorsqu'un sous-ensemble de balises tel que celui-ci est détecté pour un segment, Instana est alors en mesure de mieux traiter, analyser, visualiser et signaler les segments entrants.

Notez que les balises répertoriées comme suit sont un superset des balises OpenTracing standard. Chaque balise est marquée selon qu'elle est OpenTracing compatible avec un ✓ ou x si ce n'est pas le cas.

Certaines descriptions de balises ci-dessous sont tirées directement du document sur les conventions sémantiques de l' OpenTracing.

• OpenTracing documents

• OpenCensus documents