> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognee.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Logging

> Understand how Cognee logs work, where log files are stored, and how to control log output

Cognee writes structured logs to two destinations simultaneously: the console and a log file. A new log file is created each time Cognee starts. The file captures everything from `DEBUG` upward. The console shows only the level you configure.

## How Logging Works in Cognee

When you import or start Cognee, `setup_logging()` is called automatically. It configures two handlers:

* **Console handler** — writes colored output to `stderr`, filtered by `LOG_LEVEL` (default: `INFO`)
* **File handler** — writes plain text to a timestamped `.log` file, always at `DEBUG` level

One log file is created per startup and shared across all sub-processes. Cognee keeps the 10 most recent log files and deletes older ones automatically.

<Accordion title="Default log file locations">
  The default `logs/` directory is created next to the `cognee` package directory, one level above it. The exact path depends on how Cognee is installed.

  **Installed via pip** (e.g. `pip install cognee`):

  ```
  ~/.venv/lib/python3.x/site-packages/logs/
  ```

  **Running from source** (cloned repository):

  ```
  <repo-root>/logs/
  ```

  **Using the MCP server:**
  The MCP server uses the same logging setup. The log directory is the same as above, depending on your environment. When a background task is launched, the MCP server returns the full path to the active log file in its response.

  <Warning>
    When Cognee is installed via pip or used as an MCP server, log files end up inside your virtual environment's `site-packages/` directory. Set `COGNEE_LOGS_DIR` to write logs to a predictable location instead.
  </Warning>
</Accordion>

## Controlling Logging

### Environment Variables

* `COGNEE_LOGS_DIR` — Absolute path to a custom log directory. Cognee creates it if it does not exist. Must be an absolute path — relative paths cause a startup error. Default: `logs/` next to the `cognee` package.
* `LOG_LEVEL` — Console log verbosity. One of `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`. Default: `INFO`. Does not affect the log file, which always captures `DEBUG` and above.

### Configuration Examples

```dotenv theme={null}
# Write logs to a predictable absolute path
COGNEE_LOGS_DIR="/home/user/my-project/logs"

# Reduce console noise in production
LOG_LEVEL="ERROR"

# Show all output during development
LOG_LEVEL="DEBUG"
```

### Fallback Behavior

If Cognee cannot write to `COGNEE_LOGS_DIR`, it falls back to `/tmp/cognee_logs`. If that also fails, file logging is skipped silently and only console output is produced.

## Log Files and Their Content

### File Format

Log files use plain text, one entry per line. Timestamps are in UTC:

```
2025-02-14T15:32:47.123456 [WARNING ] From version 0.5.0 onwards... [cognee.shared.logging_utils]
2025-02-14T15:32:47.234567 [INFO    ] Log file created at: /path/to/logs/2025-02-14_15-32-47.log [cognee.shared.logging_utils]
2025-02-14T15:32:47.345678 [INFO    ] Logging initialized python_version=3.11.0 cognee_version=0.x.x os_info=... database_path=... graph_database_name=... vector_config=... relational_config=... [cognee.shared.logging_utils]
2025-02-14T15:32:47.456789 [INFO    ] Database storage: /path/to/.cognee_system/databases [cognee.shared.logging_utils]
```

### Console Format

The console uses structlog's colored renderer, written to `stderr`. Level colors: `DEBUG` blue, `INFO` green, `WARNING` yellow, `ERROR` and `CRITICAL` red.

### What to Expect at Startup

Every time Cognee initializes, the following four messages are logged in order:

1. **WARNING** — A notice that multi-user access control is on by default since version 0.5.0. This is expected and not an error.
2. **INFO** — The full path to the log file created for this session.
3. **INFO** — System metadata: Python version, Cognee version, OS, database paths, and the active graph, vector, and relational providers.
4. **INFO** — The database storage path.

If messages 2–4 are missing from the console, file logging may have failed. Check whether the log directory is writable or set `COGNEE_LOGS_DIR` to a path you control.

### File Naming

Each log file is named after the startup timestamp:

```
YYYY-MM-DD_HH-MM-SS.log
```

Example: `2025-02-14_15-32-47.log`

## Troubleshooting

<AccordionGroup>
  <Accordion title="Can't find the log file">
    Run this snippet after importing cognee to get the exact path:

    ```python theme={null}
    from cognee.shared.logging_utils import get_log_file_location
    print(get_log_file_location())
    ```
  </Accordion>

  <Accordion title="No log file is created">
    Cognee falls back to console-only logging if the log directory is not writable. This is common in managed environments where `site-packages/` is read-only.

    Set `COGNEE_LOGS_DIR` to an absolute path you own:

    ```dotenv theme={null}
    COGNEE_LOGS_DIR="/home/user/my-project/logs"
    ```
  </Accordion>
</AccordionGroup>

<Columns cols={3}>
  <Card title="Overview" icon="settings" href="/setup-configuration/overview">
    Return to setup configuration overview
  </Card>

  <Card title="Relational Databases" icon="database" href="/setup-configuration/relational-databases">
    Configure metadata and state storage
  </Card>

  <Card title="Installation" icon="rocket" href="/getting-started/installation">
    Install Cognee and set up your environment
  </Card>
</Columns>