Nœud de The Graph

Graph Node est le composant qui indexe les subgraphs et rend les données résultantes disponibles pour interrogation via une API GraphQL. En tant que tel, il est au cœur de la pile de l’indexeur, et le bon fonctionnement de Graph Node est crucial pour exécuter un indexeur réussi.

Ceci fournit un aperçu contextuel de Graph Node et de certaines des options les plus avancées disponibles pour les Indexeurs. Une documentation et des instructions détaillées peuvent être trouvées dans le dépôt Graph Node ⁠.

Nœud de The Graph

Graph Node⁠ est l’implémentation de référence pour l’indexation des subgraphs sur The Graph Network, la connexion aux clients de la blockchain, l’indexation des subgraphs et la mise à disposition des données indexées pour les requêtes.

Graph Node (et l’ensemble de la pile de l’indexeur) peut être exécuté sur serveur dédié (bare metal) ou dans un environnement cloud. Cette souplesse du composant central d’indexation est essentielle à la solidité du protocole The Graph. De même, Graph Node peut être compilé à partir du code source⁠, ou les Indexeurs peuvent utiliser l’une des images Docker fournies⁠.

PostgreSQL database

Le magasin principal du nœud de graph, c’est là que les données des sous-graphes sont stockées, ainsi que les métadonnées sur les subgraphs et les données réseau indépendantes des subgraphs telles que le cache de blocs et le cache eth_call.

Clients réseau

Pour indexer un réseau, Graph Node doit avoir accès à un client réseau via une API JSON-RPC compatible avec EVM. Cette RPC peut se connecter à un seul client ou à une configuration plus complexe qui équilibre la charge entre plusieurs clients.

Alors que certains subgraphs peuvent ne nécessiter qu’un nœud complet, d’autres peuvent avoir des caractéristiques d’indexation qui nécessitent des fonctionnalités RPC supplémentaires. En particulier, les subgraphs qui font des eth_calls dans le cadre de l’indexation nécessiteront un noeud d’archive qui supporte EIP-1898⁠, et les subgraphs avec des callHandlers, ou des blockHandlers avec un filtre call, nécessitent le support de trace_filter (voir la documentation du module trace ici⁠).

**Network Firehoses : un Firehose est un service gRPC fournissant un flux de blocs ordonné, mais compatible avec les fork, développé par les principaux développeurs de The Graph pour mieux prendre en charge une indexation performante à l’échelle. Il ne s’agit pas actuellement d’une exigence de l’Indexeur, mais les Indexeurs sont encouragés à se familiariser avec la technologie, en avance sur la prise en charge complète du réseau. Pour en savoir plus sur le Firehose ici⁠.

Nœuds IPFS

Les métadonnées de déploiement de subgraphs sont stockées sur le réseau IPFS. The Graph Node accède principalement au noed IPFS pendant le déploiement du subgraph pour récupérer le manifeste du subgraph et tous les fichiers liés. Les indexeurs de réseau n’ont pas besoin d’héberger leur propre noed IPFS. Un noed IPFS pour le réseau est hébergé sur https://ipfs.network.thegraph.com⁠.

Serveur de métriques Prometheus

Pour activer la surveillance et la création de rapports, Graph Node peut éventuellement enregistrer les métriques sur un serveur de métriques Prometheus.

Getting started from source

Install prerequisites

• Rust

• PostgreSQL

• IPFS

• Exigences supplémentaires pour les utilisateurs d’Ubuntu - Pour faire fonctionner un Graph Node sur Ubuntu, quelques packages supplémentaires peuvent être nécessaires.

1sudo apt-get install -y clang libpq-dev libssl-dev pkg-config

Setup

1. Start a PostgreSQL database server

1initdb -D .postgres2pg_ctl -D .postgres -l logfile start3createdb graph-node

2. Clonez le repo Graph Node⁠ et compilez les sources en lançant cargo build

3. Now that all the dependencies are setup, start the Graph Node:

1cargo run -p graph-node --release -- \2  --postgres-url postgresql://[USERNAME]:[PASSWORD]@localhost:5432/graph-node \3  --ethereum-rpc [NETWORK_NAME]:[URL] \4  --ipfs https://ipfs.network.thegraph.com

Bien démarrer avec Kubernetes

Un exemple complet de configuration Kubernetes se trouve dans le dépôt d’Indexeur⁠.

Ports

Lorsqu’il est en cours d’exécution, Graph Node expose les ports suivants :

Configuration avancée du nœud graph

Dans sa forme la plus simple, Graph Node peut être utilisé avec une seule instance de Graph Node, une seule base de données PostgreSQL, un nœud IPFS et les clients réseau selon les besoins des subgraphs à indexer.

Cette configuration peut être mise à l’échelle horizontalement, en ajoutant plusieurs Graph Nodes, et plusieurs bases de données pour supporter ces Graph Nodes. Les utilisateurs avancés voudront peut-être profiter de certaines des capacités de mise à l’échelle horizontale de Graph Node, ainsi que de certaines des options de configuration les plus avancées, via le fichier config.toml et les variables d’environnement de Graph Node.

config.toml

Un fichier de configuration TOML⁠ peut être utilisé pour définir des configurations plus complexes que celles exposées dans la CLI. L’emplacement du fichier est transmis avec via l’option de ligne de commande —config.

Un fichier config.toml minimal peut être fourni ; le fichier suivant équivaut à l’utilisation de l’option —postgres-url en ligne de commande :

1[store]2[store.primary]3connection="<..argument postgres-url ..>"4[deployment]5[[deployment.rule]]6indexers = [ "<.. liste de tous les nœuds d'indexation ..>" ]

La documentation complète de config.toml peut être trouvée dans la documentation de Graph Node⁠.

Multiple Graph Nodes

L’indexation Graph Node peut être mise à l’échelle horizontalement, en exécutant plusieurs instances de Graph Node pour répartir l’indexation et l’interrogation sur différents nœuds. Cela peut être fait simplement en exécutant des Graph Nodes configurés avec un node_id différent au démarrage (par exemple dans le fichier Docker Compose), qui peut ensuite être utilisé dans le fichier config.toml pour spécifier les nœuds de requête dédiés, les ingesteurs de blocs et en répartissant les subgraphs sur les nœuds avec des règles de déploiement.

Règles de déploiement

Étant donné plusieurs Graph Node, il est nécessaire de gérer le déploiement de nouveaux subgraphs afin que le même subgraph ne soit pas indexé par deux nœuds différents, ce qui entraînerait des collisions. Cela peut être fait en utilisant des règles de déploiement, qui peuvent également spécifier dans quel shard les données d’un subgraph doivent être stockées, si le partitionnement de base de données est utilisé. Les règles de déploiement peuvent correspondre au nom du subgraph et au réseau que le déploiement indexe afin de prendre une décision.

Exemple de configuration de règle de déploiement :

1[deployment]2[[deployment.rule]]3match = { name = "(vip|important)/.*" }4shard = "vip"5indexers = [ "index_node_vip_0", "index_node_vip_1" ]6[[deployment.rule]]7match = { network = "kovan" }8# No shard, so we use the default shard called 'primary'9indexers = [ "index_node_kovan_0" ]10[[deployment.rule]]11match = { network = [ "xdai", "poa-core" ] }12indexers = [ "index_node_other_0" ]13[[deployment.rule]]14# There's no 'match', so any subgraph matches15shards = [ "sharda", "shardb" ]16indexers = [17    "index_node_community_0",18    "index_node_community_1",19    "index_node_community_2",20    "index_node_community_3",21    "index_node_community_4",22    "index_node_community_5"23  ]

En savoir plus sur les règles de déploiement ici⁠.

Nœuds de requête dédiés

Les nœuds peuvent être configurés pour être explicitement des nœuds de requête en incluant les éléments suivants dans le fichier de configuration :

1[general]2query = "<expression regulière>"

Tout nœud dont —node-id correspond à l’expression régulière sera configuré pour répondre uniquement aux requêtes.

Mise à l’échelle de la base de données via le partitionnement

Pour la plupart des cas d’utilisation, une seule base de données Postgres suffit pour prendre en charge une instance de nœud graph. Lorsqu’une instance de nœud graph dépasse une seule base de données Postgres, il est possible de diviser le stockage des données de nœud graph sur plusieurs bases de données Postgres. Toutes les bases de données forment ensemble le magasin de l’instance de nœud graph. Chaque base de données individuelle est appelée une partition.

Les fragments peuvent être utilisés pour diviser les déploiements de subgraph sur plusieurs bases de données et peuvent également être utilisés pour faire intervenir des réplicas afin de répartir la charge de requête sur plusieurs bases de données. Cela inclut la configuration du nombre de connexions de base de données disponibles que chaque graph-node doit conserver dans son pool de connexions pour chaque base de données, ce qui devient de plus en plus important à mesure que davantage de subgraph sont indexés.

Le partage devient utile lorsque votre base de données existante ne peut pas suivre la charge que Graph Node lui impose et lorsqu’il n’est plus possible d’augmenter la taille de la base de données.

En termes de configuration des connexions, commencez par max_connections dans postgresql.conf défini sur 400 (ou peut-être même 200) et regardez les métriques store_connection_wait_time_ms et store_connection_checkout_count Prometheus. Des temps d’attente notables (tout ce qui dépasse 5 ms) indiquent qu’il y a trop peu de connexions disponibles ; des temps d’attente élevés seront également dus au fait que la base de données est très occupée (comme une charge CPU élevée). Cependant, si la base de données semble par ailleurs stable, des temps d’attente élevés indiquent la nécessité d’augmenter le nombre de connexions. Dans la configuration, le nombre de connexions que chaque instance de nœud graph peut utiliser constitue une limite supérieure, et Graph Node ne maintiendra pas les connexions ouvertes s’il n’en a pas besoin.

En savoir plus sur la configuration du store ici⁠.

Ingestion de blocs dédiés

Si plusieurs nœuds sont configurés, il sera nécessaire de spécifier un nœud responsable de l’ingestion de nouveaux blocs, afin que tous les nœuds d’indexation ne sondent pas simultanément le head de la chaîne. Cela s’effectue dans la section chains du fichier de configuration, en spécifiant le node_id à utiliser pour l’ingestion de blocs :

1[chains]2ingestor = "block_ingestor_node"

Prise en charge de plusieurs réseaux

The Graph Protocol augmente le nombre de réseaux pris en charge pour l’indexation des récompenses, et il existe de nombreux subgraphs indexant des réseaux non pris en charge. Un indexeur peut choisir de les indexer malgré tout. Le fichier config.toml permet une configuration riche et flexible :

• Plusieurs réseaux
• Plusieurs fournisseurs par réseau (cela peut permettre de répartir la charge entre les fournisseurs, et peut également permettre la configuration de nœuds complets ainsi que de nœuds d’archives, Graph Node préférant les fournisseurs moins chers si une charge de travail donnée le permet).
• Détails supplémentaires sur le fournisseur, tels que les fonctionnalités, l’authentification et le type de fournisseur (pour la prise en charge expérimentale de Firehose)

La section [chains] contrôle les fournisseurs ethereum auxquels graph-node se connecte, et où les blocs et autres métadonnées pour chaque chaîne sont stockés. L’exemple suivant configure deux chaînes, mainnet et kovan, où les blocs pour mainnet sont stockés dans le shard vip et les blocs pour kovan sont stockés dans le shard primaire. La chaîne mainnet peut utiliser deux fournisseurs différents, alors que kovan n’a qu’un seul fournisseur.

1[chains]2ingestor = "block_ingestor_node"3[chains.mainnet]4shard = "vip"5provider = [6  { label = "mainnet1", url = "http://..", features = [], headers = { Authorization = "Bearer foo" } },7  { label = "mainnet2", url = "http://..", features = [ "archive", "traces" ] }8]9[chains.kovan]10shard = "primary"11provider = [ { label = "kovan", url = "http://..", features = [] } ]

Consultez les informations sur la configuration des fournisseurs ici⁠.

Variables d’environnement

Graph Node supporte une série de variables d’environnement qui peuvent activer des fonctionnalités ou modifier le comportement de Graph Node. Elles sont documentées ici⁠.

Déploiement continu

Les utilisateurs qui utilisent une configuration d’indexation à grande échelle avec une configuration avancée peuvent bénéficier de la gestion de leurs nœuds graph avec Kubernetes.

• Le dépot de l’Indexeur a un exemple de référence Kubernetes⁠
• Launchpad⁠ est une boîte à outils pour l’exécution d’un Graph Protocol Indexer sur Kubernetes maintenue par GraphOps. Il fournit un ensemble de graphiques Helm et une CLI pour gérer le déploiement Graph Node.

Gestion du nœud de graph

Étant donné un nœud de graph en cours d’exécution (ou des nœuds de graph !), le défi consiste alors à gérer les subgraphs déployés sur ces nœuds. Graph Node propose une gamme d’outils pour vous aider à gérer les subgraphs.

Journal de bord

Les logs de Graph Node peuvent fournir des informations utiles pour le débogage et l’optimisation de Graph Node et de subgraphs spécifiques. Graph Node supporte différents niveaux de logs via la variable d’environnement GRAPH_LOG, avec les niveaux suivants : error, warn, info, debug ou trace.

De plus, fixer GRAPH_LOG_QUERY_TIMING à gql fournit plus de détails sur la façon dont les requêtes GraphQL s’exécutent (bien que cela génère un grand volume de logs).

Supervision & alertes

Graph Node fournit les métriques via le point de terminaison Prometheus sur le port 8040 par défaut. Grafana peut ensuite être utilisé pour visualiser ces métriques.

Le dépôt indexer propose un [exemple de configuration Grafana] (https://github.com/graphprotocol/indexer/blob/main/k8s/base/grafana.yaml⁠).

Graphman

graphman est un outil de maintenance pour Graph Node, aidant au diagnostic et à la résolution de différentes tâches quotidiennes et exceptionnelles.

La commande graphman est incluse dans les conteneurs officiels, et vous pouvez docker exec dans votre conteneur graph-node pour l’exécuter. Elle nécessite un fichier config.toml.

La documentation complète des commandes graphman est disponible dans le dépôt Graph Node. Voir /docs/graphman.md⁠ dans le dépôt Graph Node /docs

Travailler avec des subgraphs

API d’état d’indexation

Disponible sur le port 8030/graphql par défaut, l’API d’état d’indexation expose une gamme de méthodes pour vérifier l’état d’indexation de différents subgraphs, vérifier les preuves d’indexation, inspecter les fonctionnalités des subgraphs et bien plus encore.

Le schéma complet est disponible ici⁠.

Performances d’indexation

Le processus d’indexation comporte trois parties distinctes :

• Récupération des événements d’intérêt auprès du fournisseur
• Traiter les événements dans l’ordre avec les gestionnaires appropriés (cela peut impliquer d’appeler la chaîne pour connaître l’état et de récupérer les données du magasin)
• Écriture des données résultantes dans le magasin

Ces étapes sont pipeline (c’est-à-dire qu’elles peuvent être exécutées en parallèle), mais elles dépendent les unes des autres. Lorsque les subgraphs sont lents à indexer, la cause sous-jacente dépendra du subgraph spécifique.

Causes courantes de lenteur d’indexation :

• Temps nécessaire pour trouver les événements pertinents à partir de la chaîne (les gestionnaires d’appels en particulier peuvent être lents, étant donné la dépendance à trace_filter)
• Faire un grand nombre d’appels eth_call dans les gestionnaires
• Une grande quantité d’interactions avec le magasin pendant l’exécution
• Une grande quantité de données à sauvegarder dans le magasin
• Un grand nombre d’événements à traiter
• Temps de connexion à la base de données lent, pour les nœuds encombrés
• Le prestataire lui-même prend du retard sur la tête de la chaîne
• Lenteur dans la récupération des nouvelles recettes en tête de chaîne auprès du prestataire

Les métriques d’indexation de subgraphs peuvent aider à diagnostiquer la cause première de la lenteur de l’indexation. Dans certains cas, le problème réside dans le subgraph lui-même, mais dans d’autres, des fournisseurs de réseau améliorés, une réduction des conflits de base de données et d’autres améliorations de configuration peuvent améliorer considérablement les performances d’indexation.

Subgraphs ayant échoué

Lors de l’indexation, les subgraphs peuvent échouer s’ils rencontrent des données inattendues, si certains composants ne fonctionnent pas comme prévu ou s’il y a un bogue dans les gestionnaires d’événements ou la configuration. Il existe deux types généraux de pannes :

• Échecs déterministes : ce sont des échecs qui ne seront pas résolus par de nouvelles tentatives
• Échecs non déterministes : ils peuvent être dus à des problèmes avec le fournisseur ou à une erreur inattendue de Graph Node. Lorsqu’un échec non déterministe se produit, Graph Node réessaiera les gestionnaires défaillants, en reculant au fil du temps.

Dans certains cas, un échec peut être résolu par l’indexeur (par exemple, si l’erreur est due au fait de ne pas disposer du bon type de fournisseur, l’ajout du fournisseur requis permettra de poursuivre l’indexation). Cependant, dans d’autres cas, une modification du code du subgraph est requise.

Bloquer et appeler le cache

Graph Node met en cache certaines données dans le store afin d’éviter de les récupérer auprès du fournisseur. Les blocs sont mis en cache, ainsi que les résultats des eth_calls (ces derniers étant mis en cache à partir d’un bloc spécifique). Cette mise en cache peut augmenter considérablement la vitesse d’indexation lors de la « resynchronisation » d’un subgraph légèrement modifié.

Cependant, dans certains cas, si un nœud Ethereum a fourni des données incorrectes pendant une certaine période, cela peut se retrouver dans le cache, conduisant à des données incorrectes ou à des subgraphs défaillants. Dans ce cas, les Indexeurs peuvent utiliser graphman pour effacer le cache empoisonné, puis rembobiner les subgraph affectés, ce qui permettra de récupérer des données fraîches auprès du fournisseur (que l’on espère sain).

Si une incohérence du cache de blocs est suspectée, telle qu’un événement de réception de transmission manquant :

1. graphman chain list pour trouver le nom de la chaîne.
2. graphman chain check-blocks <CHAIN> by-number <NUMBER> vérifiera si le bloc mis en cache correspond au fournisseur, et supprimera le bloc du cache si ce n’est pas le cas.
   1. S’il y a une différence, il peut être plus sûr de tronquer tout le cache avec graphman chain truncate <CHAIN>.
   2. Si le bloc correspond au fournisseur, le problème peut être débogué directement auprès du fournisseur.

Interroger les problèmes et les erreurs

Une fois qu’un subgraph a été indexé, les indexeurs peuvent s’attendre à traiter les requêtes via le point de terminaison de requête dédié du subgraph. Si l’indexeur espère traiter un volume de requêtes important, un nœud de requête dédié est recommandé, et en cas de volumes de requêtes très élevés, les indexeurs peuvent souhaiter configurer des fragments de réplique afin que les requêtes n’aient pas d’impact sur le processus d’indexation.

Cependant, même avec un nœud de requête et des répliques dédiés, certaines requêtes peuvent prendre beaucoup de temps à exécuter et, dans certains cas, augmenter l’utilisation de la mémoire et avoir un impact négatif sur le temps de requête des autres utilisateurs.

Il n’existe pas de solution miracle, mais une gamme d’outils permettant de prévenir, de diagnostiquer et de traiter les requêtes lentes.

Mise en cache des requêtes

Graph Node met en cache les requêtes GraphQL par défaut, ce qui peut réduire de manière significative la charge de la base de données. Ceci peut être configuré avec les paramètres GRAPH_QUERY_CACHE_BLOCKS et GRAPH_QUERY_CACHE_MAX_MEM - en savoir plus ici⁠.

Analyser les requêtes

Les requêtes problématiques apparaissent le plus souvent de deux manières. Dans certains cas, les utilisateurs eux-mêmes signalent qu’une requête donnée est lente. Dans ce cas, le défi consiste à diagnostiquer la raison de la lenteur, qu’il s’agisse d’un problème général ou spécifique à ce subgraph ou à cette requête. Et puis bien sûr de le résoudre, si possible.

Dans d’autres cas, le déclencheur peut être une utilisation élevée de la mémoire sur un nœud de requête, auquel cas le défi consiste d’abord à identifier la requête à l’origine du problème.

Les Indexeurs peuvent utiliser qlog⁠ pour traiter et résumer les logs de requêtes de Graph Node. GRAPH_LOG_QUERY_TIMING peut également être activé pour aider à identifier et déboguer les requêtes lentes.

Étant donné une requête lente, les indexeurs disposent de quelques options. Bien entendu, ils peuvent modifier leur modèle de coûts pour augmenter considérablement le coût d’envoi de la requête problématique. Cela peut entraîner une réduction de la fréquence de cette requête. Cependant, cela ne résout souvent pas la cause première du problème.

Optimisation de type compte

Les tables de base de données qui stockent les entités semblent généralement se décliner en deux variétés : les tables de type « transaction », où les entités, une fois créées, ne sont jamais mises à jour, c’est-à-dire qu’elles stockent quelque chose qui s’apparente à une liste de transactions financières, et les « de type compte », où les entités sont mis à jour très souvent, c’est-à-dire qu’ils stockent quelque chose comme des comptes financiers qui sont modifiés à chaque fois qu’une transaction est enregistrée. Les tables de type compte se caractérisent par le fait qu’elles contiennent un grand nombre de versions d’entités, mais relativement peu d’entités distinctes. Souvent, dans de tels tableaux, le nombre d’entités distinctes représente 1 % du nombre total de lignes (versions d’entités)

Pour les tables de type compte, graph-node peut générer des requêtes qui tirent parti des détails de la façon dont Postgres stocke les données avec un taux de changement aussi élevé, à savoir que toutes les versions des blocs récents se trouvent dans une petite sous-section du stockage global d’une telle table.

La commande graphman stats show <sgdNNNN> montre, pour chaque type/table d’entité dans un déploiement, combien d’entités distinctes, et combien de versions d’entités chaque table contient. Ces données sont basées sur des estimations internes à Postgres, et sont donc nécessairement imprécises, et peuvent être erronées d’un ordre de grandeur. Un -1 dans la colonne entités signifie que Postgres pense que toutes les lignes contiennent une entité distincte.

En général, les tables où le nombre d’entités distinctes est inférieur à 1% du nombre total de versions de lignes/d’entités sont de bons candidats pour l’optimisation de type compte. Lorsque la sortie de graphman stats show indique qu’une table pourrait bénéficier de cette optimisation, l’exécution de graphman stats show <sgdNNN> <table> effectuera un comptage complet de la table - ce qui peut être lent, mais donne une mesure précise du ratio d’entités distinctes par rapport au nombre total de versions d’entités.

Une fois qu’une table a été déterminée comme étant de type compte, l’exécution de graphman stats account-like <sgdNNN>.<table> activera l’optimisation de type compte pour les requêtes sur cette table. L’optimisation peut être désactivée à nouveau avec graphman stats account-like --clear <sgdNNN>.<table> Il faut compter jusqu’à 5 minutes pour que les noeuds de requêtes remarquent que l’optimisation a été activée ou désactivée. Après avoir activé l’optimisation, il est nécessaire de vérifier que le changement ne ralentit pas les requêtes pour cette table. Si vous avez configuré Grafana pour surveiller Postgres, les requêtes lentes apparaîtront dans pg_stat_activity en grand nombre, prenant plusieurs secondes. Dans ce cas, l’optimisation doit être désactivée à nouveau.

Pour les subgraphs de type Uniswap, les tables pair et token sont les meilleurs candidats pour cette optimisation, et peuvent avoir un effet considérable sur la charge de la base de données.

Supprimer des subgraphs

A un moment donné, un Indexeur peut vouloir supprimer un subgraph donné. Cela peut être facilement fait via graphman drop, qui supprime un déploiement et toutes ses données indexées. Le déploiement peut être spécifié soit comme un nom de subgraph, soit comme un hash IPFS Qm.., ou alors comme le namespace sgdNN de la base de données . Une documentation plus détaillée est disponible ici⁠.