Example: Enriching an event with interface name

You can configure event enrichment so that for all interface events, the name of the interface on which the event occurred is added to a field in the event.

Before you begin

You must create a new custom field in the ObjectServer alerts.status table to store the enriched interface name value. In this example, it is assumed that a new custom field called InterfaceName has been created in the alerts.status table.

About this task

The name of an interface is available in the NCIM topology database interface table. This field can be accessed using NCIM cache, and is held in the ncimCache.entityData table.

The following steps explain how to configure this extra event enrichment.

Procedure

  1. Edit the Event Gateway schema file, $NCHOME/etc/precision/EventGatewaySchema.cfg, to allow the Event Gateway to update the new field. To do this, add the text in bold to the outgoing event filter. Remember to add a comma at the end of the line containing the NmosSerial field, before the line containing the new InterfaceName field.
    insert into config.ncp2nco
    (
        FieldFilter
    )
    values
    (
        [
            "NmosCauseType",
            "NmosDomainName",
            "NmosEntityId",
            "NmosManagedStatus",
            "NmosObjInst",
            "NmosSerial",
            "InterfaceName"
        ]
    );
    Note: Fields that are added to the outgoing event filter are automatically added to the incoming field filter, config.nco2ncp, thus ensuring that the current value of the field is retrieved. This allows the StandardEventEnrichment stitcher in the next step to check the value of the InterfaceName field before updating it. This technique ensures that the Event Gateway does not keep updating the same value.
  2. Edit the Event Gateway stitchers to retrieve the interface name information from the topology database and to populate the InterfaceName field.
    One way to do this is to add the following code to the StandardEventEnrichment stitcher. Adding this code ensures that this procedure is performed for all topology events that are matched to an entity. Add this code to the stitcher immediately before the final line, the call to GwEnrichEvent( enrichedFields ) and after determining the entityType value.
    Table 1. Lines of code relevant to the interface name example
    Line numbers Description
    1 This event enrichment is only relevant for interface events. Check that this event relates to an interface by ensuring that the entityType value is 2, and if so, continue processing.
    3 Retrieve the ifName data from the interface table.
    Note: Whenever you retrieve data from NCIM cache, the field within the entity data must be specified in uppercase; for example, @mainNode.chassis.SYSLOCATION.
    5 - 8 Only populate the InterfaceName field if the interface name value is not already present in the in-scope event.
    if ( entityType == 2 )
    {
        text interfaceName = @entity.networkInterface.IFNAME;
        
        if ( interfaceName <> eval(text, '&InterfaceName') )
        {
              @enrichedFields.InterfaceName = interfaceName;
        }
    }