DEV Community: seyed mojtaba shadab

Exploring customLogger: Smart, Customizable Logging in Payload CMS

seyed mojtaba shadab — Tue, 27 May 2025 05:51:03 +0000

🧾 Brief Introduction to Payload CMS

Payload CMS is a Headless content management system based on Node.js and TypeScript, designed for developers. Unlike many traditional CMSs that come with pre-built UIs or themes, Payload focuses on providing a developer-centric, API-driven, and customizable experience.

🎯 Key Features of Payload:

TypeScript-first structure: All structures, data models, and configurations are defined with the powerful TypeScript type system.
Modern admin interface: Automatically generates a complete content management UI from your schema.
Built-in security and authentication: It has a built-in, extensible authentication and access control system.
Hooks and Plugins Support: You can control the behavior of the system precisely using hooks and plugins.

Payload allows developers to create a highly customizable, secure, and extensible content management system without being limited to predefined structures. That is why it is a popular choice for complex, custom, and modern projects.

🔍 What is the `payload-auditor` plugin?

The payload-auditor plugin is a powerful plugin for Payload CMS that allows for precise audit of operations performed on collections. The plugin automatically records all changes such as create, update, and delete data and stores them in a structured log format.

✨ The main goal of this plugin:

Provide a transparent and reliable logging system for monitoring user behavior and reviewing database-level change history.

⚙️ Key features:

Automatic logging of operations on collections
Support for defining custom logger for custom logging
Support for all CMS payload hooks
Modular design with extensibility for complex projects

Using this plugin, developers and system administrators can easily understand who, when, and what changes were made to the system; a vital feature for projects where security, transparency, and audit trails are of high importance. To learn more about this plugin, you can read the article Tracking and Security in Payload CMS with the Payload-Auditor Plugin.

📚 The importance of custom logging in content management systems (CMS)

In content management systems, especially in enterprise or sensitive projects, accurate tracking of user activities and data changes plays a very important role. While basic logging can capture general information about operations, custom logging allows for accurate, targeted, and analyzable information to be stored for the specific needs of each project.

Why do we need custom logging?

1. 🎯 Customization

Projects are different; one project may need to record user IP, another may want to store user roles or geographic information. Custom logging allows for critical information tailored to the project scenario to be recorded.

2. 🕵️‍♀️ Transparency and Audit Trail

For systems that require user behavior to be investigated or security issues to be addressed, the complete change trail (who changed what, when, and how) must be clearly visible. This transparency cannot be achieved without accurate and customized logging.

3. 🔐 Security and Accountability

In many projects, especially in areas such as finance, medicine or government, accurate recording of activities plays an important role in data security and user accountability. Custom logs can also be used as legal evidence.

4. 📊 Analytics and Intelligence

With rich and structured logs, you can analyze user behavior, identify process weaknesses and ultimately make more informed decisions to improve system performance.

Logging is not just a monitoring tool; it is an integral part of security, optimization and professional management of content systems. By providing the ability to record custom logs, you can have much more control and insight into what is happening in the system.

🔧 What is `customLogger`?

In the payload-auditor plugin, the customLogger feature allows developers to fully customize logging behavior at the hook level. This feature is designed for projects that need to generate or modify log content in a specific way depending on different conditions, since it is almost impossible to predict the default values for logging in the logs.

🧩 Defining `customLogger` at the Hook Level

customLogger is an optional function that can be specified in the payload-auditor plugin configuration. This function is called when the hook used for each operation is executed and can edit or overwrite the log data before final storage.

customLogger?: (
  args: Parameters<AllCollectionHooks['afterChange']>[0],
  fields: Omit<AuditorLog, 'hook'>,
) => Omit<AuditorLog, 'hook'> | Promise<Omit<AuditorLog, 'hook'>>

In this function:

args: Contains information about the hook for the same document and can have values like req, operation, doc, etc.
fields: Contains the default log structure without the hook field (because the principle of which hook created this log should not change).
The output of the function should be a final version of AuditorLog (except for the hook added by the plugin).

🔀 Multi-level `customLoggers`

In payload-auditor, we have considered four levels of the customLogger function to increase flexibility.

🔢 `customLogger` definition levels (in order of execution priority):

1. 🥇 Operation-Level

At this level, a dedicated customLogger can be defined for each specific operation (create, update, delete). This level has the highest execution priority and if it exists, no other levels will be executed.

create: {
  customLogger: (args, fields) => {
    return { ...fields, user: null }
  },
  enabled: true,
}

📌 Applies only to that specific operation
✅ Has the highest priority

2. 🥈 Hook-Level

If customLogger is not defined for a specific operation, the system looks for customLogger at the hook level, such as afterChange.

customLogger: (args, fields) => {
  return { ...fields, user: null }
}

📌 Only for specific hook (e.g. afterChange)
❌ Not executed if customLogger is defined as an operation level
✅ Only works on active operations

3. 🥉 All Hooks Level (Hooks-Level)

At this level, customLogger is applied to all hooks and operations, if none of the previous two levels exist.

customLogger: (args, fields) => {
  return { ...fields, type: 'error' }
}

📌 Only runs if there is no logger at the hook and operation level
✅ Only works on active operations
❌ Cannot be defined for a specific hook – covers the entire hook system

4. 🏁 Global-Level

If no customLogger is defined at the operation, hook or all hooks level, then the global customLogger is run. This level works for all collections.

customLogger: (args, fields) => {
  return { ...fields, userAgent: 'custom user agent' }
}

📌 Last level of fallback in execution priority
✅ Works only on active operations

🔁 Execution hierarchy summary:

[Highest priority] Operation → Hook → All hooks → Global [Lowest priority]

The more detailed the definition level, the higher the execution priority. This hierarchy provides great flexibility for precise, customized, and targeted logging.

🧬 `customLogger` structure

The customLogger function is the heart of the custom logging mechanism in the payload-auditor plugin. This function allows you to edit or generate log fields before final logging. To do this, the function takes two inputs and must return a specific output.

🛠 Function Inputs

The customLogger function has two main inputs:

1. `args`: All hook arguments

This argument contains complete information about the current hook and the operation that was executed. Typically contains values like:

req: HTTP request object
operation: Operation type (create, update, delete)
doc: Final document after modification
previousDoc: Previous document (in update and delete operations)
Other information depending on the hook type

2. `fields`: Initial log structure (Log Fields)

This object contains the default log data generated by the plugin, without fields hook. You can override, modify, or add fields to this object.

📍Note: If you want to add a new field, you must define that field for the plugin root collection using configureRootCollection

📤 Expected Output

The customLogger function should return an object that has the following structure:

Omit<AuditorLog, 'hook'>

That is, it must include all the fields required for logging, except hook which is automatically added by the plugin.

📌 Simple example:

(args, fields) => {
return {
...fields,
user: null,
ip: args.req?.ip || 'unknown',
}
}

⏳ Support for async operations

The customLogger function can also operate asynchronously (*****async* ) . That is, you can use async functions such as accessing a database, reading from external APIs or long-running processes and return the final value with await.

📌 Example with Promise:

async (args, fields) => {
const geoInfo = await getGeoInfo(args.req?.ip)
return {
...fields,
location: geoInfo.city,
}
}

🔄 If the function output is of type Promise, the plugin will automatically resolve it.

This flexibility in the customLogger structure allows you to generate the structure you want for any scenario, from simple logging to the most complex analytics.

📌 Practical examples

In this section, we will examine two common examples of customLogger usage; one simple and the other with async operations. Each example is analyzed line by line to make the practical concepts clear.

1. 🧼 Changing the user value to `null`

customLogger: (args, fields) => {
return { ...fields, user: null };
}

🧩 Line-by-line analysis

customLogger: is a synchronous function that takes two parameters:
args: information about the operation, such as request, document, etc.
fields: raw log data before final processing.
...fields: first we keep all the initial fields of the log.
user: null: then we manually set the value of user to null.

🎯 Real-world uses of this change

Removal of sensitive information: In some scenarios you may not want to record user IDs or information (for example, in anonymous forms).
Anonymization of logs for privacy or in test environments.
Automated processes where no human user is involved and user is irrelevant.

2. 🌐 Adding custom information (e.g. IP)

📍Note: If you want to add a new field, you must define that field for the plugin root collection using configureRootCollection

customLogger: async (args, fields) => {
const ip = await getIPFromRequest(args.req);
return { ...fields, meta: { ...fields.meta, ip } };
}

🧩 Line-by-line analysis

The function is async because it uses the await helper function.
getIPFromRequest(args.req): A hypothetical function to extract the IP from the request.
...fields: Preserve the original data.
meta: { ...fields.meta, ip }: Add the IP to the log metadata section, without removing the previous metadata.

🧰 Introducing the helper function

The getIPFromRequest function can be defined simply as:

function getIPFromRequest(req?: PayloadRequest): string {
return req?.ip || req?.headers['x-forwarded-for']?.toString() || 'unknown';
}

This function first gets the IP from req.ip, otherwise it uses proxy headers.

🎯 Real-world applications

Security analysis: Detect suspicious situations by examining IP.
Recording user behavior based on geographic location.
Monitoring system load from specific regions or specific users.

⚠️ Critical points when using `customLogger`

To use customLogger correctly and effectively in the payload-auditor plugin, it is crucial to be familiar with some limitations and prioritization behaviors. In this section, we will review the most important critical points:

🔄 1. Prioritization when using customLogger

If you have defined customLogger at different levels (for example, both at the operation level and at the hook or global level), the plugin will always use the closest definition. The order of precedence is as follows:

customLogger at the operation-level For example:

create: {
customLogger: ...
}

✅ Highest priority – will only be executed for that specific operation.

customLogger at hook level For example:

afterChange: {
customLogger: ...
}

✅ Runs only if the corresponding operation does not have a dedicated customLogger.

customLogger at the global hooks level For example:

hooks: {
customLogger: ...
}

✅ Runs if neither operation-level nor hook-level customLogger exists.

customLogger at global level (for all collections) For example:

auditor: {
customLogger: ...
}

✅ Finally, the final fallback; runs only if no other level has a customLogger.

🧩 2. Differences with `customLogger` at hook level

There are important differences between customLogger at hook level (e.g. afterChange) and operation level:

Feature	customLogger (operation)	customLogger (hook-level)
Dependent on operation type	For any operation you have defined	Yes, but only when not defined
Scope of effect	A specific operation	All operations related to that hook
Execution priority	Higher	Lower than operation level

⚠️ It is important not to confuse these two levels, as you might think your customLogger is running, but because there is a more precise version at a lower level, it is not called at all.

✅ Best Practices

To make your logging system both fast and secure, it is very important to follow a few key principles in the design and implementation of customLogger. In this section, we will discuss recommendations that will both improve the developer experience and make the system easier to maintain:

🧼 1. Keep your log structure simple

Minimalism in logging helps reduce data volume and storage costs.
Avoid adding unnecessary or nested fields.
Always design logs for fast processing in analytics systems (like ELK, Datadog, or Logstash).

✅ Good example:

return {
...fields,
action: 'create',
user: user.id,
};

❌ Bad example:

return {
...fields,
debugDump: req.body,
requestHeaders: req.headers,
timestamp: new Date(),
callStack: new Error().stack,
};

🔐 2. Avoid storing sensitive data (unless encrypted)

📍Note: The plugin itself may store email in raw form in the logs. It is the developer's responsibility to use encryption to store sensitive data

Avoid storing private user data such as email, IP, or phone number in raw form.
If you need to store this data, use encryption or hashing.

✅ Suggested example:

return {
...fields,
meta: {
emailHash: sha256(user.email),
},
};

🌐 3. Use async for external data

If you need to get data from external sources (such as IP location, browser information, or external validations), customLogger fully supports async functions.

Example: Adding user location from IP

customLogger: async (args, fields) => {
const location = await getGeoLocation(args.req?.ip);
return {
...fields,
meta: {
...fields.meta,
location,
},
};
}

📌 Note: If you use external resources:

Pay attention to API latency.
Consider caching or rate-limiting.
Use appropriate timeouts so that the entire log process does not break.

🎯 Other recommendations

Use collections for testing customLogger whose changes are less critical.
Do not use customLogger to modify the original data (it is only for creating logs).
If you need a different customLogger based on the user type, you can put a condition in it:

if (args.req?.user?.role === 'admin') {
return { ...fields, severity: 'high' };
}

📍 Conclusion

The customLogger feature in the payload-auditor plugin is a very powerful tool for customizing the logging process in Payload CMS-based projects. This feature allows you to precisely and with full control, tailor the content of the logs to your project's security, analytical, and operational needs.

🧩 Summary of features

High flexibility at four levels: operation level, hook, hooks-level and global
Ability to process synchronously and asynchronously (async) in log generation
Support for external data such as IP, geolocation or user role
Ability to filter, modify, or remove sensitive information before saving

🎯 More accurate tracking of system changes

By using customLogger wisely, you can:

Record and analyze specific changes based on user context
Generate targeted and actionable logs that are valuable for monitoring and security tools
Make the debugging process faster and more accurate for the development team

💡 Suggestions for developers

Use customLogger to build a reliable logging infrastructure alongside other observability tools like Sentry Or use Grafana.
For projects with high security requirements, be sure to encrypt sensitive data in logs.
Use async loggers to balance system performance with log richness.

Ultimately, customLogger is not just an optional feature, but can be a key part of your audit and security strategy. If used correctly, it can be the difference between a purely decorative log and a real analysis and response tool.

🔗 Link to the main plugin documentation

Official documentation payload-auditor Includes a full explanation of options, log structure, logging levels, and practical examples.

💻 GitHub Repository Link

GitHub Repository: 👉 https://github.com/shaadcode/payload-auditor

In this repo you can:

View and install the latest version of the plugin
Track Issues and Feature Requests
Contribute to the plugin development

🤝 Appreciation and Contribution

If you found this plugin useful or this article helped you understand it better, please support me by giving the payload-auditor repo a ⭐️. This motivates me to develop more open source tools.

🙏 Thank you for your support!

Tracking and Security in Payload CMS with the Payload-Auditor Plugin

seyed mojtaba shadab — Sat, 24 May 2025 05:32:37 +0000

Before we get into the main topic of the article, let's first learn about Payload CMS.

A Brief Introduction to Payload CMS

Payload CMS is a modern, fully JavaScript-based, headless content management system. Unlike many traditional CMSs, Payload has a strong focus on customization, high performance, and a developer-centric experience.

Instead of using pre-built panels, it allows you to fully define the structure and behavior of your admin panel through code. Some of its notable features include:

Full support for TypeScript
Advanced system for defining collections and fields
Ability to add hooks and detailed access control
Headless design for use in separate Frontend projects (React, Next.js, Vue, etc.)
And strong support for authentication, file upload, and REST and GraphQL APIs

Overall, Payload CMS is a powerful option for developers who want full control over the structure and functionality of their CMS — without having to deal with the limitations of traditional platforms.

Why do we need logging and tracing in Payload?

In the world of modern software, especially in projects built with headless CMSs like Payload CMS, the issue of security, transparency, and user behavior analysis is of utmost importance.

As the scale of the project grows and the number of users or administrators increases, knowing who did what, when, and where is no longer an optional feature — it is a vital need.

Here are some reasons why logging and tracing is necessary:

🧑‍💻 Track user actions: Who changed the information? When was a file deleted? Did someone log in with the wrong access?
🛡️ Increase security: Recording suspicious or sensitive events (such as changes to user information or suspicious logins) is the first line of defense against attacks.
🧾 Organizational Transparency: In multi-person teams, knowing the history of actions prevents repetitive errors and creates order in team processes.
🧪 Debugging and analyzing system behavior: Having a history of operations is very helpful when developing or investigating problems.

Payload Auditor Plugin: Answering Your Monitoring and Security Needs

This is where the Payload Auditor plugin comes in. It is designed to work seamlessly with Payload CMS, allowing for detailed logging of operations, event tracking, and greater control over backend security.

Not only does the plugin allow you to specify which collections to track, but you can even fine-tune the type of operation (create, update, delete) per hook. Simply put, you have complete control over what gets logged — without any added overhead or unnecessary complexity.

I’ll give you a more complete explanation later.

Why Payload Auditor?

Common Problems in Payload Projects Without a Logging System

In many projects built with Payload CMS, developers focus primarily on data structure, admin panel design, and API interaction — but an important part that is often overlooked is the logging and event monitoring system.

Here are some common problems that arise in the absence of a proper logging system:

🔍 Lack of Clear Change View
In projects with multiple content managers or developers, it is often unclear who made what changes and when. This can lead to confusion, repeated errors, or even damage to important data.

🛠️ Difficult Debugging
In the event of a problem, the lack of detailed reporting of the operations performed causes the development team to spend a lot of time searching through data or code to understand what happened.

🛡️ High Security Risks
When no traces of sensitive operations (such as updating user information or deleting data) remain, it becomes very difficult to identify suspicious actions or possible abuses.

📉 Lack of internal documentation of system performance
In organizational or team projects, automated documentation of user and system behavior plays a vital role in analyzing and improving processes. Otherwise, this task is either completely forgotten or performed manually and incompletely.

⏸️ Lack of tracking and targeted stopping of operations
Without a monitoring system, it is not possible to centrally specify whether logging should be stopped in a specific section or only certain operations (such as creation or deletion) should be logged.

Payload Auditor fills these gaps — as a simple, flexible, and powerful tool for:

Tracking all important activities
Accurately recording the history of operations
Controlling access to logs
and increasing the overall security of your project

Benefits of Using the Payload Auditor Plugin

Using the Payload Auditor plugin allows developers to make their projects more professional, secure, and more analyzable. Here are the most important benefits of this tool:

✅ Full Activity Tracking
This plugin allows for accurate recording of operations such as user creation, editing, deletion, and login. You can know who did what, when, and what — something that is practically impossible in systems without logging.

🔐 More security in multi-user environments
In projects where multiple users with different access levels are working, tracking and limiting access to logs plays an important role in preventing abuse or unwanted changes. This plugin allows you to control access to reports and closely monitor activities.

🏢 Suitable for SaaS and Enterprise Projects
In SaaS and Enterprise-level projects, detailed reports, change history, and analytical tools are a must. By providing these features, Payload Auditor helps you build a professional, reliable, and industry-standard product.

⚙️ High customization for specific needs
Through flexible settings, this plugin allows you to track only the collections that are important to you, select the type of operations, and even disable its functionality in certain situations.

📊 Analysis of behavioral and operational data
By recording structured events, you can perform valuable analyses on user behavior, system problems, or usage patterns in the future. This information can be useful in optimizing the user experience or making management decisions.

Install and set up the Payload Auditor plugin

Setting up the payload-auditor plugin is very simple and quick, and it can be added to the Payload CMS project in a few short steps. Here are the basic installation and configuration steps:

🧱 Installing with npm / yarn / pnpm

First, add the plugin to your project using your preferred package manager (although we recommend using pnpm):

npm install payload-auditor

Or if you are using yarn:

yarn add payload-auditor

Or with pnpm:

pnpm add payload-auditor

⚙️ Adding the plugin to the Payload configuration

After installation, simply import and enable the plugin in the Payload configuration file (usually payload.config.ts or payload.config.js).

import { buildConfig } from 'payload/config'
import { auditorPlugin } from 'payload-auditor'

export default buildConfig({
  collections: [
    // ... your collections here
  ],
  plugins: [
    auditorPlugin({
      // plugin settings go here
    }),
  ],
})

🛠️ Basic configuration (simple example)

In this simple example, we will configure only one collection called media for logging. Payload-Auditor uses payload cms hooks for logging operations. In this configuration, only update operations will be logged using the afterChange hook:

auditorPlugin({
  collection: {
    trackCollections: [
      {
        slug: 'media',
        hooks: {
          afterChange: {
            update: {
              enabled: true,
            },
          },
        },
      },
    ],
  },
})

With these simple settings, the plugin starts logging changes to the media collection.

Payload Auditor Plugin Configuration Options

The payload-auditor plugin is designed for high flexibility, allowing you to specify exactly which collections are logged, under what conditions, and with what operations. Here are the most important configuration options:

🕒 `automation`

This option manages automated operations in the logging system. For example, you can specify how many old logs you want to delete. You can even specify which logs are considered old:

      automation: {
        logCleanup: {
          strategy: {
            name: 'manual',
            amount: 66,
            olderThan: '2m',
          },
        },
      },

In the above code, logs that are more than two minutes old are considered old and 66 of them are deleted each time. Please note that this is just an example.

📁 `trackCollections`

In this option, you introduce a list of collections whose activities you want to track. For each collection you can have its own settings. The settings in this section are very flexible, meaning you can enable all Payload hooks for each collection and even specify which operations you want to enable.

trackCollections: [
  {
    slug: 'users',
    hooks: {
      afterChange: {
        update: { enabled: true },
        create: { enabled: true },
      },
    },
  },
]

🎯 Filtering operations inside hooks

The plugin allows you to log only some specific operations (for example, only update or delete).
This way, the logs become more targeted and lightweight.

hooks: {
  afterOperation: {
    delete: { enabled: true },
    create: { enabled: false },
  },
}

📦 Complete example of an advanced configuration

In the following example, two collections (users and posts) are tracked. In the users collection, only the update operation is logged in the afterChange hook. In the posts collection, only the delete is logged in the afterOperation hook. Also, the logs are deleted after 30 days:

auditorPlugin({
      automation: {
        logCleanup: {
          strategy: {
            name: 'manual',
            amount: 150,
            olderThan: '7d',
          },
        },
      },
      collection: {
        trackCollections: [
          {
            slug: 'users',
            hooks: {
              afterChange: {
                update: {
                  enabled: true,
                },
              },
            },
          },
          {
            slug: 'posts',
            hooks: {
              afterOperation: {
                delete: {
                  enabled: true,
                },
              },
            },
          },
        ],
      },
    })

How the Payload Auditor Plugin Works

The payload-auditor plugin uses the very powerful hooks feature of Payload CMS to log and track important operations at the collection level. This approach makes logging non-destructive, modular, and controllable.

🔄 Using hooks for logging

By default, Payload CMS provides a set of hooks for each collection, including:

beforeChange
afterChange
beforeOperation
afterOperation
and all payload cms hooks...

By connecting to these hooks, the payload-auditor plugin intercepts and logs all operations that occur in your project — but only if you have enabled it.

📌 Unlike some other tools, this plugin only logs when you tell it to, so there is no additional overhead to your project.

⚙️ Differences between operations (create, update, delete)

For each hook you can specify exactly which type of operation should be logged. For example:

hooks: {
  beforeValidate: {
    update: { enabled: true },
    create: { enabled: false },
  },
}

In this example:

The update operation is logged in the afterChange hook.
But the create operation is ignored. Of course, it is also ignored if you do not fully define this operation. This feature is mostly for when you want to ignore this operation for now and enable it later.

This level of fine-grained control allows you to tailor the logging system to exactly the needs of your project.

⏸️ Ability to temporarily stop logging for a specific collection

You may want to temporarily stop logging on a collection — for example, to fix a bug or during development. The plugin provides this feature as well. Just set the enabled property value to false or remove the collection from the trackCollections list.

Example:

{
  slug: 'comments',
  enabled: false, // This collection is temporarily untracked.
}

Or remove it altogether so that no hooks are attached to it.

This design is both simple and extensible

Usage Scenarios

The payload-auditor plugin is not just a logging tool; it is a tool for analysis, security, and better management of real projects. Here are some of the most common scenarios where this plugin will be very useful:

🔐 Logging user logins and profile changes

In projects where users can log into the admin panel, accurate tracking of when and how they log in or changes to their profile is very important from a security and support perspective.

By enabling logging on the users collection (assuming that site users are stored in a collection with the slug users), you can:

Identify who logged in and when.
Document changes to email, name, password, or user role.
Track support reports faster.

🔍 Security Issues Investigation and User Behavior Analysis

In many cases, suspicious behavior or security issues can be identified simply by looking at the logs. This plugin allows you to:

Track unusual deletion or editing operations.
Analyze specific user or admin behaviors and identify dangerous patterns.
Generate a detailed report for security or compliance audits (in development).

👥 Use in multi-user projects with different access levels

In projects where several people with different roles work on a CMS, such as:

Content Editors
Support Agents
Admins

Managing changes and answering the question "Who did what?" becomes extremely difficult.
The payload-auditor plugin is essential in such environments:

Accurately logging operations for each role
Preventing unwanted or erroneous changes
Helping to build team discipline and trust in large teams

Best practices for using Payload Auditor

To use the payload-auditor plugin effectively and securely, it is recommended to follow some tips and recommendations. Here are some important ones:

✅ 1. Optimal and targeted configuration

Not all collections need logging. Only select those that contain sensitive data or important operations (such as users, orders, payments).

Recommendation:

Only enable hooks and operations that really need to be tracked.
This will reduce the size of the logs and improve system performance.

🧹 2. Intelligent long-term log retention

If not managed properly, logs can cause database size to increase and performance to decrease over time. Use the automation option to control the lifetime of logs.

Example:

 automation: {
        //  ...
      },

In sensitive projects:
If you need long-term retention, move logs to archive systems or centralized logging tools (like ELK Stack or Logstash). For this, you can use customLogger which is provided at 4 levels: global, hook level, specific hook level and operation level.

🔒 3. Restrict access to logs

Not all users should have access to logs. For added security:

Only root admins or users with specific roles (e.g. Auditor) should be able to view or analyze logs.
Restrict access to log collections using Access Control in Payload.

Simple example:

Accessibility:{
          // Your configuration
        },

🧪 4. Testing and Monitoring in the Development Environment

Before using in the production environment, test the plugin’s performance thoroughly in the development or staging environment. Check:

Are logs recorded accurately?
Are unnecessary operations not logged?
Is system performance not degraded?

Following these practices will make the Payload Auditor plugin one of the pillars of your project’s security and professional maintenance, rather than an additional tool.

Conclusion

The Payload Auditor plugin is a powerful and flexible tool that allows you to accurately and securely track user activities and important changes in your Payload CMS projects. With this plugin, you can:

Increase project security in multi-user environments,
Quickly identify problems and suspicious behavior,
Generate detailed and analytical reports for better project management,
And experience all these features with high customization capabilities and precise log management.

If you are also looking to improve security and transparency in your Payload CMS projects, we recommend that you definitely try this plugin.

Contribute to development

This project is open source and interested developers can help improve and expand it by providing feedback, suggestions, or contributing to its development. To view the source code, complete documentation, and start contributing, visit its official GitHub repository:

Payload Auditor on GitHub

With this tool, take an important step towards increasing the security, control, and monitoring of your Payload CMS projects and experience more sustainable development.

Resources and Links

To learn more and better use the Payload Auditor plugin, as well as learn related concepts, you can refer to the following resources:

If you’re looking to increase security, transparency, and analytics in your Payload CMS projects, try the Payload Auditor plugin today.
We’re eager to hear your feedback, suggestions, and contributions to the development of this tool.
Check out the project on GitHub, give it a ⭐ star, and join us in building a stronger and more secure Payload ecosystem!

DEV Community: seyed mojtaba shadab

Exploring customLogger: Smart, Customizable Logging in Payload CMS

🧾 Brief Introduction to Payload CMS

🎯 Key Features of Payload:

🔍 What is the payload-auditor plugin?

✨ The main goal of this plugin:

⚙️ Key features:

📚 The importance of custom logging in content management systems (CMS)

Why do we need custom logging?

1. 🎯 Customization

2. 🕵️‍♀️ Transparency and Audit Trail

3. 🔐 Security and Accountability

4. 📊 Analytics and Intelligence

🔧 What is customLogger?

🧩 Defining customLogger at the Hook Level

🔀 Multi-level customLoggers

🔢 customLogger definition levels (in order of execution priority):

1. 🥇 Operation-Level

2. 🥈 Hook-Level

3. 🥉 All Hooks Level (Hooks-Level)

4. 🏁 Global-Level

🔁 Execution hierarchy summary:

🧬 customLogger structure

🛠 Function Inputs

1. args: All hook arguments

2. fields: Initial log structure (Log Fields)

📤 Expected Output

⏳ Support for async operations

📌 Practical examples

1. 🧼 Changing the user value to null

🧩 Line-by-line analysis

🎯 Real-world uses of this change

2. 🌐 Adding custom information (e.g. IP)

🧩 Line-by-line analysis

🧰 Introducing the helper function

🎯 Real-world applications

⚠️ Critical points when using customLogger

🔄 1. Prioritization when using customLogger

🧩 2. Differences with customLogger at hook level

✅ Best Practices

🧼 1. Keep your log structure simple

🔐 2. Avoid storing sensitive data (unless encrypted)

🌐 3. Use async for external data

🎯 Other recommendations

📍 Conclusion

🧩 Summary of features

🎯 More accurate tracking of system changes

💡 Suggestions for developers

🔗 Link to the main plugin documentation

💻 GitHub Repository Link

🤝 Appreciation and Contribution

Tracking and Security in Payload CMS with the Payload-Auditor Plugin

A Brief Introduction to Payload CMS

Why do we need logging and tracing in Payload?

Payload Auditor Plugin: Answering Your Monitoring and Security Needs

Why Payload Auditor?

Common Problems in Payload Projects Without a Logging System

Benefits of Using the Payload Auditor Plugin

Install and set up the Payload Auditor plugin

🧱 Installing with npm / yarn / pnpm

⚙️ Adding the plugin to the Payload configuration

🛠️ Basic configuration (simple example)

Payload Auditor Plugin Configuration Options

🕒 automation

📁 trackCollections

🎯 Filtering operations inside hooks

📦 Complete example of an advanced configuration

How the Payload Auditor Plugin Works

🔄 Using hooks for logging

⚙️ Differences between operations (create, update, delete)

⏸️ Ability to temporarily stop logging for a specific collection

Usage Scenarios

🔐 Logging user logins and profile changes

🔍 Security Issues Investigation and User Behavior Analysis

👥 Use in multi-user projects with different access levels

Best practices for using Payload Auditor

✅ 1. Optimal and targeted configuration

🧹 2. Intelligent long-term log retention

🔒 3. Restrict access to logs

🧪 4. Testing and Monitoring in the Development Environment

🔍 What is the `payload-auditor` plugin?

🔧 What is `customLogger`?

🧩 Defining `customLogger` at the Hook Level

🔀 Multi-level `customLoggers`

🔢 `customLogger` definition levels (in order of execution priority):

🧬 `customLogger` structure

1. `args`: All hook arguments

2. `fields`: Initial log structure (Log Fields)

1. 🧼 Changing the user value to `null`

⚠️ Critical points when using `customLogger`

🧩 2. Differences with `customLogger` at hook level

🕒 `automation`

📁 `trackCollections`