1. Home
2. Run Agents
3. Observability

Agent activity logging¶

Agent Development Kit (ADK) provides flexible and powerful logging capabilities to monitor agent behavior and debug issues effectively.

Logging philosophy¶

ADK's approach to logging is to provide detailed diagnostic information without being overly verbose by default. It is designed to be configured by the application developer, allowing you to tailor the log output to your specific needs, whether in a development or production environment.

• Standard Library Integration: ADK uses the standard logging facilities of the host language (e.g., Python's logging module, Go's log package).
• Structured GenAI Logging: ADK uses OpenTelemetry to log structured events for GenAI requests and responses, allowing for advanced monitoring and debugging in cloud environments.
• User-Configured: While ADK provides defaults and integration with its CLI tools, it is ultimately the responsibility of the application developer to configure logging to suit their specific environment.

Logging schema¶

ADK emits logs using standard library facilities and structured GenAI events via OpenTelemetry.

Structured GenAI logs¶

Structured GenAI logs emitted via OpenTelemetry follow the Semantic Conventions for GenAI.

By default prompt content is elided in logs for security. You can enable prompt logging using environment variables or programmatic configuration. See Capture prompt content for adk web, and Capture prompt content programmatically for setup in code.

Log levels (Python)¶

The following table describes what is logged at different levels in Python when using the standard logger:

Logging in ADK Web¶

When running agents using the ADK's adk web, adk api_server, adk deploy cloud_run and adk deploy gke commands, you can control the log verbosity or destination.

Logging level in ADK Web¶

To start the web server with DEBUG level logging, run:

adk web --log_level DEBUG path/to/your/agents_dir

The available log levels for the --log_level option are: DEBUG, INFO (default), WARNING, ERROR, CRITICAL.

Capture prompt content in ADK Web¶

By default a prompt content is elided in logs for security. You can enable prompt logging using the environment variable:

export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true

The available values for this variable are: NO_CONTENT, EVENT_ONLY, SPAN_ONLY, and SPAN_AND_EVENT. A boolean true or 1 means EVENT_ONLY, which records content on the emitted log events; any value outside these four falls back to NO_CONTENT. To record content on the inference span, SPAN_ONLY and SPAN_AND_EVENT also require OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental.

OTLP export in ADK Web¶

To export logs to an OTLP-compatible backend, set the standard OTel environment variables:

export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT="http://your-collector:4318/v1/logs"
adk web path/to/your/agents_dir

GCP export setup in ADK Web¶

You can enable GCP export using the --otel_to_cloud flag:

adk web --otel_to_cloud path/to/your/agents_dir

Programmatic setup¶

Programmatic setup configures the underlying logging framework and OpenTelemetry exporters from your own code, for system-level diagnostics and production observability. ADK uses the following logging facilities:

• Python: ADK uses the standard logging module and OpenTelemetry for structured GenAI logs.
• Go: ADK uses the google.golang.org/adk/v2/telemetry package for OpenTelemetry configuration, and the standard log package for general events, which it writes to stderr by default.
• Kotlin: ADK uses standard JVM logging facilities, defaulting to Flogger, and OpenTelemetry for structured GenAI logs.

Logging level¶

You can set the logging level for your ADK agent using standard logging controls, as follows:

import logging

logging.basicConfig(
    level=logging.DEBUG,
    format='%(asctime)s - %(levelname)s - %(name)s - %(message)s'
)

Capture prompt content¶

import os

os.environ["OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT"] = "true"

from google.adk.agents.run_config import RunConfig
from google.adk.telemetry import ContentCapturingMode, TelemetryConfig

run_config = RunConfig(
    telemetry=TelemetryConfig(
        capture_message_content=ContentCapturingMode.SPAN_AND_EVENT,
    ),
)

package main

import (
    "context"
    "os"

    "google.golang.org/adk/v2/telemetry"
)

func main() {
    ctx := context.Background()

    // Enable GenAI message content capture via the OpenTelemetry environment variable
    os.Setenv("OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT", "true")

    tp, err := telemetry.New(ctx)
    if err != nil {
        // handle error
    }
    defer tp.Shutdown(ctx)
    tp.SetGlobalOtelProviders()
}

// Enable full prompt and response logging
TelemetryConfig.captureMessageContent = true

OTLP export¶

from google.adk.telemetry.setup import maybe_set_otel_providers
import os

os.environ["OTEL_EXPORTER_OTLP_LOGS_ENDPOINT"] = "http://your-collector:4318/v1/logs"
os.environ["OTEL_SERVICE_NAME"] = "your-adk-agent"
os.environ["OTEL_RESOURCE_ATTRIBUTES"] = "key1=value1,key2=value2"
maybe_set_otel_providers()

GCP export setup¶

from google.adk.telemetry.google_cloud import get_gcp_exporters
from google.adk.telemetry.setup import maybe_set_otel_providers
import os

gcp_exporters = get_gcp_exporters(
  enable_cloud_logging = True,
)
os.environ["OTEL_SERVICE_NAME"] = "your-adk-agent"
os.environ["OTEL_RESOURCE_ATTRIBUTES"] = "key1=value1,key2=value2"
maybe_set_otel_providers([gcp_exporters])

package main

import (
    "context"
    "google.golang.org/adk/v2/telemetry"
)

func main() {
    ctx := context.Background()
    tp, err := telemetry.New(ctx,
        telemetry.WithOtelToCloud(true),
    )
    if err != nil {
        // handle error
    }
    defer tp.Shutdown(ctx)
    tp.SetGlobalOtelProviders()
}

go run main.go web -otel_to_cloud

Activity logging with plugins¶

ADK provides built-in plugins that capture agent activity, including user messages, model requests and responses, tool calls, and (with DebugLoggingPlugin) session state. These plugins require no changes to your agent logic.

Console logging with LoggingPlugin¶

To print structured activity logs to the console during execution, attach LoggingPlugin to your App:

from google.adk.apps import App
from google.adk.plugins import LoggingPlugin

app = App(
    name="my_app",
    root_agent=root_agent,
    plugins=[LoggingPlugin()],
)

package main

import (
    "context"
    "log"
    "os"

    "google.golang.org/adk/v2/agent"
    "google.golang.org/adk/v2/cmd/launcher"
    "google.golang.org/adk/v2/cmd/launcher/full"
    "google.golang.org/adk/v2/plugin"
    "google.golang.org/adk/v2/plugin/loggingplugin"
    "google.golang.org/adk/v2/runner"
)

func main() {
    ctx := context.Background()
    logPlugin := loggingplugin.MustNew("logging_plugin")

    config := &launcher.Config{
        AgentLoader: agent.NewSingleLoader(rootAgent),
        PluginConfig: runner.PluginConfig{
            Plugins: []*plugin.Plugin{logPlugin},
        },
    }

    l := full.NewLauncher()
    if err := l.Execute(ctx, config, os.Args[1:]); err != nil {
        log.Fatalf("run failed: %v", err)
    }
}

// Use the LoggingPlugin for structured activity logging to the console
val runner =
    InMemoryRunner(
        App(appName = agent.name, rootAgent = agent, plugins = listOf(LoggingPlugin())),
    )

Full debug capture to a file with DebugLoggingPlugin¶

To record complete interaction data as human-readable YAML appended to adk_debug.yaml rather than truncated console output, use DebugLoggingPlugin:

from google.adk.apps import App
from google.adk.plugins import DebugLoggingPlugin

app = App(
    name="my_app",
    root_agent=root_agent,
    plugins=[
        DebugLoggingPlugin(
            output_path="adk_debug.yaml",
            include_session_state=True,
            include_system_instruction=True,
        ),
    ],
)

// includeSystemInstruction = false logs has_system_instruction, not the instruction text
val debugPlugin = DebugLoggingPlugin(includeSystemInstruction = false)
val debugRunner =
    InMemoryRunner(
        App(appName = agent.name, rootAgent = agent, plugins = listOf(debugPlugin)),
    )

Understanding log output¶

Sample Python log entry¶

2025-07-08 11:22:33,456 - DEBUG - google_adk.google.adk.models.google_llm - LLM Request: contents { ... }

By reading the logger name, you can immediately pinpoint the source of the log and understand its context within the agent's architecture. ADK loggers are named google_adk. followed by the module's fully-qualified name, so every ADK logger is a child of the google_adk logger. Configure them as a group with logging.getLogger("google_adk").

Debugging example¶

After enabling DEBUG logging (see Logging level above), run your agent and look for messages from the google_adk.google.adk.models.google_llm logger. The output shows the full LLM request and response:

2025-07-10 15:26:13,778 - DEBUG - google_adk.google.adk.models.google_llm -
LLM Request:
-----------------------------------------------------------
System Instruction:
      You roll dice and answer questions about the outcome of the dice rolls.
      ...
-----------------------------------------------------------
Contents:
{"parts":[{"text":"Roll a 6 sided dice"}],"role":"user"}
{"parts":[{"function_call":{"args":{"sides":6},"name":"roll_die"}}],"role":"model"}
{"parts":[{"function_response":{"name":"roll_die","response":{"result":2}}}],"role":"user"}
-----------------------------------------------------------
Functions:
roll_die: {'sides': {'type': <Type.INTEGER: 'INTEGER'>}}
check_prime: {'nums': {'items': {'type': <Type.INTEGER: 'INTEGER'>}, 'type': <Type.ARRAY: 'ARRAY'>}}
-----------------------------------------------------------
2025-07-10 15:26:14,309 - INFO - google_adk.google.adk.models.google_llm -
LLM Response:
-----------------------------------------------------------
Text:
I have rolled a 6 sided die, and the result is 2.
...

From this output you can verify:

• Is the system instruction correct?
• Is the conversation history (user and model turns) accurate?
• Are the correct tools being provided to the model?
• Are the tools correctly called by the model?
• How long it takes for the model to respond?