Skip to main content
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

Build docs developers (and LLMs) love

Get started for freeTalk to us