# Logs

Logs contains package output, build messages, package start and stop events, and HTTP request and response events recorded by Leilani’s proxy. Everything is scoped to your signed-in workspace. No logging SDK or change to `leilani.json` is required.

## Write application logs

Write newline-terminated messages to stdout or stderr. Each nonblank line becomes a `PackageLog` entry labeled with its package name. Stdout receives `Informational` severity; stderr receives `Error`. The collector does not infer severity from words or JSON fields inside your message.

```rust
println!("order_id=42 action=created");
eprintln!("order_id=42 action=payment_failed reason=timeout");
```

A logging library works too, provided its output goes to stdout or stderr. If your formatter sends every level to stderr, every line will be labeled Error in Leilani. Configure its writer deliberately. Files written by your application are not automatically collected. Blank lines are skipped; multi-line messages appear as separate entries. Avoid putting passwords, tokens, or request bodies in logs.

For database output, use `{kind="PostgresLog"}`. These entries retain PostgreSQL severity; unclassified initialization and continuation lines are informational.

## Read and refresh logs

Open **Logs**. The table shows UTC time, severity, package, event kind, and message, newest first. A query returns up to 200 entries from the last 24 hours, across deployments in this workspace. This is the console’s search window, not a promise of retention. Narrow your query if recent traffic hides the event you need.

Auto-refresh defaults to every two seconds. Choose another interval or **Refresh off** while investigating. Refresh pauses when the tab is hidden, you scroll down to older rows, or you select text. Return to the top and clear the selection to resume. Drag column dividers to resize them, or focus a divider and use the arrow keys.

## Search with LogQL

Enter a log query in **Search (LogQL)** and select **Run query**. Start with a stream selector in braces, then add filters. `=` selects an exact label value, `=~` matches a label with a regular expression, `|=` keeps lines containing text, and `!=` excludes lines containing text. Names and exact matches are case-sensitive. Use log queries here; metric aggregations are not displayed as log rows.

All events (the default)

```logql
{kind=~".+"}
```

Output from one package

```logql
{kind="PackageLog", package="api"}
```

Errors written by a package

```logql
{kind="PackageLog", package="api", severity="Error"}
```

Find a message and exclude noise

```logql
{kind="PackageLog"} |= "order_id=42" != "healthcheck"
```

Match text without case sensitivity

```logql
{kind="PackageLog"} |~ "(?i)(timeout|connection refused)"
```

Requests to a path

```logql
{kind="HttpRequest"} | json | path="/orders"
```

Server-error responses

```logql
{kind="HttpResponse"} | json | status_code=~"5[0-9][0-9].*"
```

Package starts and stops

```logql
{kind=~"PackageStarted|PackageStopped"}
```

Build output

```logql
{kind=~"CompileMessage|CargoOutputChunk"}
```

Replace `api`, paths, and search text with your own values. The `package` stream label belongs to PackageLog entries; lifecycle events instead carry package data in their JSON message. HTTP events carry fields such as `request_id`, `path`, `method`, and `status_code`. Use `| json` to extract fields from those events. Application output is stored as a JSON string, so its embedded fields are not automatically indexed as labels.

For a failing request, find its HttpResponse entry, copy its `request_id`, then search both HTTP event kinds:

```logql
{kind=~"HttpRequest|HttpResponse"} | json | request_id="REQUEST-ID"
```

To restrict events to a known build or deployment, filter the attached metadata after the selector, for example `{kind=~".+"} | build_id="BUILD-ID"` or `{kind=~".+"} | deployment_id="DEPLOYMENT-ID"`. Use an actual identifier from your deployment; these are not stream-selector labels.

If a search returns nothing, select **Reset**, confirm the package ran and emitted a complete line within the last 24 hours, then add filters one at a time. A query error is different from an empty result: check syntax and label capitalization, or retry if log storage is temporarily unavailable.
