---
title: "Audit Logs"
component: "tigergraph-server"
version: "4.3"
module: "troubleshooting"
html_url: "/tigergraph-server/4.3/troubleshooting/audit-log"
canonical_url: "https://www.tigergraph.com/docs/tigergraph-server/4.3/troubleshooting/audit-log"
markdown_url: "https://www.tigergraph.com/docs/tigergraph-server/4.3/troubleshooting/audit-log.md"
---

[View as HTML](https://www.tigergraph.com/docs/tigergraph-server/4.3/troubleshooting/audit-log)

# Audit Logs

Audit logs maintain a historical record of activity events, noting the time, responsible user or service, and affected entity.

Audit logs enable organizations to meet certain compliance and business policy requirements. Additionally, Administrators use audit logs to track user activity, and security teams use them to investigate breaches and ensure regulatory compliance.

The sections below outline the [Key Features and Considerations](https://www.tigergraph.com/docs/tigergraph-server/4.3/troubleshooting/audit-log.md#_key_features_and_considerations), [Enabling Audit Logging](https://www.tigergraph.com/docs/tigergraph-server/4.3/troubleshooting/audit-log.md#_enabling_audit_logging), [Log File Management Policies](https://www.tigergraph.com/docs/tigergraph-server/4.3/troubleshooting/audit-log.md#_log_file_management_policies), [Audit Log Format](https://www.tigergraph.com/docs/tigergraph-server/4.3/troubleshooting/audit-log.md#_audit_log_format), [Data Masking](https://www.tigergraph.com/docs/tigergraph-server/4.3/troubleshooting/audit-log.md#_data_masking), and [Known Issues](https://www.tigergraph.com/docs/tigergraph-server/4.3/troubleshooting/audit-log.md#_known_issues).

## Key Features and Considerations

* The audit logs are structured in JSON format, ensuring machine-readability and easy integration with third-party tools.
* The gathering of audit data into one log eliminates the need to navigate through numerous log files.

### Security

* Like other `gadmin` configurations, only the Linux user with server access can enable and configure the audit log.
* Access to the audit log is restricted to those who have access to TigerGraph logs.
* Sensitive data or PII in the audit log, such as credentials or sensitive query payload information is masked by default. See the section [Data Masking](https://www.tigergraph.com/docs/tigergraph-server/4.3/troubleshooting/audit-log.md#_data_masking) for more details.

### Performance and Scalability

* Enabling audit logging records audit logs to separate files, adding a slight disk I/O workload. However, compared to the debug log, the audit log contains significantly less data, ensuring negligible performance impact.

## Configuration Parameters

| Configuration | Description | Type (Default Value) |
| --- | --- | --- |
| `System.Audit.Enable` | Setting to enable audit logs. | boolean (false) |
| `System.Audit.DiscreteJsonFormat` | Setting to print each log entry as a discrete JSON object instead of a JSON array. | boolean (false) |
| `System.Audit.DataBaseName` | Modify the DataBaseName field in log file header. | string (`TigerGraph`) |
| `System.Audit.LogDirRelativePath` | Modify the relative audit log path. | path string (`<TG_LogRoot>/AuditLog/`) |
| `System.Audit.LogConfig.LogFileMaxDurationDay` | Modify the modification date when a new audit log file is created. | Integer (90) |
| `System.Audit.LogConfig.LogFileMaxSizeMB` | Modify the audit log file's max size. | Integer (100) |
| `System.Audit.LogConfig.LogRotationFileNumber` | Modify the max amount of Audit Log files in the Audit Log folder. | Integer (100) |
| `System.Audit.MaskPII` | Mask Sensitive data or PII in the audit log. | boolean (true) |

> [!NOTE]
> By default, the `databaseName` field is no longer printed in the audit log header. Users can enable it by setting a custom value with:
> 
> gadmin config set System.Audit.DataBaseName <value>
> 
> The value provided will appear in the log file header.

For a complete list of TigerGraph `gadmin` configuration parameters, see the [Configuration Parameters](https://www.tigergraph.com/docs/tigergraph-server/4.3/reference/configuration-parameters.md) page.

### Apply Configuration Changes

If you use `gadmin` config to change any of these parameters, you need to run `gadmin config apply -y` for it to take effect. You can change multiple parameters and then run `gadmin config apply` for all of them together

After modifying the configurations, run the following command to apply the changes:

$ gadmin config apply -y
$ gadmin restart gsql -y

## Enabling Audit Logging

Audit logging is disabled by default. To enable audit logging, use the following `gadmin` command:

$ gadmin config set System.Audit.Enable true

Once enabled, the audit log will be found in the `<System.LogRoot>/AuditLog` folder. The `<System.LogRoot>` represents the default path for all TigerGraph logs, set to `tigergraph/log` by default.

To customize the **relative path** for the audit log (in relation to `<System.LogRoot>`), run the following command:

$ gadmin config set System.Audit.LogDirRelativePath <audit-log-relative-path>

You can also modify the **`<System.LogRoot>`** on your environment by:

$ gadmin config set System.LogRoot <log-root-path>

> [!NOTE]
> Altering `<System.LogRoot>` impacts the root path for ALL TigerGraph logs.

## Log File Management Policies

### File creation and size

A new audit log file will be created when **any** of the following situations occur:

* The GSQL service is restarted.
* The latest audit log file size exceeds the `System.Audit.LogConfig.LogFileMaxSizeMB` value. The default value is 100 MB.  
You can modify this value by running the following command:  
$ gadmin config set System.Audit.LogConfig.LogFileMaxSizeMB <file-size>

### File deletion

A log file will be removed if its lifetime exceeds `System.Audit.LogConfig.LogFileMaxDurationDay` days. The default value is 90 days.

You can modify this value by running the following command:

$ gadmin config set System.Audit.LogConfig.LogFileMaxDurationDay <max-duration-day>

The oldest audit log file will be automatically deleted if the number of audit logs in the audit log folder exceeds the `System.Audit.LogConfig.LogRotationFileNumber` value. The default value is 100 log files.

You can modify this value by running the following command:

$ gadmin config set System.Audit.LogConfig.LogRotationFileNumber <file-number>

## Audit Log Format

### General Format

All audit log files are stored in JSON format, even when users are actively interacting with TigerGraph, so audit logs can be consumed at run time.

> [!NOTE]
> Audit log files are separated by GSQL service and REST++ API calls. Both having separate file names:
> 
> * `log.AUDIT-GSQL` for the GSQL service.
> * `log.Audit-RESTPP` for direct REST++ API calls.
> * `log.Audit-GADMIN` for `gadmin` command executions.

Here is an example of a whole audit log file:

```json
[
    {"serverHostIP":"127.0.0.1","databaseName":"TigerGraph","version":"1.0","timestamp":"2023-12-20T14:42:50.243-07:00"},
    {"endpoint":"/gsql/file","clientHost":"127.0.0.1:43746","clientOSUsername":"tigergraph","userAgent":"GSQL Shell","userName":"tigergraph","authType":"USER_PASS","message":"Successfully created user 'u1'.","timestamp":"2023-12-20T14:42:50.243-07:00","actionName":"createUser","status":“SUCCESS”},
    {"endpoint":"/gsql/file","clientHost":"127.0.0.1:54746","clientOSUsername":"tigergraph","userAgent":"GSQL Shell","userName":"tigergraph","authType":"USER_PASS","message":"Successfully created query 'printVertex'.","timestamp":"2023-12-20T14:42:50.243-07:00","actionName":"createQuery","status":“SUCCESS”},
    {"endpoint":"/gsql/library","clientHost":"127.0.0.1:54770","clientOSUsername":"tigergraph",,"userName":"tigergraph","authType":"USER_PASS","message":"callTemplateQuery succeed","timestamp":"2023-12-20T14:42:50.243-07:00","actionName":"callTemplateQuery","status":“SUCCESS”}
]
```

* Each audit log file is a JSON array of JSON objects, one object per log entry.
* Each object is formatted as a single line for better readability of high volume data.

### GSQL Service Audit Logs

The first JSON object is the header of this file, which consists of the following fields:

```json
{
    "version": "1.0",
    "timestamp":"2023-12-20T14:42:50.243-07:00",
    "dataBaseName": "TigerGraph",
    "serverHostIP": "192.168.1.1",
}
```

The GSQL audit log will record any user-triggered activity handled by the GSQL server, whether initiated by a GSQL shell command or sent as a REST request to the GSQL server. This includes operations such as:

* Log in
* Log out
* Change password
* Create or drop a user
* Grant/drop a role (the role and target username are logged)
* Create a secret (the secret alias is logged)
* Create a query
* Run/interpret a query
* Create a loading job
* Run a loading job

In general, log entries include the timestamp, user ID, action type, and object being acted on. The graph name is logged for queries and loading jobs.

> [!NOTE]
> The following information is masked (excluded from the audit logs) by default, but it will be included if the system configuration parameter `System.Audit.MaskPII` is set to `false`:
> 
> * The body of a query, when creating a query
> * Input argument values, when running or interpreting a query
> * Filename(s) of the data source, when running a loading job

> [!NOTE]
> Each activity will have its own audit log entry and fields.

### GSQL Service Audit Log Fields

| Field Name | Type | Description |
| --- | --- | --- |
| clientHost | string | Client IP Address |
| userAgent | string | Client type: GSQL shell, GraphStudio etc. |
| userName | string | Username of GSQL service |
| clientOSUsername | string | OS-level username of the client |
| timestamp | ISODate | Event timestamp |
| authType | string | Authentication type: Password, SSO, Secret, etc. |
| endpoint | string | Endpoint URL |
| actionType | string | Standardized database action type. Possible values: DDL, DML, DQL, DCL, TCL, Other. |
| actionName | string | The specific action performed (e.g., createVertex, runQuery) |
| objectType | string | The object impacted by the action (e.g., Vertex, Edge, Graph, Job, User, Role, Privilege, Query, Function, Package, Secret, DataSource, etc.). |
| graphName | string | The graph context for the action. For global actions not tied to a specific graph (e.g., create user, grant role), the value is `"global"`. |
| commandText | string | The exact GSQL command text executed. For GraphStudio or REST requests, this may include request parameters or body. If not applicable, shown as `"N/A"`. |
| duration | string | Time taken to complete the operation (for example, `3ms`). |
| status | SUCCESS/FAILED | Whether the action executed successfully |
| message | string | A simple summary of the action |

The `createQuery` activity will produce an audit log entry with the following fields:

```json
{
    "timestamp":"2023-12-20T14:42:50.243-07:00",
    "userName": "tigergraph",
    "authType": "password",
    "clientHost": "<IP or FQDN>:<Port>",
    "clientOSUsername":"OSusername",
    "userAgent": "GSQL Shell",
    "endpoint": "/gsql/file",
    "actionType": "DDL",
    "actionName": "createQuery",
    "object": "Query",
    "duration": "2ms",
    "status": "SUCCESS",
    "message": "Successfully created query 'query_name'"
}
```

For user `login/auth` related activities, one more field called `failedAttempts` is added to the JSON. This field indicates how many times this user failed to provide the correct credentials.

Here is an example for user login event:

```json
{
    "timestamp": "2023-12-20T14:42:50.243-07:00",
    "userName": "tigergraph",
    "authType": "SAML SSO",
    "clientHost": "<IP or FQDN>:<Port>",
    "clientOSUsername":"tigergraph",
    "userAgent": "GraphStudio",
    "endpoint": "/gsql/simpleauth",
    "actionType": "OTHER",
    "actionName": "login",
    "graphName": "global",
    "failedAttempts" : 1,
    "duration":"3ms",
    "status" : "FAILURE",
    "message": "Username doesn't exist"
}
```

Here is an example of a user logout event:

```json
{
    "timestamp": "2025-08-15T08:51:20.159Z",
    "userName": "tigergraph",
    "authType": "USER_PASS",
    "clientHost": "<IP or FQDN>:<Port>",
    "clientOSUsername":"OSUser",
    "userAgent": "GSQL Shell",
    "endpoint": "/gsql/v1/statements",
    "actionType": "OTHER",
    "actionName": "logout",
    "graphName": "global",
    "commandText": "exit",
    "duration": "2ms",
    "status": "SUCCESS",
    "message": "logout succeeded"
}
```

### REST++ API Call Audit Logs

Audit logs for REST++ calls are found in the `log.Audit-RESTPP` file. They are similar to GSQL service audit logs, such as, the status for API calls will be either `SUCCESS` or `FAILURE`, but they are different in these ways:

* The duration is the runtime cost with seconds.
* The code will be the return codes from the REST++ server, see [Return Codes](https://www.tigergraph.com/docs/tigergraph-server/4.3/reference/return-codes.md#_rest).
* A new field `requestId` is also added.

Values in `requestParams` and `requestBody` will be masked if they contain PII data.

Here is an example of the REST++ call event:

```json
{
  "timestamp": "2023-10-02T15:06:18.365Z",
  "userName": "tigergraph",
  "authType": "token",
  "clientHost": "<IP or FQDN>:<Port>",
  "userAgent": "curl",
  "endpoint": "/restpp/query/{graph_name}/{query_name}",
  "actionName": "runQuery",
  "status": "SUCCESS",
  "duration": 3.24,
  "requestId": "16842763.RESTPP_1_1.1561401340785.N",
  "requestParams": "",
  "requestBody": "",
  "code": "REST-0000",
  "message": "<success/error message>"
}
```

### gadmin Audit Logs

Audit logs for gadmin command executions are found in the `log.Audit-GADMIN` file.

Besides the basic information such as `timestamp`, `OS`, `username`, they capture the `gadmin` commands executed on the node and the outcomes:

Here is an example of the event after running command: `gadmin start all`

```json
{
"timestamp": "2024-05-13 23:45:34.940",
"session id": 1418,
"OS username": "tigergraph",
"host": "10.128.0.48",
"command": "gadmin start all",
"status": "SUCCESS"
}
```

## Data Masking

By default, logs will not contain potentially sensitive data such as query parameters and query contents. For audit logs, there are three data files which are masked:

* `"queryConent"`
* `"queryParameters"`
* `"fileNames"`

These fields will have the value `"<Masked>"`. For example:

```json
{
  "queryContent":"<Masked>",
  "endpoint":"/gsql/v1/statements",
  "clientHost":"10.244.6.79",
  "clientOSUsername":"tigergraph",
  "queryParameters":"<Masked>",
  "userAgent":"GSQL Shell",
  "userName":"tigergraph",
  "authType":"USER_PASS",
  "message":"Successfully ran query 'SumOfTwoInt'.",
  "timestamp":"2025-04-25T08:51:20.159Z",
  "actionName":"runQuery",
  "status":"SUCCESS"
}
```

However, if `System.Audit.MaskPII` is set to `false`, then the log will contain the unmasked data, such as

```json
{
  "queryContent":"CREATE OR REPLACE QUERY SumOfTwoInt(Int x, Int y) {\n  Print x+y;\n}",
  "endpoint":"/gsql/v1/statements",
  "clientHost":"10.244.6.79",
  "clientOSUsername":"tigergraph",
  "queryParameters":{"x":["3"],"y":["7"]},
  "userAgent":"GSQL Shell",
  "userName":"tigergraph",
  "authType":"USER_PASS",
  "message":"Successfully ran query 'SumOfTwoInt'.",
  "timestamp":"2025-04-25T08:51:20.159Z",
  "actionName":"runQuery",
  "status":"SUCCESS"
}
```

## Known Issues

* Even when REST++ authentication is enabled and when a request that failed due to an invalid request parameter, the username in the corresponding audit log will be marked as `unknown` instead of the actual username.  
   * This is because request parameter validation happens before token validation. Thus, REST++ calls do not know the username before it gets printed in the audit log.
* If the user logs into TG Cloud using SSO, they will not be required to provide credentials again when opening GraphStudio.  
   * Therefore, the login event would not be reflected in the audit log, but the user's subsequent operations (`create query`, `install query`, etc.) will be recorded in the audit log as normal.
* \[Fixed in 3.10.2 and 4.1.1\] The real client IP address could be removed or masked by a firewall or another intermediate redirect layer before arriving at the TigerGraph service.  
   * Thus, TigerGraph cannot get the actual client ip, instead it will put the ip address of the last layer who forwarded the request to TigerGraph service in the audit log.
* If a RESTPP request is for a graph operation and thus sent to the GPE then fails inside the GPE, the RESTPP will interpret the response from the GPE as success and report SUCCEED in the audit log.
* `commandText` field double quotes may not be escaped correctly  
   * For example, the command `show function -r ".**f.**"` should be shown as `"commandText":"show function -r \".**f.**\""`, however, it is currently shown as `"commandText":"show function -r .**f.**"` for now
