Log Access Endpoints

Access and manage server logs through the Management API

The log endpoints provide access to server logs, including main logs, request logs, and error logs.

Prerequisites

Log endpoints require file logging to be enabled:

logging-to-file: true

If file logging is disabled, log endpoints return an error.

Get Logs

GET · endpoint

/v0/management/logs

Returns log entries from the main log file with support for incremental loading.

Request

curl -H "X-Management-Key: YOUR_SECRET" \
  "http://localhost:8317/v0/management/logs?limit=100&after=1710172800"

Query Parameters

limit · integer

Maximum number of log lines to return (most recent)

after · integer

Unix timestamp to filter logs after (for incremental loading)

Response

lines · string[]

Array of log lines

line-count · number

Total number of lines processed

latest-timestamp · number

Unix timestamp of the most recent log entry (use for next incremental request)

{
  "lines": [
    "[2026-03-11 10:30:45] INFO: Server started on :8317",
    "[2026-03-11 10:30:46] INFO: Management API enabled",
    "[2026-03-11 10:31:00] INFO: Request completed in 145ms"
  ],
  "line-count": 3,
  "latest-timestamp": 1710172860
}

Delete Logs

DELETE · endpoint

/v0/management/logs

Clears all log files:

• Truncates active log file (main.log)
• Removes all rotated log files (main.log.1, main-2026-03-11.log, etc.)

Request

curl -X DELETE \
  -H "X-Management-Key: YOUR_SECRET" \
  http://localhost:8317/v0/management/logs

Response

success · boolean

Whether deletion was successful

message · string

Success message

removed · number

Number of rotated log files removed

{
  "success": true,
  "message": "Logs cleared successfully",
  "removed": 5
}

Get Request Error Logs

GET · endpoint

/v0/management/request-error-logs

Lists error request log files created when request-log is disabled.

Request

curl -H "X-Management-Key: YOUR_SECRET" \
  http://localhost:8317/v0/management/request-error-logs

Response

files · object[]

List of error log files

name · string

File name

size · number

File size in bytes

modified · number

Last modified timestamp (Unix)

{
  "files": [
    {
      "name": "error-2026-03-11-10-30-45-req123.log",
      "size": 2048,
      "modified": 1710172845
    },
    {
      "name": "error-2026-03-11-10-25-30-req122.log",
      "size": 1536,
      "modified": 1710172530
    }
  ]
}

When request-log: true, this endpoint returns an empty array since all requests are logged to the main log file.

Download Error Log by Name

GET · endpoint

/v0/management/request-error-logs/:name

Downloads a specific error log file.

Request

curl -H "X-Management-Key: YOUR_SECRET" \
  -O -J \
  http://localhost:8317/v0/management/request-error-logs/error-2026-03-11-10-30-45-req123.log

Response

File download with Content-Disposition: attachment.

Get Request Log by ID

GET · endpoint

/v0/management/request-log-by-id/:id

Finds and downloads a request log file by its request ID.

Request

curl -H "X-Management-Key: YOUR_SECRET" \
  -O -J \
  http://localhost:8317/v0/management/request-log-by-id/req123

Path Parameters

id · string · required

Request ID to search for (matches log file suffix *-{id}.log)

Response

File download with the matched log file.

Error Responses

{
  "error": "log file not found for the given request ID"
}

Log File Formats

Main Log Format

[2026-03-11 10:30:45] INFO: Server started on :8317
[2026-03-11 10:30:46] DEBUG: Loading configuration from config.yaml
[2026-03-11 10:31:00] INFO: Request completed in 145ms
[2026-03-11 10:31:15] ERROR: Authentication failed for key abc123

Each line starts with:

• Timestamp: [YYYY-MM-DD HH:MM:SS]
• Level: INFO, DEBUG, WARN, ERROR
• Message

Error Log File Naming

Error logs use the format:

error-{timestamp}-{requestID}.log

Example: error-2026-03-11-10-30-45-req123.log

Rotated Log File Naming

Two rotation formats are supported:

Numeric rotation:

main.log      # Active log
main.log.1    # Most recent rotation
main.log.2    # Second most recent

Timestamp rotation:

main.log                      # Active log
main-2026-03-11T10-30-45.log  # Rotation at specific time
main-2026-03-11T09-15-30.log.gz  # Compressed rotation

Incremental Log Loading

Use the after parameter with latest-timestamp for efficient polling:

# Initial request
curl -H "X-Management-Key: YOUR_SECRET" \
  "http://localhost:8317/v0/management/logs?limit=100" > logs1.json

# Extract latest timestamp
LATEST=$(jq -r '."latest-timestamp"' logs1.json)

# Get only new logs
curl -H "X-Management-Key: YOUR_SECRET" \
  "http://localhost:8317/v0/management/logs?limit=100&after=$LATEST" > logs2.json

How It Works

1. First request returns last 100 lines with latest-timestamp: 1710172860
2. Second request with after=1710172860 returns only lines newer than that timestamp
3. Continue polling with the latest timestamp for incremental updates

Log Configuration Endpoints

Get Request Log Setting

GET /v0/management/request-log

{
  "request-log": false
}

Enable Request Logging

curl -X PUT \
  -H "X-Management-Key: YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"value": true}' \
  http://localhost:8317/v0/management/request-log

Get Logging to File Setting

GET /v0/management/logging-to-file

{
  "logging-to-file": true
}

Enable File Logging

curl -X PUT \
  -H "X-Management-Key: YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"value": true}' \
  http://localhost:8317/v0/management/logging-to-file

Log Rotation Settings

Get Max Total Size

GET /v0/management/logs-max-total-size-mb

{
  "logs-max-total-size-mb": 100
}

Set Max Total Size

Set maximum total size for all log files in MB (0 = unlimited):

curl -X PUT \
  -H "X-Management-Key: YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"value": 500}' \
  http://localhost:8317/v0/management/logs-max-total-size-mb

Get Max Error Log Files

GET /v0/management/error-logs-max-files

{
  "error-logs-max-files": 10
}

Set Max Error Log Files

Set maximum number of error log files to retain:

curl -X PUT \
  -H "X-Management-Key: YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"value": 20}' \
  http://localhost:8317/v0/management/error-logs-max-files

Complete Logging Configuration

# Enable logging to files
logging-to-file: true

# Enable request logging (logs all requests)
request-log: false

# Maximum total log size in MB (0 = unlimited)
logs-max-total-size-mb: 100

# Maximum error log files to keep (when request-log is false)
error-logs-max-files: 10

Error Responses

Logging Disabled

{
  "error": "logging to file disabled"
}

Returned when logging-to-file: false.

Log Directory Not Configured

{
  "error": "log directory not configured"
}

Log File Not Found

{
  "error": "log file not found"
}

Invalid Request ID

{
  "error": "invalid request ID"
}

Returned when request ID contains path separators.

Log Directory Location

Logs are written to:

1. Directory specified in log configuration (if set)
2. ./logs/ directory relative to server working directory (default)

The management handler automatically detects the log directory based on the server configuration.

Use Cases

Real-time Log Monitoring

#!/bin/bash
LATEST=0

while true; do
  RESPONSE=$(curl -s -H "X-Management-Key: YOUR_SECRET" \
    "http://localhost:8317/v0/management/logs?limit=50&after=$LATEST")
  
  LINES=$(echo "$RESPONSE" | jq -r '.lines[]')
  if [ -n "$LINES" ]; then
    echo "$LINES"
  fi
  
  LATEST=$(echo "$RESPONSE" | jq -r '."latest-timestamp"')
  sleep 5
done

Download All Error Logs

#!/bin/bash
FILES=$(curl -s -H "X-Management-Key: YOUR_SECRET" \
  http://localhost:8317/v0/management/request-error-logs | jq -r '.files[].name')

for FILE in $FILES; do
  curl -H "X-Management-Key: YOUR_SECRET" \
    -O -J \
    "http://localhost:8317/v0/management/request-error-logs/$FILE"
done

Clear Old Logs

# Clear all logs
curl -X DELETE \
  -H "X-Management-Key: YOUR_SECRET" \
  http://localhost:8317/v0/management/logs

Next Steps

• Configuration Endpoints - Configure logging settings
• OAuth Endpoints - Monitor OAuth authentication events
• Quota Endpoints - Track quota exceeded events