# How to Debug Worker Logs and Query Workflow Execution Status in Shannon > Debug Shannon worker logs with ./shannon logs ID and query workflow execution status using ./shannon query ID. Empower your debugging with Temporal progress queries. - Repository: [KeygraphHQ/shannon](https://github.com/keygraphhq/shannon) - Tags: how-to-guide - Published: 2026-02-16 --- **Use `./shannon logs ID=` to tail real-time worker output and `./shannon query ID=` to inspect execution status via the Temporal `getProgress` query.** Shannon, an open-source AI-driven penetration testing framework from KeygraphHQ/shannon, orchestrates every pentest as a **Temporal workflow**. Understanding how to debug worker logs and query workflow execution status is essential for monitoring long-running security assessments, diagnosing agent failures, and verifying pipeline progress without interrupting active operations. ## Understanding Shannon's Logging Architecture Shannon's observability layer splits output between persistent audit files and ephemeral worker console streams, both managed by the Node.js services defined in [`src/temporal/worker.ts`](https://github.com/KeygraphHQ/shannon/blob/main/src/temporal/worker.ts). ### The Unified Workflow Log Every workflow writes a canonical log file to `audit-logs//workflow.log`. The `WorkflowLogger` class in [`src/audit/workflow-logger.ts`](https://github.com/KeygraphHQ/shannon/blob/main/src/audit/workflow-logger.ts) initializes this file during the first activity execution, writing structured headers via `generateWorkflowLogPath` and `initialize` methods. Throughout the pentest, phase transitions (`logPhase`) and agent completions (`logAgent`) append human-readable entries: ``` [2026-02-16 12:34:56] [PHASE] Starting: recon [2026-02-16 12:35:02] [AGENT] vuln-xss: Completed (1m 20s $0.03) ``` ### Worker Console Output The **worker process** itself—bootstrapped in [`src/temporal/worker.ts`](https://github.com/KeygraphHQ/shannon/blob/main/src/temporal/worker.ts) via `NativeConnection.connect`—emits diagnostic messages to stdout/stderr. These streams capture Temporal connection events, workflow bundling status, and runtime errors before they reach the unified log. The CLI wrapper (`shannon`) forwards these streams to the Docker Compose environment, making them accessible via container inspection. ## How to Debug Worker Logs in Shannon Shannon provides three primary methods for debugging worker logs, ranging from real-time monitoring to low-level container inspection. ### Real-Time Log Monitoring The recommended approach for debugging active workflows uses the CLI wrapper to tail the unified log: ```bash ./shannon logs ID= ``` This command auto-detects the log path by searching `./audit-logs` and any custom `OUTPUT` directory, then executes `tail -f` on `workflow.log`. The implementation resides in the `shannon` script (lines 33–71), providing live updates as agents complete phases or encounter errors. ### Inspecting Worker Console Output For connection-level debugging or worker boot failures, inspect the worker container directly: ```bash docker compose logs -f worker ``` This captures output from [`src/temporal/worker.ts`](https://github.com/KeygraphHQ/shannon/blob/main/src/temporal/worker.ts) before it reaches the unified audit log, revealing Temporal server connectivity issues or workflow bundling errors. ### Accessing Logs via Docker When the CLI wrapper is unavailable, access logs directly through the worker container: ```bash docker compose exec -T worker \ tail -f ./audit-logs//workflow.log ``` This bypasses the host filesystem mounting and reads directly from the container's working directory, useful in containerized CI/CD environments. ## Querying Workflow Execution Status Shannon exposes workflow state through Temporal's query system, implemented in [`src/temporal/query.ts`](https://github.com/KeygraphHQ/shannon/blob/main/src/temporal/query.ts), allowing programmatic inspection of pipeline progress without interrupting execution. ### Using the getProgress Query The `getProgress` query, registered in [`src/temporal/workflows.ts`](https://github.com/KeygraphHQ/shannon/blob/main/src/temporal/workflows.ts), returns a `PipelineProgress` object containing real-time execution metadata. The query handler in [`src/temporal/query.ts`](https://github.com/KeygraphHQ/shannon/blob/main/src/temporal/query.ts) constructs this object by aggregating state from the running workflow, enabling external tools to poll for status. ### CLI Command Reference Execute the query through the CLI wrapper: ```bash ./shannon query ID= ``` This command runs the query via Docker exec: ```bash docker compose exec -T worker \ node dist/temporal/query.js ``` The wrapper handles workflow ID validation and formats the output for terminal readability. ### Interpreting PipelineProgress Results The query returns a structured status object with the following fields: - **status**: `running`, `completed`, or `failed` - **currentPhase**: The active pentest phase (e.g., `recon`, `exploit`) - **currentAgent**: The AI agent currently executing - **completedAgents**: Array of finished agents with timing data - **failedAgent** / **error**: Detailed failure information if the workflow encountered errors - **agentMetrics**: Token usage, execution duration, and estimated cost per agent This data enables precise debugging of stalled workflows or cost analysis of completed pentests. ## Summary - **Shannon** runs pentests as **Temporal workflows** with logs centralized in `audit-logs//workflow.log` via [`src/audit/workflow-logger.ts`](https://github.com/KeygraphHQ/shannon/blob/main/src/audit/workflow-logger.ts). - Use `./shannon logs ID=` to tail real-time worker output and phase transitions. - Query execution status programmatically via `./shannon query ID=`, which invokes the `getProgress` Temporal query defined in [`src/temporal/query.ts`](https://github.com/KeygraphHQ/shannon/blob/main/src/temporal/query.ts). - For low-level debugging, inspect the **worker container** directly with `docker compose logs` or access logs via `docker compose exec`. - The **Temporal Web UI** at `http://localhost:8233` provides a graphical interface for workflow history and task queue inspection. ## Frequently Asked Questions ### Where are Shannon workflow logs stored? Shannon stores workflow logs in `audit-logs//workflow.log` relative to the project root. The `WorkflowLogger` class in [`src/audit/workflow-logger.ts`](https://github.com/KeygraphHQ/shannon/blob/main/src/audit/workflow-logger.ts) generates this path via `generateWorkflowLogPath` and initializes the file during the first workflow activity. You can access these logs via the `./shannon logs` CLI command or directly through Docker. ### How do I check if a Shannon workflow is still running? Use the `./shannon query ID=` command to check execution status. This invokes the `getProgress` query implemented in [`src/temporal/query.ts`](https://github.com/KeygraphHQ/shannon/blob/main/src/temporal/query.ts), which returns a `PipelineProgress` object with a `status` field indicating `running`, `completed`, or `failed`. Alternatively, visit the Temporal Web UI at `http://localhost:8233` to view active workflow executions graphically. ### What information does the getProgress query return? The `getProgress` query returns a comprehensive `PipelineProgress` object containing: `status` (workflow state), `currentPhase` (active pentest phase), `currentAgent` (running AI agent), `completedAgents` (finished agents with timing), `failedAgent` and `error` (failure details), and `agentMetrics` (token usage, duration, cost). This data enables precise monitoring of AI-driven pentest progress without interrupting execution. ### Can I debug Shannon worker issues without the CLI wrapper? Yes, you can debug workers directly using Docker commands. Run `docker compose logs -f worker` to view the worker console output from [`src/temporal/worker.ts`](https://github.com/KeygraphHQ/shannon/blob/main/src/temporal/worker.ts), which captures Temporal connection events and bundling status. For log inspection, execute `docker compose exec -T worker tail -f ./audit-logs//workflow.log`. You can also attach to the worker container with `docker compose exec -T worker bash` for interactive debugging.