# How to Debug Agent Execution with Embabel's Logging Profiles > Debug agent execution in Embabel with logging profiles like thinking or streaming test. Activate TRACE-level diagnostics for LLM clients and tool-loop engines using @EnableAgents annotation. - Repository: [Embabel/embabel-agent](https://github.com/embabel/embabel-agent) - Tags: how-to-guide - Published: 2026-08-08 --- **Activate Spring Boot logging profiles such as `thinking` or `streaming-test` via the `@EnableAgents` annotation to capture TRACE-level diagnostics from Embabel's LLM clients, tool-loop engines, and streaming components.** Debugging agent execution in the `embabel/embabel-agent` framework requires deep visibility into the LLM integration layer, asynchronous tool loops, and response streaming pipelines. By leveraging Embabel's built-in logging profiles, you can dynamically adjust logger levels for specific internal packages without modifying XML configuration files. This guide demonstrates how to enable these profiles and interpret their colour-coded output to diagnose agent behavior effectively. ## Understanding Embabel's Built-In Logging Profiles Embabel Agent ships with predefined Spring Boot profiles that target specific subsystems. When activated, these profiles elevate logger levels from INFO to DEBUG or TRACE for targeted packages, exposing the internal state of agent operations. | Profile | Purpose | Target Packages | |---------|---------|----------------| | `thinking` | Verbose logging of LLM calls and tool-loop iterations | `com.embabel.agent.spi.support.springai.ChatClientLlmOperations` (TRACE)
`com.embabel.common.core.thinking` (DEBUG) | | `streaming-test` | Detailed tracing of the streaming pipeline | `com.embabel.agent.spi.support.streaming.StreamingLlmOperationsImpl` (TRACE) | | `cost-tracking-it` | Diagnostics for cost-tracking calculations | `com.embabel.agent.cost` (DEBUG) | | `starwars` | Demonstration profile for custom activation patterns | (No specific loggers; validates profile mechanism) | These profiles are processed by the framework's configuration layer to inject the appropriate `logging.level` properties into the Spring Environment at runtime. ## How Logging Profiles Work in the Embabel Agent Framework The logging profile system relies on three core components that orchestrate profile detection and output formatting. **EnableAgents Annotation** The `@EnableAgents` annotation, located in [`embabel-agent-autoconfigure/embabel-agent-platform-autoconfigure/src/main/java/com/embabel/agent/config/annotation/EnableAgents.java`](https://github.com/embabel/embabel-agent/blob/main/embabel-agent-autoconfigure/embabel-agent-platform-autoconfigure/src/main/java/com/embabel/agent/config/annotation/EnableAgents.java), serves as the entry point. When applied to a Spring Boot application class, it signals the framework to scan for active profiles and apply Embabel-specific logging configurations. **EnvironmentPostProcessor** The `EnvironmentPostProcessor` class in [`embabel-agent-autoconfigure/embabel-agent-platform-autoconfigure/src/main/java/com/embabel/agent/config/annotation/spi/EnvironmentPostProcessor.java`](https://github.com/embabel/embabel-agent/blob/main/embabel-agent-autoconfigure/embabel-agent-platform-autoconfigure/src/main/java/com/embabel/agent/config/annotation/spi/EnvironmentPostProcessor.java) reads the active Spring profiles and programmatically injects logger level mappings. This ensures that when `thinking` is active, the corresponding packages receive TRACE-level logging before the application context fully initializes. **LoggingPersonality and ColorPalette** To make debug output readable, Embabel provides a custom logging personality. The `LoggingPersonality` class in [`embabel-agent-autoconfigure/embabel-agent-shell-autoconfigure/src/main/java/com/embabel/agent/spi/logging/LoggingPersonality.java`](https://github.com/embabel/embabel-agent/blob/main/embabel-agent-autoconfigure/embabel-agent-shell-autoconfigure/src/main/java/com/embabel/agent/spi/logging/LoggingPersonality.java) defines the console formatting rules, while `ColorPalette` in [`embabel-agent-autoconfigure/embabel-agent-shell-autoconfigure/src/main/java/com/embabel/agent/spi/logging/ColorPalette.java`](https://github.com/embabel/embabel-agent/blob/main/embabel-agent-autoconfigure/embabel-agent-shell-autoconfigure/src/main/java/com/embabel/agent/spi/logging/ColorPalette.java) supplies ANSI colour codes. TRACE messages appear in bright cyan, DEBUG in green, and ERROR in red, making it easy to visually distinguish log severity during agent execution. ## Enabling Logging Profiles in Your Application Follow these steps to activate diagnostic logging for your agent. 1. **Add the `@EnableAgents` annotation** to your main application class or configuration: ```java @SpringBootApplication @EnableAgents public class MyAgentApplication { public static void main(String[] args) { SpringApplication.run(MyAgentApplication.class, args); } } ``` 2. **Activate the desired profile** using one of three standard Spring Boot mechanisms: *Via [`application.yml`](https://github.com/embabel/embabel-agent/blob/main/application.yml):* ```yaml spring: profiles: active: thinking ``` *Via command-line argument:* ```bash java -jar my-agent.jar --spring.profiles.active=thinking ``` *Programmatically before startup:* ```java public static void main(String[] args) { System.setProperty("spring.profiles.active", "streaming-test"); SpringApplication.run(MyAgentApplication.class, args); } ``` 3. **Execute your agent**. The console output will now include colour-coded TRACE and DEBUG statements from the targeted subsystems. ## Debugging Streaming and Tool Loop Execution When diagnosing complex interactions like streaming LLM responses or parallel tool loops, the `streaming-test` and `thinking` profiles provide granular insight. Consider a streaming implementation where you need to verify chunk processing: ```java @SpringBootApplication @EnableAgents public class StreamingDebugApplication { public static void main(String[] args) { System.setProperty("spring.profiles.active", "streaming-test"); ConfigurableApplicationContext ctx = SpringApplication.run(StreamingDebugApplication.class, args); // Your agent execution logic here } } ``` With this configuration, the console displays output similar to: ```text [2026-08-08 12:34:56.789] TRACE com.embabel.agent.spi.support.streaming.StreamingLlmOperationsImpl - Sending chunk #1 to stream processor [2026-08-08 12:34:56.791] DEBUG com.embabel.agent.spi.support.springai.ChatClientLlmOperations - LLM response metadata received ``` The bright cyan TRACE lines indicate low-level streaming operations, while green DEBUG lines show higher-level LLM client interactions. ## Reference Implementation in the Test Suite The `embabel/embabel-agent` repository validates these logging profiles through integration tests that verify correct logger level assignment. **ParallelToolLoopGuardRailIT** Located in [`embabel-agent-autoconfigure/models/embabel-agent-openai-autoconfigure/src/test/java/com/embabel/agent/config/models/openai/ParallelToolLoopGuardRailIT.java`](https://github.com/embabel/embabel-agent/blob/main/embabel-agent-autoconfigure/models/embabel-agent-openai-autoconfigure/src/test/java/com/embabel/agent/config/models/openai/ParallelToolLoopGuardRailIT.java), this test activates the `thinking` profile to ensure the tool-loop guardrails emit TRACE-level diagnostics during parallel execution scenarios. **LLMOpenAiStreamingBuilderIT** Found in [`embabel-agent-autoconfigure/models/embabel-agent-openai-autoconfigure/src/test/java/com/embabel/agent/config/models/openai/LLMOpenAiStreamingBuilderIT.java`](https://github.com/embabel/embabel-agent/blob/main/embabel-agent-autoconfigure/models/embabel-agent-openai-autoconfigure/src/test/java/com/embabel/agent/config/models/openai/LLMOpenAiStreamingBuilderIT.java), this class uses `@ActiveProfiles("streaming-test")` to validate that the streaming pipeline produces the expected verbose output when processing OpenAI streaming responses. **LLMOllamaThinkingIT** In [`embabel-agent-autoconfigure/models/embabel-agent-ollama-autoconfigure/src/test/java/com/embabel/agent/config/models/ollama/LLMOllamaThinkingIT.java`](https://github.com/embabel/embabel-agent/blob/main/embabel-agent-autoconfigure/models/embabel-agent-ollama-autoconfigure/src/test/java/com/embabel/agent/config/models/ollama/LLMOllamaThinkingIT.java), this test demonstrates profile usage with the Ollama backend, confirming that the `thinking` profile correctly elevates logging for local LLM interactions. ## Summary - Embabel Agent provides built-in Spring Boot logging profiles (`thinking`, `streaming-test`, `cost-tracking-it`) that expose TRACE and DEBUG output for specific agent subsystems. - The `@EnableAgents` annotation triggers the `EnvironmentPostProcessor` to inject logger configurations based on active profiles. - Colour-coded output is handled by `LoggingPersonality` and `ColorPalette`, making it easy to visually scan logs. - Activate profiles via [`application.yml`](https://github.com/embabel/embabel-agent/blob/main/application.yml), command-line arguments, or system properties to debug LLM calls, tool loops, and streaming without code changes. - Integration tests like `ParallelToolLoopGuardRailIT` demonstrate production-ready usage of these diagnostic profiles. ## Frequently Asked Questions ### How do I enable multiple logging profiles simultaneously? You can activate multiple profiles by comma-separating them in your configuration. Set `spring.profiles.active=thinking,streaming-test` in your [`application.yml`](https://github.com/embabel/embabel-agent/blob/main/application.yml) or as a command-line argument. The `EnvironmentPostProcessor` will process each profile and apply the union of their logger level configurations, giving you comprehensive visibility into both the tool loop and streaming subsystems simultaneously. ### Will enabling these profiles affect application performance? Yes, TRACE-level logging generates significant I/O overhead because it captures low-level details like individual streaming chunks and LLM request payloads. According to the source implementation in [`EnableAgents.java`](https://github.com/embabel/embabel-agent/blob/main/EnableAgents.java), these profiles are intended for debugging and testing environments only. Always deactivate verbose profiles (`thinking`, `streaming-test`) in production deployments to maintain optimal throughput. ### Where can I customize the colour scheme for log output? The colour definitions reside in [`embabel-agent-autoconfigure/embabel-agent-shell-autoconfigure/src/main/java/com/embabel/agent/spi/logging/ColorPalette.java`](https://github.com/embabel/embabel-agent/blob/main/embabel-agent-autoconfigure/embabel-agent-shell-autoconfigure/src/main/java/com/embabel/agent/spi/logging/ColorPalette.java). This class defines ANSI colour codes as constants that `LoggingPersonality` references when formatting console output. To implement a custom palette, extend `LoggingPersonality` and override the formatting methods, or modify the `ColorPalette` constants before the application context initializes. ### Do I need `@EnableAgents` if I'm only using the cost-tracking profile? Yes, the `@EnableAgents` annotation is required regardless of which specific profile you activate. As implemented in [`EnableAgents.java`](https://github.com/embabel/embabel-agent/blob/main/EnableAgents.java), this annotation registers the `EnvironmentPostProcessor` that actually parses the active profiles and injects the corresponding `logging.level` properties into the Spring Environment. Without this annotation, setting `spring.profiles.active=cost-tracking-it` will have no effect on the Embabel agent loggers.