# Grafana & Elasticsearch Know-How

## 1. Elasticsearch Datasource Provisioning (YAML)

Quando si configura il datasource Elasticsearch via provisioning (es. `datasource.yml`), utilizzare il blocco `jsonData` per le configurazioni specifiche.

**Campi Chiave in `jsonData`:**

*   **`index`**: Definisce il pattern dell'indice (es. `geodata`, `[logs-]YYYY.MM.DD`). **Nota:** Usare questo invece del campo top-level `database` che è deprecato.
*   **`timeField`**: Il nome del campo timestamp (es. `timestamp` o `@timestamp`).
*   **`esVersion`**: La versione del cluster Elasticsearch (es. `7.10.0`).
*   **`interval`**: L'intervallo di tempo predefinito per i raggruppamenti (es. `Daily`, `Hourly`, `1m`). **Attenzione:** Non impostare a `None` o valori non validi, altrimenti Grafana potrebbe crashare all'avvio.
*   **`maxConcurrentShardRequests`**: Limita le richieste concorrenti agli shard.

**Esempio `datasource.yml`:**

```yaml
apiVersion: 1

datasources:
  - name: Elasticsearch
    type: elasticsearch
    uid: elasticsearch-uid
    access: proxy
    url: http://elasticsearch:9200
    isDefault: true
    jsonData:
      index: "geodata"
      timeField: "timestamp"
      esVersion: "7.10.0"
      interval: "Daily"
      maxConcurrentShardRequests: 5
```

## 2. Grafana Geomap Panel con Elasticsearch

Per visualizzare punti GeoJSON da Elasticsearch, si utilizza l'aggregazione **Geohash Grid**.

**Configurazione Query:**

1.  **Query Type:** `Metric`.
2.  **Metric:** `Count` (o altra metrica).
3.  **Group By:**
    *   Type: `Geohash Grid`
    *   Field: Il campo mappato come `geo_point` (es. `location`).
    *   Precision: Livello di dettaglio (es. `5`).

**Configurazione Pannello (JSON Model):**

*   **`geohashField`**: Nella configurazione del layer, specifica quale campo contiene l'hash. Solitamente è `key` quando si usa l'aggregazione.
*   **`location.mode`**: Deve essere impostato su `geohash`.

**Troubleshooting "Mappa Vuota":**

*   **Precisione:** Se troppo alta (es. 12) su una mappa zoomata indietro, i punti potrebbero non apparire.
*   **Mapping:** Il campo in Elasticsearch DEVE essere di tipo `geo_point`.
*   **Geohash Field:** Assicurarsi che nel pannello Geomap, sotto "Layer" -> "Location", il "Geohash field" sia impostato correttamente (spesso `key`).

**Esempio JSON Dashboard (Snippet):**

```json
{
  "type": "geomap",
  "targets": [
    {
      "bucketAggs": [
        {
          "type": "geohash_grid",
          "field": "location",
          "settings": { "precision": "5" }
        }
      ],
      "timeField": "timestamp"
    }
  ],
  "options": {
    "layers": [
      {
        "location": {
          "mode": "geohash",
          "geohashField": "key"
        }
      }
    ]
  }
}
```

## 3. Troubleshooting & Best Practices

*   **Controllare sempre i log:** Prima di terminare un task o assumere che una fix funzioni, controllare sempre i log del container (es. `docker compose logs grafana`). Errori di provisioning o crash all'avvio sono spesso visibili solo lì.
*   **Riavvio Container:** Le modifiche ai file di provisioning (`datasource.yml`, `dashboard.yml`) richiedono spesso il riavvio del container Grafana (`docker compose restart grafana`) per essere applicate.
*   **Validazione YAML:** Assicurarsi che i file YAML siano validi e che l'indentazione sia corretta.
*   **Datasource UID:** Se si riscontrano errori "Datasource provisioning error: data source not found", provare a rimuovere il campo `uid` dal file YAML del datasource e fare riferimento al datasource tramite il suo `name` (stringa) nel JSON della dashboard, invece che tramite l'oggetto `{ type: ..., uid: ... }`.