grafana-POC/.github/copilot-instructions.md

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:

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):

{
  "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: ... }.