Events

Introduction

The controller can emit many kinds of events, useful for monitoring, management and integration with other systems. They can be enabled in the controller configuration.

Common Fields

All events have the following fields:

Type	Description	Type
namespace	The name indicating the overall event type	string
timestamp	The date/time when the event was generated	timestamp
evt_src_id	The id of the controller which emitted the event	string

Time Related Types

Type	Description	Examples
timestamp	RFC3339 formatted timestamp string	"2024-10-02T12:17:39.501821249-04:00"
duration	Duration with value and unit	"10s", "5m", "3h"

Event Types

• ApiSessionEvent
• CircuitEvent
• ClusterEvent
• ConnectEvent
• EntityChangeEvent
• EntityCountEvent
• LinkEvent
• MetricsEvent
• RouterEvent
• SdkEvent
• ServiceEvent
• SessionEvent
• TerminatorEvent
• UsageEvent

ApiSessionEvent

Namespace: edge.apiSessions

An ApiSessionEvent is emitted whenever an api session is created, deleted, refreshed or exchanged. Legacy sessions are only ever created or deleted. JWT sessions are created, refreshed and exchanged.

Valid api session event types are:

• created
• deleted
• refreshed
• exchanged

Valid api session types are:

• jwt
• legacy

Example:

{
    "namespace": "edge.apiSessions",
    "event_type": "created",
    "id": "ckvr2r4fs0001oigd6si4akc8",
    "timestamp": "2021-11-08T14:45:45.785561479-05:00",
    "token": "77cffde5-f68e-4ef0-bbb5-731db36145f5",
    "identity_id": "76BB.shC0",
    "ip_address": "127.0.0.1"
}

---

Fields

Field	Description	Type
namespace	The event group. The namespace for ApiSessionEvents is edge.apiSessions	string
event_src_id	The identifier of the controller which emitted the event	string
timestamp	The datetime that the event was generated	timestamp
event_type	The type api session event. See above for valid values.	string
id	id is the api session id.	string
type	type is the api session type. See above for valid values.	string
token	The api session token.	string
identity_id	The id of the identity that the api session belongs to.	string
ip_address	The IP address from which the identity to connected to require the api session.	string

CircuitEvent

Namespace: fabric.circuits

---

Fields

Field	Description	Type
namespace	The event group. The namespace for CircuitEvents is fabric.circuits	string
version		number (uint32)
event_type		string
event_src_id	The identifier of the controller which emitted the event	string
circuit_id		string
timestamp	The datetime that the event was generated	timestamp
client_id		string
service_id		string
terminator_id		string
instance_id		string
creation_timespan		duration
path		CircuitPath
link_count		number (int)
path_cost		number (uint32)
failure_cause		string
duration		duration
tags		map of string -> string

CircuitPath

---

Fields

Field	Description	Type
nodes		list of string
links		list of string
ingress_id		string
egress_id		string
initiator_local_addr		string
initiator_remote_addr		string
terminator_local_addr		string
terminator_remote_addr		string

ClusterEvent

Namespace: cluster

A ClusterEvent marks a change to the controller HA cluster. ClusterEvents can be of the following types:

• peer.connected
• peer.disconnected
• members.changed
• leadership.gained
• leadership.lost
• state.has_leader
• state.is_leaderless
• state.ro
• state.rw

---

Fields

Field	Description	Type
namespace	The event group. The namespace for ClusterEvents is cluster	string
event_src_id	The identifier of the controller which emitted the event	string
timestamp	The datetime that the event was generated	timestamp
eventType	The cluster event type. See above for set of valid types.	string
index	The raft index associated with the event.	number (uint64)
peers	This field is populated with all peers when membership change events or leadership is gained. It is populated with the connecting peer for connect events and the disconnecting peer for disconnect events. For other types it is omitted.	list of ClusterPeer
leaderId	The leader id. Only populated for state.has_leader events.	string

ApiAddress

An ApiAddress represents an endpoint on a controller. This may include things like REST management services and health checks.

---

Fields

Field	Description	Type
url	The URL of the API endpoint.	string
version	The version of the API endpoint. Endpoints are versioned independently of the controller version as these are expected to be stable over long periods.	string

ClusterPeer

A ClusterPeer represents a controller which is a member of the cluster.

---

Fields

Field	Description	Type
id	The controller id.	string
addr	The address at which the controller can be reached.	string
version	The version of the controller.	string
apiAddresses	The set of api addresses presented by the controller.	map of string -> list of ApiAddress

ConnectEvent

Namespace: connect

---

Fields

Field	Description	Type
namespace	The event group. The namespace for ConnectEvents is connect	string
event_src_id	The identifier of the controller which emitted the event	string
src_type		string
dst_type		string
src_id		string
src_addr		string
dst_id		string
dst_addr		string
timestamp	The datetime that the event was generated	timestamp

EntityChangeEvent

Namespace: entityChange

---

Fields

Field	Description	Type
namespace	The event group. The namespace for EntityChangeEvents is entityChange	string
eventId		string
eventType		string
event_src_id	The identifier of the controller which emitted the event	string
timestamp	The datetime that the event was generated	timestamp
metadata		map of string -> object
entityType		string
isParentEvent		boolean
initialState		object
finalState		object

EntityCountEvent

Namespace: edge.entityCounts

---

Fields

Field	Description	Type
namespace	The event group. The namespace for EntityCountEvents is edge.entityCounts	string
event_src_id	The identifier of the controller which emitted the event	string
timestamp	The datetime that the event was generated	timestamp
counts		map of string -> number (int64)
error		string

LinkEvent

Namespace: fabric.links

---

Fields

Field	Description	Type
namespace	The event group. The namespace for LinkEvents is fabric.links	string
event_type		string
event_src_id	The identifier of the controller which emitted the event	string
timestamp	The datetime that the event was generated	timestamp
link_id		string
src_router_id		string
dst_router_id		string
protocol		string
dial_address		string
cost		number (int32)
connections		list of LinkConnection

LinkConnection

---

Fields

Field	Description	Type
id		string
local_addr		string
remote_addr		string

MetricsEvent

Namespace: metrics

---

Fields

Field	Description	Type
metric_type		string
namespace	The event group. The namespace for MetricsEvents is metrics	string
event_src_id	The identifier of the controller which emitted the event	string
source_id		string
source_entity_id		string
version		number (uint32)
timestamp	The datetime that the event was generated	timestamp
metric		string
metrics		map of string -> object
tags		map of string -> string
source_event_id		string

RouterEvent

Namespace: fabric.routers

---

Fields

Field	Description	Type
namespace	The event group. The namespace for RouterEvents is fabric.routers	string
event_type		string
event_src_id	The identifier of the controller which emitted the event	string
timestamp	The datetime that the event was generated	timestamp
router_id		string
router_online		boolean

SdkEvent

Namespace: sdk

---

Fields

Field	Description	Type
namespace	The event group. The namespace for SdkEvents is sdk	string
event_type		string
event_src_id	The identifier of the controller which emitted the event	string
timestamp	The datetime that the event was generated	timestamp
identity_id		string

ServiceEvent

Namespace: services

---

Fields

Field	Description	Type
namespace	The event group. The namespace for ServiceEvents is services	string
version		number (uint32)
event_type		string
event_src_id	The identifier of the controller which emitted the event	string
service_id		string
terminator_id		string
count		number (uint64)
interval_start_utc		number (int64)
interval_length		number (uint64)

SessionEvent

Namespace: edge.sessions

---

Fields

Field	Description	Type
namespace	The event group. The namespace for SessionEvents is edge.sessions	string
event_type		string
event_src_id	The identifier of the controller which emitted the event	string
session_type		string
id		string
timestamp	The datetime that the event was generated	timestamp
token		string
api_session_id		string
identity_id		string
service_id		string

TerminatorEvent

Namespace: fabric.terminators

---

Fields

Field	Description	Type
namespace	The event group. The namespace for TerminatorEvents is fabric.terminators	string
event_type		string
event_src_id	The identifier of the controller which emitted the event	string
timestamp	The datetime that the event was generated	timestamp
service_id		string
terminator_id		string
router_id		string
host_id		string
router_online		boolean
precedence		string
static_cost		number (uint16)
dynamic_cost		number (uint16)
total_terminators		number (int)
usable_default_terminators		number (int)
usable_required_terminators		number (int)

UsageEvent

Namespace: fabric.usage

---

Fields

Field	Description	Type
namespace	The event group. The namespace for UsageEvents is fabric.usage	string
version		number (uint32)
event_type		string
event_src_id	The identifier of the controller which emitted the event	string
source_id		string
circuit_id		string
usage		number (uint64)
interval_start_utc		number (int64)
interval_length		number (uint64)
tags		map of string -> string