Feature Request: Per-Host Log Retrieval API - Proposed Implementation

[b3nw]

Feature Request: Per-Host Log Retrieval API

Project: NginxProxyManager/nginx-proxy-manager
Type: Feature Request
Status: Feedback Requested before PR draft

Problem Statement

Nginx Proxy Manager writes per-host access and error logs to predictable paths on disk
(/data/logs/proxy-host-{id}_access.log, /data/logs/proxy-host-{id}_error.log), but
provides no API to read them. The only log-related API is the audit log (GET /api/audit-log),
which tracks admin configuration changes — not HTTP traffic.

This means operators and automation tools have no programmatic way to:

• Retrieve recent access log entries for a specific proxy host
• Check error logs when debugging upstream connectivity issues
• Monitor traffic patterns or detect anomalies through the existing API surface

The only workarounds today are direct filesystem access (requiring volume mounts or
docker exec) or external log aggregation pipelines, both of which add significant
operational complexity for a task that should be simple.

Proposed Solution

Add REST API endpoints to retrieve nginx access and error logs for individual proxy hosts.

New Endpoints

GET /api/nginx/proxy-hosts/{id}/logs

Retrieve log entries for a specific proxy host.

Query Parameters:

Parameter	Type	Default	Description
type	string	"access"	Log type: "access" or "error"
lines	int	100	Number of most recent lines to return (max: 1000)
search	string	-	Filter lines containing this substring
since	string	-	ISO 8601 timestamp — only return lines after this time

Response (200):

{
  "host_id": 5,
  "log_type": "access",
  "file": "proxy-host-5_access.log",
  "total_lines": 4821,
  "returned_lines": 100,
  "lines": [
    "[01/Jun/2025:14:22:31 +0000] HIT 200 200 - GET https app.example.com \"/api/data\" [Client 10.0.0.1] [Length 1542] [Gzip -] [Sent-to 192.168.1.50] \"Mozilla/5.0\" \"https://app.example.com/\"",
    "..."
  ]
}

Error Responses:

Status	Condition
404	Proxy host not found
404	Log file does not exist
403	User lacks permission for this host

GET /api/nginx/proxy-hosts/{id}/logs/summary

Return a statistical summary of recent traffic for a proxy host.

Response (200):

{
  "host_id": 5,
  "period": "last_1000_lines",
  "status_codes": {"200": 812, "301": 45, "404": 23, "500": 3},
  "top_paths": ["/api/data", "/", "/login"],
  "top_clients": ["10.0.0.1", "10.0.0.5"],
  "cache_hit_rate": 0.42,
  "access_log_size_bytes": 524288,
  "error_log_size_bytes": 8192
}

Permissions

Permission	Description
proxy-hosts:logs	Read logs for proxy hosts the user can view

Admin users can read logs for any host. Non-admin users can only read logs
for hosts they own, consistent with existing proxy host permissions.

Backend Implementation Notes

The implementation is straightforward because log paths are already deterministic
and hardcoded in nginx templates:

// backend/templates/proxy_host.conf
access_log /data/logs/proxy-host-{{ id }}_access.log proxy;
error_log /data/logs/proxy-host-{{ id }}_error.log warn;

A minimal implementation would:

1. Add a new route in backend/routes/ (e.g., proxy-host-logs.js)
2. Verify the proxy host exists and the user has access
3. Read the last N lines from the log file using a reverse-reader (or tail-like approach)
4. Optionally filter lines by substring or timestamp
5. Return as JSON

Reference files for implementation:

• backend/routes/nginx/proxy_hosts.js — existing proxy host routes and permission model
• backend/templates/proxy_host.conf — log path template confirming the naming convention
• backend/lib/access/ — permission definition files
• docker/rootfs/etc/logrotate.d/nginx-proxy-manager — log rotation config (rotated logs
  have .1, .2.gz suffixes)

Log Rotation Consideration

NPM rotates logs weekly (access: 4 rotations, error: 10 rotations). The API should
read only the current (unrotated) log file. Rotated archives (.1, .2.gz) could be
supported in a future iteration but are not required for the initial implementation.

Motivation

Use Cases

1. MCP/AI Agent Integration — MCP servers wrapping the NPM API (like
   nginx-proxy-manager-mcp) can
   expose log retrieval to AI assistants for debugging proxy issues conversationally.

2. Quick Debugging — When a reverse proxy returns errors, operators need to quickly
   check the access and error logs for that specific host. Today this requires SSH/exec
   access to the container.

3. Monitoring Dashboards — Custom dashboards can poll the log endpoint for
   traffic summaries without deploying a full log aggregation stack.

4. Automation — CI/CD pipelines and health-check scripts can verify that traffic
   is flowing correctly to newly deployed services behind NPM.

Why Not External Log Aggregation?

External solutions (Loki, ELK, Fluentd) are powerful but heavy. Many NPM users run
single-host homelab setups where a full log pipeline is disproportionate to the need.
A built-in API covers 80% of use cases with zero additional infrastructure.

Alternatives Considered

Approach	Pros	Cons
API endpoint (proposed)	Native, zero extra infra	Requires upstream PR
Volume mount + file read	Works today, no NPM changes	Tight coupling, no access control, not portable
Docker exec	Works today	Requires Docker socket, security risk
Sidecar log server	Decoupled	Extra container, extra config, extra maintenance

Scope

In Scope (v1)

• GET /api/nginx/proxy-hosts/{id}/logs with type, lines, search params
• Permission checks consistent with existing proxy host access model
• Current (unrotated) log file only

Out of Scope (Future)

• Log streaming via WebSocket or SSE
• Rotated log archive access (.gz files)
• Log summary/analytics endpoint
• Redirection host, dead host, and stream logs (same pattern, easy to add later)
• Log download as file attachment
• Log retention configuration via API

Related Issues & Discussions

This feature has been requested multiple times over several years across different issues.
Below is a summary of existing community interest and discussion.

Open Issues

Issue	Title	Created	Description
#401	Show (access) log in web interface	May 2020	Earliest request for log visibility in the GUI. 25+ comments, repeatedly rescued from stalebot.
#2957	View access logs from the interface	May 2023	Requests a domain-selectable log viewer. 10 comments, kept open by multiple community members.
#3659	Expose nginx logs to web gui	Mar 2024	Suggests per-host and global log views for both error and access logs.
#3687	Ability to live-view logs for hosts	Apr 2024	Requests a live tail-f button in the host context menu.
#2395	Logs/Metrics within the Admin Portal to View Traffic to Proxy Hosts	Nov 2022	Broader feature request for traffic monitoring and per-host metrics in a "Monitor" section.
#746	Change access log filenames to domain name (or add option)	Jul 2020	Related: difficulty identifying log files by numeric ID.

Closed Issues (with interest)

Issue	Title	Notes
#2060	Access to logs of an proxy	Closed, but user noted they resort to reading /data/logs directly
#3576	Log viewer for the respective sites in NPM	Closed, described "web wrapper around tail -f"
#2205	Better error and access log overview	Closed, but the request is identical
#1116	Logs view in Web UI	Closed, one of the earliest iterations
#302	Add goaccess program to the container	Proposed integrating goaccess for log analysis
#698	Log Analyzer	Another goaccess/log analysis request
#724	Show logs in ui	Direct request for in-UI log viewing

Related PRs

PR	Title	Notes
#2606	Changes log filenames from ID to (first) domain	Open since Feb 2023, would affect file naming

Summary

The community has been consistently requesting log visibility in the web UI
and API since at least 2020 (issue #401). No fewer than 12 distinct issues
have been opened over 6 years on this topic — many closed by stalebot only to
be reopened or re-filed. Despite this sustained interest, no implementation
has been contributed beyond third-party workarounds (frontail, goaccess, custom
volume mounts). This PRD proposes a focused API-first approach that would
unblock both UI integration and programmatic access via third-party tools.