fichier exécutable d'intégration sur hôte : spécifications JSON

Une intégration d'agent infrastructure New Relic sur hôte sera composée d'au moins deux fichiers : un fichier exécutable et au moins un fichier configuration . Le fichier exécutable génère des données JSON qui sont consommées par l'agent d'infrastructure et envoyées à New Relic. Nous appelons l'objet JSON le protocole d'intégration SDK.

Exigences relatives aux fichiers exécutables

L'exécutable peut être n'importe quel fichier qui s'exécute à partir d'une interface de ligne de commande ; par exemple :

Un script shell
Un script
Un binaire compilé

La seule exigence de votre fichier exécutable est qu'il exporte des données JSON, dans un format sur une seule ligne, qui répond aux spécifications de ce document.

Recommandation : Utilisez Go pour créer l'intégration ; c'est le langage que nous utilisons pour créer l'intégration sur hôte et les outils de construction d'intégration. Cependant, vous pouvez créer une intégration dans n'importe quelle langue.

Placement des fichiers

Le fichier exécutable va dans ce répertoire :

Linux:
```
/var/db/newrelic-infra/custom-integrations
```

Windows:

C:\Program Files\New Relic\newrelic-infra\newrelic-integrations

Protocole d'intégration v4 : exemple de sortie JSON

La section suivante explique le nouveau schéma JSON (protocole d'intégration v4). Le SDK v4 ne prend en charge que cette nouvelle version du protocole. Voici les changements les plus importants :

Un nouvel objet integration au niveau supérieur.
Les objets entity et metrics ont été modifiés.

Consultez le guide de migration v3 vers v4 pour plus d'informations.

{
  "protocol_version":"4",                      # protocol version number
  "integration":{                              # this data will be added to all metrics and events as attributes,
                                               # and also sent as inventory
    "name":"integration name",
    "version":"integration version"
  },
  "data":[                                    # List of objects containing entities, metrics, events and inventory
    {
      "entity":{                              # this object is optional. If it's not provided, then the Entity will get 
                                              # the same entity ID as the agent that executes the integration. 
        "name":"redis:192.168.100.200:1234",  # unique entity name per customer account
        "type":"RedisInstance",               # entity's category
        "displayName":"my redis instance",    # human readable name
        "metadata":{}                         # can hold general metadata or tags. Both are key-value pairs that will 
                                              # be also added as attributes to all metrics and events
      },
      "metrics":[                             # list of metrics using the dimensional metric format
        {
          "name":"redis.metric1",
          "type":"count",                     # gauge, count, summary, cumulative-count, rate or cumulative-rate
          "value":93, 
          "attributes":{}                     # set of key-value pairs that define the dimensions of the metric
        }
      ],
      "inventory":{...},                      # Inventory remains the same
      "events":[...]                          # Events remain the same
    }
  ]
}

Protocole d'intégration v3 : exemple de sortie JSON

Le JSON comprend :

Un en-tête, avec des données d'intégration de base (nom, version)
Une liste de données, qui comprend une ou plusieurs données de rapport d'entité (données métriques, d'inventaire et/ou d'événement)

Ce diagramme montre cette structure :

New Relic Integrations SDK data structure diagram

Voici un exemple de sortie JSON (formaté avec des sauts de ligne pour plus de lisibilité). Les définitions et spécifications suivent cet exemple :

{
  "name": "my.company.integration",
  "protocol_version": "3",
  "integration_version": "x.y.z",  
  "data": [
    {
      "entity": {
        "name": "my_garage",
        "type": "building",
        "id_attributes": [
          {
            "key": "environment",
            "value": "production"
          }, 
          { 
             "key": "node",
             "value": "master"
          }
        ]
      },
      "metrics": [
        {
          "temperature": 25.3,
          "humidity": 0.45,
          "displayName": "my_garage",
          "entityName": "building:my_garage",
          "event_type": "BuildingStatus"
        }
      ],
      "inventory": {
        "out_door": {
          "status": "open"
        }
      },
      "events": []
    },
    {
      "entity": {
        "name": "my_family_car",
        "type": "car",
        "id_attributes": [ 
          {
            "key": "environment",
            "value": "production"
          },
          {
            "key": "node",
            "value": "master"
          } 
        ]
      },
      "metrics": [
        {
          "speed": 95,
          "fuel": 768,
          "displayName": "my_family_car",
          "entityName": "car:my_family_car",
          "event_type": "VehicleStatus"
        }
      ],
      "inventory": {
        "motor": {
          "brand": "renault",
          "cc": 1800
        }
      },
      "events": [
        {
          "category": "gear",
          "summary": "gear has been changed"
        }
      ],
      "add_hostname": true
    }
  ]
}

JSON : Spécifications générales

Voici les spécifications générales pour la sortie JSON :

Les données sont transmises à stdout (sortie standard) au format JSON. L'agent traitera les descripteurs de fichiers stdout et stderr comme des tampons de ligne.

Utilisez du JSON standard, et non du JSON « joliment imprimé », pour la sortie. Recommandation : inclure un commutateur de ligne de commande facultatif (par exemple, --pretty) pour rendre JSON « joliment imprimé » à des fins de débogage.

Le code de sortie doit sortir avec un code d'état 0 et suivre les conventions spécifiques à la plateforme. Par exemple:

Linux: 0 == EX_OK
Windows: 0 == ERROR_SUCCESS
Si l'exécutable se termine avec un statut différent de zéro, l'agent supprimera toutes les données de stdout et écrira un message dans son fichier log avec le nom de l'intégration, le code de sortie et toutes les informations de diagnostic qu'il peut recueillir.

JSON : En-tête

Voici un exemple de la première partie de la sortie JSON d'une intégration sur hôte :

"name":"com.myorg.nginx",
"protocol_version":"3",
"integration_version":"1.0.0",
"data": [ {entities}...]

Une charge utile minimale serait un objet JSON avec uniquement les champs d'en-tête. Recommandation : S'il n'y a pas de données à collecter, utilisez le code de retour du programme et le message de log écrit dans stderr.

Champs d'en-tête JSON	Description
`name`	Requis. Doit être identique au champ `name` dans le fichier de configuration. Recommandation : utilisez des noms de domaine inversés pour générer des noms d’intégration uniques.
`protocol_version`	Requis. Le numéro de version du protocole d’échange entre l’intégration et l’agent utilisé par l’exécutable d’intégration. La version actuelle est la 3. Ce protocole nécessite l'agent d'infrastructure 1.2.25 ou supérieur. Le protocole 2 nécessite l'agent d'infrastructure 1.0.859 ou supérieur. Le protocole 1 est compatible avec tous les agents. Pour plus d'informations, voir Modifications du SDK.
`integration_version`	Facultatif. La version d'intégration. Utilisé pour suivre la version d'intégration exécutée sur chaque hôte. Une intégration peut avoir plusieurs exécutables. Il ne s’agit donc pas simplement de la version de l’exécutable.
`data`	Obligatoire pour la création de rapports de données. Une liste contenant les données rapportées par une ou plusieurs entités.

JSON : entité

À l'intérieur de la listedata de la sortie JSON se trouvent une ou plusieurs entités. Les champs de saisie de l'entité incluent :

Champs JSON d'entité	Description
`entity`	Requis. Données ou propriétés d'entité.
`metrics`	Facultatif. liste métrique liée à l'entité.
`inventory`	Facultatif. Articles d'inventaire liés à l'entité.
`events`	Facultatif. liste des événements liés à l'entité.
`add_hostname`	Facultatif. Booléen. Si `true`, les métriques de l'entité seront décorées avec `hostname`.

À l'intérieur de la listedata de la sortie JSON se trouvent une ou plusieurs entités et leurs données. L'entrée entity comporte deux champs :

Champs JSON de données d'entité	Description
`name`	Requis. L'identifiant/nom de l'entité. Recommandation : utilisez des noms de domaine inversés pour générer des noms d’intégration uniques.
`type`	Requis. Le type d'entité. Il sera utilisé par l'agent infrastructure comme espace de nommage pour composer un unique identifier en conjonction avec le `name`.
`id_attributes`	Facultatif. Une liste d'attributs de valeur clé qui confèrent un caractère unique à une entité. Ils sont attachés au nom sous la forme `key=value` pour faciliter la lisibilité, fournir des informations supplémentaires et améliorer l'unicité du nom de l'entité. Les attributs identifiant sont utiles lorsque le nom de l'entité n'est pas suffisant pour fonctionner comme un identifiant unique, ou lorsqu'il ne fournit pas suffisamment d'informations significatives. Par exemple: `[ { "key": "service", "value": "mysql" }, { "key": "role", "value": "master" }, ... ]`

Champs JSON de données d'entité

Description

name

Requis. L'identifiant/nom de l'entité.

Recommandation : utilisez des noms de domaine inversés pour générer des noms d’intégration uniques.

type

Requis. Le type d'entité. Il sera utilisé par l'agent infrastructure comme espace de nommage pour composer un unique identifier en conjonction avec le name.

id_attributes

Facultatif. Une liste d'attributs de valeur clé qui confèrent un caractère unique à une entité. Ils sont attachés au nom sous la forme key=value pour faciliter la lisibilité, fournir des informations supplémentaires et améliorer l'unicité du nom de l'entité.

Les attributs identifiant sont utiles lorsque le nom de l'entité n'est pas suffisant pour fonctionner comme un identifiant unique, ou lorsqu'il ne fournit pas suffisamment d'informations significatives. Par exemple:

[
  {
    "key": "service", 
    "value": "mysql"
  },
  { 
    "key": "role", 
    "value": "master" 
  }, ...
]

Remplacement d'adresse de bouclage sur les noms d'entité

À partir de la infrastructure version 1.2.25 ou supérieure de l'agent , le protocole v3 améliore l'unicité des entités distantes en ajoutant le remplacement d'adresse locale sur les noms d'entité au niveau de l'agent.

Lorsque plusieurs entités distantes ont leur nom basé sur un point de terminaison (soit ip soit hostname), et que ce nom contient des adresses de bouclage, deux problèmes se posent :

Cette valeur localhost ne fournit pas d'informations précieuses sans plus de contexte.
Le name pourrait entrer en conflit avec un autre service nommé avec une adresse locale.

Cela se produit lorsque :

les noms de points de terminaison sont comme localhost:port.
Les ports ont tendance à être les mêmes pour un service donné ; par exemple, 3306 pour MySQL.

Lors de l'entrée de données du protocole v3, l'agent d'infrastructure remplace les adresses de bouclage sur le nom de l'entité (et la clé) par le premier élément disponible de la liste suivante :

ID du fournisseur de cloud d'instance, récupéré par l'agent le cas échéant
Nom d'affichage, défini via l'option de configuration de l'agent display_name
nom d'hôte, tel que récupéré par l'agent

Par exemple, si une intégration utilisant le protocole v3 renvoie une entité avec le localhost:3306 nom, et que l'agent s'exécute sur du bare metal (n'a pas d'ID d'instance de fournisseur de cloud), que le display_name n'a pas été défini et que le nom d'hôte prod-mysql-01 est, alors l'agent remplacera le localhost et produira le nom prod-mysql-01:3306 d'entité.

L'agent d'infrastructure permet le remplacement automatique de l'adresse de bouclage pour le protocole d'intégration v3. Vous pouvez également l'activer pour la version 2 via l'indicateur de configuration de l'agent replace_v2_loopback_entity_names. Dans ce cas, toutes les intégrations exécutées par l'agent utilisant v2 verront leurs noms remplacés chaque fois qu'elles porteront une adresse locale.

JSON : données métriques, d'inventaire et d'événements

Les valeurs de données suivent l’en-tête du fichier exécutable. Vous pouvez enregistrer trois types de données:

Métriques
Événements
Inventaire

Important

Du point de vue du dashboard New Relic, les métriques infrastructure et les événements sont tous deux classés comme données d'événement.

Les données métriques d'infrastructure sont généralement utilisées pour des données numériques simples ; par exemple :

Nombre de MySQL requests dans une file d'attente par seconde

Nombre de connexions actives à un système spécifique par minute

Outre les métadonnées associées, une métrique est essentiellement un simple nom de métrique et une valeur numérique. Pour en savoir plus sur ces données, consultez Données d'événement.

Voici un exemple de données métriques JSON d'une entité :

[ 
    {
         "event_type":"MyorgNginxSample",
         "net.connectionsActive": 54,  # metric data (a key/value pair)
         "net.requestsPerSecond": 21,  # metric data (a key/value pair)
         "net.reading": 23,   # metric data (a key/value pair)
    }
]

Champ de données métriques JSON	Description
`event_type`	Requis. `event_type` définit où les métriques seront stockées. Chaque ensemble de métriques est stocké sous forme d’échantillon dans le type d’événement spécifié. Chaque intégration doit stocker ses données dans son propre type d'événement. Si vous générez plusieurs types d’échantillons à partir de la même intégration, utilisez des types d’événements différents pour chacun. Recommandation : Pour garantir que les types d'événements utilisés par votre intégration sont uniques, préfixez le type d'événement avec le nom ou l'acronyme de votre entreprise. Par exemple, si votre intégration personnalisée capture les métriques de nœud Cassandra et les métriques de famille de colonnes Cassandra sous forme d'échantillons différents, stockez-les dans différents types d'événements, tels que `MyOrgCassandraSample` et `MyOrgCassandraColumnFamilySample`. Si le type d'événement n'existe pas, il sera créé automatiquement lorsque New Relic recevra les données de votre intégration et les rendra disponibles dans l'UI.
Une ou plusieurs paires de données métriques valeur clé	Obligatoire (au moins un). Une mesure métrique contenant un nom (clé) et sa valeur. Assurez-vous qu'ils sont généralement conformes à la spécification du type d'entité pour une compatibilité maximale avec les fonctionnalités infrastructure . Recommandation : préfixez votre métrique avec une catégorie pour faciliter la navigation dans les métriques dans l'UI de New Relic. L'intégration de New Relic utilise actuellement : `net`:Nombre de connexions, requests du serveur Web, d'octets transmis sur le réseau, etc. ; par exemple, `net.connectionsActive`. `query`: Métriques directement liées à la requête de base de données ; par exemple, `query.comInsertPerSecond`. `db`: Base de données métriques interne; par exemple, `db.openTables`. Utilisez des préfixes à plusieurs niveaux pour un regroupement supplémentaire lorsque cela est judicieux ; par exemple, `db.innodb.bufferPoolPagesFree`. Utilisez le format de dénomination `innerCamelCase` ; par exemple : `net.requestsPerSecond`. Utilisez un nom métrique aussi proche que possible de celui d'origine tout en respectant les autres spécifications. Par exemple: Nom d'origine: `Qcache_hits` Nom métrique : `db.qCacheHits`
Unité de mesure	Recommandation : spécifiez l'unité de mesure à l'aide d'un suffixe d'unité s'il n'est pas déjà inclus dans le nom de la métrique d'origine, comme dans les exemples suivants : Pourcentages : utilisez `Percent`; par exemple : `cpuUtilPercent`. Tarifs : Utilisez un format tel que `PerSecond`. Les secondes sont la mesure de vitesse standard, mais vous pouvez également utiliser d'autres unités, telles que `PerMinute` ou `PerDay`. Mesures d'octets : utilisez `Bytes`. Recommandation : si une métrique est capturée dans une unité différente, telle que `Megabytes`, convertissez-la en `Bytes`. Par exemple : `db.allMemtablesOffHeapSizeBytes`. Mesures de temps : utilisez `Milliseconds`. Recommandation : si une métrique est capturée dans une unité différente, telle que `Seconds`, convertissez-la en `Milliseconds`. Par exemple: `query.readLatency50thPercentileMilliseconds`
Valeur	Utilisez une chaîne ou un nombre (entier ou flottant). Les chaînes peuvent être utilisées comme métadonnées associées, permettant de filtrer les données dans l'UI de New Relic. Un booléen doit être exprimé soit sous forme de chaîne (« vrai », « faux »), soit sous forme d’entier (1, 0). N'utilisez pas de types de valeurs complexes, tels que éventail ou hacher.

Les données d'événement d'infrastructure représentent des messages arbitraires et ponctuels pour les activités clés d'un système ; par exemple :

Démarrage d'un service spécifique

Créer une nouvelle table

Vous pouvez consulter ces données dans la page infrastructure Events et infrastructure événement carte thermique. Vous pouvez également interroger le type d'événement InfrastructureEvent dans New Relic.

Voici un exemple de charge utile JSON de données d'événement d'une intégration, qui suit l'en-tête JSON et les définitions de champ.

[
   {
      "summary":"More than 10 request errors logged in the last 5 minutes",
      "category": "notifications"
   }
]

Champ d'événement JSON	Description
`summary`	Requis. Le message à envoyer. Utilisez une chaîne simple.
`category`	Facultatif. Valeur de chaîne d'une des catégories existantes utilisées dans monitoring d'infrastructure, ou d'une nouvelle catégorie. La valeur par défaut est `notifications`. Exemples de catégories : `applications` `automation` `configuration` `metadata` `notifications` `os` `packages` `services` `sessions` `system` `users`

Champ d'événement JSON

Description

summary

Requis. Le message à envoyer. Utilisez une chaîne simple.

category

Facultatif. Valeur de chaîne d'une des catégories existantes utilisées dans monitoring d'infrastructure, ou d'une nouvelle catégorie. La valeur par défaut est notifications. Exemples de catégories :

applications
automation
configuration
metadata
notifications
os
packages
services
sessions
system
users

les données d'inventaire de l'infrastructure capturent les informations en direct sur l'état du système ; Par exemple:

Données de configuration
Versions système installées
Autres métadonnées du système
Vous pouvez consulter ces données sur la pageInventory et infrastructure événement carte thermique. Vous pouvez également interroger les données relatives aux changements d'inventaire.
Le type de données inventory est un hacher d'un ou plusieurs sous-objets JSON contenant :
Une clé d'identification d'inventaire unique (obligatoire) : l'identifiant de l'élément d'inventaire. Ceci est utilisé en combinaison avec le préfixe de l'intégration pour créer un chemin vers les données de l'élément d'inventaire. Les chemins similaires se combinent à travers l'entité et montrent une variance possible. Cet identifiant pointe vers un hacheur.
Un hacher de paires valeur clé, une par attribut d'inventaire. Au moins un est requis.
Les clés doivent être des chaînes.
Les valeurs peuvent être soit un type scalaire (chaîne ou nombre) or un autre objet hacher de valeur clé. New Relic prend en charge la hiérarchie, mais les nœuds de valeur finale doivent être scalaires.
Voici un exemple d'intégration de données d'inventaire JSON :
```
{
    "events/worker_connections": {
        "value": 1024
                },
    "http/gzip" : {
        "value": "on"
                }
}
```

Cette traduction automatique est fournie pour votre commodité.

fichier exécutable d'intégration sur hôte : spécifications JSON

Exigences relatives aux fichiers exécutables

Placement des fichiers

Protocole d'intégration v4 : exemple de sortie JSON

Protocole d'intégration v3 : exemple de sortie JSON

JSON : Spécifications générales

Sortie générale et formatage JSON

Erreurs et logging

Sortie/fermeture de l'exécutable

JSON : En-tête

JSON : entité

Remplacement d'adresse de bouclage sur les noms d'entité

JSON : données métriques, d'inventaire et d'événements

Important

données métriques

données d'événement

Données d'inventaire

Cette traduction automatique est fournie pour votre commodité.

fichier exécutable d'intégration sur hôte : spécifications JSON

Exigences relatives aux fichiers exécutables .css-21sua1{background:none;border:none;width:0;padding:0;}

Placement des fichiers

Protocole d'intégration v4 : exemple de sortie JSON

Protocole d'intégration v3 : exemple de sortie JSON

JSON : Spécifications générales

Erreurs et logging

Sortie/fermeture de l'exécutable

JSON : En-tête

JSON : entité

Remplacement d'adresse de bouclage sur les noms d'entité

JSON : données métriques, d'inventaire et d'événements

Important

données métriques

données d'événement

Données d'inventaire

Exigences relatives aux fichiers exécutables