AuditLog
AuditLog
The audit log records the activities in a stack, such as publishes, updates and deletes. The AuditLog class reads that record through the Content Management API (CMA). Use this class to
- list the log items of a stack
- read the details of one log item, for example to see who changed an entry and when
Call the auditLog method of the Stack class to get an object.
Instance State
- Call stack.auditLog() without a UID to work with the whole log, for example fetchAll.
- Call stack.auditLog('<LOG_ITEM_UID>') to work with one log item, for example fetch.
- Each form has only its own request method. fetch is undefined on stack.auditLog(), and fetchAll is undefined on stack.auditLog('<LOG_ITEM_UID>'), so calling the wrong one throws TypeError.
Warning stack.auditLog('') returns the whole-log form, because the SDK treats an empty string as no UID. Check the UID before you build the object.
Class-Level Notes
Read-only access.
- This class only reads the audit log. It has no method that creates, changes or deletes a log item.
- The API returns audit log information for the last 30 days only, as Get audit log states.
Branch scoping.
- When you create the stack with branch_uid, every request from this class sends the branch header, and the API reads the audit log of that branch.
Headers.
- Every request sends the headers of this object, which start as a copy of the stack headers. Change them with addHeader, addHeaderDict and removeHeader.
Rate limiting and retry.
- This SDK automatically retries on 429 with configurable delay and attempt limits.
Additional Resource For more information on the retry options and their defaults, refer to the Contentstack documentation.
Capability Matrix
| Capability | Supported | Notes / Alternative |
|---|---|---|
| Read log items older than 30 days | No | The API keeps 30 days of audit log information |
| Read the audit log of an organization | No | This class reads the audit log of one stack |
| Filter log items with query() | No | Pass query parameters to fetchAll |
Method Index
Read the log. Available on stack.auditLog().
| Method Name | Returns | Description |
|---|---|---|
| fetchAll | The log items of the stack. | Lists the audit log items. |
Read one log item. Available on stack.auditLog('<LOG_ITEM_UID>').
| Method Name | Returns | Description |
|---|---|---|
| fetch | The API response, which holds the log item. | Retrieves one audit log item. |
Set request headers. Available on both forms.
| Method Name | Returns | Description |
|---|---|---|
| addHeader | The same audit log object, for chaining. | Adds one request header. |
| addHeaderDict | The same audit log object, for chaining. | Adds several request headers. |
| removeHeader | The same audit log object, for chaining. | Removes one request header. |
Class-Level Snippet
The snippet below lists the audit log items of a stack and prints the module and event of each one.
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const logs = await stack.auditLog().fetchAll()
for (const log of logs.items) {
console.log(log.uid, log.module, log.event_type)
}
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}Methods
Each method of the AuditLog class has its own section below, with its parameters, validation rules, behavior, and examples.
addHeader
addHeader adds one header to every request that this audit log object sends.
| Name | Type | Description |
|---|---|---|
| key (required) | string | Header name, for example x-request-id. |
| value (required) | string | Header value to send. |
Returns: AuditLog. The same audit log object, for chaining.
Validation
- There is no client-side validation. A null or undefined key leaves the headers unchanged, and addHeader returns the same object.
- An invalid value surfaces as a rejected promise from the request method you call next.
Behavior
- Client-side only. addHeader sends no request.
- The first header change on this object copies the headers that it inherited from the stack. The change then applies to this object only, not to the stack or to other objects that the same stack creates.
- Every request method of this object sends its headers. The items that fetchAll returns carry the same headers.
- A key that the object already holds gets the new value.
Example
Basic usage: tag the requests of one audit log object
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
const auditLog = stack.auditLog('<LOG_ITEM_UID>').addHeader('x-request-id', 'docs-123')
// Every request this object sends from now on carries the header
console.log(auditLog.stackHeaders['x-request-id'])addHeaderDict
addHeaderDict adds several headers at once to every request that this audit log object sends.
| Name | Type | Description |
|---|---|---|
| headerDict (required) | object | Header names and values to add. |
Returns: AuditLog. The same audit log object, for chaining.
Validation
- There is no client-side validation. A null value, or a value that is not an object, leaves the headers unchanged, and addHeaderDict returns the same object.
- An invalid value surfaces as a rejected promise from the request method you call next.
Behavior
- Client-side only. addHeaderDict sends no request.
- The first header change on this object copies the headers that it inherited from the stack. The change then applies to this object only, not to the stack or to other objects that the same stack creates.
- Every request method of this object sends its headers. The items that fetchAll returns carry the same headers.
- addHeaderDict merges headerDict into the headers of the object. A key that the object already holds gets the new value.
Example
Basic usage: add two tracing headers
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
const auditLog = stack.auditLog().addHeaderDict({
'x-request-id': 'docs-123',
'x-trace-id': 'trace-456'
})
console.log(auditLog.stackHeaders['x-request-id'], auditLog.stackHeaders['x-trace-id'])fetch
fetch retrieves the audit log item whose UID you passed to stack.auditLog('<LOG_ITEM_UID>').
| Name | Type | Description |
|---|---|---|
| param | object | Query parameters, sent as given. |
| param.include_branch | boolean | Adds the _branch key to the response. |
Returns: Promise<object>. The API response, which holds the log item.
Validation
- There is no client-side validation.
- fetch exists only on stack.auditLog('<LOG_ITEM_UID>'). On stack.auditLog() it is undefined, and calling it throws TypeError.
- The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends GET /v3/audit-logs/{log_item_uid} with every key of param as a query parameter, as Get audit log item describes.
- Resolves to the response body as a plain object, not to an AuditLog object. The log item sits under the log key.
- The API returns audit log information for the last 30 days only.
- Get a log item UID from the uid of an item that fetchAll returns. Each of those items also has its own fetch method.
Example
Basic usage: read one log item
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const response = await stack.auditLog('<LOG_ITEM_UID>').fetch()
console.log(response.log.module, response.log.event_type, response.log.created_by)
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}All parameters: include the branch of the log item
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>', branch_uid: '<BRANCH>' })
try {
const response = await stack.auditLog('<LOG_ITEM_UID>').fetch({ include_branch: true })
console.log(response.log.uid, response.log._branch)
} catch (error) {
console.error(error.errorMessage)
}Edge case: read the details of the newest log item
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const logs = await stack.auditLog().fetchAll()
if (logs.items.length > 0) {
// Each item from fetchAll has its own fetch method
const response = await logs.items[0].fetch()
console.log(response.log.request, response.log.response)
}
} catch (error) {
console.error(error.errorMessage)
}fetchAll
fetchAll retrieves the audit log items of the stack.
| Name | Type | Description |
|---|---|---|
| param | object | Query parameters, sent as given. |
| param.include_branch | boolean | Adds the _branch key to each item. |
Returns: Promise<ContentstackCollection>. The log items of the stack.
Validation
- There is no client-side validation.
- fetchAll exists only on stack.auditLog(). On stack.auditLog('<LOG_ITEM_UID>') it is undefined, and calling it throws TypeError.
- The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends GET /v3/audit-logs with every key of param as a query parameter, as Get audit log describes.
- Resolves to a ContentstackCollection. Its items array holds one AuditLog object per entry of the logs array in the response. Each item has a fetch method that reads the full log item.
- The API returns audit log information for the last 30 days only.
- fetchAll makes one request and does not page through the results. The API applies its own page size.
Example
Basic usage: list the audit log items of a stack
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const logs = await stack.auditLog().fetchAll()
for (const log of logs.items) {
console.log(log.uid, log.module, log.event_type, log.created_at)
}
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}All parameters: include the branch of each log item
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>', branch_uid: '<BRANCH>' })
try {
const logs = await stack.auditLog().fetchAll({ include_branch: true })
for (const log of logs.items) {
console.log(log.uid, log._branch)
}
} catch (error) {
console.error(error.errorMessage)
}removeHeader
removeHeader removes one header from the requests that this audit log object sends.
| Name | Type | Description |
|---|---|---|
| key (required) | string | Name of the header to remove. |
Returns: AuditLog. The same audit log object, for chaining.
Validation
- There is no client-side validation. A null or undefined key, or a key that the object does not hold, leaves the headers unchanged, and removeHeader returns the same object.
- An invalid value surfaces as a rejected promise from the request method you call next.
Behavior
- Client-side only. removeHeader sends no request.
- The first header change on this object copies the headers that it inherited from the stack. The change then applies to this object only, not to the stack or to other objects that the same stack creates.
- Every request method of this object sends its headers. The items that fetchAll returns carry the same headers.
- removeHeader can remove a header that the object inherited from the stack, such as branch. The stack and its other objects keep that header.
- Do not remove api_key. Without it, the API cannot tell which stack the request is for.
Example
Basic usage: drop a header that you added earlier
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
const auditLog = stack.auditLog('<LOG_ITEM_UID>')
.addHeaderDict({ 'x-request-id': 'docs-123', 'x-trace-id': 'trace-456' })
.removeHeader('x-trace-id')
console.log('x-trace-id' in auditLog.stackHeaders) // false