Release Announcement: NSO 6.5 is now released.
Head to the release highlights to see what's new
NSO DevCenterTry NSO

_ncs.events Module

Low level module for subscribing to NCS event notifications.

This module is used to connect to NCS and subscribe to certain events generated by NCS. The API to receive events from NCS is a socket based API whereby the application connects to NCS and receives events on a socket. See also the Notifications chapter in the User Guide. The program misc/notifications/confd_notifications.c in the examples collection illustrates subscription and processing for all these events, and can also be used standalone in a development environment to monitor NCS events.

This documentation should be read together with the confd_lib_events(3) man page.

Functions

diff_notification_done

diff_notification_done(sock, tctx) -> None

If the received event was NOTIF_COMMIT_DIFF it is important that we call this function when we are done reading the transaction diffs over MAAPI. The transaction is hanging until this function gets called. This function also releases memory associated to the transaction in the library.

Keyword arguments:

  • sock -- a previously connected notification socket

  • tctx -- a transaction context

notifications_connect

notifications_connect(sock, mask, ip, port, path) -> None

This function creates a notification socket.

Keyword arguments:

  • sock -- a Python socket instance

  • mask -- a bitmask of one or several notification type values

  • ip -- the ip address if socket is AF_INET (optional)

  • port -- the port if socket is AF_INET (optional)

  • path -- a filename if socket is AF_UNIX (optional).

notifications_connect2

notifications_connect2(sock, mask, data, ip, port, path) -> None

This variant of notifications_connect is required if we wish to subscribe to NOTIF_HEARTBEAT, NOTIF_HEALTH_CHECK, or NOTIF_STREAM_EVENT events.

Keyword arguments:

  • sock -- a Python socket instance

  • mask -- a bitmask of one or several notification type values

  • data -- a _events.NotificationsData instance

  • ip -- the ip address if socket is AF_INET (optional)

  • port -- the port if socket is AF_INET (optional)

  • path -- a filename if socket is AF_UNIX (optional)

read_notification

read_notification(sock) -> dict

The application is responsible for polling the notification socket. Once data is available to be read on the socket the application must call read_notification() to read the data from the socket. On success a dictionary containing notification information will be returned (see below).

Keyword arguments:

  • sock -- a previously connected notification socket

On success the returned dict will contain information corresponding to the c struct confd_notification. The notification type is accessible through the 'type' key. The remaining information will be different depending on which type of notification this is (described below).

Keys for type NOTIF_AUDIT (struct confd_audit_notification):

  • logno

  • user

  • msg

  • usid

Keys for type NOTIF_DAEMON, NOTIF_NETCONF, NOTIF_DEVEL, NOTIF_JSONRPC, NOTIF_WEBUI, or NOTIF_TAKEOVER_SYSLOG (struct confd_syslog_notification):

  • prio

  • logno

  • msg

Keys for type NOTIF_COMMIT_SIMPLE (struct confd_commit_notification):

  • database

  • diff_available

  • flags

  • uinfo

Keys for type NOTIF_COMMIT_DIFF (struct confd_commit_diff_notification):

  • database

  • flags

  • uinfo

  • tctx

  • label (optional)

  • comment (optional)

Keys for type NOTIF_USER_SESSION (struct confd_user_sess_notification):

  • type

  • uinfo

  • database

Keys for type NOTIF_HA_INFO (struct confd_ha_notification):

  • type (1)

  • noprimary - if (1) is HA_INFO_NOPRIMARY

  • secondary_died - if (1) is HA_INFO_SECONDARY_DIED (see below)

  • secondary_arrived - if (1) is HA_INFO_SECONDARY_ARRIVED (see below)

  • cdb_initialized_by_copy - if (1) is HA_INFO_SECONDARY_INITIALIZED

  • besecondary_result - if (1) is HA_INFO_BESECONDARY_RESULT

If secondary_died or secondary_arrived is present they will in turn contain a dictionary with the following keys:

  • nodeid

  • af (1)

  • ip4 - if (1) is AF_INET

  • ip6 - if (1) is AF_INET6

  • str - if (1) if AF_UNSPEC

Keys for type NOTIF_SUBAGENT_INFO (struct confd_subagent_notification):

  • type

  • name

Keys for type NOTIF_COMMIT_FAILED (struct confd_commit_failed_notification):

  • provider (1)

  • dbname

  • port - if (1) is DP_NETCONF

  • af (2) - if (1) is DP_NETCONF

  • ip4 - if (2) is AF_INET

  • ip6 - if (2) is AF_INET6

  • daemon_name - if (1) is DP_EXTERNAL

Keys for type NOTIF_SNMPA (struct confd_snmpa_notification):

  • pdu_type (1)

  • request_id

  • error_status

  • error_index

  • port

  • af (2)

  • ip4 - if (3) is AF_INET

  • ip6 - if (3) is AF_INET6

  • vb (optional)

  • generic_trap - if (1) is SNMPA_PDU_V1TRAP

  • specific_trap - if (1) is SNMPA_PDU_V1TRAP

  • time_stamp - if (1) is SNMPA_PDU_V1TRAP

  • enterprise - if (1) is SNMPA_PDU_V1TRAP (optional)

Keys for type NOTIF_FORWARD_INFO (struct confd_forward_notification):

  • type

  • target

  • uinfo

Keys for type NOTIF_CONFIRMED_COMMIT (struct confd_confirmed_commit_notification):

  • type

  • timeout

  • uinfo

Keys for type NOTIF_UPGRADE_EVENT (struct confd_upgrade_notification):

  • event

Keys for type NOTIF_COMPACTION (struct confd_compaction_notification):

  • dbfile (1) - name of the compacted file

  • type - automatic or manual

  • fsize_start - size at start (bytes)

  • fsize_end - size at end (bytes)

  • fsize_last - size at end of last compaction (bytes)

  • time_start - start time (microseconds)

  • duration - duration (microseconds)

  • ntrans - number of transactions written to (1) since last compaction

Keys for type NOTIF_COMMIT_PROGRESS and NOTIF_PROGRESS (struct confd_progress_notification):

  • type (1)

  • timestamp

  • duration if (1) is CONFD_PROGRESS_STOP

  • trace_id (optional)

  • span_id

  • parent_span_id (optional)

  • usid

  • tid

  • datastore

  • context (optional)

  • subsystem (optional)

  • msg (optional)

  • annotation (optional)

  • num_attributes

  • attributes (optional)

  • num_links

  • links (optional)

Keys for type NOTIF_STREAM_EVENT (struct confd_stream_notification):

  • type (1)

  • error - if (1) is STREAM_REPLAY_FAILED

  • event_time - if (1) is STREAM_NOTIFICATION_EVENT

  • values - if (1) is STREAM_NOTIFICATION_EVENT

Keys for type NOTIF_CQ_PROGRESS (struct ncs_cq_progress_notification):

  • type

  • timestamp

  • cq_id

  • cq_tag

  • label

  • completed_devices (optional)

  • transient_devices (optional)

  • failed_devices (optional)

  • failed_reasons - if failed_devices is present

  • completed_services (optional)

  • completed_services_completed_devices - if completed_services is present

  • failed_services (optional)

  • failed_services_completed_devices - if failed_services is present

  • failed_services_failed_devices - if failed_services is present

Keys for type NOTIF_CALL_HOME_INFO (struct ncs_call_home_notification):

  • type (1)

  • device - if (1) is CALL_HOME_DEVICE_CONNECTED or CALL_HOME_DEVICE_DISCONNECTED

  • af (2)

  • ip4 - if (2) is AF_INET

  • ip6 - if (2) is AF_INET6

  • port

  • ssh_host_key

  • ssh_key_alg

sync_audit_network_notification

sync_audit_network_notification(sock, usid) -> None

If the received event was NOTIF_AUDIT_NETWORK, and we are subscribing to notifications with the flag NOTIF_AUDIT_NETWORK_SYNC, this function must be called when we are done processing the notification. The user session is hanging until this function gets called.

Keyword arguments:

  • sock -- a previously connected notification socket

  • usid -- the user session id

sync_audit_notification

sync_audit_notification(sock, usid) -> None

If the received event was NOTIF_AUDIT, and we are subscribing to notifications with the flag NOTIF_AUDIT_SYNC, this function must be called when we are done processing the notification. The user session is hanging until this function gets called.

Keyword arguments:

  • sock -- a previously connected notification socket

  • usid -- the user session id

sync_ha_notification

sync_ha_notification(sock) -> None

If the received event was NOTIF_HA_INFO, and we are subscribing to notifications with the flag NOTIF_HA_INFO_SYNC, this function must be called when we are done processing the notification. All HA processing is blocked until this function gets called.

Keyword arguments:

  • sock -- a previously connected notification socket

Classes

class Notification

This is a placeholder for the c-type struct confd_notification.

Notification cannot be directly instantiated from Python.

Members:

None

class NotificationsData

This type represents the c-type struct confd_notifications_data.

The contructor for this type has the following signature:

NotificationsData(hearbeat_interval, health_check_interval, stream_name, start_time, stop_time, xpath_filter, usid, verbosity) -> object

Keyword arguments:

  • heartbeat_interval -- time in milli seconds (int)

  • health_check_interval -- time in milli seconds (int)

  • stream_name -- name of the notification stream (string)

  • start_time -- the start time (Value)

  • stop_time -- the stop time (Value)

  • xpath_filter -- XPath filter for the stream (string) - optional

  • usid -- user session id for AAA restriction (int) - optional

  • verbosity -- progress verbosity level (int) - optional

Members:

None

Predefined Values


ABORT_COMMIT = 3
CALL_HOME_DEVICE_CONNECTED = 1
CALL_HOME_DEVICE_DISCONNECTED = 3
CALL_HOME_UNKNOWN_DEVICE = 2
COMPACTION_AUTOMATIC = 1
COMPACTION_A_CDB = 1
COMPACTION_MANUAL = 2
COMPACTION_O_CDB = 2
COMPACTION_S_CDB = 3
CONFIRMED_COMMIT = 1
CONFIRMING_COMMIT = 2
DP_CDB = 1
DP_EXTERNAL = 3
DP_JAVASCRIPT = 5
DP_NETCONF = 2
DP_SNMPGW = 4
FORWARD_INFO_DOWN = 2
FORWARD_INFO_FAILED = 3
FORWARD_INFO_UP = 1
HA_INFO_BESECONDARY_RESULT = 7
HA_INFO_BESLAVE_RESULT = 7
HA_INFO_IS_MASTER = 5
HA_INFO_IS_NONE = 6
HA_INFO_IS_PRIMARY = 5
HA_INFO_NOMASTER = 1
HA_INFO_NOPRIMARY = 1
HA_INFO_SECONDARY_ARRIVED = 3
HA_INFO_SECONDARY_DIED = 2
HA_INFO_SECONDARY_INITIALIZED = 4
HA_INFO_SLAVE_ARRIVED = 3
HA_INFO_SLAVE_DIED = 2
HA_INFO_SLAVE_INITIALIZED = 4
NCS_CQ_ITEM_COMPLETED = 4
NCS_CQ_ITEM_DELETED = 6
NCS_CQ_ITEM_EXECUTING = 2
NCS_CQ_ITEM_FAILED = 5
NCS_CQ_ITEM_LOCKED = 3
NCS_CQ_ITEM_WAITING = 1
NCS_NOTIF_AUDIT_NETWORK = 268435456
NCS_NOTIF_AUDIT_NETWORK_SYNC = 536870912
NCS_NOTIF_CALL_HOME_INFO = 33554432
NCS_NOTIF_CQ_PROGRESS = 4194304
NCS_NOTIF_PACKAGE_RELOAD = 2097152
NOTIF_AUDIT = 1
NOTIF_AUDIT_SYNC = 131072
NOTIF_COMMIT_DIFF = 16
NOTIF_COMMIT_FAILED = 256
NOTIF_COMMIT_FLAG_CONFIRMED = 1
NOTIF_COMMIT_FLAG_CONFIRMED_EXTENDED = 2
NOTIF_COMMIT_PROGRESS = 65536
NOTIF_COMMIT_SIMPLE = 8
NOTIF_COMPACTION = 1073741824
NOTIF_CONFIRMED_COMMIT = 16384
NOTIF_DAEMON = 2
NOTIF_DEVEL = 4096
NOTIF_FORWARD_INFO = 1024
NOTIF_HA_INFO = 64
NOTIF_HA_INFO_SYNC = 1048576
NOTIF_HEALTH_CHECK = 262144
NOTIF_HEARTBEAT = 8192
NOTIF_JSONRPC = 67108864
NOTIF_NETCONF = 2048
NOTIF_PROGRESS = 16777216
NOTIF_REOPEN_LOGS = 8388608
NOTIF_SNMPA = 512
NOTIF_STREAM_EVENT = 524288
NOTIF_SUBAGENT_INFO = 128
NOTIF_SYSLOG = 2
NOTIF_SYSLOG_TAKEOVER = 6
NOTIF_TAKEOVER_SYSLOG = 4
NOTIF_UPGRADE_EVENT = 32768
NOTIF_USER_SESSION = 32
NOTIF_WEBUI = 134217728
PROGRESS_ATTRIBUTE_NUMBER = 2
PROGRESS_ATTRIBUTE_STRING = 1
STREAM_NOTIFICATION_COMPLETE = 2
STREAM_NOTIFICATION_EVENT = 1
STREAM_REPLAY_COMPLETE = 3
STREAM_REPLAY_FAILED = 4
SUBAGENT_INFO_DOWN = 2
SUBAGENT_INFO_UP = 1
UPGRADE_ABORTED = 5
UPGRADE_COMMITED = 4
UPGRADE_INIT_STARTED = 1
UPGRADE_INIT_SUCCEEDED = 2
UPGRADE_PERFORMED = 3
USER_SESS_LOCK = 3
USER_SESS_START = 1
USER_SESS_START_TRANS = 5
USER_SESS_STOP = 2
USER_SESS_STOP_TRANS = 6
USER_SESS_UNLOCK = 4
Previous_ncs.error ModuleNext_ncs.ha Module

Last updated

Was this helpful?