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.

Record logs to disk

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

The audit recorder, configured by the log_audit_internal subsystem, audits administrative operations such as:

• Configuration changes, including tier and log recorder configuration.
• Identity management: users, groups, policies, service accounts, and identity provider settings.
• Bucket configuration, including quota, quality of service (QoS), and inventory settings.
• Cluster operations: service, pool, site replication, healing, and batch jobs.
• Key Management Service (KMS) operations.

S3 object operations are not audited by this subsystem. The log_api_internal subsystem records them instead. If you expect an object delete in the audit log and cannot find it, query the API log.

This split applies only to log_audit_internal. The audit_webhook and audit_kafka targets described in Audit Logging are a separate subsystem with its own coverage.

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. API and error logs are written to one drive at a time. When the active drive reaches the limit, MinIO AIStor advances to the next drive in the rotation and deletes everything already in that drive’s log directory before it writes. It does not delete the oldest files on the drive it just filled. Those entries stay until the rotation returns to that drive. On a node with a single drive, the rotation returns to that same drive, so reaching the limit discards the logs already recorded on it for that log type. The API and error recorders each apply their own drive_limit and rotate independently, so one reaching its limit does not affect the other. For capacity planning, treat each recorder separately: the API and error recorders can each consume about their own drive_limit × drives-per-node × number-of-nodes, so size the drives for the sum of the two limits you set. Audit logs are not covered by drive_limit and are accounted for separately.

Where recorded logs are stored

MinIO AIStor keeps all three log types under the reserved system path .minio.sys/logs/, with a separate prefix for each type:

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

API and error logs use one storage layout and naming scheme, and audit logs use another.

API and error logs are raw files on the deployment drives, not objects. Each file holds a zstd-compressed stream of JSON log entries and is named <type>.<count>.<timestamp>.zst, for example api.1234.20250115.103000.000000000.zst:

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

Audit logs are objects in the .minio.sys meta bucket rather than raw files on the drives. MinIO AIStor appends every entry to one uncompressed active object, logs/audit/audit.log. When that object grows past 1 GiB, MinIO AIStor compresses it to logs/audit/<timestamp>.log.zst and starts a new active file. Rotated audit files carry no type prefix and no entry count. The drive_limit setting does not apply to audit logs.

Query recorded logs with mc log

Use the mc log commands to query recorded logs with time, node, bucket, and API filters:

• mc log api queries recorded API logs.
• mc log error queries recorded error logs.
• mc log audit queries recorded audit logs.

mc log api --last 24h ALIAS
mc log error --last 24h ALIAS
mc log audit --categories user ALIAS

Each command can also export its recorder configuration with --get-config and apply an edited configuration with --set-config. See each command’s reference page for the full set of filter flags and configuration keys.

Publish server logs to HTTP webhook

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=1s
#MINIO_LOGGER_WEBHOOK_PROXY="https://proxy.example.net"
#MINIO_LOGGER_WEBHOOK_TLS_SKIP_VERIFY=false
#MINIO_LOGGER_WEBHOOK_HTTP_TIMEOUT=10s
#MINIO_LOGGER_WEBHOOK_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=1s                           \
#  client_cert="/opt/minio/webhook/public.crt" \
#  client_key="/opt/minio/webhook/private.key" \
#  proxy="https://proxy.example.net"           \
#  tls_skip_verify=false                       \
#  http_timeout=10s                            \
#  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.

A change made with mc admin config set applies without a server restart. A change made through an environment variable requires a restart.

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.

Server log JSON format

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()"
        ]
    }
}

Log entry fields

Log subsystems

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:

Filtering server logs

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

Common filter patterns:

Server logs vs audit logs

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

For audit log configuration, see Audit Logging.