Observability for NetSuite Integrations — What to Monitor, What to Alert On
- Three signals predict failure before customers report it: sync lag (WooCommerce order to NetSuite Sales Order), error rate per entity type, and governance consumption trend.
- Alert on error rate above 1% for any entity type over a 15-minute window — not on individual errors, which generate noise.
- NetSuite’s CSV Import screen has a “Run Server SuiteScript and Trigger Workflows” setting. When it is off, every User Event script — including the one most teams use to write their sync log line — does not run for that import. No error is raised.
- NetSuite’s own script logging has a ceiling too: 100,000
N/logcalls per account per 60 minutes. Past it, NetSuite silently raises the offending script’s log level instead of erroring — yourlog.debug()calls keep executing and stop producing output. - Skip individual API response times and WooCommerce queue size at the integration level — both are too noisy or too late to act on.
N/log calls allowed account-wide before NetSuite raises the log levelMost NetSuite integration monitoring setups log every API call, alert on individual errors, and watch queue sizes in real time — then miss a six-hour sync backlog that started building four hours before anyone noticed. Three signals predict integration failure before a customer reports it; most of what teams instrument instead is noise. This guide covers those three signals, the alert thresholds that separate a real incident from a transient blip, and a NetSuite-specific gap that leaves an observability setup blind exactly when a bulk data load is running. It assumes the integration is already live — for the setup steps that get it there, see the full NetSuite and WooCommerce integration guide.
The Three Signals That Actually Predict Failure
Measure the time delta between the WooCommerce order’s date_created and the corresponding NetSuite Sales Order’s createdDate. Track the P50, P95, and P99, and alert when P95 exceeds your SLA — typically 10–15 minutes for a scheduled sync. A rising P95 is a leading indicator of queue buildup well before the queue size itself makes the problem obvious.
Track error count and success count separately for Orders, Products/Inventory, Customers, and Refunds, and calculate error rate as a percentage of total events per entity type. Alert when error rate exceeds 1% over any 15-minute window. This threshold prevents alert noise from transient single-record failures while still catching systematic issues early.
Call runtime.getCurrentScript().getRemainingUsage() at the end of every Scheduled Script and Map/Reduce execution and log the remaining units — the call itself costs nothing. Track the result as a time series. If governance consumption per order trends upward without a matching volume increase, a SuiteScript regression has introduced extra API calls or an inefficient loop. This is a code-quality signal, not a capacity signal.
What Not to Monitor
Individual API response times — high variance, no clean threshold. WooCommerce Action Scheduler queue size — a lagging indicator; by the time it is high, the failure has been happening for hours. Per-minute API call counts — too granular, obscures the pattern. Alerting on any of these trains the team to ignore alerts, which is worse than having none.
The Setting That Turns Off Your Sync Logging
NetSuite’s CSV Import screen carries a setting called “Run Server SuiteScript and Trigger Workflows.” When it is off, no server-side SuiteScript or workflow runs for that import job — not a subset, all of it. Most teams put their sync logging and outbound webhook calls inside a User Event script’s afterSubmit entry point, because that is the natural place to react to a record change. A CSV import that runs with this setting off writes the records fine; it just never triggers the script that logs the change or tells WooCommerce or Shopify it happened, and NetSuite raises no error to say so.
Oracle’s own guidance is specific, not blanket: enable the setting when “synching ‘live’ data or running a partner application,” and disable it when “doing a historical import.” The setting also defaults to the company-wide preference but can be overridden per import, so the account default and what a specific job actually ran with can disagree. The failure mode is not that someone disables logging on purpose — it is that a cycle-count correction or a supplier-receipt fix looks enough like a “historical import” that an operator reasonably unchecks the box to speed up the save, and every downstream system that depends on that User Event script quietly stops hearing about the change.
Why Sync Logging Shouldn’t Live in a User Event Script Alone
The CSV import gap is one symptom of a broader placement problem: a User Event script carries a 1,000-unit governance budget, versus 10,000 for a Scheduled Script and a per-invocation budget for Map/Reduce that resets with each call. Anything that needs to run reliably across a bulk operation — logging included — is safer moved to a Scheduled Script or Map/Reduce job that polls or processes in batch, independent of whether a given CSV import job happened to run with server scripting enabled. This is the same governance ceiling that our webhook-vs-polling comparison covers from the write-throughput side; here it is the same architectural fix applied to the logging problem specifically. A Scheduled Script that reads changed records on its own schedule logs its own activity regardless of how those records were written — by the UI, by a RESTlet, or by a CSV import with server scripting off.
Your Own Logging Has a Governance Ceiling Too
NetSuite caps the N/log module at 100,000 log calls across all scripts in an account within any 60-minute window. Exceeding it does not error and does not stop the script: NetSuite automatically raises the offending script’s log level instead — for example, from Debug to Audit — so a log.debug() line keeps executing but stops writing output, because its level no longer clears the raised threshold. The script owner gets an email notification, and a note is added to the script’s own Execution Log recording that the level was raised.
This matters for any integration that logs verbosely during a high-volume period, which is exactly when the log data is most valuable. A chatty debug-level log line inside a loop that processes thousands of records in one run can burn through a meaningful share of that 100,000-call account-wide budget by itself, especially on an account running several scripts concurrently. Reserve log.debug() for development and drop to log.audit() or a structured external sink (see the stack below) for anything that has to survive production volume.
RESTlet Rejections Don’t Look Like Rate Limits
If part of the integration calls NetSuite through a RESTlet, do not assume a concurrency rejection will show up as HTTP 429 in your error-rate metric. As our rate-limiting guide documents in full, NetSuite returns HTTP 400 for a RESTlet concurrency rejection, not 429 — so an alert rule or a retry policy written against 429 alone silently misses it. Tag RESTlet error-rate metrics separately from REST web services calls so this failure mode surfaces in the same 1% threshold as everything else, instead of hiding inside a generic “400 errors” bucket nobody watches closely.
Recommended Observability Stack
| Layer | Tool | What it captures |
|---|---|---|
| Integration events | Structured JSON logs (CloudWatch, Datadog, Grafana Loki) | Sync events, errors, entity IDs, timing |
| Metrics + alerts | Datadog or Grafana | Error rate, sync lag P95, governance trend |
| Error notification | PagerDuty or OpsGenie (critical) + Slack (warning) | Route critical (error rate >1%) and warning (>0.5%) separately |
| NetSuite-side | Script Execution Log (native, Customization > Scripting) + custom logging table | Governance consumed, SuiteScript errors, log-level-raise notices |
NetSuite’s native Script Execution Log retains user-generated log entries for 30 days and system error entries for 60 days — long enough for weekly review, not long enough to be a permanent record. Anything worth keeping past that window needs to land in the external log layer above, not just the native list.
Pre-Flight Checklist Before You Call an Integration Instrumented
Run through this before treating a NetSuite integration as monitored. Most items are one-time reads, not ongoing work.
- Confirm which script type owns your sync logging — a User Event script’s exposure to the CSV import setting makes it the wrong sole home for anything bulk-sensitive.
- Check the “Run Server SuiteScript and Trigger Workflows” setting on the CSV Import screen before every bulk load, not only the first one.
- Log
runtime.getCurrentScript().getRemainingUsage()at the end of every Scheduled Script and Map/Reduce execution and graph it as a time series. - Set the error-rate alert at 1% per entity type over a 15-minute window; route anything above it to a paging tool, not only Slack.
- Track sync lag P50/P95/P99 from WooCommerce order
date_createdto NetSuite Sales OrdercreatedDate, and alert on a rising P95. - Tag RESTlet errors separately from REST web services errors so an HTTP 400 concurrency rejection is not lost inside a generic bucket.
- Watch total
N/logcall volume against the 100,000-call, 60-minute account ceiling on accounts running several scripts concurrently. - Skip alerting on individual API response times or WooCommerce Action Scheduler queue size — both generate noise or arrive too late to act on.
- Review the Script Execution Log list weekly, not only after something is already broken.
Most of this is a one-week exercise on a live integration, not a rebuild. If the gaps above turn up faster than the team can close them, an eCommerce sync audit baselines the governance and error-rate picture in about that timeframe, before deciding what to build in-house.
Get the working checklists
The runbooks and decision checklists from these guides, as printable PDFs — free in the SoftXone guide library.
References
- CSV Import: Server Scripting and Workflow ExecutionOracle NetSuite Help — what the “Run Server SuiteScript and Trigger Workflows” setting controls and its data-corruption warning.
- Setting CSV Import PreferencesOracle NetSuite Help — the “enable for live sync, disable for historical imports” guidance and the company-default-vs-per-import override.
- SuiteScript 2.1 API GovernanceOracle NetSuite — the 1,000 / 10,000 usage-unit ceilings for User Event and Scheduled scripts.
- Governance on Script LoggingOracle NetSuite Help — the 100,000-call, 60-minute
N/logaccount ceiling and the automatic log-level raise. - Script.getRemainingUsage()Oracle NetSuite Help — the governance-free API call used to log remaining units at runtime.
- OpenTelemetry DocumentationCNCF — the vendor-neutral observability standard referenced for structured event instrumentation.
- Datadog Log ManagementDatadog — the log aggregation and metric pipeline used in the recommended observability stack.
Frequently asked questions
What should I monitor on a NetSuite integration?
Three signals matter: sync lag from the source order to NetSuite Sales Order creation, error rate per entity type, and SuiteScript governance consumption trending upward without a matching volume increase. Most other metrics are noise for an integration.
What should I not alert on?
Individual API response times, WooCommerce Action Scheduler queue size, and per-minute call counts. All three are either too noisy or too late to act on, and alerting on them trains the team to ignore alerts, which is worse than having none.
What does a good observability stack look like?
Structured logs feeding a metrics and alerting layer, error notifications routed by severity to a paging tool and a chat channel, and NetSuite’s own Script Execution Log reviewed on a schedule rather than only after an incident.
Does a NetSuite CSV import trigger my integration’s logging?
Only if the Run Server SuiteScript and Trigger Workflows setting is on for that specific import job. It defaults to the company-wide preference but can be overridden per import, so treat checking its state as a step in every bulk-load runbook, especially for a job that looks like a one-off correction rather than a routine sync.
Can NetSuite’s own script logging fail silently?
Yes. Past 100,000 N/log calls across the account in a 60-minute window, NetSuite raises the offending script’s log level instead of erroring, so debug-level lines keep executing but stop producing output. The only signals are an email to the script owner and a note in that script’s own Execution Log.
Leave a Reply