Audit Log
Audit logs in DID Spaces provide a comprehensive record of various activities, offering transparency and traceability for operations within your space. This section guides you through querying and managing these logs, including listing existing logs and recording the status of object synchronization processes.
For a general overview of all available commands, refer to the Commands Reference section.
List Logs#
The auditLogList command allows you to retrieve a paginated list of audit logs based on various filters and sorting options. This is useful for monitoring activities, debugging, and compliance.
Parameters
Name | Type | Description | Default Value |
|---|---|---|---|
|
| The DID Space service endpoint URL. | |
|
| The number of audit logs to return per page. Converted to an integer. |
|
|
| The page number to retrieve. Converted to an integer. |
|
|
| The field to sort the results by (e.g., |
|
|
| The sort order: |
|
|
| Optional. Filter logs by their status. Can be a single status or an array of statuses. Valid | |
|
| Optional. Filter logs by the type of action. Can be a single action type or an array of action types. Valid |
Returns
Name | Type | Description |
|---|---|---|
|
| The HTTP status code of the response. |
|
| The HTTP status message. |
|
| An object containing the list of audit logs and pagination information. The exact structure depends on the DID Space service's response, but typically includes |
Example
import { DIDSpaceClient } from '@did-space/client';
import { AuditLogAction, AuditLogStatus } from '@did-space/constants';
async function getAuditLogs(wallet, endpoint) {
const client = new DIDSpaceClient({
wallet,
endpoint,
});
try {
const response = await client.auditLog.listLogs({
endpoint: `${endpoint}/.well-known/service/api/did-space`,
size: 5,
page: 0,
sort: 'createdAt',
order: 1, // Descending
status: AuditLogStatus.SUCCESS,
actionType: AuditLogAction.APP_OBJECTS_SYNC,
});
console.log('Successfully retrieved audit logs:');
console.log('Status Code:', response.statusCode);
console.log('Status Message:', response.statusMessage);
console.log('Data:', JSON.stringify(response.data, null, 2));
if (response.data && response.data.items) {
response.data.items.forEach((log) => {
console.log(`- Log ID: ${log.id}, Action: ${log.actionType}, Status: ${log.status}`);
});
}
} catch (error) {
console.error('Error retrieving audit logs:', error);
}
}
// Replace with your actual wallet and DID Space endpoint
// const wallet = { /* your wallet object */ };
// const endpoint = 'https://your-space-did.space';
// getAuditLogs(wallet, endpoint);This example demonstrates how to retrieve the first page of up to 5 audit logs, sorted by creation time in descending order, specifically for successful APP_OBJECTS_SYNC actions. The endpoint parameter for listLogs should point to the Blocklet Service API endpoint, usually in the format https://your-space-did.space/.well-known/service/api/did-space.
Post Sync#
The PostObjectsSyncCommand allows you to record the initiation of an object synchronization process in the audit logs. This command is typically used at the start of a sync operation to log its details.
Parameters
Name | Type | Description |
|---|---|---|
|
| The source path or identifier of the objects being synchronized. Must not be empty. |
|
| The target path or identifier where the objects are being synchronized to. Must not be empty. |
|
| Optional. Additional metadata related to the synchronization process, stored as key-value pairs. |
Returns
Name | Type | Description |
|---|---|---|
|
| The HTTP status code of the response. |
|
| The HTTP status message. |
|
| The created audit log entry for the object synchronization. This model includes details like |
Example
import { DIDSpaceClient } from '@did-space/client';
async function postSyncLog(wallet, endpoint) {
const client = new DIDSpaceClient({
wallet,
endpoint,
});
try {
const response = await client.auditLog.postSync({
source: '/my-local-folder',
target: '/did-space-backup/data',
metadata: {
syncType: 'full',
initiatedBy: 'user-xyz',
},
});
console.log('Successfully posted sync log:');
console.log('Status Code:', response.statusCode);
console.log('Status Message:', response.statusMessage);
console.log('Created Log ID:', response.data.id);
console.log('Log Data:', JSON.stringify(response.data, null, 2));
} catch (error) {
console.error('Error posting sync log:', error);
}
}
// Replace with your actual wallet and DID Space endpoint
// const wallet = { /* your wallet object */ };
// const endpoint = 'https://your-space-did.space';
// postSyncLog(wallet, endpoint);This example demonstrates how to create an audit log entry for a new object synchronization process, specifying the source and target paths along with some custom metadata. The initial status of the log will typically be PENDING or INITIAL.
Put Sync#
The PutObjectsSyncCommand allows you to update the status and details of an ongoing or completed object synchronization process in the audit logs. This is crucial for tracking the progress and outcome of synchronization tasks.
Parameters
Name | Type | Description |
|---|---|---|
|
| The unique identifier of the audit log entry to update. Must not be empty. |
|
| The new status of the synchronization. Valid values include: |
|
| Optional. A descriptive reason for the status update, especially useful for |
|
| The total number of objects processed during synchronization. |
|
| The number of objects that failed to synchronize. |
|
| Optional. The number of objects successfully synchronized. |
|
| The total size (in bytes) of objects processed. |
|
| The duration (in milliseconds) of the synchronization process. |
Returns
Name | Type | Description |
|---|---|---|
|
| The HTTP status code of the response. |
|
| The HTTP status message. |
|
| The updated audit log entry for the object synchronization, reflecting the new status and metrics. |
Example
import { DIDSpaceClient } from '@did-space/client';
import { AuditLogStatus } from '@did-space/constants';
async function putSyncLog(wallet, endpoint, logId) {
const client = new DIDSpaceClient({
wallet,
endpoint,
});
try {
const response = await client.auditLog.putSync({
id: logId, // ID obtained from a previous postSyncLog call
status: AuditLogStatus.SUCCESS,
totalCount: 100,
successCount: 98,
errorCount: 2,
size: 1024 * 1024 * 50, // 50 MB
duration: 15000, // 15 seconds
reason: 'Synchronization completed successfully with minor errors.',
});
console.log('Successfully updated sync log:');
console.log('Status Code:', response.statusCode);
console.log('Status Message:', response.statusMessage);
console.log('Updated Log ID:', response.data.id);
console.log('New Status:', response.data.status);
console.log('Log Data:', JSON.stringify(response.data, null, 2));
} catch (error) {
console.error('Error updating sync log:', error);
}
}
// Replace with your actual wallet, DID Space endpoint, and a valid log ID
// const wallet = { /* your wallet object */ };
// const endpoint = 'https://your-space-did.space';
// const existingLogId = 'some-audit-log-id'; // This ID would come from the postSyncLog response
// putSyncLog(wallet, endpoint, existingLogId);This example demonstrates how to update an existing audit log entry with detailed metrics and a new status (e.g., SUCCESS). You would typically call this command after a synchronization process has finished to record its final outcome.
This section provided an in-depth look into managing audit logs within DID Spaces, from listing existing entries to tracking object synchronization progress. These commands are essential for maintaining visibility and accountability over activities in your DID Space. You can now proceed to explore other advanced commands, such as Space Head for checking space availability.