Skip to content

Commit

Permalink
Add doc generator for events. Add event doc. Fixes #2593
Browse files Browse the repository at this point in the history
  • Loading branch information
@plorenz
plorenz committed Jan 31, 2025
1 parent 3bf4aea commit 110446a
Show file tree
Hide file tree
Showing 45 changed files with 2,498 additions and 314 deletions.
53 changes: 46 additions & 7 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,48 @@

## What's New

* Moved `ziti ops verify-network` to `ziti ops verify network`
* Moved `ziti ops verify traffic` to `ziti ops verify traffic`
* Added `ziti ops verify ext-jwt-signer oidc` to help users with configuring OIDC external auth
* Use `cluster` consistently for cluster operations
* Bug Fixes
* Event Doc and Consistency
* ziti ops verify changes
* Moved `ziti ops verify-network` to `ziti ops verify network`
* Moved `ziti ops verify traffic` to `ziti ops verify traffic`
* Added `ziti ops verify ext-jwt-signer oidc` to help users with configuring OIDC external auth
* Bug fixes

## Event Doc and Consistency

The event types are now exhaustively documented as part of the [OpenZiti Reference Documentation](https://openziti.io/docs/reference/events).

During documentation, some inconsistencies were found the following changes were made.

### Namespace Cleanup
Namespaces have been cleaned up, with the following changes:

* edge.apiSessions -> apiSession
* fabric.circuits -> circuit
* edge.entityCount -> entityCount
* fabric.links -> link
* fabric.routers -> router
* services -> service
* edge.sessions -> session
* fabric.terminators -> terminator
* fabric.usage -> usage

Note that service events used `services` in the config file, but `service.events` in the event itself.
The old namespaces still work. If the old event type is used in the config file, the old namespace will be in the events as well

### Timestamp field

The following event types now have a timestamp field:

* service
* usage

This timestamp is the time the event was generated.

### Event Source ID
All event types now have a new field: `event_src_id`. This field is the id of the controller
which emitted the event. This may be useful in HA environments, during event processing.

## Cluster Operations Naming

Expand All @@ -17,11 +54,13 @@ The Raft APIs available in the fabric management API are now namespaced under Cl
## Component Updates and Bug Fixes

* github.com/openziti/ziti: [v1.3.3 -> v1.4.0](https://github.com/openziti/ziti/compare/v1.3.3...v1.4.0)
* [Issue #2720](https://github.com/openziti/ziti/issues/2720) - new verify oidc command on prints usage
* [Issue #2546](https://github.com/openziti/ziti/issues/2546) - Use consistent terminology for HA
* [Issue #2713](https://github.com/openziti/ziti/issues/2713) - Routers with no edge components shouldn't subscribe to RDM updates

# Release 1.3.3

# What's New
## What's New

* Bug Fixes

Expand All @@ -33,7 +72,7 @@ The Raft APIs available in the fabric management API are now namespaced under Cl

# Release 1.3.2

# What's New
## What's New

* Bug Fixes

Expand All @@ -45,7 +84,7 @@ The Raft APIs available in the fabric management API are now namespaced under Cl

# Release 1.3.1

# What's New
## What's New

* Bug Fixes

Expand Down
53 changes: 46 additions & 7 deletions controller/event/api_session.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,21 +25,60 @@ const ApiSessionEventTypeCreated = "created"
const ApiSessionEventTypeDeleted = "deleted"
const ApiSessionEventTypeRefreshed = "refreshed"
const ApiSessionEventTypeExchanged = "exchanged"
const ApiSessionEventNS = "edge.apiSessions"
const ApiSessionEventNS = "apiSession"

const ApiSessionTypeLegacy = "legacy"
const ApiSessionTypeJwt = "jwt"

// 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.
//
// Note: In version prior to 1.4.0, the namespace was `edge.apiSessions`
//
// Valid api session event types are:
// - created
// - deleted
// - refreshed
// - exchanged
//
// Valid api session types are:
// - jwt
// - legacy
//
// Example: Api Session Created Event
//
// {
// "namespace": "apiSession",
// "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"
// }
type ApiSessionEvent struct {
Namespace string `json:"namespace"`
EventType string `json:"event_type"`
EventSrcId string `json:"event_src_id"`
Id string `json:"id"`
Type string `json:"type"`
Timestamp time.Time `json:"timestamp"`
Token string `json:"token"`
IdentityId string `json:"identity_id"`
IpAddress string `json:"ip_address"`

// The type api session event. See above for valid values.
EventType string `json:"event_type"`

// Id is the api session id.
Id string `json:"id"`

// Type is the api session type. See above for valid values.
Type string `json:"type"`

// The api session token.
Token string `json:"token"`

// The id of the identity that the api session belongs to.
IdentityId string `json:"identity_id"`

// The IP address from which the identity to connected to require the api session.
IpAddress string `json:"ip_address"`
}

func (event *ApiSessionEvent) String() string {
Expand Down
197 changes: 171 additions & 26 deletions controller/event/circuits.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,8 @@ import (
type CircuitEventType string

const (
CircuitEventsNs = "fabric.circuits"
CircuitEventNS = "circuit"

CircuitEventsVersion = 2
CircuitCreated CircuitEventType = "created"
CircuitUpdated CircuitEventType = "pathUpdated"
Expand All @@ -34,15 +35,32 @@ const (

var CircuitEventTypes = []CircuitEventType{CircuitCreated, CircuitUpdated, CircuitDeleted, CircuitFailed}

// A CircuitPath encapsulates information about the circuit's path.
type CircuitPath struct {
Nodes []string `json:"nodes"`
Links []string `json:"links"`
IngressId string `json:"ingress_id"`
EgressId string `json:"egress_id"`
InitiatorLocalAddr string `json:"initiator_local_addr,omitempty"`
InitiatorRemoteAddr string `json:"initiator_remote_addr,omitempty"`
TerminatorLocalAddr string `json:"terminator_local_addr,omitempty"`
TerminatorRemoteAddr string `json:"terminator_remote_addr,omitempty"`
// The routers traversed in the path, going from initiating router to terminating router.
Nodes []string `json:"nodes"`

// 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.
Links []string `json:"links"`

// The xgress identifier used on the initiating router.
IngressId string `json:"ingress_id"`

// The xgress identifier used on the terminating router.
EgressId string `json:"egress_id"`

// The local address of the connection to the first ziti component.
InitiatorLocalAddr string `json:"initiator_local_addr,omitempty"`

// The remote address of the connection to the first ziti component.
InitiatorRemoteAddr string `json:"initiator_remote_addr,omitempty"`

// The local address on the terminating ziti component.
TerminatorLocalAddr string `json:"terminator_local_addr,omitempty"`

// The remote address on the terminating ziti component.
TerminatorRemoteAddr string `json:"terminator_remote_addr,omitempty"`
}

func (self *CircuitPath) String() string {
Expand All @@ -60,24 +78,151 @@ func (self *CircuitPath) String() string {
return out
}

// A CircuitEvent is emitted for various stages of a circuit lifecycle.
//
// Note: In version prior to 1.4.0, the namespace was `fabric.circuits`
//
// Valid circuit event types are:
// - created
// - pathUpdated
// - deleted
// - failed
//
// Example: Circuit Created Event
//
// {
// "namespace": "circuit",
// "event_src_id": "ctrl_client",
// "timestamp": "2025-01-17T14:09:13.603009739-05:00",
// "version": 2,
// "event_type": "created",
// "circuit_id": "rqrucElFe",
// "client_id": "cm614ve9h00fb1xj9dfww20le",
// "service_id": "3pjMOKY2icS8fkQ1lfHmrP",
// "terminator_id": "7JgrjMgEAis7V5q1wjvoB4",
// "instance_id": "",
// "creation_timespan": 1035941,
// "path": {
// "nodes": [
// "5g2QrZxFcw"
// ],
// "links": null,
// "ingress_id": "8dN7",
// "egress_id": "ZnXG"
// },
// "link_count": 0,
// "path_cost": 262140,
// "tags": {
// "clientId": "haxn9lB0uc",
// "hostId": "IahyE.5Scw",
// "serviceId": "3pjMOKY2icS8fkQ1lfHmrP"
// }
// }
//
// Example: Circuit Deleted Event
//
// {
// "namespace": "circuit",
// "event_src_id": "ctrl_client",
// "timestamp": "2025-01-17T14:09:15.138049308-05:00",
// "version": 2,
// "event_type": "deleted",
// "circuit_id": "rqrucElFe",
// "client_id": "cm614ve9h00fb1xj9dfww20le",
// "service_id": "3pjMOKY2icS8fkQ1lfHmrP",
// "terminator_id": "7JgrjMgEAis7V5q1wjvoB4",
// "instance_id": "",
// "path": {
// "nodes": [
// "5g2QrZxFcw"
// ],
// "links": null,
// "ingress_id": "8dN7",
// "egress_id": "ZnXG"
// },
// "link_count": 0,
// "duration": 1535040544,
// "tags": {
// "clientId": "haxn9lB0uc",
// "hostId": "IahyE.5Scw",
// "serviceId": "3pjMOKY2icS8fkQ1lfHmrP"
// }
// }
//
// Example: Circuit Failed Event
//
// {
// "namespace": "circuit",
// "event_src_id": "ctrl_client",
// "timestamp": "2025-01-17T14:09:30.563045771-05:00",
// "version": 2,
// "event_type": "failed",
// "circuit_id": "JvIucEQHe",
// "client_id": "cm614vrcd00fu1xj931hzepec",
// "service_id": "3pjMOKY2icS8fkQ1lfHmrP",
// "terminator_id": "",
// "instance_id": "",
// "creation_timespan": 20701,
// "path": {
// "nodes": null,
// "links": null,
// "ingress_id": "",
// "egress_id": ""
// },
// "link_count": 0,
// "failure_cause": "NO_TERMINATORS",
// "tags": {
// "clientId": "haxn9lB0uc",
// "serviceId": "3pjMOKY2icS8fkQ1lfHmrP"
// }
// }
type CircuitEvent struct {
Namespace string `json:"namespace"`
Version uint32 `json:"version"`
EventType CircuitEventType `json:"event_type"`
EventSrcId string `json:"event_src_id"`
CircuitId string `json:"circuit_id"`
Timestamp time.Time `json:"timestamp"`
ClientId string `json:"client_id"`
ServiceId string `json:"service_id"`
TerminatorId string `json:"terminator_id"`
InstanceId string `json:"instance_id"`
CreationTimespan *time.Duration `json:"creation_timespan,omitempty"`
Path CircuitPath `json:"path"`
LinkCount int `json:"link_count"`
Cost *uint32 `json:"path_cost,omitempty"`
FailureCause *string `json:"failure_cause,omitempty"`
Duration *time.Duration `json:"duration,omitempty"`
Tags map[string]string `json:"tags"`
Namespace string `json:"namespace"`
EventSrcId string `json:"event_src_id"`
Timestamp time.Time `json:"timestamp"`

// The event format version. Currently 2.
Version uint32 `json:"version"`

// The circuit event type. See above for valid circuit event types.
EventType CircuitEventType `json:"event_type"`

// The circuit id.
CircuitId string `json:"circuit_id"`

// Who the circuit was created for. Usually an edge session id.
ClientId string `json:"client_id"`

// The id of the circuit's service.
ServiceId string `json:"service_id"`

// The terminator the circuit is using.
TerminatorId string `json:"terminator_id"`

// The instance id of the terminator.
InstanceId string `json:"instance_id"`

// How long it look to create the circuit.
CreationTimespan *time.Duration `json:"creation_timespan,omitempty"`

// The circuit's path.
Path CircuitPath `json:"path"`

// How many links the circuit is using.
LinkCount int `json:"link_count"`

// The circuit's cost at the time of creation or update.
Cost *uint32 `json:"path_cost,omitempty"`

// The reason the circuit failed. Only populated for circuit failures.
FailureCause *string `json:"failure_cause,omitempty"`

// How long the circuit has been up. Not populated for circuit creates.
Duration *time.Duration `json:"duration,omitempty"`

// Contains circuit enrichment data. May contain information like the client and/or host
// identity ids.
Tags map[string]string `json:"tags"`
}

func (event *CircuitEvent) String() string {
Expand Down
Loading

0 comments on commit 110446a

Please sign in to comment.