Define asz.view 1.0, and carry on every round what a list of conversations shows
The document a viewer needs is now a format of its own, asz.view, version
1.0, defined and owned in pkg/sessionview: format and version first, the
conversation and its sessions, the head, a summary with a verification
state and the problems found, every round and every file with its digest
and its time range, the streams, the segments, every talk as a tree with
the text, usage, flags and dropped list its records carry, and the
relations. It is never a file. asz view builds it in memory once per fold
and serves it at /api/c/{id}/view, and a server that holds the same files
builds the same document. Verification is content: a gap in the chain or
a failed digest is written into the summary, never returned as an error.
A round's header now also carries the session's title and the fold's
counts of talks, steps, streams, segments and open references, and a
round's OTLP record copies them as asz.conversation.*, so a receiver
lists conversations off its newest round per conversation without
folding. Steps are counted as the document and the list page count them,
every node that is not structure, so the three agree.
The sender's defaults follow the receiver: the layer is AI_AGENT, spelled
as the OAP spells a layer; a request carries 8 MiB, under the 10 MiB the
OAP accepts over HTTP; and every record is stamped with a time inside the
session's range, a landed file with its last record time or the session's
latest, a round with the session's last activity, so a receiver can bound
a read by the range the head round carries.
Measured on the largest real conversation: the document is 19.8 MB, built
in 0.6 s; the push is 7 requests; every file rebuilt with its digest, and
every record stamped inside the session's range.
Conversation-level observability, measurement, and export for long-lived AI agents.
Status: pre-alpha. The conversation model and the Claude Code data mapping are defined and evidence-backed. Collection and assembly are implemented. The local page that serves the assembled conversations is in progress; static export and OTLP push are not started.
SkyWalking AI Sessionizer assembles fragmented agent telemetry into one durable conversation structure. It preserves sessions as source provenance, keeps parent and child-agent execution lineages separate, measures model-message continuity, and projects the same committed snapshot into storage, export and a local preview.
Agent runtimes record a single user-visible conversation as many unrelated artifacts — transcripts, traces, logs, provider request bodies, tool events, subagent metadata. That conversation can outlive one process, reactivate after a long idle period, and contain several concurrent agent lineages.
Trace-level inspection alone cannot answer: what did the whole conversation do; which input, model response, tool result or child-agent result led to the next model call; did that call preserve the previous message history or start a new context; which agents contributed; and what should be measured, stored and exported as one unit.
Conversation durable identity · ownership boundary └ Segment activity window · the COMMIT unit └ Session observed source provenance ├ ExecutionStream main ordered parent-agent lineage │ └ Context epoch × N model-context lifetime │ └ Talk × N one readable input → run → output │ └ Run → Step × N └ ExecutionStream child × N independent context per child agent
Two boundaries carry the design. Conversation is the durable aggregation and ownership boundary, and its identity is supplied — never inferred from a person, an account, or timestamp proximity. ExecutionStream is the ordered continuity boundary; model-message continuity is evaluated within one stream and one context epoch, never across them.
See the Unified Conversation Model.
Nothing is presented as observed unless it was observed.
Every claim carries a qualification (observed_replayable, observed_report_only, proposed, unavailable) and every correlation carries a resolution state (exact_unique, exact_ambiguous, strong_inference, unresolved, conflict). An exact identifier with several candidates stays ambiguous — the assembler never silently chooses one. Where a runtime cannot supply something, the adapter reports it as unavailable rather than approximating it.
| Runtime | Status | Collection |
|---|---|---|
| Claude Code | collection implemented | local files — no configuration required, and it works on history that already exists |
| Codex | planned | — |
| LangChain / LangGraph | planned | — |
Each release carries a binary package for macOS, Linux and Windows; see the quick start. Or build it:
make build # builds ./bin/asz ./bin/asz sources # list discovered sessions and their sources ./bin/asz collect -once # land everything currently on disk ./bin/asz view # serve the conversations at http://127.0.0.1:8787
Every command reads asz.yaml from the working directory when no -config flag is given. The file at the repository root is the default configuration with every value written out, so it can be read and edited without reading Go.
asz view serves what has been assembled. With the local Claude Code adapter it also runs the collector and the parser in the same process, once with -once or on the collector interval otherwise, and the list page shows when the data was last refreshed and when it will be next. On a storage root copied from another machine there is no local source, so it serves what is there.
Official documentation lives in docs/ and is indexed by docs/menu.yml: concepts and designs, setup, the data formats, adapters, guides and the changelog. It is published at skywalking.apache.org/docs/skywalking-ai-sessionizer.
design-notes/ holds working engineering notes — measurements, corrections and open questions produced while designing against real runtime data. They are deliberately unpolished and are not part of the published documentation.
Early contributions should focus on schemas, privacy-safe fixtures, deterministic assembly, qualification rules and golden tests. Please avoid adding inferred identities or causal edges that cannot retain their source evidence and resolution state.
Apache SkyWalking, SkyWalking, and the Apache feather logo are trademarks of The Apache Software Foundation.
CI publishes a Linux image for amd64 and arm64 to GHCR. It carries the asz binary only. Docker Desktop on Windows runs it as a Linux container; the Windows binary package is the path without Docker. Mount a storage root at /asz/data; by default the container serves the page on port 8787.
docker run --rm -p 8787:8787 -v "$PWD/data:/asz/data" \ ghcr.io/apache/skywalking-ai-sessionizer:latest
| Tag | Points at |
|---|---|
0.1.0 | that release, never moved |
0.1 | the newest patch of that line |
latest | the newest release |
main | the development head |
<commit id> | one commit, by its complete id, never moved |
A v* tag is a release candidate until the Apache vote passes and publishes nothing. Releasing it on GitHub, after the vote, publishes the version tags. Any asz command runs the same way: put it after the image name. See Container Image. make docker builds the image locally.