API REST Agent hôte

Au niveau de l'agent 1.1.582hôte, les métriques et les données de traçage reçues par celui-ci sont mises en corrélation avec le processus qui les a envoyées, si les conditions préalables suivantes sont remplies :

• L'agent hôte s'exécute sur un système Linux, où les commandes suivantes sont disponibles : lsns, nsenter, et ss.
• Le processus qui envoie les métriques et les données de traçage s'exécute sur le même hôte que l'agent hôte.
• Le processus qui envoie les métriques et les données de traçage n'est pas ignoré lorsque l'on utilise la fonctionnalité « Ignorer les processus ».
• Les métriques et les traces sont transmises directement à l'agent hôte, plutôt qu'à un proxy (par exemple, pour OpenTelemtry qui utilise OpenTelemetry Collector ). Si les métriques et les données de trace passent par un proxy, le processus de proxy est associé aux métriques et aux traces à la place.

Pour les données de trace, le tableau de bord du service de perspective d'application fait correctement référence à tout processus à partir duquel des traces associées ont été ingérées, y compris, par exemple, les modifications d'infrastructure qui ont eu lieu pour ce service.

Si l'une de ces conditions préalables n'est pas remplie, les métriques et les données de traçage sont associées à l'hôte sur lequel l'agent hôte est exécuté.

Pour désactiver la recherche de processus, ajoutez l'extrait de code suivant au fichier configuration.yaml de l'agent :

com.instana.processlookup:
  enabled: false

Pour plus d'informations sur l' OpenTelemetry, les métriques et l'ingestion des traces, consultez la documentation de l' OpenTelemetry.

Pour l'ingestion des métriques Prometheus, consultez la documentation sur l'écriture à distance Prometheus.

Noeud final: http://<agent_ip>:42699/com.instana.plugin.generic.event

En utilisant le service Web REST du SDK Event, vous pouvez intégrer des contrôles d'intégrité personnalisés et d'autres sources d'événements dans Instana. Chacun d'entre eux s'exécute sur l'agent « Instana » utilisé pour enregistrer les événements manuels. L'agent dispose d'un point de terminaison qui écoute sur http://<agent_ip>:42699/com.instana.plugin.generic.event et accepte, par exemple, la requête suivante JSON avec une requête de type POST :

{
  "title": <string>,
  "text": <string>,
  "severity": <integer>,
  "timestamp": <integer>,
  "duration": <integer>,
}

Les paramètres d'événement suivants sont disponibles :

• titre : Le titre qui s'affiche dans la vue « Événements » d' Instana.

• texte : La description qui apparaît dans la section « Détails » de l'événement.

• gravité : entier facultatif dont la valeur est l'une des suivantes selon le type d'événement prévu :

  • Evénement de changement : -1 (par défaut)
  • Evénement d'avertissement : 5
  • Evénement critique : 10

  De plus, un événement de changement est considéré comme un événement de présence si la zone title contient le mot clé "online" ou "offline".

• timestamp: horodatage de l'événement en millisecondes depuis l'époque UNIX. Si cette valeur n'est pas fournie, l'heure actuelle est utilisée à la place.

• duration : Durée facultative de l'événement en millisecondes. Si la valeur n'est pas désignée, l'événement est affiché en tant qu'événement "instantané" sans durée. De plus, les événements de "changement" ou de "présence" sont toujours fermés après la durée. Pour étendre la durée d'un événement, utilisez le paramètre path afin d'identifier un événement ouvert ayant la même valeur que celle définie dans le paramètre path .

• incident: valeur booléenne facultative qui la transforme en événement déclencheur Incident si elle est définie sur true. Pour cela, severity doit être positif.

• path : identificateur facultatif qui peut être défini dans le cas où un événement doit être étendu avec une demande ultérieure à ce noeud final à l'aide de la même valeur de chemin.

L'exemple suivant illustre un événement instantané:

{
    "title": "Instant critical event on the host",
    "text": "Description of the event that occurred",
    "severity": 10
}

L'exemple suivant montre un événement d'une durée de 5 minutes, qui peut être étendu à l'aide du paramètre path . Si aucun événement ultérieur avec le même identificateur path n'est envoyé, l'événement est fermé automatiquement au bout de 5 minutes:

{
    "title": "WARNING: This event started to happen",
    "text": "It will be active for 5 minutes",
    "severity": 5,
    "duration": 300000,
    "path": "unique-event-identifier"
}

Vous pouvez envoyer des événements ultérieurs avec le même paramètre path pour étendre la durée de vie de l'événement. L'exemple d'événement suivant étend l'événement de l'exemple précédent de 5 minutes supplémentaires:

{
    "title": "WARNING: This event continues to happen",
    "text": "It will be active for another 5 minutes",
    "severity": 5,
    "duration": 300000,
    "path": "unique-event-identifier"
}

Le noeud final accepte également un lot d'événements quand il reçoit un tableau :

[
  {
    "title": "First event",
    ...
  },
  {
    "title": "Second event",
    ...
  }
]

Noeud final: http://<agent_ip>:42699/com.instana.plugin.generic.trace

Le service Web Trace SDK REST permet d'intégrer Instana dans n'importe quelle application, quelle que soit son langage. Chaque agent Instana actif peut être utilisé pour alimenter des traces capturées manuellement dans le service Web, qui peuvent être jointes à des traces capturées automatiquement ou être complètement séparées. L'agent met à disposition un point de terminaison qui écoute sur l'adresse http://<agent_ip>:42699/com.instana.plugin.generic.traceURL et accepte les requêtes suivantes JSON via une requête POST :

{
  "spanId": <string>,
  "parentId": <string>,
  "traceId": <string>,
  "timestamp": <64 bit long>,
  "duration": <64 bit long>,
  "name": <string>,
  "type": <string>,
  "error": <boolean>,
  "data": {
    <string> : <string>
  }
}

spanId est l'identificateur unique pour une portée particulière. La trace est définie par une portée racine, c'est-à-dire une portée qui n'a pas de parentId. traceId doit être identique pour toutes les étendues appartenant à la même trace et peut se chevaucher avec un spanId. traceId, spanIdet parentId sont des valeurs uniques de 64 bits codées en tant que chaîne hexadécimale comme b0789916ff8f319f. Les portées forment une hiérarchie et font référence au spanId du parent en tant que parentId. Voici un exemple de hiérarchie d'étendue dans une trace:

      root (spanId=1, traceId=1, type=Entry)
          child A (spanId=2, traceId=1, parentId=1, type=Exit)
            child A (spanId=3, traceId=1, parentId=2, type=Entry)
              child B (spanId=4, traceId=1, parentId=3, type=Exit)
        child B (spanId=5, traceId=1, parentId=4, type=Entry)

Les zones timestamp et duration sont exprimées en millisecondes. L'horodatage doit être l'horodatage d'époque coordonné en temps universel coordonné.

La zone name peut être n'importe quelle chaîne utilisée pour visualiser et regrouper des traces et peut contenir n'importe quel texte. Toutefois, il est recommandé de faire preuve de simplicité.

La zone type est facultative. Si aucune valeur n'est fournie, elle est traitée comme ENTRY. Les options sont ENTRY, EXIT, INTERMEDIATE, ou EUM. La définition du type est importante pour l'interface utilisateur. Il est supposé qu'après une ENTRY, les portées enfant sont INTERMEDIATE ou EXIT. Après un EXIT, un ENTRY suit. Ceci est visualisé comme un appel distant.

La zone data est facultative et peut contenir des paires clé-valeur arbitraires. Le comportement en cas de duplication de clés n'est pas spécifié.

La zone error est facultative et peut être définie sur true pour indiquer une portée erronée.

Le noeud final accepte également un lot de portées, qui doit ensuite être rendu sous forme de tableau :

[
  {
    // span as above
  },
  {
    // span as above
  }
]

Pour les traces reçues via le service Web Trace SDK, les mêmes règles relatives à la conversion et à la dénomination des services/points de terminaison s'appliquent que pour le Trace SDK d' Java. En particulier, ces paires clé-valeur dans data sont utilisées pour nommer: service, endpointet call.name.