Logging

Configure Levee's diagnostic logs with config.json, read them with levee log, and understand how they differ from the audit trail

Diagnostic logs record what Levee's own components were doing, so IT and Vediram support can fix problems. They are not the audit trail. The audit trail is the evidence of what the AI agent asked for and what Levee decided, and it is always on. This page covers diagnostic logs only.

How do diagnostic logs differ from the audit trail?

For the audit trail, see Activity and audit.

Diagnostic logs are built not to contain secrets or sensitive content: no credentials, tokens, cookies, connection strings, SQL text, search queries, or prompts.

config.json

Logging is configured in one file, %ProgramData%\Vediram\Levee\config.json. The defaults suit most organizations. Change them only to get more detail for a support case, or to keep logs longer.

The installer creates the file with these defaults and never overwrites it on upgrade, so your changes survive updates.

{
  "schemaVersion": 1,
  "logging": {
    "defaultLevel": "Information",
    "componentLevels": {},
    "categoryLevels": {
      "Microsoft": "Warning",
      "System.Net.Http": "Warning"
    },
    "retention": {
      "maxTotalSizeMb": 256,
      "maxAgeDays": 7,
      "segmentSizeMb": 8
    }
  }
}

The file is readable by all users and writable only by Administrators. It must never contain secrets.

Keys

Component names

An unknown component name is ignored with a warning (logging.unknown_component).

Example: debug web access for a troubleshooting session

{
  "schemaVersion": 1,
  "logging": {
    "defaultLevel": "Information",
    "componentLevels": {
      "proxy.http": "Debug",
      "service": "Debug"
    },
    "categoryLevels": {
      "Microsoft": "Warning",
      "System.Net.Http": "Warning"
    },
    "retention": { "maxTotalSizeMb": 512, "maxAgeDays": 7, "segmentSizeMb": 8 }
  }
}

Set levels back to Information when you're done; Debug and Trace produce a lot of data and use up the size budget faster.

Applying changes

Most changes apply on their own within moments. Only the container engine needs a restart.

• Changes are picked up automatically by the service, the app, and the Levee channels. No restart is needed.
• The container engine is the exception: after changing the engine level, restart it (Restart-Service LeveeContainerEngine, elevated).
• If the file becomes invalid, unreadable, or is deleted, every component keeps its last good configuration. A typo never turns logging off.

Validate a file before you deploy it:

levee config validate .\config.candidate.json
# Valid.

Diagnostic codes you may see:

How do I read the logs?

Use levee log tail. It merges all components, decompresses rolled files, and enforces who may see what, so you don't need to open the files.

# Your recent warnings and errors
levee log tail --level Warning --since 1h

# One component for one project, live
levee log tail --component proxy.llm --project 3f9c1a7e42b0 --follow

# Several components at once
levee log tail --component service --component engine --since 30m

# Everything on the machine (elevated PowerShell)
levee log tail --all --since 1d --json > "$env:TEMP\levee-logs.json"

Who can read what?

• Each user sees their own app and CLI logs and the logs of projects they own.
• Administrators (with --all) see machine logs, every project, and every user.

Log store status

levee log status

Reports the space used against maxTotalSizeMb, the oldest data kept, whether each component has applied the current configuration, and whether any events were recently dropped.

Where are the files?

%ProgramData%\Vediram\Levee\logs\
  machine\<component>\...
  projects\<project id>\<component>\...
  users\<user SID>\<component>\...

Files are JSON lines, compressed (.gz) once rolled. The LeveeFSHost service writes its log in the project's folder, under fs.service. If a component can't write to this folder at all, it writes to an emergency location instead, %TEMP%\Vediram\Levee\<component>-<pid>-fallback, so nothing is lost silently.

Other logs worth knowing:

Sending logs to Vediram support

See Collecting logs for support for the exact commands to gather everything support needs in one archive.

Related

• CLI reference
• Files and locations