Skip to content

DOC-2876 Update GSQL audit-log [4.3] #863

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
AyeshaFirdausTG merged 2 commits into from
Oct 27, 2025
Merged

DOC-2876 Update GSQL audit-log [4.3] #863

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0938e36
DOC-2876 Update GSQL audit-log [4.3]
AyeshaFirdausTG Sep 19, 2025
822a20f
Update audit-log.adoc
AyeshaFirdausTG Sep 22, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Next Next commit
DOC-2876 Update GSQL audit-log [4.3]
  • Loading branch information
@AyeshaFirdausTG
AyeshaFirdausTG authored Sep 19, 2025
commit 0938e36e307b72d77c85e6122b3b22b027b7d2dd
90 changes: 80 additions & 10 deletions modules/troubleshooting/pages/audit-log.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,8 @@ However, compared to the debug log, the audit log contains significantly less da

¦ `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/`)
Expand All @@ -54,6 +56,15 @@ However, compared to the debug log, the audit log contains significantly less da

|===

[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 xref:reference:configuration-parameters.adoc[] page.

=== Apply Configuration Changes
Expand Down Expand Up @@ -98,15 +109,6 @@ $ gadmin config set System.LogRoot <log-root-path>
Altering `<System.LogRoot>` impacts the root path for ALL TigerGraph logs.
====

There is a *"DatabaseName"* field appended to the header of each audit log file.
*The* value of this field is "TigerGraph" by default.

You can modify this value by running the following command:
[source, console]
----
$ gadmin config set System.Audit.DataBaseName <database-name>
----

== Log File Management Policies

=== File creation and size
Expand Down Expand Up @@ -217,6 +219,70 @@ The following information is masked (excluded from the audit logs) by default, b
====
Each activity will have its own audit log entry and fields.
====

=== GSQL Service Audit Log Fields

[options="header"]
|===
| 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"`.

| 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:
[source, json]
----
Expand All @@ -228,7 +294,9 @@ Each activity will have its own audit log entry and fields.
"clientOSUsername":"OSusername",
"userAgent": "GSQL Shell",
"endpoint": "/gsql/file",
"actionType": "DDL",
"actionName": "createQuery",
"object": "Query",
"status": "SUCCESS",
"message": "Successfully created query 'query_name'"
}
Expand All @@ -248,7 +316,9 @@ This field indicates how many times this user failed to provide the correct cred
"clientOSUsername":"tigergraph",
"userAgent": "GraphStudio",
"endpoint": "/gsql/simpleauth",
"actionType": "Other",
"actionName": "login",
"graph": "global",
"failedAttempts" : 1,
"status" : "FAILURE",
"message": "Username doesn't exist"
Expand Down Expand Up @@ -370,4 +440,4 @@ However, if `System.Audit.MaskPII` is set to `false`, then the log will contain
* [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.
* 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.