Server Logging

AIStor Server publishes its server logs to the system console. These logs can include errors, information output, or other information useful during troubleshooting or debugging.

Server logs do not emit for all operations and cannot support audit trail or similar compliance requirements. If you require such a trail, configure and use audit logging instead.

You can read the server logs using any of the following methods:

• Run journalctl -u minio from any host machine.
• Run mc admin logs against the MinIO AIStor deployment.

MinIO AIStor can record API, error, and audit logs directly to disk as compressed JSON files. This complements webhook-based logging for compliance, forensics, and offline analysis.

You can configure disk-based log recording using either environment variables or runtime configuration settings:

export MINIO_LOG_API_INTERNAL_ENABLE="on"
export MINIO_LOG_API_INTERNAL_DRIVE_LIMIT="1Gi"
export MINIO_LOG_API_INTERNAL_FLUSH_COUNT="10000"
export MINIO_LOG_API_INTERNAL_FLUSH_INTERVAL="1h"

export MINIO_LOG_ERROR_INTERNAL_ENABLE="on"
export MINIO_LOG_ERROR_INTERNAL_DRIVE_LIMIT="1Gi"
export MINIO_LOG_ERROR_INTERNAL_FLUSH_COUNT="10000"
export MINIO_LOG_ERROR_INTERNAL_FLUSH_INTERVAL="1h"

export MINIO_LOG_AUDIT_INTERNAL_ENABLE="on"

mc admin config set ALIAS log_api_internal \
   enable=on                               \
   drive_limit=1Gi                         \
   flush_count=10000                       \
   flush_interval=1h

mc admin config set ALIAS log_error_internal \
   enable=on                                 \
   drive_limit=1Gi                           \
   flush_count=10000                         \
   flush_interval=1h

mc admin config set ALIAS log_audit_internal enable=on

The drive_limit is enforced independently on every drive of every node. When the limit is reached (for API and error logs), MinIO AIStor automatically removes the oldest log files on that drive to make room for new entries. For capacity planning, the total log space a cluster can consume is approximately drive_limit × drives-per-node × number-of-nodes.

MinIO AIStor stores recorded logs on the deployment drives under the system path .minio.sys/logs/, with a separate prefix for each log type:

.minio.sys/
└── logs/
    ├── api/
    ├── error/
    └── audit/

Each file is a zstd-compressed JSON file named using the format <type>.<count>.<timestamp>.zst, for example api.1234.20250115.103000.000000000.zst:

• type: api, error, or audit.
• count: number of log entries in the file.
• timestamp: UTC time in the format YYYYMMDD.HHMMSS.nnnnnnnnn.
• .zst: the zstd compression extension.

Use mc ls to list the recorded files and mc cat piped through zstd -d to decompress and read them:

mc ls ALIAS/.minio.sys/logs/audit/
mc cat ALIAS/.minio.sys/logs/audit/FILE.zst | zstd -d

MinIO AIStor supports publishing logs to a webhook consumer through an HTTP PUT operation, where the body of the request is the log as a JSON document.

You can configure a new HTTP webhook endpoint to which AIStor Server publishes minio server logs using either environment variables or runtime configuration settings:

MINIO_LOGGER_WEBHOOK_ENABLE="on"
MINIO_LOGGER_WEBHOOK_ENDPOINT="https://webhook-1.example.net"
#MINIO_LOGGER_WEBHOOK_AUTH_TOKEN="TOKEN"
#MINIO_LOGGER_WEBHOOK_BATCH_SIZE=10
#MINIO_LOGGER_WEBHOOK_CLIENT_CERT="/opt/minio/webhook/public.crt"
#MINIO_LOGGER_WEBHOOK_CLIENT_KEY="/opt/minio/webhook/private.key"
#MINIO_LOGGER_WEBHOOK_MAX_RETRY=5
#MINIO_LOGGER_WEBHOOK_RETRY_INTERVAL=1
#MINIO_LOGGER_WEBHOOK_PROXY="https://proxy.example.net"
#MINIO_LOGGER_WEBHOOK_TLS_SKIP_VERIFICATION=false
#MINIO_LOGGER_WEBHOOK_HTTP_TIMEOUT=10
#MINIO_LOGGER_WEBHOOK_HTTP_ENCODING="json"

mc admin config set ALIAS logger_webhook        \
   endpoint="https://webhook-1.example.net"     \
#  auth_token="TOKEN"                           \
#  batch_size=10                                \
#  max_retry=5                                  \
#  retry_interval=1                             \
#  client_cert="/opt/minio/webhook/public.crt"  \
#  client_key="/opt/minio/webhook/private.key"  \
#  proxy="https://proxy.example.net"            \
#  tls_skip_verification=false                  \
#  http_timeout=10                              \
#  http_encoding="json"

For options that require specifying a directory path, ensure the minio-user user and group have read, write, and list access to those resources. Where possible use chown and chmod to limit access and ownership to only the minio-user.

Restart MinIO AIStor to apply the new settings.

You can specify multiple webhook loggers by appending a unique identifier to each group of environment variables or settings. For example, MINIO_LOGGER_WEBHOOK_ENDPOINT_PRIMARY or mc admin config set alias logger_webhook:primary.

The following example json document resembles the format used by MinIO AIStor for webhook logging:

{
    "deploymentid": "c8484a3f-2fb0-416b-b0dd-06c7c60a6925",
    "level": "WARNING",
    "time": "2025-08-15T16:06:01.16308316Z",
    "api": {
        "name": "SYSTEM.iam",
        "args": {}
    },
    "error": {
        "message": "Enabling MINIO_IDENTITY_TLS_SKIP_VERIFY is not recommended in a production environment (*errors.errorString)",
        "source": [
            "internal/logger/logger.go:271:logger.LogIf()",
            "cmd/logging.go:29:cmd.iamLogIf()",
            "cmd/iam.go:270:cmd.(*IAMSys).Init()",
            "cmd/server-main.go:1006:cmd.serverMain.func15.1()",
            "cmd/server-main.go:566:cmd.bootstrapTrace()",
            "cmd/server-main.go:1005:cmd.serverMain.func15()"
        ]
    }
}

The api.name field identifies the subsystem that generated the log entry.

For background operations (healing, scanning, bootstrap), the value is SYSTEM.<subsystem>. For errors during S3 API requests, the value is the S3 operation name (for example, GetObject, PutObject) rather than the subsystem name.

Storage and drives:

Network and internode:

Data operations:

Cluster operations:

Security and identity:

Administration:

Features:

Use the api.name field to filter logs by subsystem in your log pipeline.

Common filter patterns:

Server logs and audit logs serve different purposes and capture different data.

For audit log configuration, see Audit Logging.