Log Collection Plugin

Lets you group log files into named collections and start conversations scoped to them. On the welcome page, a Log Collections widget lists your collections; Analyze opens a conversation against one. A banner in the conversation shows the active collection.

Configuration

plugins:
  - module: codumentor.plugins.log_collection
    class: LogCollectionPlugin
    args:
      enabled: true
      allowed_log_roots:
        - /var/log/my-application

Parameters

Key	Type	Default	Description
enabled	bool	true	Master switch.
allowed_log_roots	list of absolute directory paths	[]	Trusted host directories whose regular files may be attached. Empty denies all attachments.

Host-file security

This plugin is operator opt-in. Configure narrowly scoped log directories, never
an instance data directory, configuration directory, or the filesystem root.
Every user with access to this plugin can attach files under these roots; the
allowlist is not a per-tenant authorization mechanism. Roots must exist when the
plugin starts. Keep them and their ancestors protected from untrusted writes.

API and agent-tool attachments must resolve to existing regular files contained
in an allowed root. Symlinks and .. are resolved before containment is checked;
only the canonical path is stored. Collection names and workspace filenames must
be single safe path components. Persisted entries are revalidated when a session
is prepared, so old unsafe entries and files outside a changed allowlist fail
closed. The sandbox receives individual read-only file mounts, not their parent
directories; unattached sibling files are not exposed by those mounts.

Path checks do not eliminate filesystem replacement races when an attacker can
modify trusted directories. Changing the allowlist does not revoke mounts in
already-running sessions; end those sessions when tightening access.

Isolation modes

Mode	What the agent sees	Disabled tools
isolated (default)	Only the collection's log files — no code repos	knowledge_search, replace_in_file, write_file, agentic_developer
merged	Log files plus all configured code repos	—

Using the UI

1. On the welcome page, click + New Collection
2. Set Name, optional Description, and Isolation Mode
3. Add files: Label, Real Path (absolute path on the server, must resolve to a readable regular file under allowed_log_roots), and Symlink Name (the name the agent sees)
4. Create Collection, then Analyze

The widget refreshes about every 30 seconds. Existing conversations are not affected when you delete a collection.

Operator API

All routes require authentication and are scoped to the calling user. They are mounted under /ui/plugins/log_collection.

Method	Path	Description
POST	/	Create a collection
GET	/	List the caller's collections
GET	/{id}	Collection details including files
PUT	/{id}	Update name, description, or isolation mode
DELETE	/{id}	Delete a collection
POST	/{id}/files	Add files
DELETE	/{id}/files/{file_id}	Remove a file

Create a collection:

curl -X POST http://localhost:2638/ui/plugins/log_collection \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"name": "production-logs", "description": "Prod logs", "isolation_mode": "isolated"}'

Add files (real_path must resolve to a regular file under allowed_log_roots):

curl -X POST http://localhost:2638/ui/plugins/log_collection/1/files \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "files": [{"label": "App Log", "real_path": "/var/log/my-application/app.log", "symlink_name": "app.log"}]
  }'

Start a conversation against a collection:

curl -X POST "http://localhost:2638/ui/conversations?source_type=log_collection&source_id=1" \
  -H "Authorization: Bearer $TOKEN"

Agent tools

During a log-collection conversation the agent can manage collections:

• manage_log_collection — create, list, get, update, or delete collections
• manage_log_collection_files — add, list, or remove files in a collection

Troubleshooting

Widget missing. Confirm the plugin is in plugins with enabled: true.

404 on a collection API call. The collection must belong to the authenticated user and the id must exist.

Agent cannot read a log file. Configure allowed_log_roots; its empty default denies all. real_path must resolve to an existing regular file inside an allowed root and be readable by the Codumentor process. Existing unsafe collection entries must be removed before starting another session.