parseablehq · praveen5959 · May 16, 2026
diff --git a/content/docs/integrations/visualization/grafana.mdx b/content/docs/integrations/visualization/grafana.mdx
@@ -8,101 +8,115 @@ redirect_from:
   - /integrations/grafana-data-source-configuration
 ---
 
-Parseable data source plugin allows you to query and visualize log data stored in Parseable server, in your Grafana dashboard.
+Parseable data source plugin lets you query and visualize **logs, metrics, and traces** stored in Parseable from your Grafana dashboards, Explore views, and alert rules.
 
 ## Pre-requisites
 
-- Parseable server setup and receiving logs from your application.
-- Grafana installed and running.
+- Parseable server running and receiving telemetry from your application.
+- Grafana `>= 10.0.0` installed and running.
 
 ## Installation
-There are several ways to install the plugin:
+Several ways to install the plugin:
 
-- Grafana UI: Install the plugin from your Grafana instance (Configuration > Data sources > Add Data source). Add Parseable as a data source at the data source configuration page.
+- **Grafana UI**: install from your Grafana instance (Configuration > Data sources > Add Data source > search "Parseable").
 
-- Grafana CLI: Install the plugin using the command grafana-cli plugins install parseable-parseable-datasource. Then restart Grafana.
-
-- Grafana Helm Chart: Install the plugin by modifying the Grafana Chart `values.yaml` file. Add the following lines under `plugins` section.
+- **Grafana CLI**: `grafana-cli plugins install parseable-parseable-datasource`. Restart Grafana.
 
+- **Grafana Helm Chart**: add under the `plugins` section of `values.yaml`:
 
 ```yaml
 plugins:
-  # - digrich-bubblechart-panel
-  # - grafana-clock-panel
-  ## You can also use other plugin download URL, as long as they are valid zip ## files, and specify the name of the plugin after the semicolon. Like this:
-    - https://grafana.com/api/plugins/parseable-parseable-datasource/versions/1.0.2/download;parseable-parseable-datasource
+  - https://grafana.com/api/plugins/parseable-parseable-datasource/versions/2.0.0/download;parseable-parseable-datasource
 ```
 
-Add the following lines under `datasources` section.
+Add under the `datasources` section:
 
 ```yaml
-## Configure grafana datasources
 ## ref: http://docs.grafana.org/administration/provisioning/#datasources
-##
 datasources:
- datasources.yaml:
-   apiVersion: 1
-   datasources:
-   - name: Parseable
-     type: parseable-parseable-datasource
-     url: http://parseable.parseable
-     access: proxy
-     isDefault: true
-     basicAuth: true
-     basicAuthUser: admin
-     secureJsonData:
-        basicAuthPassword: admin    
+  datasources.yaml:
+    apiVersion: 1
+    datasources:
+    - name: Parseable
+      type: parseable-parseable-datasource
+      url: http://parseable.parseable
+      access: proxy
+      isDefault: true
+      basicAuth: true
+      basicAuthUser: admin
+      secureJsonData:
+        basicAuthPassword: admin
 ```
 
-Please remember to update the `url`, `basicAuthUser` and `basicAuthPassword` values with your Parseable server instance details.
+Update `url`, `basicAuthUser`, and `basicAuthPassword` for your instance.
 
-If you're deploying Grafana and would like to install the plugin at the same time, you can use the `GF_INSTALL_PLUGINS` environment variable. For example, `GF_INSTALL_PLUGINS=parseable-parseable-datasource 1.0.2`. Then restart Grafana.
+To install the plugin alongside Grafana itself, set `GF_INSTALL_PLUGINS=parseable-parseable-datasource 2.0.0` and restart Grafana.
 
-If you're provisioning Grafana using [config management tools like Ansible](https://grafana.com/docs/grafana/latest/administration/provisioning/#datasources), you can manage data sources in Grafana by adding YAML configuration files in the `provisioning/datasources` directory. Refer [Grafana documentation](https://grafana.com/docs/grafana/latest/administration/provisioning/#datasources) for more details.
+For Ansible / config-management provisioning, see the [Grafana provisioning docs](https://grafana.com/docs/grafana/latest/administration/provisioning/#datasources).
 
 ## Configuration
-Configure the data source specifying URL and port like `https://demo.parseable.com:443`. Parseable supports basic auth, so toggle the `Basic Auth` option under Auth section and enter the username and password under ` Basic Auth Details` section. If you're using Parseable demo server as the backend, use `admin, admin` as the credentials.
+Set the URL and port of your Parseable server (e.g. `https://<your-parseable-host>:8000`). Parseable uses basic auth — toggle **Basic Auth** under the Auth section and enter the credentials under **Basic Auth Details**.
+
+Click **Save & Test**. If it fails, check credentials and connectivity.
+
+## Query Modes
+
+The plugin auto-selects available editor modes based on the dataset type of the selected stream.
+
+### Logs and Traces — Builder or SQL
+
+- **Builder**: dropdown-driven UI for filters, aggregates, time range, and ordering. Filter values populate from `dataset_stats` with top-5 suggestions and an inline **Show more** for the full set.
+- **SQL** (Code): full SQL editor with autocomplete for fields, types, and operators. Double-quote wrapping for identifiers happens automatically.
 
-Push the `Save & Test` button, if there is an error message, check the credentials and connection.
+### Metrics — Builder or PromQL
 
-## Usage
-Once the plugin is configured with correct Parseable server instance. You can start using it to query and visualize logs. Use the query editor to write your own queries.
+Metrics streams expose Prometheus-compatible endpoints.
 
-### Alerts
-Grafana allows you to set up alerts to continuously monitor your data and notify you when specific conditions are met. It ensures that you are promptly informed about any critical issues, allowing for quick resolution and maintaining system reliability.
+- **Builder**: Prometheus-style UI — pick a metric name, add label matchers (`=`, `!=`, `=~`, `!~`), live PromQL preview of the assembled selector. Label values are scoped to the selected metric and time range.
+- **PromQL** (Code): full PromQL editor with Lezer-based syntax highlighting, completion (metric names, labels, functions), signature help, hover docs, and inline error markers.
 
-#### Setting Up an Alert
+Switching between modes preserves your selection where possible (Builder selectors compose into a valid PromQL selector when you flip to Code).
+
+## Alerts
+
+Grafana alerts work against any of the three dataset types.
+
+- Logs / traces: use **Builder** or **SQL** to produce numeric reducers (`count`, `avg`, `sum`, etc.).
+- Metrics: use **PromQL** with the standard `rate(...)`, `sum by (...)`, threshold patterns.
+
+### Setting Up an Alert
 - Navigate to `your-domain:port/alerting/new/alerting`.
-- Add a unique rule name to identify the alert.
-- Add a query that returns numerical values, as Grafana supports alerts only on numerical data.
+- Add a unique rule name.
+- Add a query that returns numeric values.
 - Specify threshold behavior for the defined rule query.
-- Define the evaluation behavior (e.g., eval frequency, grouping).
+- Define evaluation behavior (frequency, grouping).
 - Save the alert.
 
-#### Managing Alerts
-You can list, update, or delete all the alerts you have created by navigating to `your-domain:port/alerting/list`.
+### Managing Alerts
+List, edit, or delete alerts at `your-domain:port/alerting/list`.
+
+### Notification Channels
+Configure receivers at `your-domain:port/alerting/notifications/receivers/new`. Grafana supports Alertmanager, Email, Slack, Telegram, Webhook, Microsoft Teams, and more.
 
-#### Alert Notification Channels
-Set alert notification channels to receive alerts by navigating to `your-domain:port/alerting/notifications/receivers/new`. Grafana supports multiple integration targets, including Alertmanager, Email, Slack, Telegram, Webhook, Microsoft Teams, etc.
+### Notification Policies
+Route alerts to the right channels at `your-domain:port/alerting/routes`.
 
-#### Notification Policies
-Define notification policies to ensure you receive alerts on your preferred channels by configuring settings in `your-domain:port/alerting/routes`.
+The alerts list page shows current status, last fired/evaluated times, and the rule query results.
 
-You can also check the alert status in the Grafana UI by navigating to the list page. There, you can view the current status of alerts, last fired time, last evaluated time, and rule query results.
+## Mapping Non-Numeric Values for Alerts
 
-## Workarounds for Non-Numeric Data
-In Grafana, alerting is primarily designed for numeric data since it relies on evaluating numerical thresholds and conditions. This means that most alert rules are based on numerical metrics, such as CPU usage, memory consumption, error rates, etc. However, you can get creative with how you process and transform other types of data into numeric forms suitable for alerting.
+This applies to SQL queries on logs / traces. PromQL queries on metrics don't need this — metric values are already numeric, label matchers filter strings, and comparison operators return `0`/`1` directly.
 
-For example, you can map statuses like "OK", "WARN", and "ERROR" to values like 0, 1, and 2 respectively.
+Grafana alert evaluators compare numeric values. Map string statuses to numbers in SQL when alerting on log fields:
 
 ```sql
 SELECT
   ...
   CASE
-    WHEN status = 'OK' THEN 0
-    WHEN status = 'WARN' THEN 1
+    WHEN status = 'OK'    THEN 0
+    WHEN status = 'WARN'  THEN 1
     WHEN status = 'ERROR' THEN 2
-  END as status_value
+  END AS status_value
 FROM
   table_name
 ```