Graph Node

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.

Bu belge, Graph Düğümü’nün bağlamsal bir genel görünümünü ve Endeksleyicilerin kullanımına açık olan bazı daha gelişmiş seçenekleri sunar. Ayrıntılı dokümantasyon ve talimatlar Graph Düğümü deposunda⁠ bulunabilir.

Graph Node

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 Düğümü (ve tüm endeksleyici yığını), çıplak metal sunucular üzerinde veya bir bulut ortamında çalıştırılabilir. Merkezi endeksleme bileşeninin bu esnekliği, The Graph Protokolü’nün dayanıklılığı için çok önemlidir. Benzer şekilde, Graph Düğümü kaynak kodundan inşa edilebilir⁠, veya endeksleyiciler sağlanan Docker Görüntülerinden⁠ birini kullanabilirler.

PostgreSQL veritabanı

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.

Ağ istemcileri

Bir ağı endekslemek için, Graph Düğümü’nün EVM uyumlu bir JSON-RPC API üzerinden bir ağ istemcisine erişimi olması gerekir. Bu RPC, tek bir istemciye bağlanabilir veya birden fazla istemci arasında yük dengelemesi yapan daha karmaşık bir yapı olabilir.

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⁠).

**Ağ Firehose’ları ** - Firehose, sıralı ancak çatallanmaların farkında olacak şekilde blok akışı sağlayan bir gRPC hizmetidir. The Graph’in çekirdek geliştiricileri tarafından, ölçeklenebilir ve yüksek performanslı endekslemeyi daha iyi desteklemek amacıyla geliştirilmiştir. Firehose şu an için bir Endeksleyici gereksinimi değildir. Ancak Endeksleyicilerin tam ağ desteğinden önce bu teknolojiye aşina olmaları teşvik edilmektedir. Firehose hakkında daha fazla bilgiye buradan⁠ ulaşılabilir.

IPFS Düğümleri

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⁠.

Prometheus metrik sunucusu

İzleme ve raporlama etkinleştirmek için Graph Düğümü, metrikleri bir Prometheus metrik sunucusuna opsiyonel olarak kaydedebilir.

Getting started from source

Install prerequisites

• Rust

• PostgreSQL

• IPFS

• Ubuntu kullanıcıları için Ek Gereksinimler - Graph Düğümü’nü Ubuntu üzerinde çalıştırmak için birkaç ek paket gerekebilir.

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. Graph Düğümü⁠ github deposunu klonlayın ve cargo build komutunu çalıştırarak kaynağı derleyin

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.thegraph.com

Kubernetes’i kullanmaya başlarken

Kubernetes örnek yapılandırmasının bütüncül bir örneği endeksleyici Github deposunda⁠ bulunabilir.

Portlar

Graph Düğümü çalışırken aşağıdaki portları açar:

Gelişmiş Graph Düğüm yapılandırması

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.

Bu yapılandırma, birden fazla Graph Düğümü ekleyerek ve bu Graph Düğümlerini desteklemek için birden fazla veritabanı ekleyerek, yatay olarak ölçeklenebilir. İleri düzey kullanıcılar, Graph Düğümü’nün bazı yatay ölçekleme özelliklerinden faydalanmak isteyebilir. Ayrıca config.toml dosyası ve Graph Düğümü’nün ortam değişkenleri aracılığıyla daha gelişmiş yapılandırma seçeneklerinden yararlanabilir.

config.toml

TOML⁠ yapılandırma dosyası, CLI’da sunulanlardan daha karmaşık yapılandırmalar ayarlamak için kullanılabilir. Dosyanın konumu —config komut satırı anahtarı ile iletilir.

Minimal bir config.toml dosyası sağlanabilir; aşağıdaki dosya —postgres-url komut satırı seçeneğini kullanmakla eşdeğerdir:

1[store]2[store.primary]3connection="<.. postgres-url argümanı ..>"4[deployment]5[[deployment.rule]]6indexers = [ "<.. tüm endeksleme düğümlerinin listesi ..>" ]

config.toml dosyasının tam dokümantasyonu, Graph Düğümü belgelerinde⁠ bulunabilir.

Birden Fazla Graph Düğümü

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.

Dağıtım kuralları

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.

Örnek dağıtım kuralı yapılandırması:

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  ]

Dağıtım kuralları hakkında daha fazla bilgi için burayı⁠ okuyabilirsiniz.

Özelleştirilmiş sorgu düğümleri

Düğümler, yapılandırma dosyasına aşağıdakini dahil ederek açıkça sorgu düğümleri olarak yapılandırılabilir:

1[general]2query = "<regular expression>"

—node-id’si düzenli ifade ile eşleşen herhangi bir düğüm, sadece sorgulara yanıt vermek üzere ayarlanacaktır.

Sharding ile veritabanı ölçeklendirme

Çoğu kullanım durumu için, tek bir Postgres veritabanı bir graph-düğümü örneğini desteklemek için yeterlidir. Bir graph-düğümü örneği tek bir Postgres veritabanından daha büyük hale geldiğinde, bu graph düğümü verilerinin depolanmasını birden fazla Postgres veritabanına yaymak mümkündür. Tüm veritabanları birlikte, graph-düğümü örneğinin deposunu oluşturur. Her tekil veritabanına bir shard denir.

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.

Sharding, Graph Düğümü’nün üzerine koyduğu yükü mevcut veritabanınıza koyamadığınızda ve veritabanı boyutunu artıramayacağınızda faydalı hale gelir.

Bağlantı yapılandırması açısından postgresql.conf’da max_connections değerinin 400 (veya belki de 200) olarak ayarlanması ve store_connection_wait_time_ms ve store_connection_checkout_count Prometheus metriklerine bakılması önerilir. Belirgin bekleme süreleri (5 milisaniye’nin üzerinde herhangi bir değer) yetersiz bağlantıların mevcut olduğunun bir işaretidir; yüksek bekleme süreleri veritabanının çok yoğun olması gibi sebeplerden de kaynaklanabilir. Ancak, veritabanı genel olarak stabil görünüyorsa, yüksek bekleme süreleri bağlantı sayısını arttırma ihtiyacını belirtir. Yapılandırmada her graph-düğümü örneğinin ne kadar bağlantı kullanabileceği bir üst sınırdır ve Graph Düğümü bunları gereksiz bulmadığı sürece açık tutmaz.

Mağaza yapılandırması hakkında daha fazla bilgi için bu yazıyı⁠ okuyun.

Özelleştirilmiş blok alınması

Birden fazla düğüm yapılandırıldığında, yeni blokların toplanmasından sorumlu olacak tek bir düğüm belirlemek gerekir. Böylece tüm yapılandırılmış endeksleme düğümleri zincir başını sorgulamaz. Bu işlem, chains ad alanında node_id belirterek gerçekleştirilir:

1[chains]2ingestor = "block_ingestor_node"

Birden fazla ağın desteklenmesi

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:

• Birden fazla ağ
• Ağ başına birden fazla sağlayıcı (bu, yükü sağlayıcılar arasında bölme ve bir Graph Düğümü’nün deneyimsel Firehose desteği gibi daha ucuz sağlayıcıları tercih etmesi ile tam düğümlerin yanı sıra arşiv düğümlerinin yapılandırılmasına da izin verebilir).
• Özellikler, kimlik doğrulama ve sağlayıcı türü gibi ek sağlayıcı detayları (deneysel Firehose desteği için)

[chains] bölümü, graph-node’un bağlandığı Ethereum sağlayıcılarını kontrol eder ve her zincir için blokların ve diğer meta verilerin nerede depolandığını belirler. Aşağıdaki örnek, ana ağ ve kovan olmak üzere iki zinciri yapılandırır; ana ağ blokları vip parçasında, kovan blokları ise birincil parçada depolanır. Ana ağ zinciri iki farklı sağlayıcı kullanabilirken, kovan yalnızca bir sağlayıcıya sahiptir.

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 = [] } ]

Sağlayıcı yapılandırması hakkında daha fazla bilgi için bu yazıyı⁠ okuyun.

Ortam değişkenleri

Graph Düğümü, özellikleri etkinleştirebilecek veya Graph Düğümünün davranışını değiştirebilecek çeşitli ortam değişkenlerini destekler. Bunlar burada⁠ belgelenmiştir.

Sürekli dağıtım

Gelişmiş yapılandırmaya sahip ölçeklendirilmiş bir dizinleme kurulumu işleten kullanıcılar, Graph Düğümler’ini Kubernetes ile yönetmekten faydalanabilirler.

• Endeksleyici GitHub deposunda bir örnek Kubernetes referansı⁠ bulunmaktadır
• Launchpad⁠, GraphOps tarafından geliştirilen ve Kubernetes üzerinde bir Graph Protokolü Endeksleyicisi çalıştırmak için kullanılan bir araç setidir. Bir Graph Düğümü dağıtımını yönetmek için bir dizi Helm şeması ve bir CLI sağlar.

Graph Düğümü Yönetimi

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.

Kayıt tutma

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.

Ek olarak, GRAPH_LOG_QUERY_TIMING’i gql olarak ayarlamak, GraphQL sorgularının nasıl çalıştığı hakkında daha fazla ayrıntı sağlar (ancak bu, büyük bir günlük hacmi oluşturacaktır).

İzleme & uyarma

Graph Düğümü, varsayılan olarak 8040 port’undaki Prometheus uç noktası aracılığıyla metrikleri sağlar. Ardından Grafana, bu metrikleri görselleştirmek için kullanılabilir.

Endeksleyici deposunda örnek bir Grafana yapılandırması⁠ bulunmaktadır.

Graphman

graphman, Graph Düğümü için bakım aracıdır. Günlük işlerdeki ve olağanüstü görevlerdeki tanı ve çözümlemeye yardımcı olur.

graphman komutu resmi konteynerlerde mevcuttur, ve çalıştırmak için graph-node docker exec komutunu kullanarak konteynerinize girebilirsiniz. Bunun için bir config.toml dosyası gereklidir.

graphman komutlarının tam dokümantasyonu Graph Düğümü deposunda mevcuttur. Graph Düğümü /docs (dokümanlar) dizini içindeki /docs/graphman.md⁠ dosyasına bakın.

Working with Subgraphs

İndeksleme durum API’si

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.

Tam şemaya buradan⁠ ulaşabilirsiniz.

Endeksleme performansı

İndeksleme sürecinin üç ayrı parçası bulunmaktadır:

• Sağlayıcıdan ilgili olayları getirme
• Uygun işleyicilerle sırayla olayları işleme (bu, durumu sormak için zincire çağrı yapmayı ve depodan veri getirmeyi içerebilir)
• Elde edilen verileri depoya yazma

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.

İndeksleme yavaşlığının yaygın nedenleri:

• Zincirde ilgili olayları bulmak için geçen süre (trace_filtera bağlı olmalarından dolayı, özellikle çağrı işleyicileri yavaş olabilir)
• İşleyicilerin içinde çok fazla eth_calls çağrısı yapmak
• Yürütme sırasında büyük miktarda depolama etkileşimi
• Depoya kaydedilecek büyük miktarda veri
• İşlenecek büyük miktarda olay
• Kalabalık düğümler için yavaş veritabanı bağlantı süresi
• Sağlayıcının zincir başından geriye düşmesi
• Sağlayıcıdan zincir başındaki yeni makbuzların alınmasındaki yavaşlık

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:

• Deterministik başarısızlıklar: Bu, yeniden denemelerle çözülmeyecek hatalardır
• Deterministik olmayan başarısızlıklar: Bunlar, sağlayıcının sorunları veya beklenmedik bir Graph Düğüm hatası gibi nedenlere bağlı olabilir. Deterministik olmayan bir başarısızlık meydana geldiğinde Graph Düğümü, başarısız olan işleyicileri yeniden deneyecek ve zamanla geri çekilecektir.

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.

Blok ve çağrı önbelleği

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.

Örneğin tx makbuzu etkinlik eksikliği gibi bir blok önbellek tutarsızlığı şüphesi varsa:

1. Zincir ismini bulmak için graphman chain list komutunu kullanın.
2. graphman chain check-blocks <CHAIN> by-number <NUMBER> önbellekteki bloğun sağlayıcıyla eşleşip eşleşmediğini kontrol edecek ve eşleşmezse bloğu önbellekten silecektir.
   1. Bir fark varsa, graphman chain truncate <CHAIN> ile tüm önbelleği kırpmak daha güvenli olabilir.
   2. Blok sağlayıcıyla eşleşirse, sorun doğrudan sağlayıcıya karşı hata ayıklanabilir.

Sorgulama sorunları ve hataları

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.

Bununla birlikte, özel bir sorgu düğümü ve replikalarda bile, belirli sorguların yürütülmesi uzun zaman alabilir, bazı durumlarda bellek kullanımını artırabilir ve diğer kullanıcılar için sorgu süresini olumsuz etkileyebilir.

Tek bir “sihirli çözüm” yoktur, ancak yavaş sorguların önlenmesi, teşhisi ve işlenmesi için bir dizi araç bulunmaktadır.

Sorgu önbellekleme

Graph Düğümü, varsayılan olarak GraphQL sorgularını önbelleğe alır, bu da veritabanı yükünü önemli ölçüde azaltabilir. GRAPH_QUERY_CACHE_BLOCKS ve GRAPH_QUERY_CACHE_MAX_MEM ayarlarıyla başka yapılandırmalar da uygulanabilir. Daha fazla bilgi için bu linkteki dokümantasyonu⁠ okuyun.

Sorguların analizi

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.

Diğer durumlarda, tetikleyici sorgu düğümündee yüksek bellek kullanımı olabilir, bu durumda zorluk ilk olarak soruna neden olan sorguyu belirlemektir.

Endeksleyiciler, Graph Düğümünün sorgu günlüklerini işlemek ve özetlemek için qlog⁠ aracını kullanabilirler. Yavaş sorguları tanımlayıp hata ayıklamak amacıyla GRAPH_LOG_QUERY_TIMING parametresi de etkinleştirilebilir.

Yavaş bir sorgu verildiğinde, indeksleyicilerin birkaç seçeneği vardır. Tabii ki, sorunlu sorgunun gönderilme maliyetini önemli ölçüde artırmak için maliyet modelini değiştirebilirler. Bu, o sorgunun sıklığında azalmaya neden olabilir. Ancak, genellikle sorunun temek nedenini çözmez.

Hesabımsı optimizasyon

Varlıkları depolayan veritabanı tablolarının genellikle iki çeşit olduğu görünmektedir: oluşturulduktan sonra hiçbir zaman güncellenmeyen mesela finansal işlemler listesine benzer şeyler saklayan olan ‘işlemimsi’ ve varlıkların çok sık güncellendiği, mesela her işlem kaydedildiğinde değiştirilen finansal hesaplar gibi şeyler saklayan ‘hesabımsı’. Hesabımsı tablolar, birçok varlık sürümünü içermelerine rağmen, nispeten az sayıda farklı varlığa sahip olmasıyla bilinir. Çoğu durumda, böyle bir tabloda farklı varlık sayısı, toplam satır (varlık sürümleri) sayısının %1’ine eşittir

Hesap benzeri (account-like) tablolar, sık sık güncellenen veriler içerdiğinden, PostgreSQL bu tür değişiklikleri depolarken eski satır sürümlerini de bir süre saklar. Ancak, en yeni bloklara ait sürümler genellikle tablonun küçük bir bölümünde bulunur. graph-node, bu yapıyı dikkate alarak sorgular oluşturur ve böylece veriye daha verimli bir şekilde erişilmesini sağlar.

graphman stats show <sgdNNNN> komutu, bir dağıtımda her bir varlık türü/tablosu için, kaç farklı varlık olduğunu ve her tablonun kaç varlık sürümü içerdiğini gösterir. Bu veri, Postgres’in içsel tahminlerine dayalıdır ve bu nedenle zorunlu olarak kesin değildir. Ayrıca bu veri, bir büyüklük derecesi kadar hatalı olabilir. entities sütunundaki bir -1 değeri, Postgres’in tüm satırların farklı bir varlık içerdiğine inandığını gösterir.

Genel olarak, farklı varlıkların sayısının, toplam satır/varlık sürümleri sayısının %1’inden daha az olduğu tablolar, hesap benzeri optimizasyon için iyi adaylardır. graphman stats show çıktısı bir tablonun bu optimizasyondan faydalanabileceğini gösterdiğinde, graphman stats show <sgdNNN> <table> komutunu çalıştırmak tablonun tam bir sayımını yapacaktır. Bu sayım yavaş olabilir ama farklı varlıkların genel varlık sürümlerine oranını tam olarak ölçer.

Bir tablonun hesap benzeri olduğuna karar verildikten sonra, graphman stats account-like <sgdNNN>.<table> komutunu çalıştırmak, bu tabloya yapılan sorgular için hesap benzeri optimizasyonu etkinleştirecektir. Optimizasyon, graphman stats account-like --clear <sgdNNN>.<table> ile tekrar kapatılabilir. Sorgu düğümlerinin optimizasyonun açıldığını veya kapatıldığını fark etmesi 5 dakikayı bulabilir. Optimizasyonu açtıktan sonra, değişikliğin o tablo için sorguları yavaşlatmadığını doğrulamak gerekir. Grafana’yı Postgres’i izlemek için yapılandırdıysanız, pg_stat_activity’de çok sayıda, birkaç saniyeden uzun süren, yavaş sorgular görünecektir. Bu durumda optimizasyonun kapatılması gereklidir.

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⁠.