Syslog Ingest Guide

ServiceRadar collects log events through a stateless gateway that forwards messages to CNPG/Timescale for storage and alerting. Pair this quick guide with the Device Configuration Reference when onboarding new platforms.

Provision the Gateway

1. Expose the syslog listener (service/serviceradar-syslog) on UDP/TCP 514. In Docker Compose, this maps to the host automatically; in Kubernetes, create a LoadBalancer or NodePort.
2. Allocate dedicated volumes if you need to buffer bursts; CNPG ingests events in near real time, but disk headroom protects against traffic spikes.
3. Tag syslog inputs with tenant, site, or device metadata using the Sync service configuration so SRQL queries stay filterable.

Configure Devices

• Use TLS-capable transports (TCP/TLS or RELP) where supported. When restricted to UDP, enforce ACLs and use an out-of-band management network.
• Normalize time zones to UTC to keep SRQL queries aligned with SNMP and OTEL data.
• Leverage structured data fields (RFC 5424) for network appliances that support it; ServiceRadar stores them as JSON for easier filtering.

Event Pipeline

1. The serviceradar-flowgger gateway accepts syslog over UDP/TCP 514 and publishes each message to the NATS JetStream stream named events on the events.syslog subject.
2. JetStream retains the raw envelope while serviceradar-zen (the zen engine) consumes the same stream using the zen-consumer durable. The consumer appends a .processed suffix (for example events.syslog.processed) after rules execute so downstream writers can subscribe without reprocessing the original payload.
3. The serviceradar-db-event-writer deployment reads the .processed subjects and batches inserts into the CNPG/Timescale tables. Because both the raw and processed subjects live in the events stream you can replay either layer during troubleshooting.

Zen Rules

The default decision group for syslog chains two GoRules/zen flows that focus on Ubiquiti-style events:

• strip_full_message removes the duplicated full_message field that UniFi devices emit so only the structured payload remains.
• cef_severity inspects the CEF header segment and maps the embedded numeric severity into the ServiceRadar priority scale (Low, Medium, High, Very High, or Unknown).

You can inspect the JSON definitions in packaging/zen/rules/ or the rendered ConfigMap k8s/demo/base/serviceradar-zen-rules.yaml. Future releases will surface these flows in a Web UI rule builder powered by GoRules so operators can drag-and-drop additional matchers without touching JSON.

Managing Rules

• Rules are stored in the NATS JetStream key-value bucket serviceradar-datasvc using the key pattern agents/<agent-id>/<stream>/<subject>/<rule>.json. The demo agent ID is default-agent, stream events, and subject events.syslog.

• The zen-put-rule helper (packaged in the serviceradar-tools container) publishes rule updates. Launch the toolbox pod and run:

  kubectl -n demo exec deploy/serviceradar-tools -- \
    zen-put-rule --agent default-agent --stream events \
    --subject events.syslog --rule strip_full_message \
    --file /etc/serviceradar/zen/rules/strip_full_message.json

  The helper validates JSON before writing to JetStream and will create the key if it is missing.

Parsing and Routing

• The zen engine now owns all parsing before data lands in CNPG. Add or update GoRules flows under packaging/zen/rules/ and redeploy serviceradar-zen (or push the rule via the KV helper) to change normalization.
• Route noisy facilities (e.g., local7.debug) to lower retention tiers by adjusting db-event-writer stream mappings or by downsampling in CNPG (see the CNPG monitoring guide for helper queries).
• Convert critical events into alerts through the Core API; see the Service Port Map for sample selectors.

Verification Checklist

• Confirm throughput via kubectl logs deploy/serviceradar-syslog -n demo.
• Run SRQL queries such as SELECT message FROM syslog.events ORDER BY timestamp DESC LIMIT 20;.
• Cross-link syslog and SNMP data in dashboards to highlight correlation during incidents.