> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bytebase.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Audit Log

Audit logging tracks all configuration changes and data operations within your Bytebase workspace. These logs help you identify who performed what action, when it occurred, and what resources were affected. This enables compliance monitoring, security analysis, and troubleshooting.

<Info>
  Audit logging is available only for **Pro** and **Enterprise** plans.
</Info>

## Accessing Audit Logs

### GUI

**Workspace Admin** or **DBA** can access audit logs through the Bytebase console:

1. Navigate to the **Settings** page
2. Select **Audit Log** from the sidebar
3. View the chronological list of all audit events

<img src="https://mintcdn.com/dbx/hVml3kA8vNK6vcVL/content/docs/security/audit-log/overview.webp?fit=max&auto=format&n=hVml3kA8vNK6vcVL&q=85&s=e7d660ecbd7fa1df2a425cc063fec38a" alt="overview" width="1334" height="956" data-path="content/docs/security/audit-log/overview.webp" />

You can filter audit logs by:

* User
* Action type
* Resource
* Time range

<img src="https://mintcdn.com/dbx/hVml3kA8vNK6vcVL/content/docs/security/audit-log/filter.webp?fit=max&auto=format&n=hVml3kA8vNK6vcVL&q=85&s=12d9ac5354cd694a10e9940cc61130c6" alt="filter" width="994" height="328" data-path="content/docs/security/audit-log/filter.webp" />

<img src="https://mintcdn.com/dbx/hVml3kA8vNK6vcVL/content/docs/security/audit-log/filter-date.webp?fit=max&auto=format&n=hVml3kA8vNK6vcVL&q=85&s=324b03753cabe0a4a23733c7201b869c" alt="filter-date" width="1246" height="423" data-path="content/docs/security/audit-log/filter-date.webp" />

### API

Use the Bytebase API to programmatically access audit logs for integration with external systems and automated monitoring.

<Tip>
  For detailed API documentation and examples, see [Audit Log API](/integrations/api/audit-log/).
</Tip>

### Streaming

Stream audit logs to external logging and monitoring systems for centralized management. It supports JSON format output in addition to the default text format.

1. Navigate to **Settings** → **General** → **Audit Log Export**
2. Enable **Enable audit logging to stdout**
3. Save the configuration

Once enabled, all audit events stream to stdout of your Bytebase service.

To enable **JSON format output**, start Bytebase with the `--enable-json-logging` flag:

```bash theme={null}
docker run --rm --init \
  --name bytebase \
  --publish 8080:8080 --pull always \
  --volume ~/.bytebase/data:/var/opt/bytebase \
  bytebase/bytebase:latest \
  --enable-json-logging
```

Supported integrations:

* **SIEM Platforms**: e.g., Splunk, Datadog, Elastic Security
* **Log Aggregators**: e.g., Fluentd, Logstash, Grafana Loki
* **Cloud Services**: e.g., AWS CloudWatch, Google Cloud Logging, Azure Monitor

## Log Structure

### Example Entry

```json theme={null}
{
  "parent": "projects/sample-project",
  "method": "/bytebase.v1.SQLService/Query",
  "resource": "instances/prod-postgres/databases/mydb",
  "user": "users/developer@example.com",
  "severity": "INFO",
  "request": "{\"name\":\"instances/prod-postgres/databases/mydb\",\"statement\":\"SELECT * FROM users LIMIT 10\",\"limit\":100}",
  "response": "{\"results\":[{\"columnNames\":[\"id\",\"name\"],\"columnTypeNames\":[\"int4\",\"text\"],\"rowsCount\":10}]}",
  "status": { "code": 0 },
  "latency": { "seconds": 0, "nanos": 125000000 },
  "requestMetadata": {
    "callerIp": "192.168.1.100",
    "callerSuppliedUserAgent": "Mozilla/5.0 Chrome/120.0"
  }
}
```

### Payload Fields

| Field             | Type   | Description                                                                      |
| ----------------- | ------ | -------------------------------------------------------------------------------- |
| `parent`          | string | Scope of the audit log. Format: `projects/{project}` or `workspaces/{workspace}` |
| `method`          | string | Full API method name. Example: `/bytebase.v1.SQLService/Query`                   |
| `resource`        | string | The primary resource being acted upon                                            |
| `user`            | string | User who performed the action. Format: `users/{email}`                           |
| `severity`        | string | Log severity level                                                               |
| `request`         | string | JSON-serialized request payload (sensitive fields redacted)                      |
| `response`        | string | JSON-serialized response payload (sensitive fields redacted)                     |
| `status`          | object | gRPC status with `code` and `message` fields                                     |
| `latency`         | object | Operation duration with `seconds` and `nanos` fields                             |
| `serviceData`     | object | Service-specific metadata (e.g., IAM policy changes)                             |
| `requestMetadata` | object | Client information including `callerIp` and `callerSuppliedUserAgent`            |

### Severity Levels

| Level                  | Value | Description                      |
| ---------------------- | ----- | -------------------------------- |
| `SEVERITY_UNSPECIFIED` | 0     | Unspecified                      |
| `DEBUG`                | 1     | Debug-level information          |
| `INFO`                 | 2     | Informational messages (default) |
| `NOTICE`               | 3     | Notable events                   |
| `WARNING`              | 4     | Warning conditions               |
| `ERROR`                | 5     | Error conditions                 |
| `CRITICAL`             | 6     | Critical conditions              |
| `ALERT`                | 7     | Action must be taken immediately |
| `EMERGENCY`            | 8     | System is unusable               |

### Status Codes

Status codes follow [gRPC conventions](https://grpc.io/docs/guides/status-codes/):

| Code | Name                 | Description                                                              |
| ---- | -------------------- | ------------------------------------------------------------------------ |
| 0    | OK                   | Operation succeeded (no error)                                           |
| 1    | CANCELED             | Operation was canceled, typically by the caller                          |
| 2    | UNKNOWN              | Operation failed for an unknown reason                                   |
| 3    | INVALID\_ARGUMENT    | Client supplied an invalid argument                                      |
| 4    | DEADLINE\_EXCEEDED   | Deadline expired before the operation could complete                     |
| 5    | NOT\_FOUND           | Requested entity (e.g., file, resource) was not found                    |
| 6    | ALREADY\_EXISTS      | Entity that client attempted to create already exists                    |
| 7    | PERMISSION\_DENIED   | Caller doesn't have permission to execute the operation                  |
| 8    | RESOURCE\_EXHAUSTED  | Some resource has been exhausted (e.g., quota, disk space)               |
| 9    | FAILED\_PRECONDITION | System is not in a state required for operation's execution              |
| 10   | ABORTED              | Operation aborted due to concurrency issue (e.g., transaction abort)     |
| 11   | OUT\_OF\_RANGE       | Operation attempted past the valid range (e.g., seek past EOF)           |
| 12   | UNIMPLEMENTED        | Operation isn't implemented, supported, or enabled                       |
| 13   | INTERNAL             | Internal error - some invariants expected by the system have been broken |
| 14   | UNAVAILABLE          | Service is currently unavailable (usually temporary)                     |
| 15   | DATA\_LOSS           | Unrecoverable data loss or corruption                                    |
| 16   | UNAUTHENTICATED      | Request does not have valid authentication credentials                   |

## Audited Events

<AccordionGroup>
  <Accordion title="Authentication">
    | Event          | Method                                   | Description                                          |
    | -------------- | ---------------------------------------- | ---------------------------------------------------- |
    | User Login     | `/bytebase.v1.AuthService/Login`         | User authentication (password, SSO, MFA)             |
    | User Logout    | `/bytebase.v1.AuthService/Logout`        | User session termination                             |
    | Token Exchange | `/bytebase.v1.AuthService/ExchangeToken` | Workload Identity token exchange for CI/CD pipelines |

    **Notes:**

    * Sensitive fields redacted: `password`, `otpCode`, `recoveryCode`, `mfaTempToken`, `idpContext`
    * MFA phase logs extract user email from MFA temp token when email is not in request
  </Accordion>

  <Accordion title="User Management">
    | Event        | Method                                  | Description                        |
    | ------------ | --------------------------------------- | ---------------------------------- |
    | Create User  | `/bytebase.v1.UserService/CreateUser`   | Create new user account            |
    | Update User  | `/bytebase.v1.UserService/UpdateUser`   | Modify user settings, MFA, profile |
    | Delete User  | `/bytebase.v1.UserService/DeleteUser`   | Soft-delete user account           |
    | Restore User | `/bytebase.v1.UserService/UndeleteUser` | Restore deleted user               |
    | Update Email | `/bytebase.v1.UserService/UpdateEmail`  | Change user email address          |

    **Notes:**

    * User responses redacted to only include: `name`, `email`, `title`, `userType`
  </Accordion>

  <Accordion title="Group Management">
    | Event        | Method                                  | Description                      |
    | ------------ | --------------------------------------- | -------------------------------- |
    | Create Group | `/bytebase.v1.GroupService/CreateGroup` | Create user group                |
    | Update Group | `/bytebase.v1.GroupService/UpdateGroup` | Modify group membership/settings |
    | Delete Group | `/bytebase.v1.GroupService/DeleteGroup` | Delete user group                |
  </Accordion>

  <Accordion title="Role Management">
    | Event       | Method                                | Description             |
    | ----------- | ------------------------------------- | ----------------------- |
    | Create Role | `/bytebase.v1.RoleService/CreateRole` | Create custom role      |
    | Update Role | `/bytebase.v1.RoleService/UpdateRole` | Modify role permissions |
    | Delete Role | `/bytebase.v1.RoleService/DeleteRole` | Delete custom role      |
  </Accordion>

  <Accordion title="Identity Provider (SSO)">
    | Event                    | Method                                                        | Description                |
    | ------------------------ | ------------------------------------------------------------- | -------------------------- |
    | Create Identity Provider | `/bytebase.v1.IdentityProviderService/CreateIdentityProvider` | Configure new SSO provider |
    | Update Identity Provider | `/bytebase.v1.IdentityProviderService/UpdateIdentityProvider` | Modify SSO configuration   |
    | Delete Identity Provider | `/bytebase.v1.IdentityProviderService/DeleteIdentityProvider` | Remove SSO provider        |
  </Accordion>

  <Accordion title="Project Management">
    | Event                  | Method                                            | Description                       |
    | ---------------------- | ------------------------------------------------- | --------------------------------- |
    | Delete Project         | `/bytebase.v1.ProjectService/DeleteProject`       | Soft-delete project               |
    | Restore Project        | `/bytebase.v1.ProjectService/UndeleteProject`     | Restore deleted project           |
    | Batch Delete Projects  | `/bytebase.v1.ProjectService/BatchDeleteProjects` | Delete multiple projects          |
    | Set Project IAM Policy | `/bytebase.v1.ProjectService/SetIamPolicy`        | Modify project member permissions |

    **Notes:**

    * IAM policy changes include `serviceData` with `PolicyDelta` showing added/removed bindings
  </Accordion>

  <Accordion title="Workspace IAM">
    | Event                    | Method                                       | Description                        |
    | ------------------------ | -------------------------------------------- | ---------------------------------- |
    | Set Workspace IAM Policy | `/bytebase.v1.WorkspaceService/SetIamPolicy` | Modify workspace-level permissions |

    **Notes:**

    * Includes `serviceData` with `PolicyDelta` showing added/removed bindings
  </Accordion>

  <Accordion title="Instance Management">
    | Event                  | Method                                              | Description                    |
    | ---------------------- | --------------------------------------------------- | ------------------------------ |
    | Create Instance        | `/bytebase.v1.InstanceService/CreateInstance`       | Register new database instance |
    | Update Instance        | `/bytebase.v1.InstanceService/UpdateInstance`       | Modify instance configuration  |
    | Delete Instance        | `/bytebase.v1.InstanceService/DeleteInstance`       | Soft-delete instance           |
    | Restore Instance       | `/bytebase.v1.InstanceService/UndeleteInstance`     | Restore deleted instance       |
    | Batch Update Instances | `/bytebase.v1.InstanceService/BatchUpdateInstances` | Bulk update instances          |
    | Add Data Source        | `/bytebase.v1.InstanceService/AddDataSource`        | Add connection to instance     |
    | Update Data Source     | `/bytebase.v1.InstanceService/UpdateDataSource`     | Modify connection settings     |
    | Remove Data Source     | `/bytebase.v1.InstanceService/RemoveDataSource`     | Remove connection              |

    **Notes:**

    * DataSource sensitive fields redacted: `password`, `sslCa`, `sslCert`, `sslKey`, `sshPassword`, `sshPrivateKey`, `authenticationPrivateKey`, `externalSecret`, `saslConfig.krbConfig.keytab`, `masterPassword`
  </Accordion>

  <Accordion title="Database Management">
    | Event                   | Method                                                      | Description                          |
    | ----------------------- | ----------------------------------------------------------- | ------------------------------------ |
    | Update Database         | `/bytebase.v1.DatabaseService/UpdateDatabase`               | Modify database settings/labels      |
    | Batch Update Databases  | `/bytebase.v1.DatabaseService/BatchUpdateDatabases`         | Bulk update databases                |
    | Update Database Catalog | `/bytebase.v1.DatabaseCatalogService/UpdateDatabaseCatalog` | Modify schema catalog/classification |
  </Accordion>

  <Accordion title="Database Groups">
    | Event                 | Method                                                  | Description                   |
    | --------------------- | ------------------------------------------------------- | ----------------------------- |
    | Create Database Group | `/bytebase.v1.DatabaseGroupService/CreateDatabaseGroup` | Create logical database group |
    | Update Database Group | `/bytebase.v1.DatabaseGroupService/UpdateDatabaseGroup` | Modify database group         |
    | Delete Database Group | `/bytebase.v1.DatabaseGroupService/DeleteDatabaseGroup` | Delete database group         |
  </Accordion>

  <Accordion title="SQL Operations">
    | Event         | Method                                 | Description                                   |
    | ------------- | -------------------------------------- | --------------------------------------------- |
    | Execute Query | `/bytebase.v1.SQLService/Query`        | Execute read-only SQL query                   |
    | Admin Execute | `/bytebase.v1.SQLService/AdminExecute` | Execute SQL with admin privileges (streaming) |
    | Export Data   | `/bytebase.v1.SQLService/Export`       | Export query results to file                  |

    **Notes:**

    * Response rows completely redacted - only metadata captured: `columnNames`, `columnTypeNames`, `rowsCount`, `error`, `latency`, `statement`
    * Each request/response pair in streaming operations generates a separate audit log
    * Export request `password` field redacted; response `content` not logged
  </Accordion>

  <Accordion title="Issue Management">
    | Event                      | Method                                              | Description            |
    | -------------------------- | --------------------------------------------------- | ---------------------- |
    | Create Issue               | `/bytebase.v1.IssueService/CreateIssue`             | Create change request  |
    | Update Issue               | `/bytebase.v1.IssueService/UpdateIssue`             | Modify issue details   |
    | Create Issue Comment       | `/bytebase.v1.IssueService/CreateIssueComment`      | Add comment to issue   |
    | Update Issue Comment       | `/bytebase.v1.IssueService/UpdateIssueComment`      | Modify issue comment   |
    | Batch Update Issues Status | `/bytebase.v1.IssueService/BatchUpdateIssuesStatus` | Bulk status change     |
    | Approve Issue              | `/bytebase.v1.IssueService/ApproveIssue`            | Approve change request |
    | Reject Issue               | `/bytebase.v1.IssueService/RejectIssue`             | Reject change request  |
    | Request Issue              | `/bytebase.v1.IssueService/RequestIssue`            | Re-request approval    |
  </Accordion>

  <Accordion title="Plan & Rollout">
    | Event            | Method                                            | Description               |
    | ---------------- | ------------------------------------------------- | ------------------------- |
    | Create Plan      | `/bytebase.v1.PlanService/CreatePlan`             | Create deployment plan    |
    | Update Plan      | `/bytebase.v1.PlanService/UpdatePlan`             | Modify deployment plan    |
    | Create Rollout   | `/bytebase.v1.RolloutService/CreateRollout`       | Create deployment rollout |
    | Run Tasks        | `/bytebase.v1.RolloutService/BatchRunTasks`       | Execute deployment tasks  |
    | Skip Tasks       | `/bytebase.v1.RolloutService/BatchSkipTasks`      | Skip deployment tasks     |
    | Cancel Task Runs | `/bytebase.v1.RolloutService/BatchCancelTaskRuns` | Cancel running tasks      |
  </Accordion>

  <Accordion title="Policy & Settings">
    | Event          | Method                                       | Description                  |
    | -------------- | -------------------------------------------- | ---------------------------- |
    | Create Policy  | `/bytebase.v1.OrgPolicyService/CreatePolicy` | Create organizational policy |
    | Update Policy  | `/bytebase.v1.OrgPolicyService/UpdatePolicy` | Modify policy settings       |
    | Delete Policy  | `/bytebase.v1.OrgPolicyService/DeletePolicy` | Remove policy                |
    | Update Setting | `/bytebase.v1.SettingService/UpdateSetting`  | Modify system settings       |
  </Accordion>
</AccordionGroup>

## Events Not Logged

| Category                      | Operations                                                           | Reason                                                  |
| ----------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------- |
| **Read-Only Operations**      | All `Get*`, `List*`, `Search*` methods, `GetIamPolicy`               | Low security impact - viewing data doesn't modify state |
| **High-Frequency Operations** | `AuthService/Refresh`, `BatchSyncInstances`, Actuator health checks  | Too frequent, would create excessive log volume         |
| **Validate-Only Requests**    | Any request with `validate_only = true`                              | Dry-run operations that don't modify state              |
| **Utility Services**          | `CELService/*`, `SQLService/AICompletion`, `SQLService/DiffMetadata` | Utility functions with no security implications         |
| **Review & Sheet Operations** | `ReviewConfigService/*`, `SheetService/*`, `WorksheetService/*`      | Lower security impact configuration                     |
| **Release & Revision**        | `ReleaseService/*`, `RevisionService/*`                              | Schema tracking operations                              |
| **Instance Role Operations**  | `InstanceRoleService/*`                                              | Database role management                                |

## Retention

<Warning>
  Bytebase does not automatically purge audit logs. You must implement periodic cleanup to prevent disk space exhaustion, which can cause Bytebase to crash.
</Warning>

Audit logs are stored in the `audit_log` table in the Bytebase metadata database.

**Recommended retention periods:**

* **Minimum**: 90 days
* **Compliance environments**: 6–12 months

**Cleanup options:**

* Manually delete old logs from the `audit_log` table
* Set up a scheduled job using `pg_cron` or system cron
* Export logs to external log management or SIEM systems for longer-term retention

## Limitations

### Privacy and Security

* **Query results excluded**: Actual row data from queries is redacted
* **Sensitive data masking**: Passwords, API keys, SSL certificates, SSH keys automatically replaced with masked values
* **Response truncation**: Large response payloads may be omitted

### Technical Constraints

* **Synchronous generation**: Audit logs are generated during request processing
* **Pagination limit**: Maximum 5,000 entries per API call
* **Filter complexity**: Searches must use valid CEL expressions
* **Storage**: Logs stored in metadata database, following its retention policies