feat: built-in JSONL trace exporter via Hook (issue #942)

[park338]

What

Implements a built-in, out-of-the-box local JSONL trace exporter for AgentScope-Java based on the existing Hook event system (issue #942).

This makes it easy to dump a complete “LLM conversation + execution trace” to a local file for offline debugging / incident review / attaching to issues, without requiring Studio or custom hook code for every user.

Why

When troubleshooting Agent runs, users often need a simple, local, offline, file-based trace that includes:

• user input and final agent output
• every reasoning input/output (PreReasoning/PostReasoning)
• optional streaming chunks (ReasoningChunk / ActingChunk)
• optional tool events (PreActing/PostActing)
• basic metadata (timestamp, agent info, run/turn/step id)
• optional trace/span id if OpenTelemetry is enabled

Existing options (JsonSession/Memory/Studio) are useful but not a direct substitute for a lightweight, portable audit log.

Changes

• Added built-in exporter:

  • agentscope-core/src/main/java/io/agentscope/core/hook/recorder/JsonlTraceExporter.java
  • Writes one JSON object per hook event line (JSONL)
  • Default events: PRE_CALL, POST_CALL, PRE_REASONING, POST_REASONING, PRE_ACTING, POST_ACTING, ERROR
  • Optional: .includeReasoningChunks(true), .includeActingChunks(true), .includeSummary(true), .includeSummaryChunks(true)
  • Best-effort by default (does not break agent execution on IO/serialization errors), configurable failFast(true)
  • Uses Reactor boundedElastic to avoid blocking agent execution threads
  • Attempts to attach trace_id/span_id via reflection when OpenTelemetry is present (no hard dependency)

• Added tests:

  • agentscope-core/src/test/java/io/agentscope/core/hook/recorder/JsonlTraceExporterTest.java

• Updated example to demonstrate usage:

  • agentscope-examples/quickstart/src/main/java/io/agentscope/examples/quickstart/HookExample.java
  • Adds exporter hook and uses try-with-resources to ensure flush/close

• Updated docs:

  • docs/en/task/hook.md
  • docs/zh/task/hook.md

Output Format (JSONL)

Each line contains common fields like:

• ts, event_type, agent_id, agent_name
• run_id, turn_id, step_id
• optional trace_id, span_id

And event-specific payloads, e.g.:

• input_messages (PreCall/PreReasoning/PreSummary)
• reasoning_message (PostReasoning)
• final_message (PostCall)
• tool_use / tool_result (Acting events)
• incremental_chunk / accumulated (chunk events)
• error_class / error_message / stacktrace (ErrorEvent)

How To Use

import io.agentscope.core.hook.recorder.JsonlTraceExporter;
import java.nio.file.Path;

try (JsonlTraceExporter exporter =
        JsonlTraceExporter.builder(Path.of("logs", "agentscope-trace.jsonl"))
                .includeReasoningChunks(true)
                .includeActingChunks(true)
                .build()) {
    ReActAgent agent = ReActAgent.builder()
            .name("Assistant")
            .model(model)
            .toolkit(toolkit)
            .hooks(List.of(exporter))
            .build();
}

[cla-assistant]

All committers have signed the CLA.

[codecov]

Codecov Report

❌ Patch coverage is 81.34921% with 47 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...ntscope/core/hook/recorder/JsonlTraceExporter.java	81.34%	35 Missing and 12 partials ⚠️

📢 Thoughts on this report? Let us know!

[LearningGp]

Allocating a boundedElastic task for each event, along with global synchronized writes to the same file, is likely to cause performance bottlenecks under high QPS. Given it's meant for "local debugging", the design is reasonable, but I'd recommend adding a note to clarify its applicable scenarios.

[Copilot]

Pull request overview

Adds a built-in JSONL trace exporter hook to AgentScope-Java so users can persist an end-to-end local execution trace (LLM conversation + reasoning/acting events, optionally chunks and summaries) for offline debugging and incident review.

Changes:

• Introduces JsonlTraceExporter (Hook + builder) that writes one JSON record per hook event line (JSONL), with optional chunk/summary inclusion and best-effort vs fail-fast behavior.
• Adds unit tests for JSONL output, filtering, fail-fast behavior, and OpenTelemetry ID export branch coverage.
• Updates quickstart example and hook documentation (EN/ZH) to demonstrate usage; adjusts CI workflow to install mvnd if missing.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
agentscope-core/src/main/java/io/agentscope/core/hook/recorder/JsonlTraceExporter.java	New built-in JSONL exporter hook implementation and builder configuration.
agentscope-core/src/test/java/io/agentscope/core/hook/recorder/JsonlTraceExporterTest.java	New tests covering JSONL records, filtering, run IDs, fail-fast, and OTel IDs.
agentscope-core/src/test/java/io/opentelemetry/api/trace/Span.java	Test stub to simulate OpenTelemetry presence for reflection-based ID export.
agentscope-core/src/test/java/io/opentelemetry/api/trace/SpanContext.java	Companion OTel test stub for span/trace IDs.
agentscope-examples/quickstart/src/main/java/io/agentscope/examples/quickstart/HookExample.java	Demonstrates adding the JSONL exporter hook and closing it via try-with-resources.
docs/en/task/hook.md	Documents the built-in JSONL exporter and basic usage snippet.
docs/zh/task/hook.md	Adds a section for the JSONL exporter (currently in English).
.github/workflows/maven-ci.yml	Ensures mvnd is installed during Linux CI build if not present.