Nœud de The Graph

Graph Node is the component which indexes Subgraphs, and makes the resulting data available to query via a GraphQL API. As such it is central to the indexer stack, and correct operation of Graph Node is crucial to running a successful indexer.

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⁠ is the reference implementation for indexing Subgraphs on The Graph Network, connecting to blockchain clients, indexing Subgraphs and making indexed data available to query.

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

The main store for the Graph Node, this is where Subgraph data is stored, as well as metadata about Subgraphs, and Subgraph-agnostic network data such as the block cache, and eth_call cache.

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.

While some Subgraphs may just require a full node, some may have indexing features which require additional RPC functionality. Specifically Subgraphs which make eth_calls as part of indexing will require an archive node which supports EIP-1898⁠, and Subgraphs with callHandlers, or blockHandlers with a call filter, require trace_filter support (see trace module documentation here⁠).

**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

Subgraph deployment metadata is stored on the IPFS network. The Graph Node primarily accesses the IPFS node during Subgraph deployment to fetch the Subgraph manifest and all linked files. Network indexers do not need to host their own IPFS node. An IPFS node for the network is hosted at https://ipfs.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.

Démarrer à partir des sources

Installer les prérequis

• 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

Configuration

1. Démarrer un serveur de base de données PostgreSQL

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. Maintenant que toutes les dépendances sont installées, démarrez 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.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

At its simplest, Graph Node can be operated with a single instance of Graph Node, a single PostgreSQL database, an IPFS node, and the network clients as required by the Subgraphs to be indexed.

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

Graph Node indexing can scale horizontally, running multiple instances of Graph Node to split indexing and querying across different nodes. This can be done simply by running Graph Nodes configured with a different node_id on startup (e.g. in the Docker Compose file), which can then be used in the config.toml file to specify dedicated query nodes, block ingestors, and splitting Subgraphs across nodes with deployment rules.

Règles de déploiement

Given multiple Graph Nodes, it is necessary to manage deployment of new Subgraphs so that the same Subgraph isn’t being indexed by two different nodes, which would lead to collisions. This can be done by using deployment rules, which can also specify which shard a Subgraph’s data should be stored in, if database sharding is being used. Deployment rules can match on the Subgraph name and the network that the deployment is indexing in order to make a decision.

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.

Shards can be used to split Subgraph deployments across multiple databases, and can also be used to use replicas to spread query load across databases. This includes configuring the number of available database connections each graph-node should keep in its connection pool for each database, which becomes increasingly important as more Subgraphs are being indexed.

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 is increasing the number of networks supported for indexing rewards, and there exist many Subgraphs indexing unsupported networks which an indexer would like to process. The config.toml file allows for expressive and flexible configuration of:

• 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

Given a running Graph Node (or Graph Nodes!), the challenge is then to manage deployed Subgraphs across those nodes. Graph Node surfaces a range of tools to help with managing Subgraphs.

Journal de bord

Graph Node’s logs can provide useful information for debugging and optimisation of Graph Node and specific Subgraphs. Graph Node supports different log levels via the GRAPH_LOG environment variable, with the following levels: error, warn, info, debug or 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

Working with Subgraphs

API d’état d’indexation

Available on port 8030/graphql by default, the indexing status API exposes a range of methods for checking indexing status for different Subgraphs, checking proofs of indexing, inspecting Subgraph features and more.

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

These stages are pipelined (i.e. they can be executed in parallel), but they are dependent on one another. Where Subgraphs are slow to index, the underlying cause will depend on the specific Subgraph.

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

Subgraph indexing metrics can help diagnose the root cause of indexing slowness. In some cases, the problem lies with the Subgraph itself, but in others, improved network providers, reduced database contention and other configuration improvements can markedly improve indexing performance.

Failed Subgraphs

During indexing Subgraphs might fail, if they encounter data that is unexpected, some component not working as expected, or if there is some bug in the event handlers or configuration. There are two general types of failure:

• É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.

In some cases a failure might be resolvable by the indexer (for example if the error is a result of not having the right kind of provider, adding the required provider will allow indexing to continue). However in others, a change in the Subgraph code is required.

Bloquer et appeler le cache

Graph Node caches certain data in the store in order to save refetching from the provider. Blocks are cached, as are the results of eth_calls (the latter being cached as of a specific block). This caching can dramatically increase indexing speed during “resyncing” of a slightly altered Subgraph.

However, in some instances, if an Ethereum node has provided incorrect data for some period, that can make its way into the cache, leading to incorrect data or failed Subgraphs. In this case indexers can use graphman to clear the poisoned cache, and then rewind the affected Subgraphs, which will then fetch fresh data from the (hopefully) healthy provider.

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

Once a Subgraph has been indexed, indexers can expect to serve queries via the Subgraph’s dedicated query endpoint. If the indexer is hoping to serve significant query volume, a dedicated query node is recommended, and in case of very high query volumes, indexers may want to configure replica shards so that queries don’t impact the indexing process.

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

Problematic queries most often surface in one of two ways. In some cases, users themselves report that a given query is slow. In that case the challenge is to diagnose the reason for the slowness - whether it is a general issue, or specific to that Subgraph or query. And then of course to resolve it, if 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.

For Uniswap-like Subgraphs, the pair and token tables are prime candidates for this optimization, and can have a dramatic effect on database load.

Removing Subgraphs

At some point an indexer might want to remove a given Subgraph. This can be easily done via graphman drop, which deletes a deployment and all it’s indexed data. The deployment can be specified as either a Subgraph name, an IPFS hash Qm.., or the database namespace sgdNNN. Further documentation is available here⁠.