Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add doc generator for events. Add event doc. Fixes #2593 #2657

Merged
merged 1 commit into from
Jan 31, 2025
Merged

Add doc generator for events. Add event doc. Fixes #2593 #2657

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 46 additions & 7 deletions CHANGELOG.md
View file
Open in desktop
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
Open in desktop
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
Open in desktop
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
Loading