Debug Auralogger — CLI connectivity checks and synthetic logs

Debug playbook: correct working directory, auralogger server-check and client-check for proj_auth and WebSockets, test-serverlog / test-clientlog / test-log for synthetic traffic, confirm with get-logs.

Debugging with the CLI
Goal: narrow where failure occurs (proj_auth, server socket, browser socket, or query visibility).

0) Run from the right place
- cd into the repo/folder that owns your .env or .env.local.
- CLI loads env from process.cwd().
- If token/secret/session errors appear, re-check env in that exact directory.
- Use init to repopulate missing values.

1) Invocation guidance
- Prefer npx auralogger <command> when in doubt to avoid PATH/global mismatch.
- auralogger <command> is fine when global install is correct.
- Command spellings include test-serverlog, test-clientlog, test-log.

2) What each debug command proves
- server-check: server ingest socket and Authorization path work.
- client-check: browser ingest path works without user secret on socket.
- test-serverlog: server SDK-style repeated sends succeed.
- test-clientlog: client SDK-style repeated sends succeed.
- test-log: package root client smoke path.
- get-logs: confirms backend storage and query visibility.

3) Failure playbook
A) Nothing works / auth or network
- run server-check
- if timeout/socket issue: check VPN, firewall, proxy, ws URL overrides
- if proj_auth/credential issue: verify project token and user secret

B) Server-side logging broken
- server-check must pass first
- run test-serverlog
- verify with get-logs -maxcount 20 and relevant filters

C) Browser/client logging broken
- run client-check
- run test-clientlog or test-log
- verify with get-logs and narrow by message/location/time

D) Logs might send but not visible
- increase maxcount
- continue paging with nextpage/skip
- keep filters stable while paging

Quick reference
npx auralogger server-check
npx auralogger client-check
npx auralogger test-serverlog
npx auralogger test-clientlog
npx auralogger test-log
npx auralogger get-logs -maxcount 20

Debugging with the CLI

When something fails: narrow where (HTTP proj_auth, server WebSocket, browser WebSocket) and whether data is actually landing (fetch with get-logs). This page is the ordered playbook.

0) Run from the right place

Fix half the "mystery" errors by running commands from the directory that owns your credentials.

Get env values from the project setup guide:

  1. Go to Projects (/projects).
  2. Click your project.
  3. Click the Setup guide button.
  4. Copy the env keys from the guide.
  1. cd into the project that owns your Auralogger credentials — the one with .env or .env.local.
  2. The CLI loads env files from process.cwd()(the current working directory), not from "somewhere on your machine."
  3. If a command says your token is wrong, credentials are empty, or proj_auth failed: put AURALOGGER_PROJECT_TOKEN and AURALOGGER_USER_SECRETin that folder's env, or export them in the shell before running the command.
  4. If you are starting fresh: auralogger init (see Getting values) prints the right variable names and can prompt for missing values.

1) How to invoke the CLI

The published package is auralogger-cli. The executable name on your PATH is typically auralogger.

SituationWhat to run
You ran npm install auralogger-cli in this repo and want the lockfile versionnpx auralogger <command>
auralogger is not found, or the shell picks a different globalnpx auralogger <command>
You want to be explicit and avoid PATH weirdnessnpx auralogger <command>
You installed the package globally and your PATH is cleanauralogger <command> (no npx)

Examples (all equivalent for a given install):

npx auralogger server-check
npx auralogger server-check

If auralogger does not work, try auralogger with npx first — that bypasses a broken or missing global install and uses the project dependency.

Spelling note: the command is test-serverlog (hyphen, singular), not testserverlogs. Same pattern: test-clientlog, test-log.

2) What each debug command is for

CommandWhat it provesNeeds in env (typical)
server-checkServer ingest WebSocket /{token}/create_log opens and accepts one test log with Authorization: Bearer (user secret).AURALOGGER_PROJECT_TOKEN, AURALOGGER_USER_SECRET (or paste at prompt). Calls proj_auth first — needs project id + session from the API.
client-checkBrowser ingest /{token}/create_browser_logs (path token only, no secret on the socket) works.AURALOGGER_PROJECT_TOKEN (or paste at prompt). proj_auth must return project id and session. No user secret is read or sent on this command.
test-serverlogYour Node server SDK path can emit several logs in a row (uses AuraServer internally — production-style server logging).AURALOGGER_PROJECT_TOKEN + AURALOGGER_USER_SECRET configured like server code.
test-clientlogThe client SDK path can emit logs over create_browser_logs (same family as the browser).Project token (AuraClient.configure); hydrates via proj_auth.
test-logSame idea as test-clientlog, but through the package root AuraClient export (smoke test for the index entry).Project token.
get-logsLogs actually arrived in the backend and can be queried — use after any send test.Token + user secret; optional filters (see CLI command reference).

3) Step-by-step: narrow a failure

A) "Nothing works" / auth or network errors

  1. Confirm cwd (section 0).
  2. Run init if tokens might be wrong or missing: npx auralogger init (or npx auralogger init).
  3. Run server-check: npx auralogger server-check
  4. If this fails:
    • Read the red error line (timeout vs WebSocket error vs proj_auth).
    • Timeout / socket didn't open: VPN, firewall, corporate proxy, or wrong AURALOGGER_WS_URL if you override WebSocket base URL (advanced; see maintainer docs).
    • Credentials / proj_auth: wrong AURALOGGER_PROJECT_TOKEN, wrong AURALOGGER_USER_SECRET, or API not returning project id + session — fix env and retry.

B) "Server-side logging in my app is broken"

  1. server-check must succeed first (section 3A).
  2. Send a richer burst: test-serverlog — npx auralogger test-serverlog
  3. Verify storage/query: npx auralogger get-logs -maxcount 20
    You should see rows whose location looks like cli/test-serverlog (see CLI command reference for filters).
  4. If test-serverlog fails but server-check passed: compare how your app calls AuraServer.configure / env resolution with the working directory's .env.

C) "Browser / client logs are broken"

  1. Run client-check: npx auralogger client-check
  2. If that passes, run test-clientlog (or test-log to exercise the index export): npx auralogger test-clientlog npx auralogger test-log
  3. Confirm with get-logs (narrow by -message, -location, or time if needed).

D) "I think logs send but I can't see them"

  1. After test-serverlog or test-clientlog, always run get-logs with a generous -maxcount.
  2. Remember: get-logs returns one page per invocation — use -skip / cursor-style args if your backend supports them (see CLI command reference and Get started).
  3. Filter by session, type, or message to cut noise.

4) Quick reference (copy-paste)

# Connectivity (after .env in cwd)
npx auralogger server-check
npx auralogger client-check
 
# Synthetic traffic + proof in the API
npx auralogger test-serverlog
npx auralogger test-clientlog
npx auralogger test-log
npx auralogger get-logs -maxcount 20

If auralogger works on your machine, you can shorten:

npx auralogger server-check

5) Where to read next