<!-- Source: https://docs.squirro.com/en/latest/technical/admin/operations/audit-logging.html -->
# Audit Logging

This page provides an overview of audit logging, a feature that enables the systematic tracking and monitoring of user activities to ensure security and compliance. That feature requires access to the Squirro platform using the [command line interface](accessing-servers.md#operations-server-access-cli).

## Overview

The audit logging feature captures detailed information about HTTP requests and responses in a structured way for `user` API endpoints, including:

- user signups
- user logins with authentication method
- user logouts
- user session teminations due to inactivity
- changing user roles
- creating/deleting groups
- creating/deleting workspaces
- adding/removing users to/from groups
- adding/removing users to/from workspaces
- adding/removing groups to/from workspaces

and `topic` API endpoints, including:

- creating/deleting projects
- importing/exporting projects
- adding/removing users to/from projects
- adding/removing groups to/from projects

The system logs all these actions automatically using a decorator that wraps the specified endpoints, ensuring it captures all relevant interactions.

## Configuration

By default, a newly deployed Squirro instance has the audit logging feature disabled.

To enable the audit logging feature, go to Server→Configuration, check the `security.audit-logger` option, and restart the `squserd` and `sqtopicd` [services](services.md#admin-services) for the changes to take effect. The order of restarting the services does not matter.

## Log File Location

The audit logs are stored in `*.log.jsonl` files (one JSON object per line) for services that have implemented audit logging. Currently, this includes the `user` and `topic` services. The log files are located under the following paths:

- `/var/log/squirro/user/user.log.jsonl`
- `/var/log/squirro/topic/topic.log.jsonl`

All audit log entries are identified by the attribute `"log_type": "audit_log"` to differentiate them from other structured logs in the same file.

## Log Format

The audit logs are stored in JSON Lines format, with each line representing a single event. The logs are structured as follows:

| Field | Description |
| --- | --- |
| `event` | Type of the event: always `request`. |
| `level` | Log level of the event: `info` (success) or `error` (failure). |
| `log_type` | Type of the log: always `audit_log`. |
| `request_body` | Body of the HTTP request. |
| `request_headers` | Headers of the HTTP request. |
| `request_method` | Method of the HTTP request. |
| `request_params` | Query parameters of the HTTP request. |
| `request_path` | API endpoint path of the HTTP request. |
| `request_error` | Error detail (present only for failed HTTP requests). |
| `response_headers` | Headers of the HTTP response. |
| `response_status_code` | Status code of the HTTP response. |
| `timestamp` | UTC timestamp of the event. |
| `user_cluster_role` | Cluster roles of the user. |
| `user_email` | Email address of the user. |
| `user_id` | ID of the user. |

Example of an audit log entry for a successful request:

```json
{
    "event": "request",
    "level": "info",
    "log_type": "audit_log",
    "request_body": "grant_type=refresh_token&refresh_token=v4.public.r3fr3sh.t0k3n",
    "request_headers": {
        "Accept": "application/json",
        "Accept-Encoding": "gzip, deflate",
        "Connection": "keep-alive",
        "Content-Length": "62",
        "Content-Type": "application/x-www-form-urlencoded",
        "Host": "localhost",
        "User-Agent": "python-requests/2.31.0"
    },
    "request_method": "POST",
    "request_params": {
        "grant_type": "refresh_token",
        "refresh_token": "v4.public.r3fr3sh.t0k3n"
    },
    "request_path": "/api/user/oauth2/token",
    "response_headers": {
        "Content-Length": "0",
        "Content-Type": "text/html; charset=UTF-8",
        "Vary": "Accept"
    },
    "response_status_code": 200,
    "timestamp": "2025-04-16T09:37:55.466277Z",
    "user_cluster_role": [
        "Owner",
        "Admins"
    ],
    "user_email": "anna.smith@example.com",
    "user_id": "Y2qTSLzBRtOAJWlX11M9AB"
}
```

Example of an audit log entry for a failed request:

```json
{
    "event": "request",
    "level": "error",
    "log_type": "audit_log",
    "request_body": {
        "client_id": "2mL1rwP1Rr9h0aIjhPaAbC",
        "client_secret": "219025975c1d9cb9f1306ef7e5418d5ca7f4521a",
        "email": "anna.smith@example.com",
        "role": "admin"
    },
    "request_error": "409 Conflict\r\nContent-Type: text/html; charset=UTF-8\r\nContent-Length: 0\r\nVary: Accept",
    "request_headers": {
        "Accept": "application/json",
        "Accept-Encoding": "gzip, deflate",
        "Connection": "keep-alive",
        "Content-Length": "167",
        "Content-Type": "application/json",
        "Host": "127.0.0.1:81",
        "User-Agent": "SquirroToolbox/{__VERSION__} (http://squirro.com/)"
    },
    "request_method": "POST",
    "request_params": {},
    "request_path": "/api/user/v0/_global/users",
    "response_headers": {
        "Content-Length": "0",
        "Content-Type": "text/html; charset=UTF-8",
        "Vary": "Accept"
    },
    "response_status_code": 409,
    "timestamp": "2025-04-16T09:17:53.271004Z",
    "user_cluster_role": [],
    "user_email": "",
    "user_id": ""
}
```

## Monitoring Log Files

You can follow audit logs in real-time using the `tail` command with the `-f` parameter, which allows you to monitor the updates to log files:

```bash
tail -f /var/log/squirro/user/user.log.jsonl /var/log/squirro/topic/topic.log.jsonl
```