Event Mapping

Mapping and filtering MQTT or Kafka message payloads to ilert event properties.

When consuming messages from MQTT or Kafka, ilagent can map custom JSON fields in your payloads to ilert event properties. This is useful when your message format does not match the ilert event API directly.

Filtering messages

Only process messages that contain a specific JSON key or key-value pair:

--filter_key 'type' --filter_val 'ALARM'

The example above will only process payloads matching { "type": "ALARM" }. If only --filter_key is set (without --filter_val), any message containing that key will be accepted.

Setting a fixed integration key

When mapping custom events, your payloads may not include an integrationKey field. Use --event_key to set a fixed integration key for every mapped event:

--event_key 'il1api123...'

Mapping required event fields

All mapping flags support dot-notation for nested fields (e.g. data.message to access { "data": { "message": "..." } }).

Flag	Maps to	Example
--map_key_alert_key 'mCode'	alertKey	{ "mCode": "123" } → alertKey: 123
--map_key_alert_key 'data.alertId'	alertKey	{ "data": { "alertId": "abc" } } → alertKey: abc
--map_key_summary 'comment'	summary	{ "comment": "A comment" } → summary: A comment
--map_key_summary 'data.message'	summary	{ "data": { "message": "..." } } → summary: ...
--map_key_etype 'state'	eventType	{ "state": "ACK" } → eventType: ACK

If you are using custom mapping and fail to set the summary for ALERT events, a default summary will be generated using the message topic name.

Mapping eventType values

If your event type values do not match ilert's ALERT, ACCEPT, and RESOLVE, map them:

Flag	Mapping	Example
--map_val_etype_alert 'SET'	SET → ALERT
--map_val_etype_accept 'ACK'	ACK → ACCEPT
--map_val_etype_resolve 'CLR'	CLR → RESOLVE

Enriching events

Beyond the core event fields, ilagent can attach labels, a severity, a routing key, and service references to events. Each can be set as a static value applied to every event, or mapped from the message payload.

The static flags (--label, --severity, --service) also apply to a plain HTTP proxy daemon that only receives events via POST /api/events — not just MQTT and Kafka consumers.

Labels

Flag	Description	Example
--label key=value	Static label stamped on every event (repeatable)	--label env=prod
--map_key_label name=jsonpath	Pull a label value from the payload into a named label (repeatable, supports dot-notation)	--map_key_label region=data.region

Static labels take precedence: if a --label and a --map_key_label resolve to the same key, the static value wins.

Severity

Flag	Description	Example
--severity N	Default severity (1–5), applied only when the event does not already carry one	--severity 3
--map_key_severity jsonpath	Extract severity from the payload, as a string or number (supports dot-notation)	--map_key_severity data.level

Severity values outside the 1–5 range are dropped without failing the event.

Routing key

Flag	Description	Example
--map_key_routing_key jsonpath	Extract a routing key from the payload (supports dot-notation)	--map_key_routing_key data.team

Services

Flag	Description	Example
--service alias=NAME	Attach a service by alias (repeatable)	--service alias=web-frontend
--service id=NUM	Attach a service by numeric id (repeatable)	--service id=123

These enrichment flags are consumer / HTTP-daemon features. They are rejected at startup when combined with edge connector mode (--edge_mode), which is an exclusive daemon mode.

Forwarding the full message payload

By default, only mapped fields are included in the event. The original message payload is not preserved. Use --forward_message_payload to include the complete original JSON payload as customDetails:

--forward_message_payload

When enabled:

• The full original payload becomes the customDetails of the event
• The original payload is preserved as-is — no metadata is injected
• If the payload already contains an explicit customDetails field, it is preserved as-is

This is useful when you need downstream visibility into the full message while still mapping specific fields to ilert event properties.

Example with nested mapping and forwarded payload

Given this MQTT payload on topic factory/alerts:

{
    "eventType": "alertCreated",
    "source": "monitoringService",
    "data": {
        "alertId": "f9e8d7c6-...",
        "message": "Anomaly detected on pump unit 2",
        "priority": 2
    }
}

With this config:

--event_key 'il1api123...' \
--map_key_etype 'eventType' \
--map_val_etype_alert 'alertCreated' \
--map_key_summary 'data.message' \
--map_key_alert_key 'data.alertId' \
--forward_message_payload

The resulting ilert event will have:

• eventType: ALERT (mapped from alertCreated)
• summary: Anomaly detected on pump unit 2 (from data.message)
• alertKey: f9e8d7c6-... (from data.alertId)
• customDetails: the full original payload as-is

Complete example

ilagent daemon -v -v \
    -m 127.0.0.1 -q 1883 -n ilagent -e '#' \
    --mqtt_username 'my-user' --mqtt_password 'my-pass' \
    --event_key 'il1api112115xxx' \
    --map_key_alert_key 'mCode' \
    --map_key_summary 'comment' \
    --map_key_etype 'state' \
    --map_val_etype_alert 'SET' \
    --map_val_etype_accept 'ACK' \
    --map_val_etype_resolve 'CLR' \
    --filter_key 'type' \
    --filter_val 'ALARM'

Increase log verbosity with multiple -v flags to understand how events are mapped.