debug
The blocklet debug command provides a flexible way to troubleshoot a running blocklet. It allows you to dynamically set debug configurations, redirect it to a development blocklet store, or stop it for inspection. This is particularly useful for diagnosing issues in a live or staging environment without needing to rebuild or redeploy the blocklet.
Usage#
blocklet debug <value> --app-id <string>Arguments & Options#
Argument / Option | Description |
|---|---|
| The value for the debug configuration. This can be a debug flag (e.g., a string for an environment variable), a URL for a development blocklet store, or the special command |
| Required. The DID of the target blocklet you want to debug. |
How It Works#
The command's behavior depends on the <value> you provide. The following diagram illustrates the process:
Examples#
Set a DEBUG Flag#
This is the most common use case. It sets a configuration key named DEBUG on the target blocklet. The blocklet's code can then read this value to enable features like verbose logging.
# Set the DEBUG config for the blocklet with the specified App DID
blocklet debug "service:*,api:*" --app-id z8iZ3t4okHr6bwxm3vKo58gAWj4qCjkwY2B8This command sets the DEBUG config to "service:*,api:*". The blocklet can then use a library like debug to enable detailed logs for its service and API modules. You can view the output using the server logs command.
Use a Development Blocklet Store#
When developing a blocklet that depends on others, you might want to point it to a local Blocklet Store serving your latest changes.
# Point the blocklet to a local development store
blocklet debug http://localhost:3030 --app-id z8iZ3t4okHr6bwxm3vKo58gAWj4qCjkwY2B8This command tells the specified blocklet to use http://localhost:3030 as its Blocklet Store. This allows you to test interactions with components that are not yet published to the official store.
Stop a Blocklet#
In some cases, you might need a direct way to stop a misbehaving blocklet. The '$stopBlocklet' value provides a mechanism for this.
# Stop the blocklet using the debug command
blocklet debug '$stopBlocklet' --app-id z8iZ3t4okHr6bwxm3vKo58gAWj4qCjkwY2B8This command instructs the Blocklet Server to stop the specified blocklet. Note the single quotes around '$stopBlocklet' to prevent the shell from interpreting the $ as a variable.
The debug command is a powerful tool for real-time troubleshooting. After setting a debug flag, you will likely want to inspect the blocklet's output using server logs or interact with it directly using blocklet exec.