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

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

Open
#62 0 comments 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
Java
Stars
184
Forks
38
PR merge metrics
No merged PRs in 30d

Description

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

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.