Enabling Debug Mode

Learn how to enable debug logging in ADK for troubleshooting.

Debug logging in ADK

When you develop or troubleshoot an application that's built with ADK, to get more detailed information about what's happening behind the scenes, you can enable the debug logging mode. You can enable this mode in ADK through an environment variable.

Enabling the debug mode

To enable debug logging in ADK, set the ADK_LOG_LEVEL environment variable to DEBUG:

export ADK_LOG_LEVEL=DEBUG

On Windows, you can set this environment variable using the set command:

set ADK_LOG_LEVEL=DEBUG

After setting this environment variable, run your ADK application as usual, and you'll see a more detailed log in the output.

The debug mode information

When the debug mode is enabled, you'll get the following information:

• Resource OCIDs: Unique identifiers for the OCI resources that are being used
• OPC Request IDs: Request identifiers to reference when working with Oracle support
• API Request/Response Details: Details about communication with OCI services
• Internal Operation Logs: Information about how the ADK is processing your requests
• Tool Execution Traces: Detailed logs about tool invocations and their results

---

Tip: If you encounter an issue, save its debug logs. These logs are helpful when reporting problems to the OCI Generative AI Agents service team or Oracle Support.

---

Example output

Here's an example output after running an ADK application, with the debug logging mode enabled:

[05/08/25 15:19:35]  DEBUG    Invoking chat endpoint with data: {
                                "performed_actions": [
                                  {
                                    "action_id": "<example-action-id>",
                                    "function_call_output": "{\"message\": {\"role\": \"AGENT\", \"content\":
                              {\"text\": \"Your most recent order, order_222222, has been refunded.\",
                              \"citations\": null, \"paragraph_citations\": null}, \"time_created\":
                              \"2025-05-08T22:19:33.669000+00:00\"}, \"traces\": [{\"time_created\":
                              \"2025-05-08T22:19:33.233000+00:00\", \"trace_type\": \"UNKNOWN_ENUM_VALUE\"}],
                              \"tool_results\": null, \"required_actions\": null, \"guardrail_result\": null}",
                                    "performed_action_type": "FUNCTION_CALLING_PERFORMED_ACTION"
                                  }
                                ],
                                "session_id":
                              "ocid1.genaiagentsession.oc1.ap-osaka-1.xxx",
                                "should_stream": false,
                                "tool_parameters": null,
                                "user_message": "null"
                              }
[05/08/25 15:19:36]  DEBUG    Chat succeeded response: {
                                "guardrail_result": null,
                                "message": {
                                  "content": {
                                    "citations": null,
                                    "paragraph_citations": null,
                                    "text": "Your most recent order, order_222222, has been refunded."
                                  },
                                  "role": "AGENT",
                                  "time_created": "2025-05-08T22:19:36.460000+00:00"
                                },
                                "required_actions": null,
                                "tool_results": null,
                                "traces": [
                                  {
                                    "time_created": "2025-05-08T22:19:36.048000+00:00",
                                    "trace_type": "UNKNOWN_ENUM_VALUE"
                                  }
                                ]
                              }
                     DEBUG    Chat succeeded opc-request-id:
                              5DF2A7C7E07F4DBDAE43373AADB51D22/4F09D0E8DAB0C8B3F72D1D684B4958C3/114ADCF1B6EBA536C
                              3A727BE80B570C1

When to use the debug mode

Enable debug mode when:

1. Troubleshooting unexpected behaviors or errors
2. Working with Oracle Support on an issue
3. Understanding the flow of your agent's execution
4. Developing new agent features and wanting to see the detailed interactions

---

Note: Remember to disable the debug mode in production environments by unsetting this environment variable, because this mode generates verbose logs that could impact the performance.

unset ADK_LOG_LEVEL

---

Integrating with Logging Frameworks

ADK uses Python's standard logging module. If your application uses a custom logging configuration, you can also control the ADK log level programmatically:

import logging
logging.getLogger('adk').setLevel(logging.DEBUG)

This method gives you a more fine-grained control over logging in complex applications.