[Feature Request] Add Observability Support (Tracing & Logging) in Java Runtime

[xuehuitian45]

Description

The Python version of AgentScope Runtime provides a comprehensive observability module that supports:

• Event tracing with multiple trace types (LLM, TOOL, AGENT_STEP, RAG, etc.)
• Decorator-based automatic tracing (@trace)
• Context manager–based manual tracing with fine-grained control
• Pluggable handlers (e.g., local logging, future support for Langfuse)
• Automatic error capture and structured logging

This greatly aids debugging, monitoring, and performance analysis in complex agent workflows.

However, the Java runtime currently lacks equivalent observability capabilities. To ensure feature parity and production readiness, we propose adding a similar tracing/logging framework to the Java implementation.

Proposed Features

1. Trace Types Enum: Define standard event types (e.g., LLM_CALL, TOOL_EXECUTION, AGENT_STEP).
2. Annotation-Based Tracing: Similar to Python’s @trace, e.g., @Traced(TraceType.AGENT_STEP).
3. Manual Tracing API: A context-aware tracer (e.g., try (var span = tracer.startEvent(...)) { ... }) supporting:
   • Custom payload logging
   • Nested events
   • Automatic error capture
4. Pluggable Handlers: Support for console logging, file output, and future integrations (OpenTelemetry, Langfuse, etc.).
5. Async/Await Compatibility: Ensure compatibility with Java’s async patterns (e.g., CompletableFuture).

Benefits

• Enables debugging complex agent chains
• Supports performance profiling
• Facilitates integration with observability platforms (e.g., Grafana, Datadog)
• Improves developer experience and system transparency

Additional Notes

The design should align with Java best practices (e.g., using SLF4J or OpenTelemetry standards where possible) while maintaining conceptual consistency with the Python implementation for cross-language coherence.