> For the complete documentation index, see [llms.txt](https://docs.linuxguard.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.linuxguard.io/operate/operate/log-management.md).

# Log Management

This page covers the operational characteristics of LinuxGuard agent logs: what is and is not redacted, how rate limiting protects the agent under heavy log volume, and recommended patterns for shipping agent logs to central log management or SIEM systems.

For rotation defaults and operational knobs (`logging.max_size_mb`, `log_level` runtime reload), see [Log Level and Rotation](/configure/configure/log-level-rotation.md).

## Redaction Scope

> **Important**: Redaction matches ONLY slog attribute keys whose name matches the regex `^(api_key|enroll_token|.*_token|.*_secret)$`. NO PII redaction occurs. Hostnames, IPs, usernames, file paths, and command-line arguments are NOT additionally redacted.

### What Is Redacted

The agent's slog handler wraps every log record and applies a defense-in-depth filter to the attribute keys before the underlying handler writes them. The filter matches attribute **keys** — not values, not free-text content — against a case-insensitive regex:

```
^(api_key|enroll_token|.*_token|.*_secret)$
```

When an attribute key matches, the value is replaced with the literal string `[REDACTED]` before the record is serialized. Matching is case-insensitive and applies recursively to nested slog groups. Attribute key examples that match:

* `api_key` (exact match)
* `enroll_token` (exact match)
* `auth_token`, `refresh_token`, `bearer_token` (suffix match on `*_token`)
* `client_secret`, `webhook_secret` (suffix match on `*_secret`)

In addition to runtime redaction, a `redactvet` go/analysis analyzer flags `slog.*` call sites whose argument list contains identifiers from the package's `ForbiddenSymbols` set at compile time. Both layers share the same source-of-truth regex.

### What Is NOT Redacted (PII Out of Scope)

The agent's log redaction is **explicitly limited to secret-bearing attribute keys**. The following classes of data are NOT additionally redacted and may appear in agent logs verbatim — **PII NOT additionally redacted**:

* **Hostnames** — host identifiers appear in event fields, error messages, and trace lines verbatim
* **IP addresses** — both IPv4 and IPv6 addresses, including addresses captured from network events
* **Usernames** — UNIX user names, account names, login UIDs, and any user-identifier captured by eBPF auth probes
* **File paths** — fully qualified file paths, including paths under user home directories
* **Process command-line arguments** — exec/execve event payloads include the full argv vector
* **Free-text values of any kind** — error messages, debug strings, and structured event payloads that are not key-matched by the regex

Customers shipping agent logs to centralized log management or SIEM systems are responsible for any additional PII redaction required by their compliance regime (GDPR, CCPA, HIPAA, or equivalent). Treat agent logs as containing PII-equivalent content by default.

### Difference From Support-Bundle Redaction

The support-bundle's `config.redacted.json` uses an **explicit struct mapping** with SHA256 fingerprints, NOT the regex-based log redaction described above. The agent log content shipped inside a support bundle uses the same regex-based redaction as live logs — bundle inclusion does NOT add a PII redaction pass. See [Support Bundles](/operate/operate/support-bundles.md) for the per-file redaction status table.

## Rate Limiting and Drop Summaries

Under heavy log volume, the agent's slog handler applies **per-level token-bucket rate limiting** to protect the rotation file and downstream consumers.

### What Is Rate-Limited

Only TRACE and DEBUG levels are rate-limited. INFO, WARN, and ERROR are always allowed and never touch any rate counter — bounding them would hide operator-visible signals under load.

Default per-second rates (configurable per build):

| Level | Default rate (events/sec) | Burst |
| ----- | ------------------------- | ----- |
| TRACE | 1000                      | 1000  |
| DEBUG | 500                       | 500   |
| INFO  | unlimited                 | n/a   |
| WARN  | unlimited                 | n/a   |
| ERROR | unlimited                 | n/a   |

Burst equals the per-second rate, so a one-second window of events passes through before the limiter starts dropping. Subsequent events at the same level that exceed the bucket are dropped and counted in per-level atomic drop counters.

### Drop Summary Emission

Every 60 seconds, a summary goroutine snapshots the per-level drop counters, resets them, and emits a log record describing how many events were dropped at each rate-limited level. The summary is itself a regular log record at INFO level — operators can grep for `dropped` summaries to detect log floods.

The summary mechanism means a flood at TRACE or DEBUG will NOT silently disappear; the count of dropped records appears in the next 60-second window's summary line. The summary itself is not rate-limited.

## Central Log Collection Patterns

The agent writes structured logs (slog text or JSON, depending on build configuration) to `/var/log/linuxguard/agent.log`. Operators commonly ship these to central log management. Three patterns are validated against the agent's logging characteristics.

### journald Integration

When the agent runs under systemd (the standard install on Debian/Ubuntu, RedHat/CentOS, SUSE/openSUSE), systemd's journal captures stdout/stderr of the unit. The packaged unit file writes to a file-based log via lumberjack, NOT stdout, so journald does not capture agent records directly.

To make the agent log visible to journald, an operator can configure systemd to read from the rotated file via `journalctl --file /var/log/linuxguard/agent.log` or set up a systemd-journald `ForwardToSyslog` policy. For most operators, scraping `/var/log/linuxguard/agent.log` with a log shipper (vector, fluent-bit, syslog-ng) is more direct.

### Syslog Forwarding

To forward agent logs to a remote syslog endpoint:

1. Configure a local syslog daemon (rsyslog, syslog-ng) to tail `/var/log/linuxguard/agent.log`.
2. Forward to the remote endpoint using TLS-protected RFC 5424 framing.
3. Configure the SIEM-side redaction layer to strip PII before storage.

See [Syslog Forwarding](/respond/respond/syslog-forwarding.md) for the integration pattern.

### Structured JSON Shipping

For shipping to log aggregators that ingest structured JSON (Splunk HEC, Elasticsearch, Datadog logs):

1. Configure the agent to emit JSON-format records (per build configuration).
2. Run a log shipper (vector, fluent-bit) tailing `/var/log/linuxguard/agent.log`.
3. Authenticate the shipper to the aggregator using a service-account credential stored as a host-local secret — NOT in the agent's config.
4. Apply field-level redaction at the shipper or aggregator for any PII categories your compliance regime requires.

### TLS and Authentication Recommendations

* Always TLS-protect the log transport, including journald-forwarded paths.
* Authenticate the log shipper with a credential that has write-only scope on the destination index/topic — never reuse the agent's API key.
* Do NOT route agent logs through unauthenticated UDP syslog in production. UDP loss + unauthenticated reception together breach almost every compliance regime's audit-log integrity requirement.

## Cross-References

* [Log Level and Rotation](/configure/configure/log-level-rotation.md) — Operational knobs: rotation defaults, `log_level` SIGHUP reload, logrotate sample.
* [Support Bundles](/operate/operate/support-bundles.md) — Per-file redaction status table for the support bundle.
* [Syslog Forwarding](/respond/respond/syslog-forwarding.md) — Forwarding agent logs to remote syslog endpoints.

***

**Related**: [Log Level and Rotation](/configure/configure/log-level-rotation.md) | [Support Bundles](/operate/operate/support-bundles.md) | [Syslog Forwarding](/respond/respond/syslog-forwarding.md) | [Troubleshooting](/troubleshooting.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.linuxguard.io/operate/operate/log-management.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.