/hedera-stats

Scripts and tools for hedera stats calculations

Primary LanguagePLpgSQLApache License 2.0Apache-2.0

Hedera Stats: Shared Ecosystem and Network Insights

Hedera Stats provides quantitative statistical measurements for the Hedera network, leveraging open-source methodologies, Hedera mirror node data, third-party data sources, and Hgraph's GraphQL API. These statistics include network performance metrics, NFT analytics, account activities, and economic indicators, enabling transparent and consistent analysis of the Hedera ecosystem.

📖 View Full Documentation →

Getting Started

Prerequisites

  • Hedera Mirror Node or access to Hgraph's GraphQL API
  • Prometheus (promtool) for avg_time_to_consensus (view docs)
  • PostgreSQL database needed for SQL script execution (view docs)
  • DeFiLlama API for decentralized finance metrics (view docs).

Installation

Clone this repository:

git clone https://github.com/hgraph-io/hedera-stats.git
cd hedera-stats

Install Prometheus CLI (promtool):

curl -L -O https://github.com/prometheus/prometheus/releases/download/v3.1.0/prometheus-3.1.0.linux-amd64.tar.gz
tar -xvf prometheus-3.1.0.linux-amd64.tar.gz
# one way to add the tool to the PATH
cp prometheus-3.1.0.linux-amd64/promtool /usr/bin

Initial Configuration

Set up your database:

  • Execute src/up.sql to create necessary database schema and tables.
  • Load initial data using SQL scripts from the src/jobs directory.

Configure environment variables (example .env):

DATABASE_URL="postgresql://user:password@localhost:5432/hedera_stats"
HGRAPH_API_KEY="your_api_key"

Schedule incremental updates:

crontab -e
1 * * * * cd /path/to/hedera-stats/src/time-to-consensus && bash ./run.sh >> ./.raw/cron.log 2>&1

Repository Structure

hedera-stats/
├── src/
│   ├── dashboard/             # SQL for Grafana dashboards & Grafana template
│   ├── helpers/               # Helper SQL functions
│   ├── jobs/                  # Incremental data update scripts
│   ├── metrics/               # SQL queries for metrics
│   └── up.sql                 # Initial database schema setup
├── LICENSE
└── README.md

Available Metrics & Usage

Metrics categories include:

  • Accounts & Network Participants
  • NFT-specific Metrics
  • Network Performance & Economic Metrics

View all metrics & documentation →

Usage Example: Custom Grafana Dashboard

Use Grafana to visualize metrics:

  • Import Hedera_KPI_Dashboard.json from src/dashboard.
  • SQL queries provided in the same directory serve as data sources.

Usage Example: Fetching Metrics via GraphQL API

Query available metrics dynamically via GraphQL API (test in our developer playground):

query AvailableMetrics {
  ecosystem_metric(distinct_on: name) {
    name
    description {
      description
      methodology
    }
  }
}

Troubleshooting & FAQs

Missing data or discrepancies?

  • Verify you're querying the correct API endpoint:
    • Staging environment (hgraph.dev) may have incomplete data.
    • Production endpoint (hgraph.io) requires an API key.

Improve query performance:

  • Use broader granularity (day/month) for extensive periods.
  • Limit result size with limit and order_by.
  • Cache frequently accessed data.

Additional Resources

Contribution Guidelines

We welcome contributions!

  1. Fork this repository.
  2. Create your feature branch (git checkout -b feature/new-metric).
  3. Commit changes (git commit -am 'Add new metric').
  4. Push to the branch (git push origin feature/new-metric).
  5. Submit a Pull Request detailing your changes.

License

Apache License 2.0