diff --git a/manual/english/Integration/Grafana.md b/manual/english/Integration/Grafana.md new file mode 100644 index 0000000000..b400bb3c70 --- /dev/null +++ b/manual/english/Integration/Grafana.md @@ -0,0 +1,100 @@ +# Integration with Grafana + +> NOTE: The integration with Grafana requires [Manticore Buddy](../Installation/Manticore_Buddy.md). If it doesn't work, make sure Buddy is installed. + +[Grafana](https://grafana.com/) is an open-source data visualization and monitoring platform that allows you to create interactive dashboards and charts. Manticore Search integrates seamlessly with Grafana using the default MySQL connector, enabling you to visualize search data, monitor performance metrics, and analyze trends in real-time. + +Currently, Grafana versions 10.0-12.2 are tested and supported. + +## Prerequisites + +Before integrating Manticore Search with Grafana, ensure that: + +1. Manticore Search (version 6.2.0 or later) is properly installed and configured on your server. Refer to the [official Manticore Search installation guide](../Installation/Installation.md) for assistance. +2. Grafana is set up on your system. Follow the [official Grafana installation guide](https://grafana.com/docs/grafana/latest/setup-grafana/installation/) for installation instructions. + +## Connecting Manticore Search to Grafana + +To connect Manticore Search to Grafana: + +1. Log in to your Grafana dashboard and click on "Configuration" (the gear icon) in the left sidebar. +2. Select "Data Sources" and click on "Add data source." +3. Choose "MySQL" from the list of available data sources. +4. In the settings page, provide the following details: + - **Name**: A name for the data source (e.g., "Manticore Search") + - **Host**: The hostname or IP address of your Manticore Search server (with MySQL port, default: `localhost:9306`) + - **Database**: Leave empty or specify your database name + - **User**: The username with access to Manticore Search (default: `root`) + - **Password**: The password for the specified user (default: empty) +5. Click on "Save & Test" to verify the connection. + +## Creating Visualizations and Dashboards + +After connecting Manticore Search to Grafana, you can create dashboards and visualizations: + +1. In the Grafana dashboard, click on the "+" icon in the left sidebar and select "New dashboard." +2. Click on the "Add visualization" button to start configuring your chart. +3. Choose the Manticore Search data source that you connected via the MySQL connector. +4. Select the type of chart you want to create (e.g., Time Series, Bar chart, Candlestick, Pie chart). +5. Use Grafana's query builder or write an SQL query to fetch data from your Manticore Search tables. +6. Customize the chart's appearance, labels, and other settings as needed. +7. Click "Apply" to save your visualization to the dashboard. + +## Example Use Case + +Here's a simple example using time-series data. First, create a table and load sample data: + +```sql +CREATE TABLE btc_usd_trading ( + id bigint, + time timestamp, + open float, + high float, + low float, + close float +); +``` + +Load the data: +```bash +curl -sSL https://gist.githubusercontent.com/donhardman/df109ba6c5e690f73198b95f3768e73f/raw/0fab3aee69d7007fad012f4e97f38901a64831fb/btc_usd_trading.sql | mysql -h0 -P9306 +``` + +In Grafana, you can create: +- **Time Series chart**: Visualize price changes over time +- **Candlestick chart**: Display open, high, low, close values for financial data +- **Aggregation charts**: Use COUNT, AVG, MAX, MIN functions + +Example queries: +```sql +-- Time series query +SELECT time, close FROM btc_usd_trading ORDER BY time; + +-- Aggregation query +SELECT DATE(time) as date, AVG(close) as avg_price +FROM btc_usd_trading +GROUP BY date +ORDER BY date; +``` + +## Supported Features + +When working with Manticore Search through Grafana, you can: + +- Execute SQL queries against Manticore Search tables +- Use aggregation functions: COUNT, AVG, MAX, MIN +- Apply GROUP BY and ORDER BY operations +- Filter data with WHERE clauses +- Access table metadata via `information_schema.tables` +- Create various visualization types supported by Grafana + +## Limitations + +- Some advanced MySQL features may not be available when working with Manticore Search through Grafana. +- Only features supported by Manticore Search are available. Refer to the [SQL reference](../Searching/Full_text_matching/Basic_usage.md) for details. + +## References + +For more information and detailed tutorials: +- [Grafana integration blog post](https://manticoresearch.com/blog/manticoresearch-grafana-integration/) +- [Official Grafana documentation](https://grafana.com/docs/) diff --git a/test/clt-tests/integrations/grafana/test-integrations-check-grafana-versions.rec b/test/clt-tests/integrations/grafana/test-integrations-check-grafana-versions.rec index 7b80cf6720..e7b5d84856 100644 --- a/test/clt-tests/integrations/grafana/test-integrations-check-grafana-versions.rec +++ b/test/clt-tests/integrations/grafana/test-integrations-check-grafana-versions.rec @@ -76,35 +76,76 @@ Using tested versions: 12.0 12.1 12.2 +––– comment ––– +If new versions are detected, test will fail with detailed instructions: +- Lists files that need to be updated in manticoresearch repo +- Shows where to add new version tests +- Reminds to update documentation in manual/ +- Reminds to update website in site repo (manticoresearch-grafana-integration blog post) ––– input ––– bash << 'SCRIPT' -# Check blog post for Grafana version -echo "Checking Grafana version in blog post..." +# Check documentation versions for Grafana +echo "Checking Grafana version references in documentation..." echo "" # Must match LATEST_TESTED_VERSION above GRAFANA_LATEST="12.2" +# 1. Check manual documentation (local file mounted via workflow) +echo "=== Checking manual documentation ===" +GRAFANA_MANUAL="/manual/english/Integration/Grafana.md" +if [ -f "$GRAFANA_MANUAL" ]; then + echo "✓ Checking $GRAFANA_MANUAL" + FOUND_VERSION=$(grep -o "versions [0-9.–-]* are" "$GRAFANA_MANUAL" | head -1) + if echo "$FOUND_VERSION" | grep -q "${GRAFANA_LATEST}"; then + echo "✅ Manual: $FOUND_VERSION" + else + echo "❌ Manual must contain version ${GRAFANA_LATEST}" >&2 + echo " Current: $FOUND_VERSION" >&2 + echo " Update to: versions 10.0-${GRAFANA_LATEST} are tested and supported" >&2 + exit 1 + fi +else + echo "❌ Manual not found at $GRAFANA_MANUAL" >&2 + echo "Manual must be mounted via workflow: -v \$(pwd)/manual:/manual" >&2 + exit 1 +fi + +echo "" echo "=== Checking website blog post ===" +# 2. Check website blog post BLOG_URL="https://manticoresearch.com/blog/manticoresearch-grafana-integration/" echo "✓ Fetching $BLOG_URL" -BLOG_CONTENT=$(curl -s "$BLOG_URL") +# Try curl first, fallback to wget +if command -v curl > /dev/null 2>&1; then + BLOG_CONTENT=$(curl -s "$BLOG_URL") +elif command -v wget > /dev/null 2>&1; then + BLOG_CONTENT=$(wget -qO- "$BLOG_URL") +else + echo "❌ Neither curl nor wget available" >&2 + exit 1 +fi if [ -z "$BLOG_CONTENT" ]; then echo "⚠️ WARNING: Blog fetch failed - skipping" >&2 -elif echo "$BLOG_CONTENT" | grep -q "Grafana versions.*${GRAFANA_LATEST}"; then - FOUND_FORMAT=$(echo "$BLOG_CONTENT" | grep -o "Grafana versions [0-9.-]*${GRAFANA_LATEST}" | head -1) - echo "✅ Blog: $FOUND_FORMAT" +elif echo "$BLOG_CONTENT" | grep -E "compatible with Grafana versions.*(up to |-|–)${GRAFANA_LATEST}" > /dev/null; then + echo "✅ Blog: contains ${GRAFANA_LATEST}" else - BLOG_VERSION=$(echo "$BLOG_CONTENT" | grep -o "Grafana versions [0-9.-]*" | head -1) - echo "⚠️ WARNING: Blog does NOT contain ${GRAFANA_LATEST}" >&2 - echo " Found: $BLOG_VERSION" >&2 - echo " Expected: Grafana versions 10.0-${GRAFANA_LATEST}" >&2 + BLOG_VERSION=$(echo "$BLOG_CONTENT" | grep -o "compatible with Grafana versions [0-9.–-]* " | head -1 | sed 's/compatible with Grafana versions //') + echo "⚠️ WARNING: Blog does NOT contain ${GRAFANA_LATEST} (found: ${BLOG_VERSION})" >&2 + echo " Update: site/content/english/blog/manticoresearch-grafana-integration/index.md" >&2 fi + +echo "" +echo "✅ Documentation validation complete" SCRIPT ––– output ––– -Checking Grafana version in blog post... +Checking Grafana version references in documentation... +=== Checking manual documentation === +✓ Checking /manual/english/Integration/Grafana.md +✅ Manual: versions 10.0-12.2 are === Checking website blog post === ✓ Fetching https://manticoresearch.com/blog/manticoresearch-grafana-integration/ -✅ Blog: Grafana versions 10.0-12.2 +✅ Blog: contains 12.2 +✅ Documentation validation complete