diff --git a/website/docs/development.md b/website/docs/development.md index cd9457c5c6..981241abf9 100644 --- a/website/docs/development.md +++ b/website/docs/development.md @@ -140,3 +140,61 @@ The Grafana VS Code extension allows you to open Grafana dashboards as JSON file - From the editor UI, save the updated dashboard back to the original JSON file see: [grafana-vs-code-extension](https://github.com/grafana/grafana-vs-code-extension) + +## Best Practices + +### Queries involving timestamp columns + +Datetime values are currently stored in columns of type `timestamp`. [This is NOT recommended](https://wiki.postgresql.org/wiki/Don't_Do_This#Don.27t_use_timestamp_.28without_time_zone.29_to_store_UTC_times). + +While [Grafana macros](https://grafana.com/docs/grafana/latest/datasources/postgres/#macros) like `$__timeFilter` & `$__timeGroup` are working PostgreSQL functions like `DATE_TRUNC()` require additional treatment. + +```sql +DATE_TRUNC('day', TIMEZONE('UTC', date)) +``` + +In addition ensure to compare either values with or without time zone. + +### Streaming API data / positions table usage in dashboard queries + +When Streaming API is enabled roughly 1 GB of data is gathered per car and 30.000km. Most of that data (95+ percent) is stored in positions table. For optimal dashboard performance these recommendations should be followed: + +- only query positions table when really needed +- if data in 15 second intervals is sufficient consider excluding streaming data by adding `ideal_battery_range_km IS NOT NULL and car_id = $car_id` as WHERE conditions + +Before opening pull requests please diagnose index usage & query performance by making use of `EXPLAIN ANALYZE`. + +### Enable _pg_stat_statements_ to collect query statistics + +To quickly identify performance bottlenecks we encourage all contributors to enable the pg_stat_statements extension in their instance. For docker based installs you can follow these steps: + +- Enable the pg_stat_statements module + + ```yml + services: + database: + image: postgres:17 + ... + command: postgres -c shared_preload_libraries=pg_stat_statements + ... + ``` + +- Create Extension to enable `pg_stat_statements` view + + ```sql + CREATE EXTENSION IF NOT EXISTS pg_stat_statements; + ``` + +- Identify potentially slow queries (mean_exec_time) + + ```sql + SELECT query, calls, mean_exec_time, total_exec_time FROM pg_stat_statements ORDER BY mean_exec_time DESC LIMIT 10; + ``` + +- Identify frequently executed queries (calls) + + ```sql + SELECT query, calls, mean_exec_time, total_exec_time FROM pg_stat_statements ORDER BY calls DESC LIMIT 10; + ``` + +Additional details about pg_stat_statements can be found here: https://www.postgresql.org/docs/current/pgstatstatements.html