Logging & Debugging

This page explains RocketShipIt's logging behavior in server mode: what is written to the log.log error file, what per-request metadata can be emitted to stdout, and how to inspect the actual carrier traffic using the debug parameter.

Short version: By default RocketShipIt logs only errors, to a log.log file, and prints nothing per request to stdout. You can opt in to per-request logging with the log level setting (-log-level / RS_LOG_LEVEL): metadata adds one JSON line per request to stdout (carrier, action, status, timing, client IP), and full additionally logs the request and response JSON bodies. To see what RocketShipIt sent to and received from a carrier, use the debug parameter, which returns that information in the API response (not in a log).

Log levels

Per-request logging is controlled by a single, cumulative log level. Each level includes everything the level below it logs.

LevelWhat it logsWhere
errors (default)Internal errors onlylog.log file
metadataErrors, plus one JSON line per request (no bodies)stdout
fullErrors and metadata, plus the request and response JSON bodiesstdout

Set the level with the -log-level flag or the RS_LOG_LEVEL environment variable. If both are set, the flag wins:

# via flag
./RocketShipIt -s -log-level metadata

# via environment variable
RS_LOG_LEVEL=metadata ./RocketShipIt -s

An unrecognized value falls back to errors, and a warning is printed to stderr.

What is and isn't logged in server mode

Eventerrors (default)metadatafull
Internal errors (failed license check, unwritable response, bad request body, etc.)log.loglog.loglog.log
Per-request metadata (carrier, action, HTTP status, duration, client IP)Nostdoutstdout
App-level request and response JSON bodiesNoNostdout
Underlying carrier request/response trafficNeverNeverNever (use debug)

On the default errors level, RocketShipIt writes nothing per request to its logs, which keeps your customers' shipping data off disk.

Per-request logging on stdout

At the metadata and full levels, RocketShipIt prints one JSON object per request to stdout. Each line includes:

  • time - timestamp of the request
  • carrier - the carrier from the request (empty if the body could not be parsed)
  • action - the action from the request
  • status - the HTTP status code RocketShipIt returned (e.g. 200, 401)
  • duration_ms - total time spent handling the request, in milliseconds
  • client_ip - the originating client address (first X-Forwarded-For entry if present, otherwise the connection's remote host)
  • remote_addr - the raw connection remote address

A metadata line looks like this:

{"time":"2026-05-27T12:34:56.789Z","level":"INFO","msg":"request","carrier":"ups","action":"getallrates","status":200,"duration_ms":142.3,"client_ip":"203.0.113.7","remote_addr":"10.0.0.1:54321"}

Because the output is line-delimited JSON on stdout, it flows into your service manager's logs (for example the systemd journal) and into log aggregators without a reverse proxy. Health check requests to /api/v1/health and CORS OPTIONS preflight requests are not logged.

client_ip can be spoofed. When RocketShipIt is exposed directly (not behind a trusted reverse proxy), the X-Forwarded-For header is client-controlled. The raw remote_addr field is always logged alongside it so you can tell the difference.

The full level

Warning: full writes customer data to your logs. At the full level, RocketShipIt logs the complete app-level request and response JSON bodies to stdout. These contain addresses, account numbers, and other shipping details, and they will be persisted by your service logs. Use full only while actively troubleshooting, and prefer the debug parameter when you need to see carrier traffic.

At the full level, each request line additionally includes:

  • request_body - the JSON body RocketShipIt received (embedded as nested JSON)
  • response_body - the JSON body RocketShipIt returned

If a body is not valid JSON it is logged as a string under request_body_raw instead, so the log line itself is always valid JSON. The response body is only included when the response is JSON, so the API Explorer's HTML responses are omitted.

Note that full logs the app-level request and response, that is, what your application sent to and received from RocketShipIt. It does not log the underlying SOAP/REST traffic between RocketShipIt and the carrier. For that, use the debug parameter.

Where errors go: the log.log file

Regardless of log level, internal errors are written to a file named log.log in the same directory as the RocketShipIt executable. The file is created automatically and appended to across restarts.

A few things to know:

  • log.log is not stdout and not stderr. The per-request logging described above is separate, and goes to stdout.
  • If RocketShipIt can't create or open log.log (for example, a read-only working directory), logging is silently discarded and no errors are written anywhere. If you expect a log.log and don't see one, check the executable directory's permissions.
  • If you run RocketShipIt with Docker, the log.log file lives inside the container; use docker exec -it <container_id> /bin/bash to read it. See Self-Hosting for Docker setup.

Inspecting requests with the debug parameter

The supported way to see exactly what RocketShipIt sent to and received from a carrier is the debug parameter. Set it to true and the information is returned in the API response body under meta.debug_information; it is never written to a log file.

For a normal request, set debug inside params:

{
  "carrier": "ups",
  "action": "getallrates",
  "params": {
    "debug": true
  }
}

For a batch request, set debug at the root of the request to get debug information for every request in the batch.

When debug is true, meta.debug_information includes:

  • RocketShipIt version, build hash, and build time
  • The original request JSON RocketShipIt received
  • Every underlying carrier transaction, each with the carrier URL, HTTP status code, duration, request and response bodies, request/response headers, and an equivalent curl command

See Request & Response Format for the full structure and Troubleshooting for how to use it when contacting support.

Keep debug off in production. It defaults to false. Because the debug payload contains the full carrier request and response (including addresses and account details), only enable it when you are actively troubleshooting.

← Self-HostingCloud API →