Audit Log

Grainite Audit Log provides a security-relevant, chronological set of records documenting the sequence of actions within a cluster. The cluster audits the activities generated by principals, and by applications that use the Grainite API.


Prior to enabling auditing on Grainite clusters, the following prerequisites must be met.

  1. Deploy a secure Grainite cluster in a cloud environment.

  2. Create a user who has the privileges to perform security-related tasks as outlined in the Role-Based Access Control document. Alternatively, the cluster_admin can enable auditing of the applications within the cluster.

On your local machine:

  1. Download and set up gx as described in the environment setup.

  2. Ensure you have a Maven installation (version 3.8.3 or higher).


Audit log is implemented as a Grainite application. Thus you will first need to run the below command to generate the application YAML configuration file which we'll be loading to your cluster.

gx security setup-audit

Once the command is complete, you'll see that the application's YAML configuration file was generated with the path provided in the output. Please replace <path_to_app.yaml> in the command below with the path provided in your console output.

gx load -c <path_to_app.yaml>


To set up the auditing environment, you will need to update the global_policies.yaml file and add the audit section. A sample is provided below.

    - <env_name>/<app_name>
  log-level: 3
  destination: <remote_ip>:<port>

apps: This allows you to specify the applications for which auditing must be enabled within the cluster. It is specified using the following format: <environment>/<app_name>

log-level: The log levels provide control over the type of information that admins want to be captured with auditing.

  • 1: Global level commands (e.g. gx security)

  • 2: Level 1 + Application level commands (e.g. gx topic dump)

  • 3: Everything (includes read/write/update operations)

destination: This contains the listener of the audit messages.

Reading Audit Log Message:

A sample message that is generated by the auditing feature is shown below.

Jun  7 22:27:08 grainite-RBAC audit: {"PodRequestId":"8","RequestType":"authorization","TimeStamp":"2023-06-07 22:27:08.0876","PodId":"gxs-2","ClientIp":"XX.XXX.XX.X","ClientPort":"XXXXX","ServerIp":"XX.XXX.XX.XX","ServerPort":"5057","ClusterName":"my-cluster","ErrorCode":"1000","ErrorMessage":"","OriginalQuery":"RegisterApp","Environment":"default","Application":"userflows","Principal":["cluster_admin"],"Roles":["cluster_admin"],"Operation":"NONE","Resource":"","Succeeded":"True","Destination":"XX.XXX.XX.XXX:XXX"}#015

Below is a description of each field in the audit log message:



A unique entry generated for each audit log message per pod(podID).


Type of request to carry out the operation. We currently support Authorization.


UTC time stamp of the request to the cluster.


Grainite Pod on which request was executed. In a 3-node cluster, the possible values are gxs-0, gxs-1, and gxs-2.


Client IP address of the user or application making the request.


Port from the client side of the connection


Server IP address that received and executed the request.


Server port that received the request.


This is the name of the cluster.


Generated error code.


Database generated error text.


Type of query from the principal.


Namespace to which query was sent. If no namespace exists, the default will be specified.


Specifies the name of the application which executed the database action.


The principal that initiated the request (from client certificate or other grainite app).


Role(s) assigned to the Principal


Type of operation performed on the resource


Grainite resources such as Topic or Table


Status of operation


Remote Destination server IP that the log will be sent to

Last updated