AccessLogPlugin Schema

Schema definition for the Access Log Plugin, which provides HTTP request logging in various formats (Apache Common, Combined, JSON).

Schema Information

Property	Value
Schema URL	`https://rustybeam.net/schema/AccessLogPlugin`
Parent Schema	https://rustybeam.net/schema/UtilityPlugin
Description	HTTP request access logging with multiple format options

Properties

Property	Type	Cardinality	Description
logfile	https://rustybeam.net/schema/URL	0..1	Path to access log file. Supports file:// URLs. If not specified, logs to stdout. Plugin creates parent directories automatically.
log_file	https://rustybeam.net/schema/URL	0..1	Alternative name for logfile property (backward compatibility). Use logfile instead.
format	https://rustybeam.net/schema/Text	0..1	Log format style: "common" (Apache Common Log), "combined" (Apache Combined Log), or "json". Defaults to "common".
name	https://rustybeam.net/schema/Text	0..1	Plugin instance name for identification. Defaults to "access-log" if not specified.

Usage Examples

Basic Access Logging to File

<tr itemscope itemtype="https://rustybeam.net/schema/AccessLogPlugin">
    <span itemprop="library">file://./plugins/librusty_beam_access_log.so</span>
    <span itemprop="logfile">file://./logs/access.log</span>
</tr>

JSON Format Logging

<tr itemscope itemtype="https://rustybeam.net/schema/AccessLogPlugin">
    <span itemprop="library">file://./plugins/librusty_beam_access_log.so</span>
    <span itemprop="logfile">file://./logs/access.json</span>
    <span itemprop="format">json</span>
    <span itemprop="name">json_logger</span>
</tr>

Combined Format (Apache-style)

<tr itemscope itemtype="https://rustybeam.net/schema/AccessLogPlugin">
    <span itemprop="library">file://./plugins/librusty_beam_access_log.so</span>
    <span itemprop="logfile">file://./logs/combined.log</span>
    <span itemprop="format">combined</span>
</tr>

Stdout Logging (No File)

<tr itemscope itemtype="https://rustybeam.net/schema/AccessLogPlugin">
    <span itemprop="library">file://./plugins/librusty_beam_access_log.so</span>
    <span itemprop="format">common</span>
</tr>

Log Formats

Common Log Format

Standard Apache Common Log Format with basic request information:

127.0.0.1 - - [10/Jul/2025:14:30:45 +0000] "GET /index.html HTTP/1.1" 200 1234

Fields: IP, identity, authuser, timestamp, request, status, bytes

Combined Log Format

Extended Apache format with referrer and user agent:

127.0.0.1 - - [10/Jul/2025:14:30:45 +0000] "GET /index.html HTTP/1.1" 200 1234 "https://example.com" "Mozilla/5.0..."

Fields: Common format + referrer + user agent

JSON Log Format

Structured JSON format for machine parsing and log analysis:

{
  "timestamp": "2025-07-10T14:30:45Z",
  "remote_ip": "127.0.0.1",
  "method": "GET",
  "path": "/index.html",
  "protocol": "HTTP/1.1",
  "status": 200,
  "bytes": 1234,
  "referrer": "https://example.com",
  "user_agent": "Mozilla/5.0...",
  "duration_ms": 15
}

IP Address Detection
The Access Log Plugin intelligently detects client IP addresses by checking headers in this order:

X-Forwarded-For (proxy/load balancer)
X-Real-IP (reverse proxy)
Direct connection (fallback)

Schema Inheritance

This schema inherits from the UtilityPlugin schema, which provides:

logfile - Log file path (used by AccessLogPlugin)
directory - Directory configuration
enabled - Plugin enable/disable state

And ultimately from the base Plugin schema, which provides:

library - Plugin library path
plugin - Base plugin reference property

File Management

Auto-creation: Plugin creates parent directories automatically
File Rotation: Use external tools like logrotate for log rotation
Permissions: Ensure server has write access to log directory
Performance: Buffered writes for high-traffic logging
Error Handling: Graceful fallback if log file becomes unavailable

Validation Rules

The logfile property should be a valid file path or file:// URL
Log file directory must be writable by the server process
The format property must be one of: "common", "combined", "json"
The name property should be unique if multiple access log plugins are used
Use either logfile or log_file, not both (prefer logfile)

Plugin Pipeline Placement
The Access Log Plugin should typically be placed near the end of the plugin pipeline to capture the final response status and timing. It logs all requests regardless of success or failure.

Log Analysis and Monitoring

Common Log Analysis Tools

GoAccess: Real-time web log analyzer
AWStats: Advanced web statistics
Logstash/ELK Stack: For JSON format logs
Standard Unix tools: grep, awk, sed for basic analysis

Example Log Analysis Commands

# Most common IPs
grep -o '^[^ ]*' access.log | sort | uniq -c | sort -nr | head -10

# Most requested paths
awk '{print $7}' access.log | sort | uniq -c | sort -nr | head -10

# Error requests (4xx/5xx status codes)
awk '$9 ~ /^[45]/ {print}' access.log

# Requests by hour
awk '{print $4}' access.log | cut -d: -f2 | sort | uniq -c

Integration with Other Plugins

Rate Limit Plugin: Logs rate-limited requests for monitoring
Authorization Plugin: Tracks authorization success/failure patterns
Error Handler Plugin: Records custom error page responses
Redirect Plugin: Logs redirect patterns and sources
File Handler Plugin: Records file access patterns

Performance Considerations

Disk I/O: Logging adds file write overhead
Log Rotation: Implement log rotation to prevent large files
JSON Format: Slightly more overhead but better for analysis
Network Logging: Consider remote logging for high-traffic sites
Async Logging: Plugin uses buffered writes for performance