How openbb-finance/openbb-metricsv2 works
Project type and purpose
• This is a small open-source metrics-collection tool written in Python.
• It runs as a scheduled GitHub Action (cron) every 12 hours to fetch usage and engagement metrics from external services (YouTube, Discord, PyPI, etc.) and writes them into a JSON file (metrics.json).
• There is no user-facing frontend; it’s essentially a lightweight ETL/data-ingest pipeline triggered by GitHub Actions.
File structure
• Top level:
– .github/workflows/metrics-runner.yml → defines the scheduled GitHub Action
– main.py → orchestrator script
– metrics.json → target output file
– pyproject.toml / requirements.txt → dependency & packaging info
• utilities/ package:
– config.py → loads environment variables (API keys, tokens) from .env
– helpers.py → contains the actual functions that call each external API and transform the responses
README for additional insights
• Describes setup (pip install, .env) and execution (python main.py)
• Confirms the schedule (GitHub Action runs every 12 hours)
• Identifies the external platforms (YouTube, Discord, PyPI, …)
a. Main components:
– Scheduler (GitHub Actions cron job)
– Runner Environment (the VM/container that executes the workflow)
– Python Application:
• Entry point: main.py
• Configuration layer: utilities/config.py
• Metric collectors: functions in utilities/helpers.py
– External Services/APIs (YouTube Data API, Discord API, PyPI API, etc.)
– Output Store: metrics.json in the repo (or artifact storage)
b. Relationships & data flows:
1. GitHub Actions scheduler triggers at 00:00 and 12:00 UTC
2. Action spins up a runner environment, checks out the code
3. Runner loads environment variables from .env via config.py
4. main.py calls helper functions to fetch from each API
5. Responses are aggregated and written to metrics.json
6. (Optionally) the workflow commits/pushes the updated metrics.json back to the repo
c. Architectural patterns & principles:
– Modular utilities (config vs. helpers vs. orchestrator)
– Single responsibility: each helper method targets one external service
– ETL-style pipeline: Extract (API calls), Transform (normalize), Load (write JSON)
d. Key technologies/frameworks:
– Python 3.x (entry point main.py)
– dotenv or python-decouple (in utilities/config.py)
– requests or specialized SDKs (in utilities/helpers.py)
– GitHub Actions (YAML workflow)
– JSON output (metrics.json)