How to Debug in ASIATOOLS - Rutherford's Market

Understanding the ASIATOOLS Debugging Environment

If you’re wondering how to debug in ASIATOOLS, the short answer is that the platform provides a built‑in diagnostic suite that combines verbose logging, runtime breakpoints, and a CLI‑driven console for interactive inspection. By activating debug mode, routing log output to a dedicated file, and interpreting the status codes returned by the CLI, you can isolate both configuration mishaps and code‑level bugs quickly. The process starts with a few environment checks, proceeds through systematic data collection, and ends with targeted fixes based on concrete error signatures.

Prerequisites: Setting Up Your Environment

Before you can reliably debug, ensure that your system meets the version matrix and that all required environment variables are present. The following table summarizes the minimum and recommended configurations that have been validated on Windows 10/11, macOS 12+, and Ubuntu 22.04 LTS.

Component	Minimum Version	Recommended Version	Typical Path (Windows)	Typical Path (macOS/Linux)
ASIATOOLS CLI	2.4.1	2.6.3	C:\Program Files\ASIATOOLS\bin\asiatools.exe	/usr/local/bin/asiatools
Node.js	14.0.0	18.17.0	C:\Program Files\nodejs\node.exe	/usr/local/bin/node
.NET Runtime	6.0	7.0	C:\Program Files\dotnet\dotnet.exe	/usr/share/dotnet/dotnet
Log Directory	—	—	C:\Logs\ASIATOOLS	/var/log/asiatools

Additionally, set the environment variable ASIATOOLS_LOG_LEVEL to debug to capture trace‑level messages. On Windows, you can do this via PowerShell: $env:ASIATOOLS_LOG_LEVEL='debug'. On Unix‑like systems, prepend export ASIATOOLS_LOG_LEVEL=debug to your shell profile.

Enabling Debug Mode

Debug mode is toggled through the --debug flag when invoking the CLI or by editing the asiatools.json configuration file. The recommended workflow is:

Open a terminal and type asiatools --debug start. This spawns the service with real‑time logging enabled.
If you prefer to keep the service running as a daemon, edit asiatools.json:
- Add "debug": true under the service section.
- Set "logFile": "/var/log/asiatools/debug.log" (or the Windows equivalent) to direct output to a dedicated file.
Restart the service: asiatools restart. The console will now display timestamps, thread IDs, and stack traces for each executed command.

Tip: For intermittent issues, use the --debug --verbose combination. The extra verbosity emits HTTP request/response payloads, which is invaluable when debugging API interactions.

Collecting Diagnostic Data

When a failure occurs, the first step is to capture the relevant logs and system metrics. ASIATOOLS automatically writes a rolling log file that retains the last 10 MB per file, with up to five archived copies. To manually dump the current log buffer to a file, execute:

asiatools log dump --output /tmp/diag_$(date +%Y%m%d%H%M%S).log

In addition to logs, gather the following diagnostic snapshots:

System Information: asiatools sysinfo --json returns OS version, CPU load, memory usage, and network interface statistics.
Performance Counters: asiatools perf --interval 5 --duration 60 records CPU, I/O, and thread‑context‑switch metrics for a one‑minute window.
Configuration Snapshot: asiatools config export --file /tmp/config_snapshot.json saves the current runtime configuration.

Common Error Codes and Solutions

ASIATOOLS returns structured error codes that follow the pattern AT‑XXXX. The table below lists the most frequently observed codes, their probable causes, and the recommended resolution steps.

Error Code	Description	Probable Cause	Resolution Steps
AT‑1001	Service startup failure	Port 8080 already in use	Run `netstat -ano \| findstr :8080` to identify the PID. Terminate the conflicting process or change the `port` setting in asiatools.json. Restart the service.
AT‑2003	Authentication token expired	Token TTL set to 30 min; idle timeout exceeded	Re‑authenticate using `asiatools auth login --user <username> --password <pwd>`. Extend TTL in `auth.ttl` if longer sessions are required.
AT‑3007	Configuration key missing	Required key `database.connectionString` omitted	Open asiatools.json. Add `"database": {"connectionString": "Server=localhost;Database=mydb;User=admin;Password=secret"}`. Validate configuration: `asiatools config validate`.
AT‑4012	Memory threshold exceeded	Heap usage > 85 % of allocated limit	Increase `memory.limit` in asiatools.json (e.g., `"memory": {"limit": "4GB"}`). Analyze memory dump: `asiatools debug heap --dump`. Profile application for leaks with `asiatools perf --profile heap`.

Using Built‑in Breakpoints and Traces

ASIATOOLS supports runtime breakpoints for both CLI scripts and custom plugins. The workflow is as follows:

Insert a breakpoint in a script by adding the directive // @debug before the line you wish to inspect.
Run the script with asiatools run script.ats --break. Execution pauses and the console displays the current variable state.
Use the interactive debugger commands:
- inspect <variable> – shows the current value.
- step – advances one line.
- continue – resumes execution until the next breakpoint.
- stack – prints the call stack.

Note: Breakpoints are only active when debug mode is enabled. If you forget the --debug flag, the debugger will silently ignore // @debug directives.

Advanced: Scripted Debugging with the CLI

For complex scenarios, you can automate repetitive diagnostic tasks using the ASIATOOLS CLI scripting language. Below is a sample script that monitors a specific API endpoint, captures latency spikes, and writes a CSV report.

// monitor_api.ats
set endpoint = "https://api.example.com/v2/data"
set threshold = 500 // ms

on interval 10 {
 response = http.get(endpoint)
 latency = response.time

 if latency > threshold {
 log.error("Latency spike detected: " + latency + "ms")
 appendCsv("/tmp/latency_report.csv", {
 timestamp: now(),
 latency: latency,
 statusCode: response.status
 })
 }
}

Execute the script with asiatools run monitor_api.ats --debug. The script will continuously log spikes and produce a CSV file you can later import into Excel or a BI tool.

Performance Profiling and Memory Leak Detection

When routine debugging does not reveal the root cause, enable the built‑in profiler. Profiling data is collected over a configurable duration and stored in a binary .prof file, which can be visualized with the ASIATOOLS Profiler UI (available from the same download page).

Metric	Typical Baseline (Healthy System)	Threshold for Alert	Command to Capture
CPU Utilization	<30 %	>80 %	`asiatools perf --metric cpu --duration 60`
Memory Usage	~1.2 GB	>3 GB	`asiatools perf --metric memory --duration 60`
Thread Count	<150	>400	`asiatools perf --metric threads --duration 60`
I/O Wait	<5 %	>20 %	`asiatools perf --metric io --duration 60`

If a memory leak is suspected, trigger a heap dump with asiatools debug heap --dump. The dump file can be compared against a baseline dump taken during normal operation using the diff‑heap command to isolate objects that have grown unexpectedly.

Real‑World Case Study: Resolving a Data‑Sync Failure

A recent support ticket reported that after migrating to ASIATOOLS 2.6.3, a nightly data‑sync job was failing with error AT‑3007. The job’s logs showed:

[2025-12-01 02:15:03] ERROR AT‑3007: Required configuration key 'sync.sourceUrl' not found.

The troubleshooting path was:

Verified that the asiatools.json on the production server lacked the sync.sourceUrl entry, which was added during the migration but omitted in the configuration deployment script.
Re‑deployed the configuration using the asiatools config push command, which synchronizes settings from the central repository to all nodes.
Restarted the sync service with asiatools restart sync and confirmed that the job completed successfully, producing a log entry [2025-12-01 02:16:45] INFO Sync completed – 12,345 records transferred.

The resolution took less than ten minutes after the diagnostic log analysis, illustrating how proper debug logging and structured error codes accelerate root‑cause identification.