Contentful Audit Logs Practical Guide: Understanding the Structure of Audit Logs from JSON and Key Points for Utilization

Introduction

In this article, we will examine the Audit logs feature provided by Contentful, checking the actual JSON data output and organizing its structure and characteristics. Official documentation often only covers feature overviews and usage procedures, with limited opportunities to concretely understand how actual data is formatted when output. Therefore, this article will use JSON examples and demonstrate step-by-step how to interpret them. The aim is to help readers better understand how to handle logs in their own environments.

What is Contentful

Contentful is a cloud-based content management platform. Its ability to flexibly manage content through APIs makes it suitable for various channels including websites and mobile applications. In enterprise use cases where multiple users are expected to update entries simultaneously, managing change history and audit trails is essential. The Audit logs feature is provided for this purpose.

For information on how to enable Audit logs, please refer to this article.

Target Audience

• Engineers and administrators using Contentful
• Information system personnel involved in system auditing and security response
• Technical personnel who need to directly handle JSON data and perform log analysis

References

• Contentful official documentation: https://www.contentful.com/developers/docs/tutorials/general/audit-logs/
• DevelopersIO article: https://dev.classmethod.jp/articles/contentful-audit-log/

Examining the JSON Structure

Overview of the Logs

Contentful Audit logs are output in JSON format. Each element represents an "event" and is recorded whenever an operation is performed by a user or API. At the top level of the JSON, multiple events are stored as an array, with each event recording operation details.

Each event typically contains the following information, allowing you to understand "who" did "what" to "which resource" and "when":

• Type of operation (e.g., Update, Create)
• Time when the operation was performed
• Operating entity (user or API client)
• Target of operation (resources such as entries or spaces)
• HTTP request and response content
• Associated metadata### Main Fields

Below is an example of a typical Update event excerpted from the actual JSON. All customer data and internal IDs have been masked as ****.

			
			{
  "activity_name": "Update",
  "activity_id": 3,
  "category_uid": "6",
  "class_uid": "6001",
  "type_uid": "600103",
  "time": "2025-07-15 23:39:06.688",
  "actor": {
    "type": "User",
    "id": "****"
  },
  "http_request": {
    "http_method": "PATCH",
    "url": {
      "path": "/spaces/****/environments/master/entries/****"
    }
  },
  "http_response": {
    "code": 200
  },
  "web_resources": [
    {
      "type": "Entry",
      "uid": "****"
    }
  ],
  "metadata": {
    "version": "1.3.0",
    "uid": "****"
  }
}

		

Here's an explanation of the key fields according to this excerpt:

• activity_name: Indicates the type of operation. Here, Update is recorded.
• time: The time when the operation was performed, recorded in ISO format.
• actor: The entity that performed the operation. The type can be User or App, and the id contains the user ID or client ID.
• http_request: Information about the actual HTTP request sent. It records which method (PATCH, PUT, etc.) was called on which API path.
• http_response: The response code to the request. 200 for normal, 4xx or 5xx for abnormal cases.
• web_resources: The resource that was the target of the operation. Here, Entry is the target, and the uid contains the entry ID.
• metadata: Additional information, such as the identifier for the log event itself.

Interpreting Events### Typical Example of Update Events

Let's take a closer look at the Update event mentioned earlier. The Update event occurs when an existing Entry is edited.

			
			{
  "activity_name": "Update",
  "time": "2025-07-15 23:38:47.120",
  "actor": {
    "type": "User",
    "id": "****"
  },
  "http_request": {
    "http_method": "PATCH",
    "url": {
      "path": "/spaces/****/environments/master/entries/****"
    }
  },
  "http_response": {
    "code": 200
  },
  "web_resources": [
    {
      "type": "Entry",
      "uid": "****"
    }
  ]
}

		

From this event, we can understand the following:

• A PATCH request was executed against a specific Entry in the master environment.
• The operation was performed by a specific user (id: ****).
• The response code is 200, indicating the update was successfully applied.

In other words, this event represents "a specific user edited an entry and it completed successfully." Operationally, this can be used to track who edited which entry and when.

Events During Errors

There are also cases where non-successful response codes are recorded. Below is an example where http_response.code is 500.

			
			{
  "activity_name": "Update",
  "time": "2025-07-15 23:04:09.831",
  "actor": {
    "type": "User",
    "id": "****"
  },
  "http_request": {
    "http_method": "PATCH",
    "url": {
      "path": "/spaces/****/environments/master/entries/****"
    }
  },
  "http_response": {
    "code": 500
  }
}

		

In this case, the user attempted to update an entry, but an error occurred on the server side. From an auditing perspective, you can confirm who caused the error, which resource it affected, and when it occurred. From a system operations perspective, monitoring for frequent 500 errors can help detect API issues or signs of invalid requests early.

Checking Event Continuity

When examining Audit logs in detail, you may notice PATCH events recorded at intervals of a few seconds. Below is an example series:

			
			[
  {
    "time": "2025-07-15 23:38:26.390",
    "http_request": { "http_method": "PATCH" },
    "http_response": { "code": 200 }
  },
  {
    "time": "2025-07-15 23:38:40.624",
    "http_request": { "http_method": "PATCH" },
    "http_response": { "code": 200 }
  },
  {
    "time": "2025-07-15 23:38:47.120",
    "http_request": { "http_method": "PATCH" },
    "http_response": { "code": 200 }
  }
]

		

Such sequential records may indicate that multiple PATCH operations occur when saving edits from the management console. During audits or investigations, these should be interpreted as "a single set of update operations" rather than individual operations. Especially when investigating unauthorized access or operational mistakes, it's important to consider the temporal continuity of events rather than examining them in isolation.## Features and Operational Considerations Based on Actual Verification

After examining Contentful's Audit logs in practice, several features and operational points became apparent.

• Update events are recorded multiple times
  Even for a single entry update, multiple PATCH events may be output consecutively. For auditing purposes, it's important to interpret these as "groups of operations."

• Pay attention to actor information granularity
  Actors are recorded as either User or App. For API-based operations, the client ID is recorded, so operations must maintain mapping information to track the actual users.

• Error events serve as signals
  500 and 400 series codes are also recorded, allowing you to see who failed on which resource. Monitoring frequency and patterns can help detect signs of unauthorized operations or system malfunctions early.

• Utilizing metadata.uid
  Each event is assigned a unique identifier, making it effective for use as a key when importing into external audit platforms, or for deduplication and chronological organization.

• Understanding log limitations
  Audit logs are specialized for audit trails and not suitable for detailed application debugging. It's practical to focus their use on "tracking unauthorized or erroneous operations."

Summary

Contentful's Audit logs provide a mechanism for detailed recording of operations by users and applications in JSON format, which can be utilized as audit trails. Based on actual verification, the following characteristics were confirmed:

• Operations are recorded clearly showing "who", "when", "which resource", and "what was done"
• Events including errors are recorded, making it possible to identify signs of unauthorized operations or system failures
• Multiple events may be recorded consecutively for the same operation, requiring interpretation in actual operation

On the other hand, Audit logs are primarily for auditing purposes and not suited for debugging or tracking detailed differences. It's important to clearly distinguish their purpose and utilize them as a foundation for auditing and security responses.