Références pour les ressources d'intégration
Rapport de recherche Datadog : Bilan sur l'adoption de l'informatique sans serveur Rapport : Bilan sur l'adoption de l'informatique sans serveur

Références pour les ressources d'intégration

Fichier de configuration

Lorsque vous préparez une nouvelle intégration, vous devez inclure un exemple de configuration contenant les options requises et des valeurs par défaut appropriées. L’exemple de fichier de configuration, ici situé dans <NOM_CHECK>/datadog_checks/<NOM_CHECK>/data/conf.yaml.example, comprend deux éléments de premier niveau : init_config et instances. La configuration sous init_config est appliquée à l’ensemble de l’intégration et utilisée à chaque instanciation de l’intégration, tandis que ce qui trouve sous instances est spécifique à une instanciation donnée.

Les blocs de configuration sous chaque section prennent le format suivant :

## @<COMMANDE> [- <ARGUMENTS>]
## <LIGNE DESCRIPTION 1>
## <LIGNE DESCRIPTION 2>
#
<KEY>: <VALUE>

Les blocs de configuration doivent respecter quelques principes :

  • La description ne doit pas être vide.
  • Les placeholders doivent toujours respecter ce format : <CECI_EST_UN_PLACEHOLDER>, conformément aux règles de contribution à la documentation.
  • Par défaut, tous les paramètres requis ne sont pas mis en commentaire.
  • Par défaut, tous les paramètres facultatifs sont mis en commentaire.
  • Si un placeholder présente une valeur par défaut pour une intégration (comme l’endpoint de statut d’une intégration), celle-ci peut être utilisée à la place d’un placeholder générique.

Spécification @param

En pratique, la seule commande est @param, qui est utilisée pour décrire les blocs de configuration, principalement à des fins de documentation. @param doit être implémentée en respectant l’un des formats suivants :

@param <nom> - <type> - requis
@param <nom> - <type> - facultatif
@param <nom> - <type> - facultatif - valeur par défaut : <valeur_defaut>

Arguments :

  • nom : le nom du paramètre, p. ex. search_string (obligatoire).
  • type : le type de données de la valeur du paramètre (obligatoire). Valeurs autorisées :
    • boolean
    • string
    • integer
    • double
    • float
    • dictionary
    • list*
    • object
  • valeur_defaut : valeur par défaut pour le paramètre ; peut être laissé vide (facultatif).

Les variables list et object couvrent plusieurs lignes et font l’objet de règles spéciales.

  • Dans une list, les éléments individuels ne sont pas documentés via la spécification @param
  • Dans un object, vous avez la possibilité de documenter les éléments individuellement avec la spécification @param ou de spécifier une description commune au niveau supérieur juste après la spécification de l’objet.

Paramètres facultatifs

Un paramètre facultatif doit être mis en commentaire par défaut. Au début de chaque ligne couverte par le paramètre, ajoutez # en appliquant la même indentation que pour la spécification @param.

Commentaires de bloc

Vous pouvez ajouter un commentaire de bloc n’importe où dans le fichier de configuration. Les règles suivantes doivent être appliquées :

  • Les commentaires doivent commencer par ##.
  • Les commentaires doivent être indentés comme les variables (le trait d’union ne compte pas).

Pour en savoir plus sur la syntaxe YAML, consultez l’article Wikipedia. Et n’hésitez pas à faire bon usage du parser en ligne Online YAML Parser !

Fichier manifest

Chaque intégration contient un fichier manifest.json qui décrit les paramètres de fonctionnement de l’intégration, sa place dans l’écosystème d’intégrations global de Datadog, et d’autres informations semblables.

Voici la liste complète des attributs obligatoires et facultatifs pour le fichier manifest.json :

AttributTypeObligatoire/FacultatifDescription
integration_idChaîneObligatoireLe nom d’identification unique de cette intégration. Généralement, il s’agit de la version kebab case du nom d’affichage
categoriesTableau de chaînesObligatoireLes catégories d’intégration utilisées sur la page Intégrations de la documentation publique.
creates_eventsBooléenObligatoireDéfinit si l’intégration est en mesure de créer des événements. Si cet attribut est défini sur false, une erreur se produit lorsque l’intégration tente de créer un événement.
display_nameChaîneObligatoireLe titre affiché sur le carré d’intégration correspondant dans l’application Datadog et sur la page Intégrations de la documentation publique.
guidChaîneObligatoireL’ID unique de l’intégration. Cliquez ici pour générer un UUID.
is_publicBooléenObligatoireSi cet attribut est défini sur false, le contenu du fichier README.md de l’intégration n’est pas indexé par les robots dans la documentation publique de Datadog.
maintainerChaîneObligatoireL’adresse e-mail du propriétaire de l’intégration.
manifest_versionChaîneObligatoireLa version du manifeste actuel.
nameChaîneObligatoireLe nom unique de l’intégration. Utilisez le nom du répertoire pour ce paramètre.
public_titleChaîneObligatoireLe titre de l’intégration affiché dans la documentation. Doit respecter le format : Datadog-<NOM_INTÉGRATION> integration.
short_descriptionChaîneObligatoireCe texte s’affiche en haut du carré d’intégration ainsi qu’au passage de la souris sur la page Intégrations. 80 caractères maximum.
supportChaîneObligatoireLe propriétaire de l’intégration.
supported_osTableau de chaînesObligatoireLa liste des systèmes d’exploitation pris en charge. Valeurs autorisées : linux, mac_os ou windows.
typeChaîneObligatoireLe type d’intégration, doit être défini sur check.
aliasesTableau de chaînesFacultatifUne liste d’alias d’URL pour la documentation Datadog.
descriptionChaîneFacultatifCe texte s’affiche lorsque quelqu’un partage un lien vers la documentation de l’intégration.
is_betaBooléenFacultatiffalse par défaut. Lorsque cet attribut est défini sur true, le contenu du fichier README.md de l’intégration ne s’affiche pas dans la documentation publique de Datadog.
metric_to_checkChaîneFacultatifLa présence de cette métrique indique que l’intégration fonctionne correctement. Si cette métrique n’est pas reçue une fois l’intégration installée, l’intégration est signalée comme non fonctionnelle dans l’application Datadog.
metric_prefixChaîneFacultatifL’espace de nommage des métriques de cette intégration. Cette valeur sera ajoutée en préfixe pour chaque métrique envoyée par cette intégration.
process_signaturesTableau de chaînesFacultatifUne liste de signatures qui correspond à la ligne de commande de cette intégration.
assetsDictionnaireObligatoireL’emplacement relatif où se trouvent certains fichiers ressources et leurs noms respectifs.
assets-> dashboardsDictionnaireObligatoireLe dictionnaire dont la clé est le nom du dashboard (doit être unique dans l’ensemble des intégrations) et la valeur est le chemin relatif du fichier où se trouve la définition du dashboard.
assets-> monitorsDictionnaireObligatoireLe dictionnaire dont la clé est le nom du monitor (doit être unique dans l’ensemble des intégrations) et la valeur est le chemin relatif du fichier où se trouve la définition du dashboard.
assets-> service_checksChaîneObligatoireL’emplacement relatif où se trouve le fichier service_checks.json.

Fichier metadata des métriques

Le fichier metadata.csv décrit toutes les métriques pouvant être recueillies par l’intégration.

Description de chaque colonne du fichier metadata.csv :

Nom de la colonneObligatoire/FacultatifDescription
metric_nameObligatoireNom de la métrique.
metric_typeObligatoireType de la métrique.
intervalFacultatifIntervalle de collecte de la métrique en secondes.
unit_nameFacultatifUnité de la métrique. Voir la liste complète des unités prises en charge.
per_unit_nameFacultatifEn cas de sous-division de l’unité, p. ex. requêtes par seconde
descriptionFacultatifDescription de la métrique.
orientationObligatoireDéfinir sur 1 si la métrique doit augmenter, p. ex. myapp.turnover. Définir sur 0 si les variations ne la métrique n’importent pas. Définir sur -1 si la métrique doit diminuer, p. ex. myapp.latency.
integrationObligatoireNom de l’intégration qui envoie la métrique. Doit correspondre à la version normalisée du display_name dans le fichier manifest.json. Les caractères autres que les lettres, underscores, tirets et nombres sont convertis en underscores. Par exemple, Openstack Controller -> openstack_controller, ASP.NET -> asp_net et CRI-o -> cri-o.
short_nameObligatoireIdentifiant unique et explicite de la métrique.

Fichier service_check

Le fichier service_check.json décrit les checks de service effectués par l’intégration.

Le fichier service_checks.json contient les attributs obligatoires suivants :

AttributDescription
agent_versionLa version minimale prise en charge de l’Agent.
integrationLe nom de l’intégration qui envoie le check de service. Doit correspondre au display_name non normalisé de manifest.json.
checkLe nom du check de service. Doit être unique.
statusesLa liste des différents statuts du check. Valeurs autorisées : ok, warning, critical ou unknown.
groupsLes tags envoyés avec le check de service.
nameLe nom d’affichage du check de service. Le nom d’affichage doit être clair et unique dans l’ensemble des intégrations.
descriptionDescription du check de service