gitea
/
fiberguardian
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'ce68d22dbb'
${ noResults }
fiberguardian/FiberGuardian_Summary.md

23 KiB
Raw Blame History Escape

FiberGuardian – Summary Document

This document summarizes the ServiceNow event export, Netcool rules logic, and MIB-based OID/trap mappings for the FiberGuardian (ADVA FSP3000 fiber monitoring) integration.

1. Summary of Events in ServiceNow

Source and scope

  • File: test_events_servicenow.xml
  • Export date: 2026-02-23 13:38:14
  • Total event records: 83 (em_event rows)

Event classification

  • Event class: All events are Trap From Enterprise 2544 (ADVA enterprise OID 1.3.6.1.4.1.2544).
  • Source: Trap From Enterprise 2544
  • Node: Events are reported from node 10.82.8.55 (trap receiver / mid-server).

Processing and state

  • Processing notes: All 83 events have No event rule applied — no ServiceNow event rule matched these traps.
  • Resolution state: All New.
  • State: All events are in Error state.
  • Error message: severity: Invalid value — the trap’s severity could not be mapped or validated, which likely contributes to “No event rule applied” and Error state.

So in this export: every event is an ADVA Enterprise 2544 trap, unclassified by event rules, and in Error due to invalid/missing severity.

Event types (by snmpTrapOID)

Traps use the ALM trap OID branch: iso.org.dod.internet.private.enterprises.2544.1.14.0.* (numeric: .1.3.6.1.4.1.2544.1.14.0.X).

Count Trap OID (last digit) Trap name (from MIB)
47 .14.0.62 authenticationNotification
8 .14.0.9 alarmFaRunning
8 .14.0.19 objectChangedTrap
4 .14.0.63 authenticationNotificationSummary
4 .14.0.44 transientFaSaved
4 .14.0.42 transientFaCompleted
4 .14.0.41 transientFaStarted
4 .14.0.14 alarmLinkBudgetExceeded

Total: 83 events across 8 trap types. Most frequent: authenticationNotification (62), then alarmFaRunning and objectChangedTrap (8 each).

Typical payload (from additional_info / description)

  • Common OIDs in varbinds:
    2544.1.14.1.4.1.2.X (event type name), 2544.1.14.4.2.1.2/4.X (timestamp, entity ID), 2544.1.14.2.2.1.4/5.1 (duct/port name, unit name), 2544.1.14.5.8.* (auth: user, IP, protocol, etc.), sysUpTime.
  • Example resources: MCH-1-1, SHMON-1, “Duct 1-miniduct 2 Grijs”.

2. Summary of Logic in the Netcool File

File and purpose

  • File: FiberGuardianSNMPRules-netcool.txt
  • Role: Netcool (OMNIbus) rules for normalizing and enriching FiberGuardian SNMP traps (enterprise 2544) before forwarding or display.

High-level flow

  1. Match: Traps whose @AlertKey matches .1.3.6.1.4.1.2544 (enterprise 2544).
  2. Normalize node: Hostname is taken from @Node, then trimmed to the part before .nl.eu.abnamro.com and stored back in @Node.
  3. Fixed enrichment:
    • @ApplId = "FiberGuardian"
    • Log line: AAB Specific : Fiber Guardian trap from <hostname>
  4. Branch by OID: Depending on the full trap OID (.1.3.6.1.4.1.2544.1.14.6.X for ALM or .1.3.6.1.4.1.2544.1.15.6.X for SCALM), the rule sets:
    • Severity (@Severity)
    • Reason code ($Event_Reasoncode)
    • Summary (@Summary) using trap-specific varbinds (e.g. portAidString, portName, alarmSeverity, neEventLogIdentityTranslation).
  5. Unknown traps: If the OID does not match any known branch, the trap is discarded and a log line is written with enterprise and specific-trap number.

Severity and reason codes

  • @Severity 5 → MON.I.FIB.00001 (link/fiber-related: threshold, link budget, root link fault).
  • @Severity 4 → MON.I.FIB.00002 (system/equipment: internal error, reboot, bad sys stat, monitoring process, auth, hardware, temperature, voltage, fan, etc.).

Reason code by trap (info from the trap → reason code)

The reason code is derived from the trap type (the trap OID / snmpTrapOID that comes in the trap). Netcool does not read a “reason code” varbind; it maps each trap OID to a fixed reason code. Use this table when enriching events (e.g. set reason code in event/incident info from snmpTrapOID).

Trap OID (suffix) Trap name Reason code
ALM (1.14.0.X)
.14.0.11 alarmThresCrossedFast MON.I.FIB.00001
.14.0.12 alarmThresCrossedMedium MON.I.FIB.00001
.14.0.13 alarmThresCrossedSlow MON.I.FIB.00001
.14.0.14 alarmLinkBudgetExceeded MON.I.FIB.00001
.14.0.15 alarmLinkBudgetNearlyExceeded MON.I.FIB.00001
.14.0.45 transientInternalError MON.I.FIB.00002
.14.0.46 alarmRebootRunning MON.I.FIB.00002
.14.0.48 alarmBadSysStat MON.I.FIB.00002
.14.0.50 alarmMonProcNotRunning MON.I.FIB.00002
.14.0.60 alarmEmailNotifyLinkBudgetExceeded MON.I.FIB.00001
.14.0.63 authenticationNotificationSummary MON.I.FIB.00002
.14.0.68 alarmRootLinkFault MON.I.FIB.00001
SCALM (1.15.0.X)
.15.0.11 alarmThresCrossedFast MON.I.FIB.00001
.15.0.12 alarmThresCrossedMedium MON.I.FIB.00001
.15.0.13 alarmThresCrossedSlow MON.I.FIB.00001
.15.0.14 alarmLinkBudgetExceeded MON.I.FIB.00001
.15.0.15 alarmLinkBudgetNearlyExceeded MON.I.FIB.00001
.15.0.50 alarmMonProcNotRunning MON.I.FIB.00002
.15.0.102 alarmAinsState MON.I.FIB.00002
.15.0.103 alarmRemoved MON.I.FIB.00002
.15.0.104 alarmHwFailure MON.I.FIB.00002
.15.0.107 alarmDatabaseFailure MON.I.FIB.00002
.15.0.110 alarmHwDegrade MON.I.FIB.00002
.15.0.111 alarmHwFailure MON.I.FIB.00002
.15.0.112 alarmLinkDown MON.I.FIB.00002
.15.0.121 transientSwResetReload MON.I.FIB.00002
.15.0.122 alarmTemperatureTooHigh MON.I.FIB.00002
.15.0.123 transientBootUpFailed MON.I.FIB.00002
.15.0.124 transientBootUpCompleted MON.I.FIB.00002
.15.0.125 transientBootUpStarted MON.I.FIB.00002
.15.0.128 alarmVoltageOutOfRange MON.I.FIB.00002
.15.0.129 alarmMultipleFanFailure MON.I.FIB.00002
.15.0.130 alarmCurrentTooHigh MON.I.FIB.00002
.15.0.131 alarmInputVoltageFailure MON.I.FIB.00002
.15.0.303 authenticationNotificationSummary MON.I.FIB.00002

Note: Trap OID in the trap is usually 1.3.6.1.4.1.2544.1.14.0.X (ALM) or 1.3.6.1.4.1.2544.1.15.0.X (SCALM). Netcool matches .14.6.X / .15.6.X (same trap number X). Traps not listed (e.g. .14.0.62 authenticationNotification) are not handled in the Netcool rules and are discarded; if you handle them elsewhere, you can assign e.g. MON.I.FIB.00002 for authenticationNotification to align with auth summary.

Trap branches implemented (by OID suffix)

ALM branch (2544.1.14.6.X) – monitor-unit style (portAidString, portName, alarmSeverity):

  • 11 → alarmThresCrossedFast
  • 12 → alarmThresCrossedMedium
  • 13 → alarmThresCrossedSlow
  • 14 → alarmLinkBudgetExceeded
  • 15 → alarmLinkBudgetNearlyExceeded
  • 45 → transientInternalError
  • 46 → alarmRebootRunning
  • 48 → alarmBadSysStat
  • 50 → alarmMonProcNotRunning
  • 60 → alarmEmailNotifyLinkBudgetExceeded (many varbinds in summary)
  • 63 → authenticationNotificationSummary
  • 68 → alarmRootLinkFault

SCALM branch (2544.1.15.6.X) – neEventLogIdentityTranslation, alarmSeverity where applicable:

  • 11, 12, 13 → alarmThresCrossedFast/Medium/Slow
  • 14, 15 → alarmLinkBudgetExceeded / NearlyExceeded
  • 50 → alarmMonProcNotRunning
  • 102 → alarmAinsState
  • 103 → alarmRemoved
  • 104, 111 → alarmHwFailure
  • 107 → alarmDatabaseFailure
  • 110 → alarmHwDegrade
  • 112 → alarmLinkDown
  • 121 → transientSwResetReload
  • 122 → alarmTemperatureTooHigh
  • 123 → transientBootUpFailed
  • 124 → transientBootUpCompleted
  • 125 → transientBootUpStarted
  • 128 → alarmVoltageOutOfRange
  • 129 → alarmMultipleFanFailure
  • 130 → alarmCurrentTooHigh
  • 131 → alarmInputVoltageFailure
  • 303 → authenticationNotificationSummary

Gaps vs ServiceNow events

  • authenticationNotification (62) and authenticationNotificationSummary (63) are only partially handled: Netcool implements .14.6.63 and .15.6.303, but not .14.6.62 (single auth notification). So trap 62 can fall through to “unknown” and be discarded if the probe sends 2544.1.14.6.62.
  • alarmFaRunning (9), objectChangedTrap (19), transientFaStarted (41), transientFaCompleted (42), transientFaSaved (44), alarmLinkBudgetExceeded (14) are implemented for the branches and OID style used in the Netcool file (e.g. .14.6.X / .15.6.X). If ServiceNow receives the same traps under .14.0.X (standard trap OID), the Netcool logic still applies to the probe’s AlertKey format (which may use .6.X).
  • ServiceNow’s “severity: Invalid value” suggests the trap varbinds (e.g. alarmSeverity) are not being mapped to a valid ServiceNow severity in event rules — alignment with Netcool’s severity and reason codes may help when defining or adjusting those rules.

3. Summary of OID and Value Mapping (from MIBs)

MIB files

  • ADVA-FSP3000ALM-MIB.txt – FSP3000 ALM (standalone monitor), Version V3.2.1 (2019), ::= { products 14 }.
  • ADVA-FSP3000SCALM-MIB.txt – FSP3000 SCALM (controller-based), Version V2.1.1 (2017), ::= { products 15 }.

Enterprise: advaMIB = 1.3.6.1.4.1.2544 (enterprises.2544).

OID tree (relevant branches)

Branch OID (numeric) Description
advaMIB 1.3.6.1.4.1.2544 ADVA enterprise
products 2544.1
fsp3000alm 2544.1.14 ALM product
fsp3000scalm 2544.1.15 SCALM product
ALM trap 2544.1.14.0 trap subtree (ALM)
SCALM almTrap 2544.1.15.0 almTrap subtree (SCALM)

Trap OIDs in SNMP are typically 2544.1.14.0.X (ALM) or 2544.1.15.0.X (SCALM), where X is the trap number below.

ALM trap definitions (ADVA-FSP3000ALM-MIB) – selected

# Name Description (short)
1–6 alarmTempCPU, alarmTempBoard1/2Low/2High, alarmTempLaserLow/High Temperature thresholds
7 alarmMonNotRunning Monitoring function enabled/disabled
8 alarmFpRunning Fingerprint calculation in progress
9 alarmFaRunning Fault analysis in progress
10 alarmFpMissing Fingerprint not calculated for port
11–13 alarmThresCrossedFast/Medium/Slow Loss deviation vs fast/medium/slow threshold
14 alarmLinkBudgetExceeded Link loss vs budget threshold
15 alarmLinkBudgetNearlyExceeded Link loss vs “close to budget” threshold
16–17 alarmManagementState, alarmDisabledState portAdminState changes (mgt / dsbld)
18 stateChangedTrap Entity state change (OperState/AdminState)
19 objectChangedTrap Object change (e.g. severity, threshold)
24–26 transientFpStarted/Completed/Failed Fingerprint lifecycle
30–32 transientDbMgmtActionStarted/Completed/Failed Database management
41–44 transientFaStarted/Completed/Failed/Saved Fault analysis lifecycle
45 transientInternalError Critical error affecting monitoring
46–50 alarmRebootRunning, alarmWarmupRunning, alarmBadSysStat, alarmWrongFWVersion, alarmMonProcNotRunning Reboot, warmup, system/process alarms
62 authenticationNotification Single authentication event
63 authenticationNotificationSummary Auth events (e.g. >5 in 10 s)

(Additional ALM traps 20–23, 27–29, 33–40, 51–61, 64–83 exist in the MIB; above list focuses on those seen in ServiceNow or Netcool.)

SCALM trap definitions (ADVA-FSP3000SCALM-MIB) – selected

Same trap names as ALM for overlapping numbers; OBJECTS often use neEventLogIdentityTranslation and neEventLogTimeStamp instead of portAidString/portName. Examples:

  • 1–19, 24–26, 30–32, 34, 37–44, 50–56: same semantic as ALM where defined.
  • 100–131: creation/deletion, Ains, maintenance, removed, DB/hardware/link/temperature/boot/voltage/fan/current, etc.
  • 302 → authenticationNotification
  • 303 → authenticationNotificationSummary

Alarm list type (integer enumeration)

Both MIBs define an alarm/trap list type with the same numeric identifiers for trap types (e.g. 9 = alarmFaRunning, 14 = alarmLinkBudgetExceeded, 41–44 = transientFa*, 62–63 = authentication*). These appear in tables and varbinds (e.g. 2544.1.14.1.4.1.2.X in ServiceNow additional_info).

Severity and state (from MIBs)

  • alarmSeverity in traps is typed TrapAlarmSeverity (imported from ADVA-MIB; not in the provided MIB files). Typical conventions: integer severity (e.g. 2 = minor, 5/6 = clear/warning, etc.); exact values are defined in ADVA-MIB.
  • Fsp3000scalmAdminState: is(2), mgt(4), dsbld(6).
  • Fsp3000scalmOperState: undefined(0), nr(1), anr(2), out(3), un(4).

Mapping table: trap number → name (for ALM .14.0.X and SCALM .15.0.X)

OID suffix ALM / SCALM name
9 alarmFaRunning
14 alarmLinkBudgetExceeded
19 objectChangedTrap
41 transientFaStarted
42 transientFaCompleted
44 transientFaSaved
62 authenticationNotification
63 authenticationNotificationSummary

This matches the 8 trap types observed in the ServiceNow export and aligns with the trap numbers in the ALM MIB.

4. Message key: what uniquely identifies an event

Purpose of the message key: In ServiceNow (and similar event managers), the message_key is used to uniquely identify an event so that:

  • Deduplication: The same trap received more than once (e.g. multiple listeners, retries) updates one event record instead of creating many.
  • Correlation: Raise and clear for the same alarm can be tied to the same logical event.
  • Uniqueness: Two different events (different device, trap type, or occurrence) get different keys.

In your export, message_key is empty for all events (<message_key/>), so every trap creates a new event and duplicates are not collapsed.

What makes an event unique (from the trap payload)

From the MIB and the ServiceNow payload:

  1. Trap type — snmpTrapOID (e.g. .1.3.6.1.4.1.2544.1.14.0.62). Identifies what happened (e.g. authenticationNotification, alarmFaRunning).
  2. Source entity (unit name) — The device/unit that generated the event. In the trap it appears as the value of the varbind whose OID is 2544.1.14.4.2.1.4.X (event log table, entity name). In additional_info the key is the long form iso.org.dod.internet.private.enterprises.2544.1.14.4.2.1.4.XXX; the XXX is the event log row index. The value is the entity name (e.g. MCH-1-1, SHMON-1).
  3. Event log index — The index X in the event log OIDs (2544.1.14.4.2.1.2.X and 2544.1.14.4.2.1.4.X). The device uses this to identify a specific event record. Different occurrences have different indices (e.g. 188, 189, 190, 191, 192, 193, 194). Duplicate receptions of the same trap carry the same index and entity, so they can be deduplicated.

Analysis of your XML shows that duplicate receptions (e.g. events 1 & 2, 3 & 4, 5 & 7) share the same entity + trap OID + event log index, while distinct events have different indices or entities.

Recommended message_key construction

Use a composite key built from trap varbinds (and optionally the trap source IP if available):

Component Source in payload Example
Entity name Value of 2544.1.14.4.2.1.4.X (any X present) MCH-1-1, SHMON-1
Trap OID snmpTrapOID (full or normalized, e.g. last part) 2544.1.14.0.62 or 62
Event log index The index X from the OID 2544.1.14.4.2.1.4.X (extract from the varbind key) 194, 192, 191

Recommended formula:

message_key = {entityName}|{snmpTrapOID}|{eventLogIndex}
  • entityName — value of the varbind 2544.1.14.4.2.1.4.* (e.g. MCH-1-1). If multiple, use the first or the one that matches the event (same index as the timestamp varbind).
  • snmpTrapOID — full OID (e.g. 1.3.6.1.4.1.2544.1.14.0.62) or a normalized form (e.g. 2544.1.14.0.62) so that ALM vs SCALM and trap number are unambiguous.
  • eventLogIndex — the numeric suffix from 2544.1.14.4.2.1.4.X (e.g. 194).

Examples:

  • SHMON-1|2544.1.14.0.62|194 → one unique event (e.g. one auth notification on SHMON-1, log entry 194). Duplicate receptions get the same key.
  • MCH-1-1|2544.1.14.0.42|192 → one unique event (transientFaCompleted on MCH-1-1, log entry 192).
  • MCH-1-1|2544.1.14.0.9|191 vs MCH-1-1|2544.1.14.0.9|189 → two different alarmFaRunning events (different log entries).

Fallback when event log varbinds are missing

Some traps (e.g. objectChangedTrap) may not include the event log table varbinds (2544.1.14.4.2.1.4.X / 1.2.X). In that case:

  • Use event log timestamp if present: value of 2544.1.14.4.2.1.2.X (device timestamp).
  • Or use time_of_event (ServiceNow ingestion time) as a last resort:
    message_key = {entityName}|{snmpTrapOID}|{eventLogTimestamp} or ...|{time_of_event}.

That way you still get a stable key for deduplication, with slightly less precision than the event log index.

Optional: include resource (port/monitor point)

For alarm correlation (raise/clear), the same logical alarm is often identified by entity + trap type + resource (port/monitor point). The MIB uses portAidString / portName or neEventLogIdentityTranslation. If you want the message_key to represent “this alarm on this port” rather than “this trap occurrence,” you can extend the key with the resource when present:

message_key = {entityName}|{snmpTrapOID}|{eventLogIndex}|{resource}

resource = value of portAidString, portName, or neEventLogIdentityTranslation (from varbinds 2544.1.14.2.2.1.4.1 / 2544.1.14.2.2.1.5.1 or equivalent). Omit or leave empty when the trap has no port/resource.

Summary

  • Uniquely identify an event: Use entity name + snmpTrapOID + event log index from the trap varbinds.
  • Deduplicate duplicate receptions: Same key → update existing event instead of creating a new one.
  • Implement in event rules: In ServiceNow (or the probe), compute this string from additional_info / varbinds and set message_key so that event management can deduplicate and correlate correctly.

Netcool incidents: how this aligns with real incidents

Imported incidents from Netcool (e.g. incident (business_service.name=FIBER MONITORING NLNL).xml) show the following:

What Netcool sends into ServiceNow (per incident):

  • Node / CI: Hostname of the trap sender after the Netcool rule (e.g. INFRAMON-CCAN, INFRAMON-N, INFRAMON-Z) — from @Node after stripping .nl.eu.abnamro.com.
  • Summary / short_description: The Netcool @Summary format, e.g.
    :MON.I.FIB.00001: - aab_inframon-ccan: alarmThresCrossedFast: portAidString = MCH-1-10, portName = Duct 1-miniduct 3 Bruin, alarmSeverity = 4 - AlertKey: NCOSnmpProbe:FATAL
  • Alert ID: Netcool’s own identifier (e.g. Alert1778303, Alert1621700). One incident corresponds to one Netcool Alert; close_notes reference “Closed the task associated with alert: Alert1778303”.
  • Reason code: MON.I.FIB.00001 / MON.I.FIB.00002 (from the Fiber Guardian rules).
  • Trap type name: alarmThresCrossedFast, alarmThresCrossedSlow, alarmLinkBudgetExceeded, etc. (from the rule branch).
  • portAidString / portName: Resource (e.g. MCH-1-10, “Duct 1-miniduct 3 Bruin”).
  • No event log index is present in the incident — Netcool does not forward that to ServiceNow; it uses its own Alert ID for correlation.

Conclusion:

  1. Event (em_event) message_key — The key entityName|snmpTrapOID|eventLogIndex is for raw trap events. It uses data that exists in the trap varbinds (and in your test trap). It is the right key for deduplicating incoming traps at the event layer. Netcool incidents don’t contain event log index because Netcool correlates by Alert ID internally; that doesn’t change the validity of the message_key for events built from raw traps.
  2. Incident-level correlation — For creating or updating incidents from events (so that “same alarm on same port” maps to one incident), the Netcool data shows the effective uniqueness is Node + trap type + port (portAidString). So a good incident correlation key when you don’t have Netcool Alert ID is: 
    incident_correlation_key = {Node}|{trapTypeName}|{portAidString}
    Example: aab_inframon-ccan|alarmThresCrossedFast|MCH-1-10. That matches how each Netcool incident is effectively “one alert per node + alarm type + port.” For traps without a port (e.g. authenticationNotification), use Node and trap type only.
  3. Mapping entity to Node — In traps, “entity” is often the unit name (e.g. MCH-1-1) from the event log varbind; in incidents, “Node” is the hostname (e.g. INFRAMON-CCAN). They can differ (one device may host multiple units). When building incident correlation from raw traps, use the trap source hostname (or resolved CI) as Node, and keep entityName from the varbind for context in the event; the incident key should use the same Node concept as Netcool (sending host) plus trap type and port when present.

So: the message_key we defined is appropriate for events; for incidents, use Node|trapTypeName|portAidString (with port omitted when not applicable) to mirror Netcool’s one-incident-per-alert-per-port behavior.

5. Cross-reference: ServiceNow vs Netcool vs MIB

  • ServiceNow receives traps with OID .1.3.6.1.4.1.2544.1.14.0.X (ALM trap number X). No event rule is applied; severity is invalid, state is Error.
  • Netcool matches .1.3.6.1.4.1.2544.1.14.6.X and .1.3.6.1.4.1.2544.1.15.6.X and sets Severity, Reason code, and Summary; unknown OIDs are discarded (e.g. .14.6.62 not implemented).
  • MIBs define trap names and numbers under .14.0 (ALM) and .15.0 (SCALM); the .6 in Netcool likely corresponds to a different subtree (e.g. event log) used by the probe.

To improve ServiceNow handling:

  1. Map snmpTrapOID (e.g. .14.0.62, .14.0.9, .14.0.14) to event type and severity using the same semantics as Netcool (and MIB names).
  2. Define or extend event rules so that Enterprise 2544 traps get a valid severity (and optionally reason code / summary) from trap OID and varbinds (e.g. alarmSeverity, port/entity identifiers).
  3. Optionally normalize node (e.g. strip .nl.eu.abnamro.com) and set a fixed application (e.g. FiberGuardian) for consistency with Netcool.

Generated from: test_events_servicenow.xml, FiberGuardianSNMPRules-netcool.txt, ADVA-FSP3000ALM-MIB.txt, ADVA-FSP3000SCALM-MIB.txt.

Powered by TurnKey Linux.