Skip to content

Trace routing, injection and delivery ​

Select a debug context before creating the application. CHO writes its diagnostics to stderr, which leaves a command's stdout available for its output.

ContextUse it to inspect
cho:diModule scopes, resolutions, provider creation and failures
cho:webRegistered method/path pairs, startup errors and route exceptions
cho:openapiOpenAPI document generation and validators whose schemas could not be converted
cho:commandDiscovered actions, selected command, duration and exit status
cho:messageComplete topics, graph creation and delivery failures
cho:kafkaSubscription, retry, dead-letter handling, commit failures and shutdown

Enable a focused trace ​

For the HTTP quick start, run one of the following in a POSIX shell. The startup log should include GET /api/books/:id and Books.find.

sh
CHO_DEBUGLOG=cho:web,cho:di deno run --allow-env=CHO_DEBUGLOG --allow-net main.ts
sh
CHO_DEBUGLOG=cho:web,cho:di npx tsx main.ts
sh
CHO_DEBUGLOG=cho:web,cho:di bun run main.ts

Use CHO_DEBUGLOG='cho:*' for matching context names or CHO_DEBUG=1 for all contexts. On a host that supplies environment bindings directly, call set_env(bindings) from @chojs/core/utils before creating the application. The environment source is process-wide and a logger reads the setting when constructed.

Use the trace to isolate a failure ​

  1. An HTTP method never runs. Find its full method and path in cho:web. Compare the verb, application prefix and ordering of literal and parameter routes. With an unmatched path the adapter answers before route middleware.
  2. A dependency cannot be created. Find the first failure in cho:di. The named module is where the dependency must be visible. Inspect the original error's cause if a factory failed.
  3. A Kafka message appears twice. Inspect cho:message for handler failures and cho:kafka for retries or commit errors. A successful handler can still precede a failed offset commit.
  4. A CLI returns a surprising status. Check which action cho:command selected. Then compare the command, middleware and error-handler return values with the exit-code table.

For setup failures grouped by phase, see error diagnostics.

Released under the MIT License.