Integrating External Grafana

Problem Description

Neutree includes a built-in Grafana for monitoring and visualizing system metrics. However, in some cases, you may want to use an existing external Grafana instance to centrally manage monitoring data from multiple systems.

Solution

Step 1: Configure External Grafana for Anonymous Access and UI Embedding

The external Grafana must support anonymous access and UI embedding before Neutree can embed Grafana dashboards into its management interface.

Edit the Grafana configuration file (typically grafana.ini or configured via environment variables).
Enable anonymous access:
```
[auth.anonymous]
enabled = true
```
Allow UI embedding:
```
[security]
allow_embedding = true
```
Restart the Grafana service for the configuration to take effect.

Step 2: Add Neutree Metrics Data Source in External Grafana

Configure the external Grafana data source to point to the Prometheus metrics endpoint configured in Neutree.

Log in to the external Grafana management interface, navigate to Configuration (or Connections in some versions) > Data Sources.
Click Add data source and select Prometheus.
Configure the data source parameters:

Parameter Description
Name Data source name, must be neutree-cluster.
URL The Prometheus service address configured in Neutree, e.g., http://<prometheus-host>:9090.
Click Save & Test to verify the connection.

Parameter	Description
Name	Data source name, must be `neutree-cluster`.
URL	The Prometheus service address configured in Neutree, e.g., `http://<prometheus-host>:9090`.

Step 3: Import Neutree Dashboards

Neutree provides pre-configured Grafana dashboards for displaying key system metrics.

Use the Neutree CLI to obtain the dashboard configuration files.

Execute the following command to export dashboard configuration files:

neutree-cli launch obs-stack --dry-run

The exported dashboard configuration files are located in the neutree-deploy/obs-stack/grafana/dashboards directory:

tree neutree-deploy/obs-stack/grafana/dashboards

Directory structure:

neutree-deploy/obs-stack/grafana/dashboards
├── data_grafana_dashboard.json
├── dcgm_exporter_dashboard.json
├── default_grafana_dashboard.json
├── node_exporter_dashboard.json
├── overview_dashboard.json
├── router_dashboard.json
├── serve_deployment_grafana_dashboard.json
├── serve_grafana_dashboard.json
└── vllm_grafana_dashboard.json

Import the dashboards in Grafana.
1. Log in to the external Grafana management interface, navigate to Dashboards > Import.
2. Click Upload JSON file and select the downloaded dashboard JSON file, or paste the JSON content directly.
3. Complete the following configuration in the import settings:
  - Name: Keep the default dashboard name.
  - Folder: Select or create a folder to organize dashboards (e.g., Default).
4. Click Import to complete the import.
Repeat the above steps to import other dashboard files.

Step 4: Configure External Grafana Address in Neutree

Choose the appropriate method to configure the external Grafana address based on your Neutree deployment method, so that dashboards can be embedded in the Neutree management interface:

For Docker Compose deployments, configure the external Grafana address using launch --grafana-url.
For Kubernetes deployments, refer to the Modifying Monitoring Component Configuration section to update Grafana-related configuration items, disable the built-in Grafana, and configure system.grafana.url to the external Grafana address.

Step 5: Verify Configuration

Access the external Grafana and confirm that Neutree dashboards display data correctly.
Log in to the Neutree management interface and check whether the monitoring page correctly embeds and displays the external Grafana dashboards.