AuditLog

View as Markdown

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.

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

CapabilitySupportedNotes / Alternative
Read log items older than 30 daysNoThe API keeps 30 days of audit log information
Read the audit log of an organizationNoThis class reads the audit log of one stack
Filter log items with query()NoPass query parameters to fetchAll

Method Index

Read the log. Available on stack.auditLog().

Method NameReturnsDescription
fetchAllThe log items of the stack.Lists the audit log items.

Read one log item. Available on stack.auditLog('<LOG_ITEM_UID>').

Method NameReturnsDescription
fetchThe API response, which holds the log item.Retrieves one audit log item.

Set request headers. Available on both forms.

Method NameReturnsDescription
addHeaderThe same audit log object, for chaining.Adds one request header.
addHeaderDictThe same audit log object, for chaining.Adds several request headers.
removeHeaderThe 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.

NameTypeDescription
key (required)string

Header name, for example x-request-id.

Default: Not applicable
value (required)string

Header value to send.

Default: Not applicable

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.

NameTypeDescription
headerDict (required)object

Header names and values to add.

Default: Not applicable

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>').

NameTypeDescription
paramobject

Query parameters, sent as given.

Default: {}
param.include_branchboolean

Adds the _branch key to the response.

Default: API default

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.

NameTypeDescription
paramobject

Query parameters, sent as given.

Default: {}
param.include_branchboolean

Adds the _branch key to each item.

Default: API default

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.

NameTypeDescription
key (required)string

Name of the header to remove.

Default: Not applicable

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