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
A CircuitEvent is emitted when circuits change.
Valid circuit event types are:
- created
- pathUpdated
- deleted
- failed
Fields
| Field | Description | Type |
|---|---|---|
| namespace | The event group. The namespace for CircuitEvents is fabric.circuits | string |
| event_src_id | The identifier of the controller which emitted the event | string |
| timestamp | The datetime that the event was generated | timestamp |
| version | The event format version. Currently 2. | number (uint32) |
| event_type | The circuit event type. See above for valid circuit event types. | string |
| circuit_id | The circuit id. | string |
| client_id | Who the circuit was created for. Usually an edge session id. | string |
| service_id | The id of the circuit's service. | string |
| terminator_id | The terminator the circuit is using. | string |
| instance_id | The instance id of the terminator. | string |
| creation_timespan | How long it look to create the circuit. | duration |
| path | The circuit's path. | CircuitPath |
| link_count | How many links the circuit is using. | number (int) |
| path_cost | The circuit's cost at the time of creation or update. | number (uint32) |
| failure_cause | The reason the circuit failed. Only populated for circuit failures. | string |
| duration | How long the circuit has been up. Not populated for circuit creates. | duration |
| tags | Contains circuit enrichment data. May contain information like the client and/or host identity ids. | map of string -> string |
CircuitPath
A CircuitPath encapsulates information about the circuit's path.
Fields
| Field | Description | Type |
|---|---|---|
| nodes | The routers traversed in the path, going from initiating router to terminating router. | list of string |
| links | The links traversed in the path, going from initiating router to terminating router. If the initiating and terminating routers are the same, this will be empty. | list of string |
| ingress_id | The xgress identifier used on the initiating router. | string |
| egress_id | The xgress identifier used on the terminating router. | string |
| initiator_local_addr | The local address of the connection to the first ziti component. | string |
| initiator_remote_addr | The remote addresss of the connection to the first ziti component. | string |
| terminator_local_addr | The local address on the terminating ziti component. | string |
| terminator_remote_addr | The remote address on the terminating ziti component. | 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
A ConnectEvent is emitted when a connection is made to a ziti controller or router.
Valid source types are:
- router - router connecting to a controller or another router)
- peer - controller connecting to another controller
- identity - identity connecting to a router or controller
Valid destination types are:
- ctrl - connection is being made to a controller
- router - connection is being made to a router
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 |
| timestamp | The datetime that the event was generated | timestamp |
| src_type | The type of software initiating the connection. | string |
| dst_type | The type of software receiving the connection. | string |
| src_id | The id of the initiating component. | string |
| src_addr | The source address of the connection. | string |
| dst_id | The id of the receiving component. | string |
| dst_addr | The destination address of the connection. | string |
EntityChangeEvent
Namespace: entityChange
An EntityChangeEvent is emitted when a entity in the data model changes.
Valid entity change event types are:
- created
- updated
- deleted
- committed
Entity change events happen in two parts. First the created,updated or deleted event is emitted. This happens inside a transaction. After the transaction is committed, a committed event with the same event id is generated. This lets the event consumer know that the event is finalized. All changes within a transaction will share the same event id. If a new event id is seen before the previous event is committed, that indicates that the transaction was rolled back.
Fields
| Field | Description | Type |
|---|---|---|
| namespace | The event group. The namespace for EntityChangeEvents is entityChange | string |
| event_src_id | The identifier of the controller which emitted the event | string |
| timestamp | The datetime that the event was generated | timestamp |
| eventId | An identifier shared by all changes in a given transaction. | string |
| eventType | The entity change event type. See above for valid values. | string |
| metadata | metadata will include information about who initiated the change and how. | map of string -> object |
| entityType | The type of the entity being changed. | string |
| isParentEvent | True if the entity type has a parent type (like services and routers), and this event only contains the parent data. | boolean |
| initialState | The state before the change. Will be empty for creates. | object |
| finalState | The state after the change. Will be empty for deletes. | 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 |