Node-RED koppelen aan Splunk met de HTTP Event Collector

HEC inschakelen en een token aanmaken

De HTTP Event Collector ontvangt events via HTTP of HTTPS. In Splunk Enterprise schakelt u HEC in via Settings, Data inputs, HTTP Event Collector, onder Global Settings. Standaard luistert HEC op poort 8088 met SSL ingeschakeld. In Splunk Cloud is HEC al beschikbaar en verschilt alleen de URL.

Maak daarna een token aan. Bij het aanmaken kiest u een standaard sourcetype, een standaard index en de indexes waarin het token mag schrijven. Maak per bron of toepassing een eigen token aan. Dan kunt u een koppeling uitschakelen zonder de rest te raken en ziet u in de interne logs welke bron problemen geeft.

Het endpoint en de payload

Events gaan als POST naar https://<host>:8088/services/collector/event met de header Authorization: Splunk <token>. De body is JSON met het event zelf in het veld event. Met time (epoch-seconden, eventueel met decimalen), sourcetype, index, host en source overschrijft u de standaardwaarden van het token. Met fields kunt u extra indexed fields meesturen.

{
  "time": 1792231200.123,
  "host": "node-red-01",
  "source": "node-red:sensoren",
  "sourcetype": "nodered:meting",
  "index": "iot",
  "event": {
    "sensor": "pomp-3",
    "temperatuur": 41.7,
    "status": "ok"
  }
}

Testen met curl

Test het token eerst buiten Node-RED, zodat u weet dat Splunk de events accepteert. Een geslaagde aanvraag geeft {"text":"Success","code":0} terug. Gebruik -k alleen tijdelijk in een testomgeving.

curl https://splunk.example.nl:8088/services/collector/event \
  -H "Authorization: Splunk <token>" \
  -d '{"sourcetype": "nodered:meting", "index": "iot", "event": {"sensor": "pomp-3", "status": "ok"}}'

De flow in Node-RED

In Node-RED bouwt u het event in een function- of change-node op msg.payload en stuurt u het met een http request node naar Splunk. Zet de methode op POST, kies als return type een parsed JSON object en zet de Authorization-header in msg.headers of in de node zelf. Bewaar het token bij voorkeur in een omgevingsvariabele of in de credentials, niet als platte tekst in de flow die u exporteert.

Bij grotere aantallen events is het verstandig om te bundelen. HEC accepteert meerdere JSON-objecten achter elkaar in één aanvraag, zonder omringende array. Met een join-node of een eigen buffer in een function-node verzamelt u bijvoorbeeld honderd events of de events van vijf seconden en stuurt u die in één keer. Dat scheelt verbindingen en houdt de flow licht.

TLS en certificaten

Laat certificaatcontrole aan staan in productie. Voeg in de http request node een TLS-configuratie toe met het CA-certificaat dat het certificaat van Splunk heeft ondertekend. Het uitzetten van de controle lost een foutmelding snel op, maar verplaatst het probleem naar de beveiliging.

Foutafhandeling en retries

De http request node geeft bij een verbindingsfout, zoals een time-out of een geweigerde verbinding, een fout die u met een catch-node opvangt. Een antwoord met een foutcode, zoals 400 bij een ongeldige payload, 403 bij een ongeldig token of 503 wanneer HEC het tijdelijk niet aankan, komt daarentegen gewoon uit de node met msg.statusCode. Controleer die waarde daarom met een switch-node.

Voor tijdelijke fouten werkt een eenvoudige retry goed: verhoog een teller op het bericht, wacht met een delay-node en stuur het bericht opnieuw. Na een vast aantal pogingen schrijft u het event naar een bestand of een wachtrij, zodat er niets verloren gaat. Een 400 of 403 herhalen heeft geen zin; die vragen om een melding aan de beheerder.

De andere richting: Splunk-alerts opvolgen

Node-RED kan ook reageren op wat Splunk vindt. Geef een alert in Splunk de webhook alert action en laat die posten naar een http in node in Node-RED, bijvoorbeeld op /splunk/alert. Splunk stuurt dan JSON mee met onder meer de naam van de zoekopdracht, de search id, een link naar de resultaten en in het veld result de eerste rij van de resultaten. Sluit de flow af met een http response node, zodat Splunk een antwoord krijgt. In Splunk Cloud moet de URL van de webhook op een allow list staan.

Vanuit die flow maakt u bijvoorbeeld een ticket aan via de API van uw service management tool, zoals TOPdesk. Controleer eerst of er voor hetzelfde probleem al een open ticket is, anders levert een alert die elke vijf minuten afgaat twaalf tickets per uur op. Bescherm het endpoint met TLS en sta alleen verkeer vanaf de Splunk-servers toe.

Bij een IT-dienstverlener heb ik op deze manier Node-RED-flows gebouwd die gecorreleerde events afvangen en incidenten automatisch afhandelen. Voor de meeste incidenten daalde de hersteltijd daardoor sterk, omdat het eerste werk al gedaan was voordat iemand het ticket opende.