`), `status`, `errorCount`, `errors[]` of at most 20 `{code, componentId}`, `truncated` |
| `pattern/validate` | identity, `status`, `errorCount`, `errors[]` of at most 20 `{code, componentId}`, `truncated` - no `viewLink`. Meshery server does not emit this event; Meshery UI's `SchemaValidationFormatter` reads it in this shape |
| a failed design event | identity and `error` (the MeshKit error) |
`errorCount` is always the full count; `truncated` marks that `errors[]` was capped. `design` is allowed only as the two-field identity object - `models.IsDesignIdentityObject` is the check. Persisted metadata larger than 16 KB (`models.MaxEventMetadataBytes`) is reduced by `models.GuardEventMetadataSize` to the identity fields, `historyTitle` and that `design` object.
Readers must tolerate older rows: events stored earlier, and rows Meshery Cloud rewrote to this shape, may spell the identity in snake_case (`design_id`, `design_name`, `view_link`) and may lack `evaluationStatus`, `evaluationDurationMs` and `designLink`. A rewritten validate error's `code` is the JSON-schema keyword (`required`, `type`), not a MeshKit code. Meshery UI reads all of this through `ui/components/layout/NotificationCenter/formatters/design_event_metadata.ts`.
## Event Persistence in Meshery
Events in Meshery are persisted through two distinct mechanisms to ensure reliable event management. [Read more about providers](/reference/extensibility/providers/).
### Local Event Storage
The `provider.PersistEvent(*event,nil)` method stores all events in Meshery's local database. This method works identically for both Local and Remote providers, ensuring events are always accessible within your Meshery instance.
An event raised outside any user request - the registrant summaries and registration failures emitted while models are seeded at boot - has no provider to route through, and on a deployment that pins `PROVIDER` the provider registration map may not even hold the one you would name. Persist those through `HandlerConfig.SystemEventPersister`, which writes to the same local database. See [Enforced Provider Flow](/reference/extensibility/providers/) for why a name lookup is not an option there.
### Remote Event Publishing
The `provider.PublishEventToProvider(token, event)` method enables event synchronization with remote providers (like Meshery Cloud). For Local providers, this method is a no-op (does nothing), while Remote providers use it to send events to their remote services.
To see it in action and gain a better understanding, you can explore the [design_engine_handler.go](https://github.com/meshery/meshery/blob/master/server/handlers/design_engine_handler.go) file.
## An Example in Code
func (h *Handler) KubernetesPingHandler(w http.ResponseWriter, req *http.Request, _ *models.Preference, user *models.User, provider models.Provider) {
userID := uuid.FromStringOrNil(user.ID)
token, ok := req.Context().Value(models.TokenCtxKey).(string)
if !ok {
w.WriteHeader(http.StatusInternalServerError)
fmt.Fprintf(w, "failed to get the token for the user")
return
}
// Canonical query param is `connectionId` (camelCase per the schemas
// identifier-naming contract); legacy `connection_id` is still
// dual-accepted by handlers but should not be used in new client code.
connectionID := req.URL.Query().Get("connectionId")
eventBuilder := events.NewEvent().FromUser(userID).FromSystem(*h.SystemID).WithCategory("connection").WithAction("ping")
if connectionID != "" {
// Get the context associated with this ID
k8sContext, err := provider.GetK8sContext(token, connectionID)
eventBuilder.ActedUpon(uuid.FromStringOrNil(connectionID))
if err != nil {
eventBuilder.WithSeverity(events.Error).WithDescription(fmt.Sprintf("Encountered an issue while retrieving kubernetes context for connection ID `%s`", connectionID)).
WithMetadata(map[string]interface{}{
"error": err,
})
event := eventBuilder.Build()
_ = provider.PersistEvent(*event,nil)
go h.config.EventBroadcaster.Publish(userID, event)
w.WriteHeader(http.StatusInternalServerError)
fmt.Fprintf(w, "failed to get kubernetes context for the given ID")
return
}
eventBuilder.WithSeverity(events.Success).WithDescription("Retrieved kubernetes context successfully").
WithMetadata(map[string]interface{}{
"Context Name": k8sContext.Name,
"Server Address": k8sContext.Server,
})
event := eventBuilder.Build()
_ = provider.PersistEvent(*event,nil)
go h.config.EventBroadcaster.Publish(userID, event)
// Remaining code ...
}
}
In the given code block, the "resource" refers to the connection on which the server is performing the "ping" action. The "ActedUpon" field is supplied with the "connectionID" value obtained from the query parameter. `provider.GetK8sContext` returns the [K8sContext](https://github.com/meshery/meshery/blob/995ab671a12013088f874430cfa2c0f025b073d2/server/models/k8s_context.go#L26) object which serves as a representation of a Kubernetes context within the Meshery. if `provider.GetK8sContext` returns an error, the event is constructed with severity [Error](https://github.com/meshery/meshkit/blob/ea3c60907a1cd1902902a4113206579992772083/models/events/events.go#L18), description and enriched with metadata fields to provide the user with a complete context about the event.
If `provider.GetK8sContext` succeeds, an event with a [Success](https://github.com/meshery/meshkit/blob/ea3c60907a1cd1902902a4113206579992772083/models/events/events.go#L21) severity level is constructed. The event includes a success message and metadata containing the context name and the address of the Kubernetes API server, obtained from the operation. This information aims to provide users with relevant details about the successful operation.
after constructing the Event object using the Build function, event is stored into database for records and subsequently published in a new goroutine through [EventBroadcaster](https://github.com/meshery/meshery/blob/995ab671a12013088f874430cfa2c0f025b073d2/server/models/handlers.go#L241) member variable of [HandlerConfig](https://github.com/meshery/meshery/blob/995ab671a12013088f874430cfa2c0f025b073d2/server/models/handlers.go#L206), which is part of [Handler](https://github.com/meshery/meshery/blob/995ab671a12013088f874430cfa2c0f025b073d2/server/handlers/handler_instance.go#L18) instance.
To gain a deeper understanding and examine events more closely, you can explore the source code files [k8config_handler.go](https://github.com/meshery/meshery/blob/master/server/handlers/k8sconfig_handler.go) and [design_engine_handler.go](https://github.com/meshery/meshery/blob/master/server/handlers/design_engine_handler.go) within the Meshery project's codebase.
## Sending Events to Meshery Server
Meshery has two primary clients: Mesheryctl and Meshery UI. Both clients will produce multiple events throughout their lifecycle. Meshery Server is designed to accept these client-generated events and broadcast them using the [Broadcaster](https://github.com/meshery/meshery/blob/1b5d78ed34648e0a91df8c2273026b930f748fbc/server/models/event_broadcast.go#L14).
Clients can send HTTP POST requests to [`api/events`](/reference/rest-apis/) with the event encapsulated in a JSON request body. Upon receiving an event, the server processes, validates, and broadcasts it using the Broadcaster. This ensures that all relevant events generated by Mesheryctl and Meshery UI are effectively communicated and managed by the Meshery Server.
### Example
```javascript
async function sendClientEvent(clientId, eventPayload) {
// Create a new event
const event = {
category: "client_event",
action: "create",
severity: "info",
description: "Client event creation",
metadata: eventPayload,
};
try {
// Send event to Meshery Server
const response = await fetch("http://localhost:9081/api/events", {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify(event),
});
if (!response.ok) {
throw new Error(`Server returned non-200 status: ${response.status}`);
}
console.log("Event sent successfully");
} catch (error) {
console.error("Failed to send event:", error);
}
}
sendClientEvent(clientId, eventPayload);
```
