feat: add per-host log retrieval and summary API endpoints#5648
Open
b3nw wants to merge 1 commit into
Open
Conversation
claw-io
force-pushed
the
feat/proxy-host-logs
branch
3 times, most recently
from
959a24f to
69b26a7
Compare
Implement two new read-only endpoints for retrieving proxy host logs:
- GET /api/nginx/proxy-hosts/{id}/logs
Returns the last N lines from a proxy host's access or error log file.
Supports query filters: type, lines, search, since.
- GET /api/nginx/proxy-hosts/{id}/logs/summary
Parses the last 1000 access log lines and returns structured statistics:
status code distribution, top paths, top clients, cache hit rate,
and log file sizes.
Key implementation details:
- Reverse chunk-reader (64KB buffer) for efficient tail reading of log
files without loading them entirely into memory
- Permission model reuses proxy_hosts view permission, scoped to non-admin
users' own hosts via the existing owner_user_id check
- Log format regex aligns with the 'proxy' log_format template defined
in docker/rootfs/etc/nginx/conf.d/include/log-proxy.conf
- File descriptor safety: fs.open is wrapped in a null-guarded
try-finally block to prevent leaks on I/O errors
- Cypress E2E tests cover 404, 403, 200, search, since, lines limit,
and summary accuracy
- Mock log data is written via a Cypress task (writeMockLog) instead of
a production HTTP endpoint
Co-authored-by: claw-io <agent@ben.io>
claw-io
force-pushed
the
feat/proxy-host-logs
branch
from
69b26a7 to
3e27509
Compare
|
Docker Image for build 5 is available on DockerHub: Note Ensure you backup your NPM instance before testing this image! Especially if there are database changes. Warning Changes and additions to DNS Providers require verification by at least 2 members of the community! |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
This implements the feature originally proposed in Discussion #5576. Nginx Proxy Manager currently provides no way to inspect proxy host access or error logs through the API. Users must SSH into the host and read log files manually. Sysadmins and monitoring tools need programmatic access to recent log lines and aggregate statistics (status code distribution, top paths, top clients, cache hit rate) for troubleshooting, observability, and integration with external monitoring systems.
This change adds two read-only endpoints per proxy host —
/logsfor raw log line retrieval with filtering (type, lines, search, since) and/logs/summaryfor computed statistics from the last 1000 access log lines. The implementation follows the Discussion #5576 proposal with adjustments made during code review (fileandtotal_linesfields removed to avoid leaking internal paths; permission naming aligned to codebase conventionproxy_hosts:logs).The implementation is purely additive: no existing API behavior is modified, no database migrations are required, and no configuration changes are needed. Existing proxy hosts automatically have log access for admin users and for non-admin users on their own hosts, reusing the existing
proxy_hostsview permission model.Type of Change
AI Usage
Testing Performed
Automated (Cypress E2E)
test/cypress/e2e/api/ProxyHostLogs.cy.js— 10 test cases covering:searchparameter filtersince(ISO 8601 timestamp) filterlineslimiterStatic Analysis
npm run validate-schema) — passednpm run lint) — 91 files checked, 0 issuesLive Deployment Test
A disposable NPM instance was deployed and populated with real traffic, and the following were verified against live Nginx log files:
Positive-path:
/data/logs/proxy-host-{id}_access.logfiles at the standard NPM path/data/logs/proxy-host-{id}_error.logfiles at the standard NPM pathNegative/security-path:
type(path traversal attempt../../etc/passwd) → 400lines(1001, above max 1000) → 400since(non-ISO-8601) → 400 with descriptive error messageAll negative paths return safe, consistent error responses with no internal path or stack leakage.