144 lines
7.4 KiB
Markdown
144 lines
7.4 KiB
Markdown
# Component: Audit Logging
|
|
|
|
## Purpose
|
|
|
|
The Audit Logging component records all configuration and administrative changes in the system with the resulting state after each change, providing a queryable trail of who changed what and when.
|
|
|
|
## Location
|
|
|
|
Central cluster. All auditable actions occur through central (sites receive configurations but do not originate changes).
|
|
|
|
## Responsibilities
|
|
|
|
- Provide a service interface (`IAuditService`) for components to log changes after successful operations.
|
|
- Serialize entity state as JSON and store audit entries in the configuration MS SQL database.
|
|
- Write audit entries synchronously within the same database transaction as the change (via the unit-of-work).
|
|
- Provide query capabilities for the Central UI audit log viewer.
|
|
|
|
---
|
|
|
|
## Integration Pattern
|
|
|
|
Audit logging uses a **direct service call** pattern. Components call `IAuditService` after a successful operation:
|
|
|
|
```
|
|
IAuditService.LogAsync(user, action, entityType, entityId, entityName, afterState)
|
|
```
|
|
|
|
- **`user`**: The authenticated AD user who performed the action (provided by Security & Auth).
|
|
- **`action`**: The type of operation (create, update, delete, deploy, disable, enable).
|
|
- **`entityType`**: What was changed (template, instance, alarm, shared script, etc.).
|
|
- **`entityId`**: Unique identifier of the specific entity.
|
|
- **`entityName`**: Human-readable name of the entity.
|
|
- **`afterState`**: The entity's state after the change, serialized as JSON. Null for deletes.
|
|
|
|
The `IAuditService` interface is defined in **Commons** (alongside the other shared interfaces). The implementation is provided by the Audit Logging component and registered in the DI container.
|
|
|
|
### Transactional Guarantee
|
|
|
|
Audit entries are written **synchronously** within the same database transaction as the change. Since all central components use the unit-of-work pattern (EF Core's DbContext), the audit entry is added to the same DbContext and committed in the same `SaveChangesAsync()` call. This guarantees:
|
|
|
|
- If the change succeeds, the audit entry is always recorded.
|
|
- If the change fails and rolls back, the audit entry is also rolled back.
|
|
- No audit entries are lost due to process crashes between the change and the audit write.
|
|
|
|
### Integration Example
|
|
|
|
```
|
|
Template Engine: Update Template
|
|
│
|
|
├── repository.UpdateTemplate(template)
|
|
├── auditService.LogAsync(user, "update", "Template", template.Id,
|
|
│ template.Name, serialize(template))
|
|
└── repository.SaveChangesAsync() ← both the change and audit entry commit together
|
|
```
|
|
|
|
---
|
|
|
|
## Audited Actions
|
|
|
|
| Category | Actions |
|
|
|----------|---------|
|
|
| Templates | Create, edit, delete templates |
|
|
| Scripts | Create, edit, delete template scripts and shared scripts |
|
|
| Alarms | Create, edit, delete alarm definitions |
|
|
| Instances | Create, override values, bind connections, area assignment, disable, enable, delete |
|
|
| Deployments | Deploy to instance (who, what, which instance, success/failure) |
|
|
| System-Wide Artifact Deployments | Deploy shared scripts / external system definitions / DB connections / notification lists to sites (who, what, result) |
|
|
| External Systems | Create, edit, delete definitions |
|
|
| Database Connections | Create, edit, delete definitions |
|
|
| Notification Lists | Create, edit, delete lists and recipients |
|
|
| Inbound API | API key create, enable/disable, delete. API method create, edit, delete |
|
|
| Areas | Create, edit, delete area definitions |
|
|
| Sites & Data Connections | Create, edit, delete sites. Define and assign data connections to sites |
|
|
| Security/Admin | Role mapping changes, site permission changes |
|
|
|
|
---
|
|
|
|
## Audit Entry Schema
|
|
|
|
Each audit log entry contains:
|
|
|
|
| Field | Type | Description |
|
|
|-------|------|-------------|
|
|
| **Id** | Long / GUID | Unique identifier for the audit entry. |
|
|
| **Timestamp** | DateTimeOffset | When the action occurred (UTC). |
|
|
| **User** | String | Authenticated AD username who performed the action. |
|
|
| **Action** | String (enum) | The type of operation: `Create`, `Update`, `Delete`, `Deploy`, `Disable`, `Enable`. |
|
|
| **EntityType** | String | What was changed: `Template`, `Instance`, `SharedScript`, `Alarm`, `ExternalSystem`, `DatabaseConnection`, `NotificationList`, `ApiKey`, `ApiMethod`, `Area`, `Site`, `DataConnection`, `LdapGroupMapping`. |
|
|
| **EntityId** | String | Unique identifier of the specific entity. |
|
|
| **EntityName** | String | Human-readable name of the entity (for display without needing to deserialize state). |
|
|
| **State** | JSON (nvarchar(max)) | The entity's state after the change, serialized as JSON. Null for deletes. |
|
|
|
|
### State Serialization
|
|
|
|
- Entity state is serialized as **JSON** using the standard .NET JSON serializer.
|
|
- JSON is stored in an `nvarchar(max)` column in SQL Server.
|
|
- The UI can render the JSON state for inspection. SQL Server's built-in JSON functions (`JSON_VALUE`, `OPENJSON`) can be used for ad-hoc queries against the state if needed.
|
|
- For delete operations, the state is **null** (the entity no longer exists). The previous state can be found by querying the most recent prior audit entry for the same entity.
|
|
|
|
### Granularity
|
|
|
|
- **One audit entry per save operation**. When a user edits a template and changes multiple attributes in a single save, one audit entry is created containing the full template state after the save.
|
|
- This captures the complete picture of what the entity looked like after each change without requiring per-field tracking.
|
|
|
|
### Reconstructing Change History
|
|
|
|
Since only the "after" state is stored, a full change history for an entity can be reconstructed by querying all audit entries for that entity ordered by timestamp. Comparing consecutive entries (entry N-1's state vs. entry N's state) reveals what changed at each step. This is a query-time concern handled by the Central UI, not a write-time concern.
|
|
|
|
---
|
|
|
|
## Storage
|
|
|
|
- Stored in the **configuration MS SQL database** in a dedicated audit table, accessed via the `IAuditLoggingRepository`.
|
|
- Entries are **append-only** — audit records are never modified or deleted.
|
|
- No retention policy — audit logs are retained **indefinitely**.
|
|
- Indexes on: `Timestamp`, `User`, `EntityType`, `EntityId`, `Action` for efficient filtering.
|
|
|
|
---
|
|
|
|
## Query Capabilities
|
|
|
|
The Central UI audit log viewer can filter by:
|
|
- **User**: Who made the change.
|
|
- **Entity type**: What kind of entity was changed.
|
|
- **Action type**: What kind of operation was performed.
|
|
- **Time range**: When the change occurred.
|
|
- **Specific entity ID/name**: Changes to a particular entity.
|
|
|
|
Results are returned in reverse chronological order (most recent first) with pagination support.
|
|
|
|
---
|
|
|
|
## Dependencies
|
|
|
|
- **Configuration Database**: Storage for audit entries via `IAuditLoggingRepository`. Audit entries participate in the same unit-of-work transaction as the changes they record.
|
|
- **Security & Auth**: Provides the authenticated user identity for each entry.
|
|
- **Commons**: Defines the `IAuditService` interface and `AuditLogEntry` entity class.
|
|
|
|
## Interactions
|
|
|
|
- **All central components that modify state**: Call `IAuditService.LogAsync()` after successful operations. This includes Template Engine, Deployment Manager, Security & Auth, Inbound API, External System Gateway, and Notification Service.
|
|
- **Central UI**: Provides the audit log viewer for querying and displaying entries.
|
|
- **Configuration Database**: Audit entries are committed in the same transaction as the changes they record.
|