MQTT Verilerini Grafana'da MQTT Data Source ile Görselleştirin

Grafana bir MQTT broker'a doğrudan abone olabilir. Resmî MQTT data source eklentisi (grafana-mqtt-datasource) ile her panel sorgusu bir topic aboneliğidir ve yeni mesajlar yayınlandıktan kısa süre sonra dashboard'da görünür; arada veritabanı yoktur. Sensör verisi için canlı bir gauge veya grafik çıkarmanın en hızlı yolu budur.

Bu eğitimde eklentiyi kuracak, TLS ile bir broker'a bağlayacak, test telemetrisi yayınlayacak ve canlı paneller oluşturacağız. Ayrıca çoğu kişinin geç fark ettiği konuyu da ele alıyoruz: data source veriyi akıtır, saklamaz.

MQTT data source nasıl çalışır

Eklenti Grafana sunucusunun içinde çalışır. Bir panel veri istediğinde backend bir MQTT bağlantısı açar (data source başına bir tane), sorgudaki topic'e abone olur ve her mesajı Grafana'nın WebSocket tabanlı akış kanalı olan Grafana Live üzerinden tarayıcıya iletir.

MQTT istemcisi Grafana sunucusu olduğu için broker'ın Grafana'nın çalıştığı yerden erişilebilir olması gerekir ve kimlik bilgileri tarayıcıda değil, data source ayarlarında durur.

Grafana'yı eklentiyle çalıştırın

En hızlı kurulum Docker'dır. Eklenti açılışta Grafana eklenti kataloğundan kurulur:

docker run -d --name grafana -p 3000:3000 \
  -e GF_INSTALL_PLUGINS=grafana-mqtt-datasource \
  grafana/grafana:latest

Güncel Grafana sürümlerinde aynı işi yapmanın yeni yolu GF_PLUGINS_PREINSTALL=grafana-mqtt-datasource değişkenidir. Mevcut bir kurulumda CLI'ı kullanın ve servisi yeniden başlatın:

grafana cli plugins install grafana-mqtt-datasource
sudo systemctl restart grafana-server

http://localhost:3000 adresini açın, giriş yapın (varsayılan admin / admin, ardından değiştirin) ve Connections → Data sources → Add data source → MQTT yolunu izleyin.

Data source'u broker'a bağlayın

Ayarlar sayfası bir URI, isteğe bağlı kimlik bilgileri ve TLS seçenekleri ister:

• URI: hızlı ve şifresiz bir test için tcp://broker.connectmq.com:1883, TLS için tls://broker.connectmq.com:8883 (bazı eklenti sürümleri ssl:// de kabul eder). Demo dışındaki her şey için TLS kullanın.
• Username / Password: broker'ınızın kimlik bilgileri. Topic bazlı ACL'lerle bu kullanıcıya yalnızca dashboard'ların ihtiyaç duyduğu topic'lerde okuma izni verin.
• TLS: broker'ınız özel bir CA kullanıyorsa "With CA Cert" seçeneğini, mTLS için de istemci sertifikası kimlik doğrulamasını açın.

Save & test'e tıklayın. Başarılı bir test, Grafana sunucusunun bir MQTT bağlantısı açabildiği anlamına gelir. Başarısız olursa hata ya broker'ın CONNACK yanıtıdır ya da bir ağ hatasıdır: MQTT bağlantı hataları yazısına bakın ve kodları reason code aracıyla sorgulayın.

Tekrarlanabilir kurulumlar için tıklamak yerine data source'u bir dosyadan provision edin:

apiVersion: 1
datasources:
  - name: MQTT
    type: grafana-mqtt-datasource
    access: proxy
    jsonData:
      uri: tls://broker.connectmq.com:8883
      username: ${MQTT_USER}
    secureJsonData:
      password: ${MQTT_PASS}

Grafana provisioning dosyalarındaki ortam değişkenlerini açar; böylece parola asla Git'e düşmez. Alan adları eklenti sürümleri arasında biraz farklı olabilir; bir değer yok sayılıyorsa onu bir kez arayüzden ayarlayın ve eklentinin README dosyasıyla karşılaştırın.

Test telemetrisi yayınlayın

Bir panel yalnızca açıkken gelen mesajları gösterir; bu yüzden tasarım yaparken sürekli bir veri akışına ihtiyacınız var. Bu paho-mqtt 2.x betiği her saniye bir JSON ölçümü yayınlar:

import json, math, os, random, time
import paho.mqtt.client as mqtt

client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2, client_id="grafana-demo-sensor")
client.username_pw_set(os.environ["MQTT_USER"], os.environ["MQTT_PASS"])
client.tls_set()                       # sistem CA deposu
client.connect("broker.connectmq.com", 8883)
client.loop_start()

t = 0
while True:
    reading = {
        "temperature": round(21 + 3 * math.sin(t / 30) + random.uniform(-0.3, 0.3), 2),
        "humidity": round(45 + random.uniform(-2, 2), 1),
        "battery": max(0, 100 - t // 60),
    }
    client.publish("testmqtt/grafana/room1/telemetry", json.dumps(reading), qos=0)
    t += 1
    time.sleep(1)

Grafana'ya dokunmadan önce akışı online MQTT istemcisiyle doğrulayın: testmqtt/grafana/# topic'ine abone olun ve mesajların gelişini izleyin. Mesajlar orada görünüyor ama Grafana'da görünmüyorsa sorun yayıncıda değil, data source'tadır.

Test telemetrisini tarayıcıda izleyin

Canlı paneller oluşturun

Bir dashboard oluşturun, bir görselleştirme ekleyin ve MQTT data source'u seçin. Sorgu düzenleyicide önemli bir alan var, Topic: buraya testmqtt/grafana/room1/telemetry yazın.

1. Time series: varsayılan seçenek. Her JSON anahtarı (temperature, humidity, battery) bir seriye dönüşür. Grafiğin sıkışmak yerine kayması için dashboard zaman aralığını Last 5 minutes yapın.
2. Gauge: görselleştirmeyi değiştirin, Calculation değerini Last yapın ve Fields altında temperature alanını seçin. Eşik değerleri ekleyin (25 altı yeşil, 28 üstü kırmızı).
3. Stat: battery için uygundur; Last ve yüzde birimini kullanın.

Bir panelde yalnızca tek bir alan istiyorsanız ayrı topic'ler yayınlamak yerine Organize fields veya Filter fields by name dönüşümünü kullanın.

Çalışan payload biçimleri

Zaman damgası, payload içindeki bir zaman alanı değil, Grafana'nın mesajı aldığı andır. Cihazlar arabelleğe alıp geç gönderiyorsa grafik varış zamanını gösterir; bkz. zaman damgası sorunları.

Wildcard'lar ve çok sayıda cihaz

Güncel eklenti sürümleri topic alanında + ve # kabul eder; böylece testmqtt/grafana/+/telemetry tek bir paneli tüm odalardan besleyebilir. Kaydetmeden önce bir filtrenin hangi topic'lerle eşleşeceğini topic matcher ile kontrol edin: yoğun bir broker'da dikkatsizce kullanılan bir #, tarayıcıya bir panelin çizebileceğinden çok daha fazla veri akıtır. Büyük filolar için cihaz grubu başına bir panel tercih edin ya da cihaz tarafında toplayıp bir özet topic yayınlayın. Dashboard'ların temiz biçimde filtreleyebileceği topic'ler tasarlamak için topic'ler ve wildcard'lar yazısına bakın.

Sorun giderme

• Yeni panelde "No data": panel açıldığından beri hiçbir şey yayınlanmadı. Eklenti eski mesajları tekrar oynatmaz; retained mesajlar da ancak yayıncı retain bayrağını ayarlarsa işe yarar. Test yayıncısını başlatın ve bir saniye bekleyin.
• Save & test başarısız: Grafana sunucusunun (veya container'ın) broker'a ulaşabildiğini kontrol edin: docker exec grafana nc -vz broker.connectmq.com 8883. Kurumsal çıkış kuralları, dizüstü bilgisayarınız bağlanabilse bile 8883 portunu çoğu zaman engeller.
• Veri gelip sonra kesiliyor: aynı client ID'ye sahip başka bir istemci Grafana'yı düşürüyor ya da kullanıcının okuma izni yok ve broker aboneliği sessizce yok sayıyor. Broker loglarına bakın ve ACL'leri doğrulayın.
• Sayılar metin olarak görünüyor: yayıncı "23.5" değerini tırnak içinde gönderiyor. Payload'ı düzeltin ya da Convert field type dönüşümü ekleyin.
• Panel gecikiyor veya sekme donuyor: topic filtresi çok geniş ya da cihazlar gerekenden hızlı yayın yapıyor. Yayın sıklığını düşürün veya önce toplayın.

Geçmişe ihtiyaç duyduğunuzda

MQTT data source "şu anda ne oluyor" sorusu için mükemmeldir. Biri "dün gece ne oldu" diye sorduğu anda depolamaya ihtiyacınız olur. Yaygın yaklaşım, canlı paneli korumak ve ikinci bir data source eklemektir:

• Telegraf ile MQTT'den InfluxDB'ye: yalnızca yapılandırmayla bir zaman serisi veritabanına aktarım.
• MQTT'den PostgreSQL / TimescaleDB'ye: SQL sorguları ve iş verileriyle join'ler.

Grafana ikisini aynı dashboard'da gösterebilir: üstte canlı bir MQTT stat paneli, altta InfluxDB veya SQL'den gelen geçmiş grafikleri. Grafana olmadan yalnızca tarayıcıda çalışan bir dashboard arıyorsanız canlı MQTT dashboard oluşturma yazısına bakın.

MQTT data source bir topic'i dakikalar içinde canlı bir panele dönüştürür. Onu salt okunur bir broker kullanıcısına bağlayın, payload'ları düz JSON sayıları olarak tutun, akışı önce bir MQTT istemcisiyle doğrulayın ve dashboard'un hatırlaması gerektiğinde bir veritabanı ekleyin.

Sıkça sorulan sorular