From e00f5c760247f0589204460b2a0c4854a97e3056 Mon Sep 17 00:00:00 2001 From: Nick Gerace Date: Wed, 11 Dec 2024 18:12:30 -0500 Subject: [PATCH] Add audit trail reference and entity vocab This commit adds an audit trail reference document and entity-based vocabulary words. Signed-off-by: Nick Gerace --- app/docs/src/reference/audit-trail.md | 124 ++++++++++++++++++++++++++ app/docs/src/reference/index.md | 2 + app/docs/src/reference/vocabulary.md | 13 +++ 3 files changed, 139 insertions(+) create mode 100644 app/docs/src/reference/audit-trail.md diff --git a/app/docs/src/reference/audit-trail.md b/app/docs/src/reference/audit-trail.md new file mode 100644 index 0000000000..47ac7a942d --- /dev/null +++ b/app/docs/src/reference/audit-trail.md @@ -0,0 +1,124 @@ +# Audit Trail Reference + +The Audit Trail feature gives you the ability to know what is going on inside +of your workspace with real-time updates. Through a structured log format and a +sleek, spreadsheet-like interface, you can see mutations to the system and scope +them by entity name, user, change set and more. + +## Audit Log Structure + +All Audit Logs share the same structure, which includes the entity name, entity +type, kind, metadata and more. However, the metadata field’s structure will +change based on the Audit Log kind. This gives each Audit Log kind the ability +to attach kind-specific information, such as showing the “before value” and +“after value” when updating a property for a component. + +Let's look at two examples showcasing the consistent structure with +kind-dependent metadata in action. Here is an example of an Audit Log for a +Component that has been deleted: + +```json +{ + // The title that will be displayed. + "title": "Deleted", + // The name of the user who caused the event at the time of the event. + "userName": "nick", + // The ID of the user who caused the event. + "userId": "01GW7GQW71JD7B5GV6VBNJBRME", + // The email of the user who caused the event at the time of the event. + "userEmail": "nick@systeminit.com", + // The kind of Audit Log that was created. + "kind": "DeleteComponent", + // The type of entity involved in the event. + "entityType": "Component", + // The name of the entity involved in the event. + "entityName": "AWS Credential", + // The metadata for the event that corresponds to the Audit Log kind. + "metadata": { + // An inner field containing the same name as the entity name. + "name": "AWS Credential", + // The ID of the Component deleted. + "componentId": "01JE77FDSNEY9HECH5CRMME2XK", + // The ID of the SchemaVariant that the Component was based on. + "schemaVariantId": "01J8FRJB6ESMBMCMM2PBC1SJJY", + // The name of the aforementioned SchemaVariant. + "schemaVariantName": "AWS Credential" + }, + // This is when the event happened. + "timestamp": "2024-12-03T21:43:04.607739+00:00", + // The ID of the ChangeSet where the event happened. + "changeSetId": "01JE77M419EP6P8GVBYKRWWY6S", + // The name of the aforementioned ChangeSet. + "changeSetName": "2024-12-03-21:43" +} +``` + +Now, here is another example for that same Component, but for when one of its +properities was modified: + +```json +{ + "title": "Updated Component", + "userName": "nick", + "userId": "01GW7GQW71JD7B5GV6VBNJBRME", + "userEmail": "nick@systeminit.com", + "kind": "UpdatePropertyEditorValue", + "entityType": "Property", + "entityName": "name", + // All top-level fields have remained the same, except for those inside the + // metadata field. The inner fields will changed based on the Audit Log Kind. + "metadata": { + "propId": "01J8FRJB6ESMBMCMM2PBC1SJK8", + "propName": "name", + "afterValue": "AWS Credential", + "beforeValue": "si-1002", + "componentId": "01JE77FDSNEY9HECH5CRMME2XK", + "componentName": "AWS Credential", + "schemaVariantId": "01J8FRJB6ESMBMCMM2PBC1SJJY", + "attributeValueId": "01JE77FDSQ30ANJP1021Z0N438", + "schemaVariantDisplayName": "AWS Credential" + }, + "timestamp": "2024-12-03T21:40:55.268312+00:00", + "changeSetId": "01JE77F4E5P1S4228A3P5978NR", + "changeSetName": "2024-12-03-21:40" +} +``` + +Let's say that a new field has been added to the metadata for an +`UpdatePropertyEditorValue` event. It is called `containsWhitespace` and +indicates whether or not the `afterValue` contains a whitespace. + +While this scenario is a bit contrived, it shows that metadata not only changes +for a given kind, but can also be expanded in the future, so long as the change +is backwards-compatible. Here is an example using the same Audit Logas as above, +but with the new field: + +```json +{ + "title": "Updated Component", + "userName": "nick", + "userId": "01GW7GQW71JD7B5GV6VBNJBRME", + "userEmail": "nick@systeminit.com", + // The kind is the same as the above Audit Log. + "kind": "UpdatePropertyEditorValue", + "entityType": "Property", + "entityName": "name", + // The metadata is the same as the above Audit Log, except it has a new field. + "metadata": { + "propId": "01J8FRJB6ESMBMCMM2PBC1SJK8", + "propName": "name", + "afterValue": "AWS Credential", + "beforeValue": "si-1002", + "componentId": "01JE77FDSNEY9HECH5CRMME2XK", + "componentName": "AWS Credential", + "schemaVariantId": "01J8FRJB6ESMBMCMM2PBC1SJJY", + "attributeValueId": "01JE77FDSQ30ANJP1021Z0N438", + "schemaVariantDisplayName": "AWS Credential", + // This is the new field! + "containsWhitespace": true + }, + "timestamp": "2024-12-03T21:40:55.268312+00:00", + "changeSetId": "01JE77F4E5P1S4228A3P5978NR", + "changeSetName": "2024-12-03-21:40" +} +``` diff --git a/app/docs/src/reference/index.md b/app/docs/src/reference/index.md index 88c9e9d5ae..7cdda81fa9 100644 --- a/app/docs/src/reference/index.md +++ b/app/docs/src/reference/index.md @@ -5,6 +5,8 @@ of System Initiative. - [Asset Schema](./asset/schema.md) - all the options for creating asset schema - [Asset Functions](./asset/function.md) - reference guide to asset functions +- [Audit Trail](./audit-trail.md) - reference guide to how to view what's + happened in your workspace - [Authorization Roles](./authorization-roles.md) - a guide to the roles available for users in a workspace - [Vocabulary](./vocabulary.md) - a comprehensive guide to the terminology we diff --git a/app/docs/src/reference/vocabulary.md b/app/docs/src/reference/vocabulary.md index 1900d9cc0c..a5fa150f71 100644 --- a/app/docs/src/reference/vocabulary.md +++ b/app/docs/src/reference/vocabulary.md @@ -81,6 +81,19 @@ will connect to the input sockets of the frame. A representation of a relationship between one component's output socket and another component's input socket. +## Entity + +This word encapsulates relevant objects that can be mutated, used, or are actors in System Initiative. +The Audit Trail dashboard makes use of this term to standardize all relevant objects seen in Audit Logs. + +### Entity Type + +This is the type of an entity. A "Component" and a "Func" are entity types in System Initiative. + +### Entity name + +This is the name of an entity. A "Component" could have the name "Server" and a Func could have the name "Validate Container Image". + ## HEAD HEAD is the change set that represents "the real world". It can only be altered