Log Collections

Log collections let you analyze sets of log files with Codumentor's agent, without needing a code repository. You curate a collection of log files, link a conversation to it, and the agent gains read access to those files plus shell tools for analysis.

Overview

A log collection is a named group of log files that the agent can analyze. Use log collections when you want the agent to:

Search through application or infrastructure logs
Correlate events across multiple log files
Summarize errors, warnings, or patterns in log data

Each collection belongs to the user who created it. The agent sees the log files as symlinks in a temporary workspace directory.

Creating a Collection

1. Create the collection

curl -X POST /ui/plugins/log_collection \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "prod-incident-2026-02",
    "description": "Production logs from Feb 2026 outage",
    "isolation_mode": "isolated"
  }'

Response:

{
  "id": 1,
  "name": "prod-incident-2026-02",
  "description": "Production logs from Feb 2026 outage",
  "isolation_mode": "isolated",
  "status": "active",
  "owner_user_id": "alice",
  "created_at": "2026-02-17T10:00:00",
  "updated_at": "2026-02-17T10:00:00"
}

2. Add files to the collection

curl -X POST /ui/plugins/log_collection/1/files \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "files": [
      {
        "label": "API gateway access log",
        "real_path": "/var/log/gateway/access.log",
        "symlink_name": "gateway-access.log",
        "file_type": "text"
      },
      {
        "label": "Backend service log",
        "real_path": "/var/log/backend/service.log",
        "symlink_name": "backend-service.log",
        "file_type": "text"
      }
    ]
  }'

The real_path must point to an existing file on the server. The symlink_name is the filename the agent sees in its workspace.

Isolation Modes

Each collection has an isolation mode that controls what the agent can access:

Mode	Log files	Code repos	Disabled tools
`isolated`	Yes	No	`knowledge_search`, `replace_in_file`, `write_file`, `agentic_developer`
`merged`	Yes	Yes	None

isolated (default) — The agent only sees the log files. Code-oriented tools are disabled. Use this for pure log analysis.
merged — The agent sees both the log files and all configured code repositories. All tools remain available. Use this when you need to correlate logs with source code.

Working with Log Collections

To start a conversation linked to a collection, include source_type and source_id in the conversation metadata:

{
  "source_type": "log_collection",
  "source_id": 1
}

When a conversation is linked to a log collection, the agent receives:

A system prompt describing the collection name, description, and available files
A workspace directory containing symlinks to the log files under a subdirectory named after the collection (e.g., prod-incident-2026-02/gateway-access.log)
Shell tools for log analysis — the agent is guided to use grep, jq, awk, head, tail, wc, sort, and uniq
Collection management tools (manage_log_collection, manage_log_collection_files) for modifying collections within the conversation

Managing Collections

List collections

curl /ui/plugins/log_collection \
  -H "Authorization: Bearer $TOKEN"

Returns all collections owned by the authenticated user.

Get a single collection (with files)

curl /ui/plugins/log_collection/1 \
  -H "Authorization: Bearer $TOKEN"

Update a collection

curl -X PUT /ui/plugins/log_collection/1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated description",
    "isolation_mode": "merged"
  }'

All fields (name, description, isolation_mode) are optional — only provided fields are updated.

Delete a collection

curl -X DELETE /ui/plugins/log_collection/1 \
  -H "Authorization: Bearer $TOKEN"

Remove a file from a collection

curl -X DELETE /ui/plugins/log_collection/1/files/3 \
  -H "Authorization: Bearer $TOKEN"

API Reference

All endpoints are under /ui/plugins/log_collection and require authentication.

Method	Path	Description
`POST`	`/`	Create a collection
`GET`	`/`	List collections for the authenticated user
`GET`	`/{collection_id}`	Get a collection (includes files)
`PUT`	`/{collection_id}`	Update a collection
`DELETE`	`/{collection_id}`	Delete a collection
`POST`	`/{collection_id}/files`	Add files to a collection
`DELETE`	`/{collection_id}/files/{file_id}`	Remove a file from a collection