> For the complete documentation index, see [llms.txt](https://docs.labs.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.labs.ai/deployment-and-infrastructure/log-administration.md).

# Log Administration

> **Base path:** `/administration/logs`\
> **Security:** `@RolesAllowed("eddi-admin")` — requires `eddi-admin` role when OIDC is enabled (`QUARKUS_OIDC_TENANT_ENABLED=true`). Not enforced while OIDC is disabled, which is the default in every launch mode.

EDDI provides a built-in log management API for platform-wide observability. It captures all application log records into an in-memory ring buffer and optionally persists them to the database for cross-restart history.

> **Note:** This API provides *system-level application logs* (JUL/JBoss log records). For conversation message history (user/assistant messages), use the [Conversation Log endpoint](https://docs.labs.ai/conversations-and-orchestration/conversations.md) (`GET /agents/{conversationId}/log`) instead.

***

## Endpoints

### Recent Logs (Ring Buffer)

```
GET /administration/logs
```

Returns recent log entries from the in-memory ring buffer. These are fast to query but do not survive restarts.

| Parameter        | Type    | Default | Description                                                                                                                                 |
| ---------------- | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `agentId`        | string  | —       | Filter by agent ID                                                                                                                          |
| `conversationId` | string  | —       | Filter by conversation ID                                                                                                                   |
| `level`          | string  | `INFO`  | Minimum log level (`TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`). Returns entries **at or above** this level                                   |
| `limit`          | integer | `100`   | Maximum number of entries to return, newest first. Above `eddi.rest.listing.max-limit` (default `1000`) the request is refused with **400** |

> The ring buffer only ever holds what the log manager actually emits. EDDI sets no `quarkus.log.level` or `quarkus.log.min-level`, so the root logger is `INFO` and no `DEBUG`/`TRACE` record reaches the buffer at all — passing `level=DEBUG` returns nothing extra. To capture them, raise `quarkus.log.min-level` (and the category level) first. `quarkus.log.console.level=DEBUG` is a *handler* setting and does not lower the logger.

**Example:**

```bash
# Get the 50 most recent WARN+ entries for a specific agent
curl "http://localhost:7070/administration/logs?agentId=my-agent&level=WARN&limit=50"
```

**Response:**

```json
[
  {
    "timestamp": 1711900800000,
    "level": "WARN",
    "loggerName": "ai.labs.eddi.modules.llm.impl.LlmTask",
    "message": "LLM response was not valid JSON, storing as plain string",
    "environment": "production",
    "agentId": "my-agent",
    "agentVersion": 3,
    "conversationId": "conv-abc123",
    "userId": "user-42",
    "instanceId": "eddi-host-a1b2"
  }
]
```

***

### Historical Logs (Database)

```
GET /administration/logs/history
```

Returns historical logs from the database. These survive restarts and work across instances. Only logs at or above the configured `eddi.logs.db-persist-min-level` are persisted.

| Parameter        | Type    | Default | Description                                                                                                                                                                                 |
| ---------------- | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `environment`    | enum    | —       | Filter by deployment environment (`production`, `test`, etc.)                                                                                                                               |
| `agentId`        | string  | —       | Filter by agent ID                                                                                                                                                                          |
| `agentVersion`   | integer | —       | Filter by agent version                                                                                                                                                                     |
| `conversationId` | string  | —       | Filter by conversation ID                                                                                                                                                                   |
| `userId`         | string  | —       | Filter by user ID                                                                                                                                                                           |
| `instanceId`     | string  | —       | Filter by EDDI instance ID (useful in multi-instance deployments)                                                                                                                           |
| `skip`           | integer | `0`     | Number of entries to skip (pagination). A negative value is refused with **400**                                                                                                            |
| `limit`          | integer | `100`   | Maximum entries to return; `0` or a negative value is treated as `100`, and a value above `eddi.rest.listing.max-limit` (default `1000`) is refused with **400** — page with `skip` instead |

**Example:**

```bash
# Get historical errors for a specific conversation
curl "http://localhost:7070/administration/logs/history?conversationId=conv-abc123&limit=100"
```

***

### Live Log Stream (SSE)

```
GET /administration/logs/stream
```

Opens a Server-Sent Events (SSE) connection for real-time log tailing. Supports the same filters as the recent logs endpoint.

| Parameter        | Type   | Default | Description                                       |
| ---------------- | ------ | ------- | ------------------------------------------------- |
| `agentId`        | string | —       | Filter by agent ID                                |
| `conversationId` | string | —       | Filter by conversation ID                         |
| `level`          | string | `INFO`  | Minimum log level (same semantics as recent logs) |

**Example:**

```bash
# Live-tail all WARN+ logs
curl -N -H "Accept: text/event-stream" \
  "http://localhost:7070/administration/logs/stream?level=WARN"
```

Each SSE event contains a JSON-serialized `LogEntry`:

```
data: {"timestamp":1711900800000,"level":"ERROR","loggerName":"...","message":"..."}
```

***

### Instance ID

```
GET /administration/logs/instance-id
```

Returns the unique identifier for this EDDI instance. Useful for correlating logs in multi-instance deployments.

**Response:**

```json
{
  "instanceId": "eddi-host-a1b2c3d4"
}
```

***

## Configuration

Log capture starts at application boot (the log store is created eagerly, and records logged before it is ready are buffered, up to 1000, and replayed into it), so the ring buffer and database history receive startup warnings without anyone having to open the log view first. Neither keeps them forever: the ring buffer holds the last `eddi.logs.buffer-size` entries, so on a busy instance older startup lines are evicted, and database history keeps only what reaches `eddi.logs.db-persist-min-level` (default `WARN`) while `eddi.logs.db-enabled` is `true`, subject to `eddi.logs.db-retention-days`. A live-tail client that connects later is first sent the 50 most recent matching entries from the ring buffer, then new ones, so an older startup warning may not appear there; `GET /administration/logs/history` is the place to look for it.

All logging configuration lives in `application.properties`:

| Property                               | Default | Description                                                                          |
| -------------------------------------- | ------- | ------------------------------------------------------------------------------------ |
| `eddi.logs.buffer-size`                | `10000` | Ring buffer capacity (in-memory entries)                                             |
| `eddi.logs.db-enabled`                 | `true`  | Enable/disable database persistence                                                  |
| `eddi.logs.db-flush-interval-seconds`  | `5`     | How often the async writer flushes to the database                                   |
| `eddi.logs.db-persist-min-level`       | `WARN`  | Minimum level to persist to the database (`TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`) |
| `eddi.logs.db-retention-days`          | `-1`    | Delete persisted entries older than this many days; `-1` (or `0`) keeps them         |
| `eddi.logs.db-retention-interval`      | `24h`   | How often the retention sweep runs                                                   |
| `eddi.logs.db-retention-initial-delay` | `4m`    | Delay before the first sweep after startup                                           |

### Retention

Persisted entries are kept until deleted unless `eddi.logs.db-retention-days` is set: a sweep then deletes, every `eddi.logs.db-retention-interval` (default `24h`), every entry whose timestamp is older than that many days, on MongoDB (`logs` collection) and PostgreSQL (`database_logs` table) alike. The sweep is idempotent, so every replica can run it. Each run adds what it deleted to `eddi_logs_db_retention_deleted_total`.

Persisted entries carry the user id of the turn that produced them, and a GDPR erasure only pseudonymizes that id — the message text stays. If a retention policy applies to your deployment, this is the setting that enforces it for the logs. (Earlier releases described this retention as configurable without any code that applied it.)

***

## Architecture

```
┌──────────────────┐     ┌─────────────────────────────────────┐
│ Quarkus Logger   │────→│ LogCaptureFilter (@LoggingFilter)   │
│ (all log records)│     │ Intercepts every JBoss LogRecord    │
└──────────────────┘     └───────────┬─────────────────────────┘
                                     │
                                     ▼
                         ┌───────────────────────┐
                         │   BoundedLogStore      │
                         │                       │
                         │  ┌─────────────────┐  │
                         │  │  Ring Buffer     │──┼──→ GET /administration/logs
                         │  │  (ArrayDeque)    │  │
                         │  └─────────────────┘  │
                         │                       │
                         │  ┌─────────────────┐  │
                         │  │  SSE Listeners   │──┼──→ GET /administration/logs/stream
                         │  └─────────────────┘  │
                         │                       │
                         │  ┌─────────────────┐  │     ┌──────────────┐
                         │  │  Async DB Queue  │──┼────→│ IDatabaseLogs│
                         │  │  (batch flush)   │  │     │ (Mongo / PG) │──→ GET .../history
                         │  └─────────────────┘  │     └──────────────┘
                         └───────────────────────┘
```

The `LogCaptureFilter` captures every record the logger emits into the ring buffer (INFO and above unless `quarkus.log.min-level` is lowered, see above) for instant query. Only entries meeting the `db-persist-min-level` threshold are enqueued for async batch persistence to the database.

### What the filter rewrites on the way out

The filter is not only a tap. Before the console handler formats a record, it rewrites that record **in place**, so every destination — container stdout, the ring buffer, the database, the SSE live tail — sees the same text:

1. **Secret redaction.** Credential-shaped material in the message, and in every message in the throwable's cause and suppressed graph, is replaced (`sk-ant-<REDACTED>` and similar). A failed outbound call routinely names the resolved URL in its exception message, and a templated credential in that URL *is* the credential.
2. **Record-boundary escaping (CWE-117).** Anything that could end a log record is escaped rather than printed: CR becomes `\r`, LF becomes `\n`, and U+2028, U+2029 and other control characters become `\uXXXX`. TAB is left alone, because it cannot end a record and it is what indents stack frames.

So a log line whose text contains a newline shows a literal `\n` instead of wrapping. **That is deliberate**: the console pattern ends in `%s%e`, `%e` prints a stack trace whose first line is the throwable's own `ClassName: message`, and without this an attacker who can get their text into an exception message could end the record and write a convincing follow-on line of their own. Stack traces are unaffected — the escaping is applied to each throwable's *message* before the trace is rendered, so frames, `Caused by:` and `... N more` come out exactly as the JVM produced them.

> **Adding a log handler?** The filter is attached to the console handler only, via `quarkus.log.console.filter=eddi-log-capture`. A file or syslog handler needs the same filter, or records reaching it are neither redacted nor escaped.

***

## Related APIs

| API                                                                                           | Path                           | Purpose                                                 |
| --------------------------------------------------------------------------------------------- | ------------------------------ | ------------------------------------------------------- |
| **Log Admin** (this page)                                                                     | `/administration/logs`         | System-wide application logs                            |
| [**Conversation Log**](https://docs.labs.ai/conversations-and-orchestration/conversations.md) | `/agents/{conversationId}/log` | Per-conversation message history (user/assistant turns) |
| [**Audit Ledger**](https://docs.labs.ai/security-and-compliance/audit-ledger.md)              | `/auditstore`                  | EU AI Act compliance audit trail                        |

These three APIs serve distinct purposes and are not redundant.
