Input Formats
An analysis needs execution traces. You can pass a local export or retrieve traces through a connector. Workflow context is optional and helps explain intended routing, retries, and fallback behavior.
Full trace files and connector exports stay on your machine. The CLI normalizes and queries them locally, sharing representative samples, a schema/profile, metadata, and bounded evidence with the service. You control sample field redaction and outbound evidence columns. Optional workflow files are sent in full. See Privacy & Data Handling.
Trace files
| Format | Extension | Layout |
|---|---|---|
| JSON | .json | A JSON document, such as one execution or a collection containing nested steps. |
| JSON Lines | .jsonl | One JSON record per nonempty line. Each record may contain nested steps. |
| CSV | .csv | Header row followed by records. Export useful step and run identifiers as columns. |
| Parquet | .parquet | Records with named columns, including nested fields when present. |
Jejoo profiles the export and asks the service for a normalization specification. It applies that specification locally to produce canonical execution facts. Your export does not need to use a fixed Jejoo trace schema. Clear identifiers and complete metrics make normalization and analysis more useful.
What to include
| Information | Why it helps |
|---|---|
| Run/trace ID and step/span ID | Separate executions and identify individual operations. |
| Parent ID, operation name, and operation type | Reconstruct execution structure and group comparable work. |
| Start/end timestamps or latency with units | Identify slow operations and compare execution durations. |
| Success/error status and retry/attempt information | Investigate failures and retry amplification. |
| Model/provider and token usage | Attribute model consumption, including cache and reasoning usage when recorded. |
| Observed cost with currency/units | Measure cost; missing cost is not evidence of zero cost. |
| Tool name, arguments, and result identifiers | Recognize repeated work and investigate behavior. |
| Input/output, finish reasons, and configured output limits | Investigate context consumption and output-budget failures when available. |
Export what your tracing system records. Missing information limits the conclusions the analysis can support. Do not invent values to fill gaps. Use timestamps with explicit time zones, consistent units, and completed executions where possible.
Example record
This is an example layout, not a required schema. Download the complete sample-traces.jsonl.
{
"id": "trace_demo_001",
"run_id": "run_demo_001",
"status": "succeeded",
"started_at": "2026-11-01T12:00:00Z",
"ended_at": "2026-11-01T12:00:04Z",
"steps": [
{
"id": "search_001",
"name": "search_documents",
"type": "tool",
"tool_name": "search_documents",
"started_at": "2026-11-01T12:00:00Z",
"ended_at": "2026-11-01T12:00:01Z",
"latency_ms": 1000,
"input": {"query": "agent retry strategies"},
"output": {"document_ids": ["doc-1"]}
}
]
}
Connected trace sources
Connectors fetch selected execution trees to your machine before the usual normalization and evidence flow. Provider credentials authenticate separately from Jejoo credentials. Do not combine a positional file path with a connector source.
LangSmith
python -m pip install 'jejoo-cli[langsmith]'
Set LANGSMITH_API_KEY in your private shell environment. Set LANGSMITH_ENDPOINT for a regional or self-hosted deployment when needed.
jejoo analyze \
--source langsmith \
--source-project research-agent \
--since 7d \
--max-traces 20 \
--api-base-url https://app.scaillabs.ai \
--output-dir .jejoo/langsmith-analysis
--source-project is required. The connector writes langsmith-runs.jsonl locally.
Langfuse
python -m pip install 'jejoo-cli[langfuse]'
Set LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, and LANGFUSE_BASE_URL in your private environment. Use the base URL for your region or deployment.
jejoo analyze \
--source langfuse \
--since 7d \
--max-traces 20 \
--api-base-url https://app.scaillabs.ai \
--output-dir .jejoo/langfuse-analysis
Credentials select the project; --source-project optionally verifies its name. The connector writes langfuse-observations.jsonl locally.
Both connectors save source-selection.json with resolved filters, IDs, counts, and the export hash. Time bounds apply to root start times. Retrieval caps follow provider result order; they are not representative sampling. A byte-limit failure stops the export rather than truncating execution trees. Use a fresh output directory for a new selection. See selection flags.
Optional workflow files
Repeat --workflow for the entry point and helpers that implement relevant behavior:
--workflow agent.py --workflow tools.py
The default --workflow-normalization llm accepts UTF-8 text, including Python, TypeScript, JSON, YAML, and Markdown. You may supply up to 10 files totaling 200,000 bytes. Files are read as text and never executed. Binary files and archives are unsupported.
Full workflow contents and relative filenames are sent to the service and its models. Trace sample redaction flags do not apply to these files. Remove secrets and unrelated private content first.
Without workflow files, Jejoo derives an observed workflow from local facts. Observed order does not prove causal control flow. Declared-route checks are disabled, and trace-only analysis currently supports at most 100 distinct observed operations.
Canonical workflow JSON
Use --workflow-normalization canonical only for a single JSON file matching DeclaredWorkflow. Arbitrary workflow JSON should use the default llm mode.
Download sample-workflow.json. Its required top-level fields are workflow_id, version, and project_id. Each node needs id, name, and type; each edge needs id, source_node_id, and target_node_id. IDs referenced by edges and entry/exit lists must exist in nodes, and node IDs must be unique.
jejoo analyze sample-traces.jsonl \
--workflow sample-workflow.json \
--workflow-normalization canonical \
--mapping sample-mapping.json \
--api-base-url https://app.scaillabs.ai \
--output-dir .jejoo/with-workflow
Download sample-mapping.json too. It maps exported operation names to declared node IDs. --mapping requires --workflow. An authenticated analysis needs a matching workflow project_id; anonymous use replaces the sample project ID with the installation's project ID.