Local Grafana Setup

This guide connects your local Grafana instance to TomoriBot’s production Cloud SQL database and GCP monitoring stack (BigQuery logs, Cloud Logging, Cloud Monitoring).

All access granted here is read-only. The grafana PostgreSQL user has SELECT only, and all GCP IAM roles are viewer-scoped. This setup exists purely for observability: query patterns, memory usage, error rates, and conversation volume — without needing to SSH into anything or touch production state.

Prerequisites

Docker Desktop running
Google Cloud CLI installed and authenticated
Cloud SQL Auth Proxy v2 installed
Terraform has been applied at least once (creates the grafana DB user)

Install Cloud SQL Auth Proxy (Windows)

Invoke-WebRequest `
  -Uri "https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.15.2/cloud-sql-proxy.x64.exe" `
  -OutFile "$env:LOCALAPPDATA\Programs\cloud-sql-proxy.exe"

Add $env:LOCALAPPDATA\Programs to your PATH if it isn’t already.

One-Time Setup

1. Authenticate with GCP

gcloud auth application-default login

This stores credentials that both the Auth Proxy and terraform commands will pick up automatically.

2. Retrieve the generated Grafana DB password

The password is auto-generated by Terraform and stored in GCS state — you never set it manually.

cd terraform/gcp
terraform output -raw grafana_db_password

Copy this value. You’ll need it when configuring the Grafana datasource.

3. Grant read-only permissions to the Grafana DB user

This only needs to be done once after the first terraform apply that creates the grafana user. Connect through the proxy (see step 4 below to start it), then run as postgres:

psql "host=localhost port=5433 dbname=tomoribot user=postgres"

GRANT CONNECT ON DATABASE tomoribot TO grafana;
GRANT USAGE ON SCHEMA public TO grafana;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO grafana;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO grafana;

Daily Workflow

4. Start the Cloud SQL Auth Proxy

Run this in a separate terminal and keep it open while using Grafana. Port 5433 is used to avoid conflicting with the local Docker postgres on 5432.

cloud-sql-proxy tomoribot-vertex:us-central1:tomoribot-db --port=5433

You should see Ready for new connections before proceeding.

5. Start Grafana

docker compose -f docker-compose.yaml -f docker-compose.monitor.yaml up

Open Grafana at http://localhost:3000.

Configure the Cloud SQL Datasource (one-time, in Grafana UI)

The local Docker postgres datasource is provisioned automatically. The Cloud SQL datasource needs to be added manually once.

Go to Connections → Data Sources → Add new data source → PostgreSQL and fill in:

Field	Value
Host	`host.docker.internal:5433`
Database	`tomoribot`
User	`grafana`
Password	(value from `terraform output -raw grafana_db_password`)
TLS/SSL Mode	`disable`

Click Save & Test — it should return a green confirmation.

host.docker.internal is Docker Desktop’s magic hostname that resolves to your PC from inside a container. The Auth Proxy running on your PC at port 5433 is reachable there.

Why This Exists (for open-repo readers)

TomoriBot runs as a persistent Cloud Run service. The monitoring setup provides:

Query volume and latency — via Cloud SQL slow query logs and direct table counts
Memory and error trends — via Cloud Monitoring and Cloud Logging (BigQuery export)
Conversation and tool usage patterns — direct SQL queries against the tomoribot DB

The grafana-monitor GCP service account used here has no write access to any resource. The grafana database user can only SELECT — it cannot INSERT, UPDATE, DELETE, or access schemas outside public. Terraform manages both the IAM and the DB user; see terraform/gcp/monitoring.tf and terraform/gcp/cloud-sql.tf.