Knowing what a production ERPNext is doing before users tell you
On a running ERPNext, many failures do not show up on screen. A scheduled job can stop, a queued email can sit unsent, or a custom server script can fail on one document type while users keep working. This section covers where ERPNext records those failures, what the built-in records do and do not tell you, and when an operations team should add its own alerting. The short answer is that ERPNext writes errors to the Error Log and job outcomes to the Scheduled Job Log inside the desk, and the team turns those records into alerts by watching them on a schedule or by forwarding server logs and worker errors to a system that can notify someone.
The need usually appears after go-live, and it grows once custom scripts, custom apps or integrations are added. Before go-live, a small set of users can report problems quickly. Afterward, a Server Script on a document event, a webhook from a payment or bank feed, or a background import can fail for hours before anyone notices. The desk logs cover application-level exceptions and scheduler outcomes, but they are only as complete as the code that writes to them. They do not replace host-level monitoring of the database, Redis, workers, disk space or the web tier, and they do not tell you that a mail server has accepted a message that never reached a recipient. Confirm with your own deployment which log files your bench or container setup writes, where they rotate, and how long they are kept.
Decide early who reads these records, how often, and what counts as an alert. Give the on-call person a short list of failure signals tied to the business process they affect, such as failed scheduled jobs, repeated errors from the same script, or a worker queue that stops draining. Test each alert against a deliberate failure in a staging site before relying on it in production. Also confirm how long the Error Log and Scheduled Job Log retain entries in your version, because a cleanup routine that removes old rows can erase the history you need for an incident review. The licenses matter for the software you deploy: ERPNext is GPL-3.0 and the Frappe Framework is MIT. Those licenses govern the code, not the operations work, monitoring design or support arrangements around it.
Which log to read for which symptom
The Error Log sits inside the ERPNext desk and records Python exceptions raised while a user or integration works in a site, such as a save that crashes, a submit that fails validation in code, or an API call that returns a server error. Application owners and functional consultants usually read it first, because each entry carries the traceback and request context. The first question it answers is what a user or integration hit on this site, and when.
- Error details: the method or document involved, the traceback and the time of the failure.
- Repeat patterns: the same traceback recurring after a release or customization change usually points to one cause.
- Custom script origin: if the traceback names a Server Script, check it first. From version 15, Server Script behavior is disabled by default and must be enabled with
server_script_enabled, so confirm in your change record who turned it on and when. - Limited scope: the log only captures failures that reached the application, so requests rejected earlier by the proxy never appear here.
- Retention: entries accumulate, so agree a review and cleanup routine with your team.
Check the Error Log first when one user reports a failure, then confirm whether the same traceback appears for other users.
The Scheduled Job Log records each run of a scheduled method, including auto repeat documents, scheduled emails and backups. Platform administrators and operations leads typically read it to confirm that recurring business processes ran. The first question it answers is whether a scheduled task ran and whether it succeeded.
- Run status: whether each scheduled method completed, failed, or has no recent run recorded.
- Method name: the scheduled job's name, which you can map to a business process such as recurring invoices or nightly backups.
- Timing gaps: missing runs over a period usually point to the scheduler process or the queue, not to the job's code.
- Failure traces: tracebacks for failed runs often show one bad record or a missing configuration value.
- Per-site scope: each site keeps its own history, so check every site that runs the job.
Compare gaps in the log with the scheduler status before changing any job code, because a stopped scheduler can look like a failing job.
Server and web logs record what happens before and around the application: HTTP access and error entries from the reverse proxy, application server output, Socket.io messages and process start-up or restart events. Platform and infrastructure engineers read them when users report timeouts or blank pages without a desk error. The first question these logs answer is whether the request reached ERPNext, and what status and timing it returned.
- Status codes: gateway errors and timeouts separate proxy or upstream problems from application exceptions.
- Response timing: slow responses with no desk error often reflect database load or a heavy report.
- Process messages: start-up failures, worker restarts and out-of-memory messages appear in process output.
- Rotation and retention: confirm how log files under the bench
logsdirectory are rotated and kept in your deployment, since names and locations vary by setup. - Container deployments: in a frappe_docker setup, logs go to container output and volumes, so check the proxy, backend and Socket.io services separately.
Check the web tier before the application when users report timeouts that leave no trace in the desk.
Worker logs record background processing across the short, default and long queues, including exceptions inside queued tasks, timeouts and jobs that were killed. Platform engineers read them, along with owners of long-running business work such as large imports and stock reposts. The first question they answer is whether queued work is stuck, slow or failing outside a web request.
- Queue names: the queue a job ran in shows which kind of workload is affected.
- Timeouts: a job stopped for exceeding its limit often leaves a short message rather than a full traceback, so read the surrounding lines.
- Failed jobs: pair the failed job record with the worker output to find the root cause.
- Long imports and reposts: these frequently stop without a desk error, which makes the worker log the main record of progress.
- Backlogs: a growing queue with idle workers points to a connection or worker health problem, so check the Redis connection and worker status.
When a user reports that a save, import or email never completes, find the matching job in the worker log before retrying it.
Log and monitoring options and when each fits
This table compares four ways to see what a production ERPNext is doing: desk logs, server log files, centralized log shipping and error tracking. Read each row against your team's setup effort, retention needs and alerting expectations. The main takeaway is that desk logs are useful for quick inspection but only as complete as the retention and purge settings you apply to them.
| Option | Setup effort | Retention control | Who can see it | Alerts |
|---|---|---|---|---|
| Desk Error Log and Scheduled Job Log | Low, nothing to install in the desk | Set by purge and retention settings per site, so old entries disappear if purging is aggressive | Users with the right desk roles, typically system administrators | False, you must check them or build your own notification |
| Server log files with rotation | Medium, needs log paths, permissions and a rotation policy | Controlled by logrotate or your host policy, independent of the desk | People with shell access to the bench or host | False by default, needs a log watcher or agent to alert |
| Centralized log shipping (Graylog, Loki or OpenSearch) | High, needs an agent, parsing rules, storage sizing and access setup | Set by the platform's index or retention policy, usually the longest and most auditable | Teams granted access in the central tool, separate from ERPNext users | True, through the tool's alert rules once the events are parsed |
| Error tracking with Sentry | Medium, needs a DSN per bench, site opt-in and privacy settings reviewed | Set by the Sentry project or self-hosted retention, separate from ERPNext purge settings | Engineers with Sentry project access | True, through Sentry issue alerts on new or recurring errors |
| Worker and scheduler logs | Low to medium, depends on how supervisor or systemd captures output | Governed by the host log policy, so confirm rotation for every worker unit | People with host access | False unless you forward them to a tool that alerts |
Setting up logs and alerts in sequence
This sequence turns ERPNext's default logging into an operating routine: known log locations, rotated files, reviewed desk logs, central collection and alerts that fire on real failures. Each step ends with a check so the team can confirm it works before moving on.
Confirm log paths on the bench
The platform engineer on the bench host lists where ERPNext, the Frappe web workers, background workers, the scheduler and the reverse proxy write their output. Look in the bench logs directory and in any service unit or container definitions, and record each path against the process that writes to it. Confirm the exact file names and locations in your own deployment, since they depend on how bench, Docker or your service manager was installed. The step is done when every service that matters has a documented log path and someone other than the author can find it from the runbook.
Set log rotation on every log file
The platform engineer configures log rotation for each file recorded in the previous step, using the system's standard rotation tool or the container runtime's log driver settings. Set the retention period, compression and rotation trigger according to your storage and audit policy, and confirm the settings with your own compliance owner where logs serve as evidence. Make sure the rotation does not break the process that holds the file open, so that writes continue into the new file. The check is a forced rotation in a test environment, followed by a confirmation that new entries land in the new file and that old files are retained or removed as configured.
Verify worker and scheduler output
The platform engineer confirms that the background worker and scheduler services write their logs to the locations recorded earlier, including separate output for each worker queue where your setup splits them. Restart the services in a non-production environment, then trigger a short job and check that its start and any error appear in the expected file. Note any service that writes only to the console or journal, because those entries disappear unless they are captured elsewhere. The step is complete when each worker and scheduler process has a visible, dated log entry for a test run.
Define the desk logs to review
The operations lead and the ERPNext administrator agree which desk logs the team reviews and how often. The core candidates are Error Log and Scheduled Job Log, which record failed server-side operations and scheduled job outcomes inside the application. Assign an owner for each log, write down the review frequency, and record what a reviewer does with a finding, such as opening a ticket or escalating to the on-call engineer. Confirm the access rights needed to view these logs, since they can contain sensitive data from failed transactions, and restrict access to the roles that need it. The step is done when the review schedule is written, assigned and accepted by the people who will carry it out.
Route logs to a central system
The platform engineer ships the server log files, worker and scheduler output and reverse proxy logs to a central log platform your organization already operates, or to one you plan to deploy. Decide which fields must be parsed, which site and bench identifiers must be attached to each entry, and how long entries stay searchable. Check how the forwarder handles log rotation and restarts so that no entries are lost or duplicated during routine maintenance. Verify the pipeline by writing a unique marker line into one log file on the bench and searching for it in the central system. The step is complete when that marker appears within the time your team expects, with the expected labels.
Create a deliberate failure test
The ERPNext administrator runs a controlled test in a non-production site that causes a known server-side error, for example by calling a custom server script that raises an exception, if your environment permits server scripts. Confirm that the failure appears in the Error Log inside the desk and that the traceback reaches the central system through the pipeline built in the previous step. Then trigger a scheduled job that fails on purpose and confirm it is recorded in the Scheduled Job Log. Remove the test script afterward and record the test in your change history. The step is done when both failures are visible in both places.
Create alert rules for failures
The operations lead and the platform engineer define alert rules in the central system and route them to the on-call channel. Start with alerts on repeated Error Log entries within a short window, failed scheduled jobs, worker process exits, scheduler silence and disk usage on the log volume. Set thresholds from observed normal behavior in your environment rather than from a generic template, and document who receives each alert and what action it expects. Test each rule by repeating the controlled failure and confirming that the alert fires and reaches the intended recipient. The step closes when every rule has a tested notification path and a named owner in the runbook.
What to alert on and what to leave for review
Only a few conditions justify waking someone up. The scheduler has stopped, workers are not consuming their queues, the same method keeps failing, or the email queue is growing without draining. Each of these stops work across the whole site: auto repeat invoices and reminders stop running, background jobs pile up behind a dead worker, and outgoing mail waits indefinitely. Watch for scheduler heartbeat gaps, the age of the oldest queued job per queue (short, default and long), and the count of failures sharing one method name in the Error Log. Route these to the on-call channel with a clear owner.
Individual Error Log entries and one-off failed jobs belong in a daily review, not in an alert. A single failed save caused by bad input, or one failed import row, is normal in a busy ERP and usually needs a person to read the traceback, not a page. Set up a short daily review of new Error Log and Scheduled Job Log entries, grouped by method and by site, and promote a pattern into an alert only when it repeats or starts affecting a queue. Confirm the retention behavior of these logs in your version before you rely on them for trend analysis, so that you capture evidence before entries are cleared.
Do not copy threshold numbers from a template or from another company's dashboard. Agree thresholds with the finance operations, integration and platform teams, then set them from your own baseline over several weeks of normal month-end, payroll and stock-count activity. A queue that is normal at month end may be an incident on a quiet Tuesday. Record each threshold, its owner and the action it triggers, and review them after each ERPNext upgrade, because log formats and job names can change between releases.
Security and privacy risks in log data
Logs help operations teams find faults, but they also collect personal data, request content and secrets that were never meant for wide circulation. The cards below cover where that exposure comes from in an ERPNext deployment and the controls that keep logs useful without turning them into a second copy of the database.
Personal data inside Error Log entries
The Error Log in the desk stores tracebacks and the context around a failed request, and that context can include customer names, addresses, bank details or employee records taken from the document being saved. Treat every Error Log entry as a record that holds personal data until you have checked a sample. Ask your team which doctypes failed most often in the last quarter, then review a few entries from each to see what they contain. Confirm with your privacy lead whether those entries fall under your retention rules.
Request payloads and credentials in tracebacks
Failed API calls and integrations can write request payloads, headers or connection strings into log files and error records. A traceback that prints a token, password or webhook secret gives anyone with log access a working credential. Search your server logs and the Error Log for patterns such as authorization headers, API secrets and database passwords. Rotate any credential you find exposed and fix the code path that logged it.
Broad roles reading the desk Error Log
Error Log and Scheduled Job Log are ordinary doctypes, so access follows role permissions. A user with a broad System Manager or report role can read entries that were written for developers and administrators. Review which roles hold read permission on these doctypes, and remove it from business users who do not need to investigate faults. Confirm the result by logging in as a user from each affected role and checking what the desk shows.
Deciding who should read logs
Separate the people who investigate faults from the people who only need to know a job is healthy. Platform engineers and the administrators who run bench commands need server log access. Finance and operations users need a status view, not raw tracebacks. Write this split down as a short access matrix and review it when staff change roles. Confirm that offboarding removes access to both the desk and the server.
Retention limits and off-site masking
Log files and desk logs grow without limit unless rotation and cleanup are configured, and older entries keep personal data longer than your policy allows. Set a retention period for each log type, then apply it in the server rotation settings and in any cleanup job for desk logs. Before you ship logs to a central tool, mask personal fields and secrets at the agent or collector, so the destination never receives them. Ask your vendor or internal team to show the masking rules in a test run.
Access control on central log tools
Once ERPNext logs reach a central platform, that platform becomes a target and a source of data leaks. Restrict who can query the index, export results and create dashboards, and require single sign-on with multi-factor authentication for every user. Keep audit trails of searches and exports where the tool supports them, and confirm that the vendor or open-source version you choose offers those controls before you commit.
Questions operations teams ask before monitoring work
What does ERPNext monitoring work cost, and what drives it up?
The cost comes from the time an engineer spends configuring log access, alert routing, rotation and dashboards, plus the time spent reviewing signals after go-live. Cost rises with the number of sites and benches, the number of worker queues and servers, whether logs are shipped to a central platform such as Graylog, Loki or OpenSearch, and how many alert channels and on-call rotations must be wired in. Ask any provider for a written quote that lists each system to be connected, who maintains the alert rules after handover, and whether the work is one-time or recurring under a support retainer. Monitoring tools may carry their own licensing or hosting costs, so confirm those separately with the tool vendor.
How long does it take to build a monitoring baseline for ERPNext?
A baseline is ready when the team knows what normal looks like for each site, including typical Error Log volume, scheduled job success rates, worker queue depth and request patterns across business hours and month-end. The duration depends on how many sites run, how much traffic they carry, and whether a representative period, such as a full month-end close, has passed since the logs were enabled. Confirm the observation window and the thresholds that will be agreed with your operations owners before work starts, because a baseline taken during a quiet period will set alerts that are too sensitive or too loose.
What must our team provide before monitoring work starts?
The engagement needs read access to the affected benches and servers, the ability to inspect Frappe logs and worker logs, and a named contact who can approve changes to log levels and retention. Operations teams should also provide the on-call rotation, escalation paths, a list of business-critical scheduled jobs such as auto repeat, email and backups, and existing runbooks. Without named owners, alerts tend to reach mailboxes that nobody checks. Agree in writing who receives each alert class, who can silence it, and who signs off on threshold changes.
Can an in-house team set up ERPNext monitoring without a partner?
Yes, a capable in-house team can do it, provided it has someone who understands bench, Frappe workers and the MariaDB and Redis services behind them. The Error Log and Scheduled Job Log in the desk show application failures, while server log files and worker logs show the rest. The main risks for internal teams are time and consistency: rotation settings, alert thresholds and log retention are easy to leave at defaults and forget. Decide whether the team will own alert tuning after go-live, because that ongoing work is what most often lapses.
Which ERPNext logs should we alert on first?
Start with the signals that stop business work. Useful first alerts usually include a growing count of new entries in the Error Log, Scheduled Job Log entries marked failed for jobs your finance or sales processes depend on, worker processes that stop consuming their queues, and server log files that stop growing when traffic continues. Add disk space alerts for the log and backup volumes. Confirm the exact fields, log locations and rotation behavior against your installed version and deployment method, since file paths differ between bench installs and Docker-based setups.
How does logging change after an ERPNext upgrade?
An upgrade can change log formats, log file locations, scheduler behavior and the set of background queues, so monitoring rules written for one major version may miss failures or raise false alarms on the next. Plan a check of every alert and dashboard as part of the upgrade test cycle, and compare Error Log and Scheduled Job Log behavior on a staging copy before production. Also confirm that the version you run is still supported, since the Frappe supported versions page lists end-of-life dates that affect how long you can rely on the current log behavior. Ask your provider to include this check in the upgrade scope.
Do logs contain personal or financial data, and how do we protect them?
Logs can include document names, user identifiers, email addresses and stack traces that reveal business data, so access to log files and log platforms should follow the same role model as the application. Define retention periods, restrict who can read raw logs, and confirm whether any log shipping leaves your network or region. Compliance obligations that apply to your organization should be confirmed with your legal and compliance owners, because DeployOpen prepares systems and evidence but does not issue audit reports or certifications.
How DeployOpen scopes and supports ERPNext monitoring
DeployOpen plans, implements, documents and supports self-hosted open-source platforms inside your own infrastructure, including the logging and monitoring around ERPNext. We start from a written scope that names which logs, jobs and alerts matter to your operations team, then build and hand over the setup in your environment.
How we scope
- Inventory the Error Log, Scheduled Job Log, server logs and worker logs your team will check each day
- Agree in writing which log sources, sites and benches are in scope before work starts
- Define who receives each alert, how it is triaged and which events are informational only
- Engagements are fixed-scope, with deliverables and timelines agreed in writing up front
How we build
- Configure log rotation and retention for the ERPNext server, worker and web logs on your hosts
- Set up alert rules for failed background jobs, stalled schedulers and repeated Error Log entries
- Test each alert with a controlled failure so the team sees what a real notification looks like
- Review log access and permissions so sensitive request data stays limited to approved staff
How we hand over
- Document where each log lives, how to read it and which entries need action
- Provide a runbook that maps each alert to a first response step and an escalation owner
- Walk your operations team through the desk logs, the log files and the alert dashboard
- Confirm the handover checklist with your team before the engagement closes
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer
- Review alert noise and log volume after your first ERPNext version upgrade or workload change
- Confirm with your team which monitoring tools and retention periods your policies require
- Ask any provider to confirm its supported ERPNext version and log format before relying on it
