Contributing to DAO Treasury

DAO Treasury was designed to make it easy for less technical users to contribute new dashboards and visuals. This guide explains how to contribute dashboard updates using Grafana’s user interface. Whether you are creating a new dashboard or editing an existing one, this guide will walk you through the steps in simple language.

Table of Contents

  1. Overview

  2. System Patterns and Best Practices

  3. Creating a New Dashboard

  4. Editing an Existing Dashboard

  5. Important Requirements for Dashboard Contributions

  6. Dashboard Tagging Policy

  7. Submitting Your Changes

  8. Additional Notes

Overview

This project provisions dashboards using JSON files loaded by Grafana. The dashboards are defined using the JSON configuration located in the .grafana/provisioning/dashboards/ folder. Community contributions can update existing dashboard visuals or create new ones by using Grafana’s intuitive UI.

System Patterns and Best Practices

DAO Treasury follows a set of repo-wide system patterns to ensure maintainability, extensibility, and professional quality across all code and workflows:

  • Code Organization: Follow the modular package structure, extensible sorting rules, and async stream processing patterns.

  • Testing & Quality: Use pytest and mypy for all new code

  • Documentation: Update Sphinx docs and onboarding instructions as needed.

  • Naming & Formatting: Use Title Case for user-facing strings, and follow consistent naming for files, classes, and functions.

  • Extensibility: Add new features (entities, rules, dashboards, streams) by following established patterns.

  • Security & Logging: Use logging throughout, explicit error handling, and environment-based secrets.

y.stuck? logger

DAO Treasury relies on ypricemagic for price lookups. ypricemagic wraps long-running async calls with a DEBUG logger named y.stuck?. It only emits when the logger is enabled for DEBUG, and logs “module.function still executing after Xm with args … kwargs …” every 5 minutes until completion.

Enable it locally when debugging slow price calls:

import logging

logging.basicConfig(level=logging.INFO)
logging.getLogger("y.stuck?").setLevel(logging.DEBUG)

Creating a New Dashboard

  1. Access the Grafana UI

    • Open Grafana in your web browser.

    • Log in with the Grafana admin credentials you set via GF_SECURITY_ADMIN_USER and GF_SECURITY_ADMIN_PASSWORD.

    • Anonymous access (if enabled) is Viewer-only; use admin creds to create or edit dashboards.

  2. Build Your Dashboard

    • Click on the “+” icon in the sidebar and choose Dashboard.

    • Add new panels by clicking “Add new panel”.

    • Configure each panel using the existing data sources available to you.

  3. Customize Visuals

    • Use the panel editor to choose the type of visualization (graph, table, etc.) and make any necessary styling or data configuration changes.

  4. Save Your Dashboard

    • Click the disk icon or choose Save from the dashboard menu.

    • Provide a name and any additional details as prompted.

  5. Export the Dashboard JSON

    • Open the dashboard settings (click the gear icon).

    • Navigate to the JSON model tab.

    • Click “Export” to download the JSON file that represents your dashboard.

  6. Prepare Your Dashboard for Inclusion in the Repo

Editing an Existing Dashboard

  1. Access the Existing Dashboard

    • Open Grafana in your web browser.

    • Log in with the Grafana admin credentials you set via GF_SECURITY_ADMIN_USER and GF_SECURITY_ADMIN_PASSWORD.

    • Navigate to the existing dashboard you wish to modify.

    • Open the dashboard and click Edit to modify panels, queries, or visual styles.

  2. Make Your Changes

    • Adjust your panels or data queries as needed, using the same tools available when creating a new dashboard.

  3. Export the Updated JSON

    • After editing, open the dashboard settings and go to the JSON model tab.

    • Export the updated JSON file.

  4. Update the Repo

    • Overwrite the existing JSON file in the appropriate folder (for example: .grafana/provisioning/dashboards/treasury/Treasury.json or .grafana/provisioning/dashboards/transactions/Treasury Transactions.json) with your updated version.

Important Requirements for Dashboard Contributions

When contributing new dashboards or updating existing ones, please follow these important requirements to ensure quality and consistency:

  • Descriptions are Required: Every dashboard and every panel must have a clear, specific, and helpful description.

    • The description should explain the purpose, key metrics, and intended use.

    • If the dashboard or panel uses filters (templating variables), describe what each filter does and how it affects the data shown.

    • If a panel uses Data Links, explain what those links do and, if possible, provide an example use case.

    • For longer descriptions, use newlines to break up content for readability.

    • Avoid leaving descriptions blank or using placeholders like “No description” or “TBD”.

Following these requirements helps keep our dashboards user-friendly, well-documented, and easy to maintain!

Credentials and Secrets

  • Do not commit Grafana admin credentials, tokens, or other secrets to the repo.

  • Use environment variables and local secrets management instead.

Dashboard Tagging Policy

  • Purpose: Dashboard tags are used to help users filter and discover dashboards by function, data type, or business process.

  • Tagging Rules:

    • Only use tags that are distinguishing and not universal (do not use tags like “treasury” or “reporting”, they could apply to all dashboards).

    • Tags should be concise, descriptive, and useful for filtering.

    • Example tags: breakdown, revenue, expenses, pnl, monthly, cashflow, operating, assets, balances, historical, unsorted, current, streams, llamapay, payments, transactions, detailed.

    • When adding or editing a dashboard, review the current tags in use and select those that best describe the dashboard’s unique purpose.

    • Update the documentation and tag mapping in docs/dashboards.rst if you introduce new tags.

Submitting Your Changes

  1. Fork or Clone the Repository

    • Ensure you have your fork or a local working copy of the repository.

  2. Create a New Branch

    • For new dashboards, consider naming your branch something like new-dashboard-<short-name>.

    • For edits, use a branch name like update-dashboard-<short-name>.

  3. Commit Your Changes

    • Add the new or updated JSON file(s) to your commit.

    • Include a commit message that clearly explains your changes (e.g., “Added new sales dashboard” or “Updated layout for Treasury dashboard”).

  4. Open a Pull Request (PR)

    • Push your branch to your fork, then open a PR against the main repository.

    • Provide a clear description of what you did and why.

    • Follow any additional PR guidelines as mentioned in the project’s README.

Additional Notes

  • Review Process: Your PR will be reviewed by the maintainers. They may provide feedback or ask for changes before merging.

  • Testing Changes: If possible, preview your dashboard changes in Grafana before exporting and submitting them. This can help catch any visual or configuration issues early.

  • Help and Questions: If you are not too technical or need clarification at any step, please don’t hesitate to ask for help via the project’s communication channels.

Thank you for contributing to the project and helping improve our Grafana dashboards!