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

Type	Description	Examples
timestamp	RFC3339 formatted timestamp string	"2024-10-02T12:17:39.501821249-04:00"
duration	Number representing a duration in nanoseconds	104100

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_src_id" : "ctrl1",
    "timestamp": "2021-11-08T14:45:45.785561479-05:00",
    "event_type": "created",
    "id": "ckvr2r4fs0001oigd6si4akc8",
    "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 for various stages of a circuit lifecycle.

Valid circuit event types are:

created
pathUpdated
deleted
failed

Example:

{
    "namespace": "fabric.circuits",
    "event_src_id": "ctrl1",
    "timestamp": "2023-05-05T11:44:03.242399585-04:00",
    "version": 2,
    "event_type": "created",
    "circuit_id": "0CEjWYiw6",
    "client_id": "clbaq7u7600o4ucgdpxy9i4t1",
    "service_id": "QbRLLTKjqfLZytmSsIqba",
    "terminator_id": "7edcd421-2b00-4b49-9ac0-8c78fe388c30",
    "instance_id": "",
    "creation_timespan": 1014280,
    "path": {
        "nodes": [
            "U7OwPtfjf",
            "a4rC9DrZd"
        ],
        "links": [
            "7Ru3hoxsfsZzUNOyvd8Jcb"
        ],
        "ingress_id": "K9lD",
        "egress_id": "rQLK",
        "initiator_local_addr": "192.168.0.1:1234",
        "initiator_remote_addr": "192.168.0.1:37640",
        "terminator_local_addr": "127.0.0.1:45566",
        "terminator_remote_addr": "127.0.0.1:1234"
    },
    "link_count": 1,
    "path_cost": 392151,
    "tags": {
        "clientId": "a7OwPtfjg",
        "hostId": "c4rC9DrZ3",
        "serviceId": "QbRLLTKjqfLZytmSsIqba"
    }
}

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

Examples:

{
    "namespace": "connect",
    "event_src_id": "ctrl_client",
    "timestamp": "2024-10-02T12:17:39.501821249-04:00"
    "src_type": "identity",
    "src_id": "ji2Rt8KJ4",
    "src_addr": "127.0.0.1:59336",
    "dst_id": "ctrl_client",
    "dst_addr": "localhost:1280/edge/management/v1/edge-routers/2L7NeVuGBU",
}

{
    "namespace": "connect",
    "event_src_id": "ctrl_client",
    "timestamp": "2024-10-02T12:17:40.529865849-04:00"
    "src_type": "router",
    "src_id": "2L7NeVuGBU",
    "src_addr": "127.0.0.1:42702",
    "dst_id": "ctrl_client",
    "dst_addr": "127.0.0.1:6262",
}

{
    "namespace": "connect",
    "event_src_id": "ctrl1",
    "timestamp": "2024-10-02T12:37:04.490859197-04:00"
    "src_type": "peer",
    "src_id": "ctrl2",
    "src_addr": "127.0.0.1:40056",
    "dst_id": "ctrl1",
    "dst_addr": "127.0.0.1:6262",
}

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.

Examples:

{
    "namespace": "entityChange",
    "event_src_id": "ctrl1",
    "timestamp": "2023-05-11T21:41:47.128588927-04:00",
    "eventId": "326faf6c-8123-42ae-9ed8-6fd9560eb567",
    "eventType": "created",
    "metadata": {
        "author": {
            "type": "identity",
            "id": "ji2Rt8KJ4",
            "name": "Default Admin"
        },
        "source": {
            "type": "rest",
            "auth": "edge",
            "localAddr": "localhost:1280",
            "remoteAddr": "127.0.0.1:37578",
            "method": "POST"
        },
        "version": "v0.0.0"
    },
    "entityType": "services",
    "isParentEvent": false,
    "initialState": null,
    "finalState": {
        "id": "6S0bCGWb6yrAutXwSQaLiv",
        "createdAt": "2023-05-12T01:41:47.128138887Z",
        "updatedAt": "2023-05-12T01:41:47.128138887Z",
        "tags": {},
        "isSystem": false,
        "name": "test",
        "terminatorStrategy": "smartrouting",
        "roleAttributes": [
            "goodbye",
            "hello"
        ],
        "configs": null,
        "encryptionRequired": true
    }
}

{
    "namespace": "entityChange",
    "event_src_id": "ctrl1",
    "timestamp": "2023-05-11T21:41:47.129235443-04:00"
    "eventId": "326faf6c-8123-42ae-9ed8-6fd9560eb567",
    "eventType": "committed",
}

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

A EntityCountEvent is emitted on a configurable interval. It contains the entity counts for all of the entities in the data model.

Examples:

{
    "namespace": "edge.entityCounts",
    "event_src_id": "ctrl_client",
    "timestamp": "2025-01-16T20:34:47.281325752-05:00",
    "counts": {
        "apiSessionCertificates": 0,
        "apiSessions": 1,
        "authPolicies": 1,
        "authenticators": 5,
        "cas": 0,
        "configTypes": 6,
        "configs": 4,
        "controllers": 0,
        "edgeRouterPolicies": 7,
        "enrollments": 11,
        "eventualEvents": 0,
        "externalJwtSigners": 0,
        "identities": 16,
        "identityTypes": 2,
        "mfas": 0,
        "postureCheckTypes": 5,
        "postureChecks": 0,
        "revocations": 0,
        "routers": 7,
        "routers.edge": 7,
        "serviceEdgeRouterPolicies": 1,
        "servicePolicies": 4,
        "services": 2,
        "services.edge": 2,
        "sessions": 0,
        "terminators": 0
    },
    "error": ""
}

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 entity type to the number of entities of that type that currently exist in the data model.	map of string -> number (int64)
error	If an error is encountered while collecting entity counts, it will be reported here.	string

LinkEvent

Namespace: fabric.links

A LinkEvent will be emitted for various link lifecycle events.

Valid values for link event types are:

dialed
fault
duplicate
connected
routerLinkNew
routerLinkKnown
routerLinkDisconnectedDest

Examples:

{
    "namespace": "fabric.links",
    "event_src_id": "ctrl1",
    "timestamp": "2022-07-15T18:10:19.752766075-04:00",
    "event_type": "dialed",
    "link_id": "47kGIApCXI29VQoCA1xXWI",
    "src_router_id": "niY.XmLArx",
    "dst_router_id": "YPpTEd8JP",
    "protocol": "tls",
    "dial_address": "tls:127.0.0.1:4024",
    "cost": 1
}

{
    "namespace": "fabric.links",
    "event_src_id": "ctrl1",
    "timestamp": "2022-07-15T18:10:19.973626185-04:00",
    "event_type": "connected",
    "link_id": "47kGIApCXI29VQoCA1xXWI",
    "src_router_id": "niY.XmLArx",
    "dst_router_id": "YPpTEd8JP",
    "protocol": "tls",
    "dial_address": "tls:127.0.0.1:4024",
    "cost": 1,
    "connections": [
        {
            "id": "ack",
            "local_addr": "tcp:127.0.0.1:49138",
            "remote_addr": "tcp:127.0.0.1:4024"
        },
        {
            "id": "payload",
            "local_addr": "tcp:127.0.0.1:49136",
            "remote_addr": "tcp:127.0.0.1:4024"
        }
    ]
}

{
    "namespace": "fabric.links",
    "event_src_id": "ctrl1",
    "timestamp": "2022-07-15T18:10:19.973867809-04:00",
    "event_type": "fault",
    "link_id": "6slUYCqOB85YTfdiD8I5pl",
    "src_router_id": "YPpTEd8JP",
    "dst_router_id": "niY.XmLArx",
    "protocol": "tls",
    "dial_address": "tls:127.0.0.1:4023",
    "cost": 1
}

{
    "namespace": "fabric.links",
    "event_src_id": "ctrl1",
    "timestamp": "2022-07-15T18:10:19.974177638-04:00",
    "event_type": "routerLinkKnown",
    "link_id": "47kGIApCXI29VQoCA1xXWI",
    "src_router_id": "niY.XmLArx",
    "dst_router_id": "YPpTEd8JP",
    "protocol": "tls",
    "dial_address": "tls:127.0.0.1:4024",
    "cost": 1
}

Fields

Field	Description	Type
namespace	The event group. The namespace for LinkEvents is fabric.links	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 link event type. See above for valid values.	string
link_id	The link identifier.	string
src_router_id	The id of the dialing router.	string
dst_router_id	The id of the accepting router.	string
protocol	The link protocol.	string
dial_address	The address dialed.	string
cost	The link cost.	number (int32)
connections	The connections making up the link.	list of LinkConnection

LinkConnection

A LinkConnection describes a physical connection that forms a link. A Link may be made up of multiple LinkConnections.

Link ids currently have three valid values:

single - meaning the link has a single connection
payload - a connection used only for payloads
ack - a connection used only for acks

Fields

Field	Description	Type
id	The connection identifier.	string
local_addr	The connection address on dialing router side.	string
remote_addr	The connection address on accepting router side.	string

MetricsEvent

Namespace: metrics

A MetricsEvent represents a point in time snapshot of a metric from a controller or router.

Valid values for metric type are:

intValue
floatValue
meter
histogram
timer

Examples:

{
    "namespace": "metrics",
    "event_src_id": "ctrl_client",
    "timestamp": "2025-01-17T02:45:21.890823877Z",
    "metric_type": "meter",
    "source_id": "ctrl_client",
    "version": 3,
    "metric": "service.policy.enforcer.run.deletes",
    "metrics": {
        "count": 0,
        "m15_rate": 0,
        "m1_rate": 0,
        "m5_rate": 0,
        "mean_rate": 0
    },
    "source_event_id": "c41fbf8d-cd14-4b8b-ae7b-0f0e93e2021d"
}

{
    "namespace": "metrics",
    "event_src_id": "ctrl_client",
    "timestamp": "2025-01-17T02:45:21.890823877Z",
    "metric_type": "timer",
    "source_id": "ctrl_client",
    "version": 3,
    "metric": "api-session.create",
    "metrics": {
        "count": 1,
        "m15_rate": 0.0006217645754885097,
        "m1_rate": 0.000002754186169011774,
        "m5_rate": 0.0005841004612303224,
        "max": 7598246,
        "mean": 7598246,
        "mean_rate": 0.0018542395091967903,
        "min": 7598246,
        "p50": 7598246,
        "p75": 7598246,
        "p95": 7598246,
        "p99": 7598246,
        "p999": 7598246,
        "p9999": 7598246,
        "std_dev": 0,
        "variance": 0
    },
    "source_event_id": "c41fbf8d-cd14-4b8b-ae7b-0f0e93e2021d"
}

Fields

Field	Description	Type
namespace	The event group. The namespace for MetricsEvents is metrics	string
event_src_id	The identifier of the controller which emitted the event	string
timestamp	The datetime that the event was generated	timestamp
metric_type	The type of metrics event. See above for valid values.	string
source_id	The id of the router or controller which emitted the metric.	string
source_entity_id	If this metric is associated with an entity, such as link, this will contain the entity id.	string
version	The version of the metrics format. The current version is 3.	number (uint32)
metric	The name of the metric.	string
metrics	The values that copmrise the metrics.	map of string -> object
tags	Some metrics include additional metadata. For example link metrics may include source and destination.	map of string -> string
source_event_id	Events will often be collected together on a schedule. This is a correlation id so that events can be tied together with other events emitted at the same time.	string

RouterEvent

Namespace: fabric.routers

A RouterEvent is generated when a router comes online or goes offline.

Valid values for router event type are:

router-online
router-offline

Examples:

{
    "namespace": "fabric.routers",
    "event_src_id": "ctrl1",
    "event_type": "router-online",
    "timestamp": "2021-04-22T11:26:31.99299884-04:00",
    "router_id": "JAoyjafljO",
    "router_online": true
}

{
    "namespace": "fabric.routers",
    "event_src_id": "ctrl1",
    "event_type": "router-offline",
    "timestamp": "2021-04-22T11:26:41.335114358-04:00",
    "router_id": "JAoyjafljO",
    "router_online": false
}

Fields

Field	Description	Type
namespace	The event group. The namespace for RouterEvents is fabric.routers	string
timestamp	The datetime that the event was generated	timestamp
event_src_id	The identifier of the controller which emitted the event	string
event_type	The router event type.	string
router_id	The router identifier.	string
router_online	Indicates whether the router is online or not. Redundant given the router event type. Should likely be removed.	boolean

SdkEvent

Namespace: sdk

An SdkEvent is emitted when an sdk's connectivity to routers changes.

Valid values for sdk event type are:

sdk-online
sdk-offline
sdk-status-unknown

Examples:

{
    "namespace": "sdk",
    "event_src_id": "ctrl1",
    "event_type" : "sdk-online",
    "identity_id": "ji2Rt8KJ4",
    "timestamp": "2024-10-02T12:17:39.501821249-04:00"
}

{
    "namespace": "sdk",
    "event_src_id": "ctrl1",
    "event_type" : "sdk-status-unknown",
    "identity_id": "ji2Rt8KJ4",
    "timestamp": "2024-10-02T12:17:40.501821249-04:00"
}

{
    "namespace": "sdk",
    "event_src_id": "ctrl1",
    "event_type" : "sdk-offline",
    "identity_id": "ji2Rt8KJ4",
    "timestamp": "2024-10-02T12:17:41.501821249-04:00"
}

Fields

Field	Description	Type
namespace	The event group. The namespace for SdkEvents is sdk	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 sdk event type. See above for valid values.	string
identity_id	The id of the identity whose connectivity state has changed.	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

Introduction​

Common Fields​

Time Related Types​

Event Types​

ApiSessionEvent​

CircuitEvent​

CircuitPath​

ClusterEvent​

ApiAddress​

ClusterPeer​

ConnectEvent​

EntityChangeEvent​

EntityCountEvent​

LinkEvent​

LinkConnection​

MetricsEvent​

RouterEvent​

SdkEvent​

ServiceEvent​

SessionEvent​

TerminatorEvent​

UsageEvent​

Introduction

Common Fields

Time Related Types

Event Types

ApiSessionEvent

CircuitEvent

CircuitPath

ClusterEvent

ApiAddress

ClusterPeer

ConnectEvent

EntityChangeEvent

EntityCountEvent

LinkEvent

LinkConnection

MetricsEvent

RouterEvent

SdkEvent

ServiceEvent

SessionEvent

TerminatorEvent

UsageEvent