DEV Reports — Reading a Report and Using It

A DEV report is a record of one operation, written step by step while the operation runs: one file upload, one chat answer, one community rebuild or one pipeline run. It shows what the system did, why it did it, and which setting decided it. Use it when an answer is wrong, a file cannot be found, or an upload is slow, and you want to know the reason instead of guessing.

This page explains how to switch reports on, how to read one, and how to use it to find a problem. Where the DEV Reports tab sits, and which switches it has, is also described on the pages of each resource:

1. What you can report

The DEV Reports tab is on the detail page of a Topic, a GraphRAG Topic and an Agent. The Topic or Agent must be running.

Resource Switch One report per The list shows it as

RAG Topic

Report uploads

File upload

Ingestion

RAG Topic

Report chat answers

Chat question

Retrieval/chat

GraphRAG Topic

Report uploads

File upload

Ingestion

GraphRAG Topic

Report chat answers

Chat question

Retrieval/chat

GraphRAG Topic

Report community rebuilds

Community rebuild (scheduled, or Recompute Communities Now)

Community recompute

Agent

Report pipeline runs

Pipeline run, whatever started it

Pipeline run

A switch is greyed out when the resource cannot write reports. The tab says why: for example the storage place inside the container is not writable, or this kind of report is not supported by the software version. The community switch is hidden when the GraphRAG software does not know it.

You need the permission Use DEV Reporting (DEV_REPORTING). It is not part of the default USER role, because reports hold full prompts and document text. See Roles & Permissions.

2. Your first report

  1. Open the resource and the DEV Reports tab.

  2. Switch on the kind of report you need.

  3. Do the thing you want to look at: upload the file, ask the question, or click Recompute Communities Now.

  4. Click Refresh. A new row appears.

  5. Click the eye icon to read the report on the page. Use report.md to download it.

  6. Switch the report off again when you are done.

Three things to know:

  • Every switch is off after a start. A switch stays on until you switch it off or the resource restarts.

  • A switch counts for everyone. While it is on, every operation of that kind is reported, whoever starts it: a user in this app, an agent, another Topic or an outside program.

  • Reports use space inside the container. The tab shows where they are saved and how much space is free. Delete reports you no longer need (trash icon, or Delete all). Reports are also gone when the container is created again, for example after a Stop and Start of an Agent.

The list

Column Meaning

Started

When the operation began

Type

Ingestion, Retrieval/chat, Community recompute or Pipeline run

Subject

The file name, the question or the pipeline name

Status

RUNNING: still being written. OK: finished. ERROR: the operation failed. INCOMPLETE: cut off, because the container restarted or the chat was cancelled

Duration, Size

How long it took, and how large the report is

While a report is RUNNING, you cannot open or delete it, and report.md is not ready yet. events.jsonl is the same report as raw events, one per line, for programs.

3. How a report is built

A report always has the same parts, in this order. Start at the top and go down only as far as you need. The first sections are short summaries. The long part is Details.

Part What it shows What to look for

Header table

Who and what: the type, the subject, Triggered by (for example a chat turn from the UI, or an MCP client), the User, start and end, duration, Status, and the error text if there is one. Below it, the request fields, such as file size and type

Status ERROR with the Error line: that is the reason in one sentence

Summary

Counts: pieces, pictures, seeds, reports found and the like. Then the number of model calls, tokens, anomalies and decisions

An unexpected zero. For example 0 pieces for a file means nothing can be found from it

Anomalies

Everything the system found odd, with a severity (INFO, WARNING, ERROR), where it happened and the setting that is involved

Read this first. A warning here often is the whole answer

Decisions

Each branch the operation took, and why: the outcome, the reason, the setting that decided it and its value

The row that explains a surprise, for example why a message was answered without a search

Effective settings

Every setting that counted for this operation, its value and where the value came from

A value that differs from what you expected (see Where a setting comes from below)

Not configurable

Fixed values in the software that shape the result. No setting changes them

Only for understanding. For example the size of a candidate list

Models

Every model that was called: its role (answer, router, reranker, …), the model name, number of calls, failed calls, tokens, time and whether the prompt is the built-in one or one you configured

A role you did not expect, many failed calls, or a very high number of calls

Flow

The top-level steps with their duration and counts

The slowest step

Details

Everything in the order it happened: each step, every decision, and every model call with its full prompt, the model’s thinking if it sent any, and its reply. Long runs are split by piece, record, report or follow-up question

The exact prompt a model received, and what it answered

Artifacts

The ids of what the operation created or used (pieces, images, graph entities). Use them to look the object up afterwards

—

A model call in Details shows its time, tokens, finish reason (a model that stopped because it ran out of room shows it here), the number of the attempt, and a note whether the prompt is built-in or configured (overrides the built-in).

Where a setting comes from

The Source column of Effective settings tells you where to change a value:

Source Meaning What to do

environment variable

The value was handed to the container when this app started it. It comes from the settings of the Topic or Agent in this app

Change it on the resource’s Configuration tab or in the wizard, then stop and start it

code default

Nobody set it. The software uses its built-in value

Usually nothing. Some defaults can be set in the wizard

application.properties or JVM system property

Set inside the image or by the person who runs the installation

Ask the administrator

Names such as cyrock.retriever.k are the technical names of the settings. The most useful ones:

Name in the report Where you change it

cyrock.embedding.chunk.size, cyrock.embedding.chunk.overlap (GraphRAG: cyrock.chunk.size, cyrock.chunk.overlap)

Chunk Size, Chunk Overlap (set at creation)

cyrock.keyword-enrichment.strategy

Keyword Enrichment

cyrock.structured-import.strategy

Import Strategy (structured files)

cyrock.docling.*

Docling Server, timeout and Docling Settings (advanced)

cyrock.picture-description., cyrock.document-images.

Picture handling: description, storing, showing

cyrock.retriever.strategy, cyrock.retriever.k, cyrock.retriever.minimum-score

Retrieval Strategy, Top-K Results, Min. Similarity Score. With reranking, the search collects about three times as many pieces as Top-K

cyrock.reranker.strategy

Reranking Strategy

cyrock.routing.*

Route before retrieval, Router Confidence Threshold and, for GraphRAG, the DIRECT settings

cyrock.chat.memory-limit

Memory on the LLM Overrides tab

cyrock.chat.system-prompt, cyrock.chat.fallback-response, cyrock.prompts.*

Custom System Prompt, Prompts tab

cyrock.local-search., cyrock.global-search., cyrock.hybrid-search.*

The Local, Global and Hybrid sections of wizard step 4 (GraphRAG)

cyrock.community.*

Resolution, Refresh Cycle (GraphRAG, wizard step 3)

4. What each report contains

RAG Topic — upload

The steps appear in this order: extract content, replace previous version, chunking, link images, embed and store, and keyword index (only with HYBRID). For every piece the report holds the chunk text as it was stored. For a standalone image it also shows the step describe image. Look in Decisions for: how the text was read (plain text, structured data, Docling), whether an older version was replaced, the chunking strategy, and why no keyword index was written.

RAG Topic — chat answer

The report shows: the router’s decision (if routing is on) and why; the retrieval query (the question plus the text of attached files); the chat memory before the turn; the search hits with their scores and whether each one was kept (Min. Similarity Score); with HYBRID, the merged list and its scores; with reranking, the new order; the pieces that went into the prompt; every model call with its prompt and reply; whether the no-answer response replaced the answer; the source check; and the pictures that were placed in the answer.

GraphRAG Topic — upload

The report shows the text as it was read, every piece, and for each piece: the entities and relationships the model found, what the deduplication did (new entity, same name, merged by the model), what was written to the graph, and the pictures: which were paired with which text and how they were written as nodes.

GraphRAG Topic — chat answer

First the router: its answer, its confidence, the threshold, and the rule behind the search mode that was used (for example "LOCAL, because PATH was not possible"). After that the report follows the mode:

  • LOCAL: the starting entities from each source, with scores; the rank fusion; the part of the graph that was followed; how the pieces were chosen; the pieces in the prompt, with the codes the model cites.

  • GLOBAL: the community summaries found; for each summary whether it was relevant and what it added; the final reduce call.

  • HYBRID: the plan, the follow-up questions and which were kept, a full LOCAL trace for each, and the synthesis.

  • PATH: the two entities, the path between them, and the answer from that path.

GraphRAG Topic — community rebuild

How the graph was grouped, every community with its size, which summaries were kept because nothing changed and which were written again, every model call, and which old summaries were removed.

Agent — pipeline run

Each module as a step with input, output and duration. Every model call in full, including those outside the agents (guardrails, validator, structured output). Every tool call with arguments and result. For control modules: the verdict with score and threshold and the branch taken, and every loop pass. See Agent — DEV Reports.

5. Using a report to find a problem

"The answer is wrong or unrelated"

  1. Switch on Report chat answers and ask the same question again.

  2. Open the report. Read Anomalies, then Decisions.

  3. In Details, find the search hits and the pieces in the prompt. Is the right content among them?

    • No: the content was not found. See "Nothing is found" below.

    • Yes, but the answer ignores it: read the prompt the answer model received. Check the Prompts tab and the Custom System Prompt.

    • Unrelated pieces are there: raise Min. Similarity Score, lower Top-K Results, or use reranking.

"Nothing is found" or "I don’t know"

Look in Anomalies for one of these warnings:

  • Retrieval returned nothing: the model answers without any document context — every piece scored below Min. Similarity Score. Lower it, or check that the file was embedded (see the upload report).

  • LOCAL found no seed node — no entity was close enough. Lower Min. Similarity Score in the Local section, or check that the file was ingested.

  • GLOBAL found no community report … community detection has not run since the last ingest — run Recompute Communities Now on the Actions tab.

"A message got no sources"

Look in Decisions for the routing decision. If the router chose DIRECT or ATTACHMENT, no search ran, so there are no sources. See the confidence and the threshold in the same row.

"An upload is slow"

Open the upload report and read Flow for the slowest step, and Models for the number of calls. Per-piece model calls (SEMANTIC chunking, Keyword Enrichment LLM, Narrate, graph extraction) multiply with the number of pieces.

"A file is accepted, but nothing of it can be found"

Look in Anomalies of the upload report: The document yielded no chunks means the file had no readable text (an empty file, or a scan that Docling could not read). For images, look for the image is stored without a description.

"A pipeline gives a wrong result"

Open the pipeline report and walk down the module steps. For each one compare its input and output. The first step whose output is wrong is the one to fix. A guardrail or validator step shows its verdict and the branch it took.

6. Privacy — what a report contains

A report is meant for people who tune a system, so it is complete.

A report contains, in full: the questions and answers of users, document text, pieces, prompts, the user name, tool arguments and results.

A report hides the values of credential-like settings: a setting whose name ends in key, secret, token or password shows (redacted), and request options with a name that contains key, token, secret, password, authorization or header are hidden too (this includes advanced Docling settings). Reports of pipelines also remove API keys, passwords, connection strings and header values from the pipeline definition.

Because of this:

  • Give DEV_REPORTING only to people who may read all content of the resource.

  • Switch reporting off when you are done and delete reports you no longer need.

  • Look through a report before you send it to someone outside your company.

Sharing a report

Download report.md and send it. It is plain text with tables. An AI assistant can read it too: hand it over and ask which setting to change. The Effective settings part tells the assistant where each value came from.

A report of more than 5 MB shows only its first sections in the tab, with a notice. Download report.md to read all of it. In the tab, the contents lists are plain text. In the downloaded file they are links.

Troubleshooting

Symptom Cause and fix

The tab says the software does not support DEV reporting

The container runs an older image. Update the image and restart the resource

A switch cannot be switched on

The container cannot write reports (the tab says why), or this kind of report is not supported

Switches are off again

The resource restarted. Switches are always off after a start

The tab shows no list

You need the permission Use DEV Reporting, and the resource must be running

The list says it could not be read

The list could not be loaded. This does not mean there are no reports. Refresh, and check that the resource runs

A report stays RUNNING

The operation is still going, for example a long upload. If the container restarted, it becomes INCOMPLETE

Related