agentscope-ai / agentscope-ai/agentscope-runtime-java

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

未关闭
#62 0 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看
enhancement
主要语言
Java
星标
184
派生
38
PR 合并指标
30 天内没有已合并 PR

描述

### 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.

贡献指南

打开贡献指南

评估

这个 Issue 还没有评估数据。

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。