diff --git a/apps/docs/guides/grafana.mdx b/apps/docs/guides/grafana.mdx new file mode 100644 index 0000000..2a7497a --- /dev/null +++ b/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 + + + + + +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 +``` + + + + + +- Username: `admin` +- Password: `admin` + +Grafana Login + + + + + +Go to plugins section and install the ClickHouse plugin. + +Grafana Install ClickHouse + + + + + +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` + + +Grafana ClickHouse Config + + + + + + 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 + + + + + +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" + } + } + ] +}' +``` + + + + + +New pageviews should be visible in the dashboard. + +Grafana Pageviews + +#### Next Steps +- Customize the dashboard based on your needs +- Add more panels for different metrics +- Set up alerts + + + + + + diff --git a/apps/docs/images/grafana-config-datasource.png b/apps/docs/images/grafana-config-datasource.png new file mode 100644 index 0000000..fab7e9f Binary files /dev/null and b/apps/docs/images/grafana-config-datasource.png differ diff --git a/apps/docs/images/grafana-dashboard.png b/apps/docs/images/grafana-dashboard.png new file mode 100644 index 0000000..313efc8 Binary files /dev/null and b/apps/docs/images/grafana-dashboard.png differ diff --git a/apps/docs/images/grafana-login.jpeg b/apps/docs/images/grafana-login.jpeg new file mode 100644 index 0000000..3f6ce32 Binary files /dev/null and b/apps/docs/images/grafana-login.jpeg differ diff --git a/apps/docs/images/grafana-plugin-install.png b/apps/docs/images/grafana-plugin-install.png new file mode 100644 index 0000000..60c609f Binary files /dev/null and b/apps/docs/images/grafana-plugin-install.png differ diff --git a/apps/docs/json/grafana-dashboard.json b/apps/docs/json/grafana-dashboard.json new file mode 100644 index 0000000..e9718c3 --- /dev/null +++ b/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": "" +} diff --git a/apps/docs/mint.json b/apps/docs/mint.json index 07bab43..f9ec124 100644 --- a/apps/docs/mint.json +++ b/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"]