Add Grafana Guide, fixes #33

apps/docs/guides/grafana.mdx

@@ -0,0 +1,119 @@
+---
+title: Grafana
+sidebarTitle: Grafana
+description: Step-by-step guide to setup Trench with Grafana dashboard
+---
+
+# Setting up Grafana with Trench
+
+This guide will walk you through setting up Grafana with Trench to visualize your analytics data.
+
+## Prerequisites
+- Docker installed
+- Trench running locally follow [Self-host Quickstart](/quickstart)
+
+## Setup Steps
+
+<Steps>
+
+<Step title="Run Grafana Container">
+
+Run the following command to start Grafana. This will make Grafana available at http://localhost:3001 and connect it to your Trench installation.
+
+
+
+```bash
+docker run -d \
+  --name grafana-trench \
+  --network trench_app-network \
+  -p 3001:3000 \
+  grafana/grafana:latest
+```
+
+</Step>
+
+<Step title="Login to Grafana, use default credentials:">
+
+- Username: `admin`
+- Password: `admin`
+
+<img src="/images/grafana-login.jpeg" alt="Grafana Login" />
+
+</Step>
+
+<Step title="Install the ClickHouse plugin in Grafana.">
+
+Go to plugins section and install the ClickHouse plugin.
+
+<img src="/images/grafana-plugin-install.png" alt="Grafana Install ClickHouse" />
+
+</Step>
+
+<Step title="Configure ClickHouse Data Source">
+
+1. Go to Data Sources section and click on `Add data source`.
+2. Select `ClickHouse` as the data source.
+3. Configure the data source with these settings:
+   - Host: `clickhouse`
+   - Port: `8123`
+   - Protocol: `http`
+   - Username: `user`
+   - Password: `password`
+
+
+<img src="/images/grafana-config-datasource.png" alt="Grafana ClickHouse Config" />
+
+</Step>
+
+<Step title="Setup Grafana Dashboard">
+
+  You can import the pre-built dashboard using the JSON configuration provided. Download the [JSON configuration](https://raw.githubusercontent.com/FrigadeHQ/trench/refs/heads/main/apps/docs/json/grafana-dashboard.json) and import it into Grafana.
+
+  The Dashboard includes:
+  - Unique pageviews over time
+  - Time series visualization
+  - 6-hour time window by default
+
+</Step>
+
+<Step title="Test Setup">
+
+Here's an example of sending pageview data:
+
+```bash
+curl --location 'http://localhost:4000/events' \
+--header 'Authorization: Bearer public-d613be4e-di03-4b02-9058-70aa4j04ff28' \
+--header 'Content-Type: application/json' \
+--data '{
+"events": [
+    {
+      "userId": "550e8400-e29b-41d4-a716-4466554400",
+      "type": "track",
+      "event": "$pageview",
+      "properties": {
+        "totalAccounts": 4,
+        "country": "Denmark"
+      }
+    }
+  ]
+}'
+```
+
+</Step>
+
+<Step title="View the dashboard">
+
+New pageviews should be visible in the dashboard.
+
+<img src="/images/grafana-dashboard.png" alt="Grafana Pageviews" />
+
+#### Next Steps
+- Customize the dashboard based on your needs
+- Add more panels for different metrics
+- Set up alerts
+
+</Step>
+
+</Steps>
+
+

apps/docs/json/grafana-dashboard.json

@@ -0,0 +1,214 @@
+{
+  "__inputs": [
+    {
+      "name": "DS_GRAFANA-CLICKHOUSE-DATASOURCE",
+      "label": "grafana-clickhouse-datasource",
+      "description": "",
+      "type": "datasource",
+      "pluginId": "grafana-clickhouse-datasource",
+      "pluginName": "ClickHouse"
+    }
+  ],
+  "__elements": {},
+  "__requires": [
+    {
+      "type": "grafana",
+      "id": "grafana",
+      "name": "Grafana",
+      "version": "11.4.0"
+    },
+    {
+      "type": "datasource",
+      "id": "grafana-clickhouse-datasource",
+      "name": "ClickHouse",
+      "version": "4.5.1"
+    },
+    {
+      "type": "panel",
+      "id": "timeseries",
+      "name": "Time series",
+      "version": ""
+    }
+  ],
+  "annotations": {
+    "list": [
+      {
+        "builtIn": 1,
+        "datasource": {
+          "type": "grafana",
+          "uid": "-- Grafana --"
+        },
+        "enable": true,
+        "hide": true,
+        "iconColor": "rgba(0, 211, 255, 1)",
+        "name": "Annotations & Alerts",
+        "type": "dashboard"
+      }
+    ]
+  },
+  "editable": true,
+  "fiscalYearStartMonth": 0,
+  "graphTooltip": 0,
+  "id": null,
+  "links": [],
+  "panels": [
+    {
+      "datasource": {
+        "type": "grafana-clickhouse-datasource",
+        "uid": "${DS_GRAFANA-CLICKHOUSE-DATASOURCE}"
+      },
+      "fieldConfig": {
+        "defaults": {
+          "color": {
+            "mode": "palette-classic"
+          },
+          "custom": {
+            "axisBorderShow": false,
+            "axisCenteredZero": false,
+            "axisColorMode": "text",
+            "axisLabel": "",
+            "axisPlacement": "auto",
+            "barAlignment": 0,
+            "barWidthFactor": 0.6,
+            "drawStyle": "line",
+            "fillOpacity": 0,
+            "gradientMode": "none",
+            "hideFrom": {
+              "legend": false,
+              "tooltip": false,
+              "viz": false
+            },
+            "insertNulls": false,
+            "lineInterpolation": "linear",
+            "lineWidth": 1,
+            "pointSize": 5,
+            "scaleDistribution": {
+              "type": "linear"
+            },
+            "showPoints": "auto",
+            "spanNulls": false,
+            "stacking": {
+              "group": "A",
+              "mode": "none"
+            },
+            "thresholdsStyle": {
+              "mode": "off"
+            }
+          },
+          "mappings": [],
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              {
+                "color": "green",
+                "value": null
+              },
+              {
+                "color": "red",
+                "value": 80
+              }
+            ]
+          }
+        },
+        "overrides": []
+      },
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 0,
+        "y": 0
+      },
+      "id": 1,
+      "options": {
+        "legend": {
+          "calcs": [],
+          "displayMode": "list",
+          "placement": "bottom",
+          "showLegend": true
+        },
+        "tooltip": {
+          "mode": "single",
+          "sort": "none"
+        }
+      },
+      "pluginVersion": "11.4.0",
+      "targets": [
+        {
+          "builderOptions": {
+            "aggregates": [],
+            "columns": [
+              {
+                "alias": "user_id",
+                "custom": false,
+                "name": "user_id",
+                "type": "String"
+              }
+            ],
+            "database": "default",
+            "filters": [],
+            "groupBy": [
+              "user_id"
+            ],
+            "limit": 1000,
+            "meta": {},
+            "mode": "aggregate",
+            "orderBy": [],
+            "queryType": "table",
+            "table": "events"
+          },
+          "datasource": {
+            "type": "grafana-clickhouse-datasource",
+            "uid": "${DS_GRAFANA-CLICKHOUSE-DATASOURCE}"
+          },
+          "editorType": "sql",
+          "format": 1,
+          "meta": {
+            "builderOptions": {
+              "aggregates": [],
+              "columns": [
+                {
+                  "alias": "user_id",
+                  "custom": false,
+                  "name": "user_id",
+                  "type": "String"
+                }
+              ],
+              "database": "default",
+              "filters": [],
+              "groupBy": [
+                "user_id"
+              ],
+              "limit": 1000,
+              "meta": {},
+              "mode": "aggregate",
+              "orderBy": [],
+              "queryType": "table",
+              "table": "events"
+            }
+          },
+          "pluginVersion": "4.5.1",
+          "queryType": "table",
+          "rawSql": "SELECT \ntoStartOfHour(timestamp) as time,\ncount(DISTINCT user_id) as unique_pageviews\nFROM \"default\".\"events\" \nwhere event = '$pageview'\nGROUP BY time\norder by time",
+          "refId": "A"
+        }
+      ],
+      "title": "Panel Title",
+      "type": "timeseries"
+    }
+  ],
+  "schemaVersion": 40,
+  "tags": [],
+  "templating": {
+    "list": []
+  },
+  "time": {
+    "from": "now-6h",
+    "to": "now"
+  },
+  "timepicker": {},
+  "timezone": "browser",
+  "title": "New dashboard",
+  "uid": "ee6c3vm4x4dtsb",
+  "version": 2,
+  "weekStart": ""
+}

apps/docs/mint.json

@@ -47,6 +47,10 @@
       "group": "Overview",
       "pages": ["introduction", "quickstart", "cloud-quickstart", "contributing"]
     },
+    {
+      "group": "Guides",
+      "pages": ["guides/grafana"]
+    },
     {
       "group": "SDK and API",
       "pages": ["client", "api-reference/overview"]