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

> ## Agent Instructions
> Pages under /latest/ document the current release. Paths that begin with a version number, for example /10.0/, are frozen snapshots of superseded releases kept for reference only — never present their instructions as current. If the reader's version is unknown, answer from /latest/ and say which version the answer describes.
> xorlab is deployed on-premises, hybrid, or as a cloud service, and integrates with either Microsoft 365 or on-premises mail infrastructure. Configuration steps often differ between these. State which deployment and integration mode an instruction applies to instead of presenting one as universal.
> Distinguish inline mode from monitoring mode when describing anything that acts on email. Monitoring mode observes a copy and cannot block or quarantine; inline mode routes mail through xorlab and can.
> Write the product name as lowercase 'xorlab'. Use the documented component names: xorlab Control Center (XCC), xorlab MTA, xorlab Sandbox (DANA), xorlab Natural Language Understanding (NLU). After the first mention, use the short forms XCC, MTA, Sandbox, and NLU. Do not use DANA as a standalone name for the Sandbox, but keep it where it is a literal string in configuration keys, container names, and hostnames.
> Do not invent configuration keys, rule parameters, list names, log properties, or API fields. If a value is not present in this documentation, say that it is not documented rather than guessing.

# Verify and Troubleshoot Logging

> Prove a new logging configuration works, and work through the reasons a record goes missing, arrives twice, or gets cut off.

If you suspect that the xorlab part of the logging is not working, the container's own log usually says why — see [Search the container logs for LOG- lines](#search-the-container-logs-for-log-lines).

## Verify a new configuration

1. Wait about a minute after clicking **Publish**, so the configuration is loaded.
2. Produce the event on purpose:
   * For a `trace.*` event, send a test email through xorlab.
   * For an `audit.*` event, do the action in XCC — log in, open a message, release a message from quarantine.
   * For `sys.*`, publish any configuration change.
3. Look for the record at the destination: your SIEM's search, the mailbox you configured, or the file you named.
4. If it is not there, [search the container logs for `LOG-`](#search-the-container-logs-for-log-lines), then work down the tables below.

## Search the container logs for LOG- lines

Logback reports its own problems into the log of the container it runs in, prefixed with `LOG-`.

1. Open **Monitoring** in the XCC side menu. It opens Grafana, which holds the collected container logs; see [Monitoring Overview](/latest/monitoring-overview). Access requires the **Monitoring User** role, see [List of Built-in Roles](/latest/built-in-user-roles).
2. Go to **Explore**.
3. Select the container whose configuration you edited, using the `container_name` label. The container names per component are in [Operation Reference](/latest/operation-reference#container-description).
4. Search for `LOG-`.

That returns every logback line for the container, so a configuration rejected shortly after you published it appears around that timestamp.

## When nothing arrives

| Check                                                         | How                                                                                                                                                                                                                                                                                                                                  |
| :------------------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Was the change published?                                     | Saved edits in the Expert Editor do nothing until you click **Publish**. Reopen the file and confirm your appender is in the published version. Sandbox (Dana) logging is the exception: it is edited over SSH and activated by restarting the Sandbox stack, see [Operation Reference](/latest/operation-reference#sandbox-dana-2). |
| Is the file in the right container's directory?               | The most common cause. Compare the `Container` column in [Log Events](/latest/logging-events) against the directory table in [How Logging Works](/latest/logging-concept#one-configuration-file-per-component). `audit.access.*` lives in `auth/auth/`, not in `xcc/backend/`.                                                       |
| Is the logger name exactly the event name, or a prefix of it? | Only prefixes cut at a dot are valid. `audit.user` works; `audit.us` matches nothing and reports nothing.                                                                                                                                                                                                                            |
| Is the appender declared before the logger?                   | An appender must appear above the logger that references it in the file, and the `ref` must match the appender `name` character for character.                                                                                                                                                                                       |
| Is the destination reachable from xorlab?                     | Syslog leaves from the container that emits the event, so both the MTA and XCC may need the path open. Ports are in the [Network Guide](/latest/network-guide).                                                                                                                                                                      |
| Does the event really occur?                                  | Some events fire only in a specific mode or configuration. A Sandbox event needs a file to scan, and `trace.msg_delivered_internal` needs a multi-tenant relay.                                                                                                                                                                      |

## When something arrives but looks wrong

| Symptom                                                      | Cause                                                                                                     | Fix                                                                                                         |
| :----------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------- |
| Every record is cut off mid-way                              | UDP truncates at 1500 bytes by default, and extended JSON is routinely larger                             | Switch to [TCP or TLS](/latest/logging-via-syslog#use-syslog-with-tcp-or-tls), or raise `messageSizeLimit`  |
| The record is nearly empty, or the pattern appears literally | The converter does not apply to that event. `%coreJsonMsg` is for message-tracing (`trace.*`) events only | Use `%jsonMsg` instead, see [Format Converters](/latest/logging-formats)                                    |
| One email produces two verdict records                       | Expected for `trace.msg_verdict` when an out-of-band Sandbox scan changes the verdict                     | Nothing to fix; correlate on the GGRID                                                                      |
| The log source name in the SIEM is wrong or missing          | `hostName` is unset                                                                                       | Set `hostName` in the appender, see [Available attributes](/latest/logging-via-syslog#available-attributes) |

## Keep a TCP connection alive

A firewall or load balancer between xorlab and the destination may drop an idle TCP connection, which shows up as records going missing after quiet periods. The `KeepAliveAppender` wraps another appender and makes it emit a periodic no-op, which keeps the connection up.

<Note>
  This is not needed for normal operation. Add it only if you have TCP connection problems.
</Note>

```xml logback-audit.xml theme={null}
<?xml version="1.0" encoding="UTF-8"?>
<included>

  <!-- Standard Syslog appender -->
  <appender name="syslogAppender" class="com.xorlab.sgappliance.shared.logback.SyslogAppender">
    <syslogHost>syslog.example.com</syslogHost>
    <port>514</port>
    <hostName>xorlab</hostName>
    <protocol>UDP</protocol>
    <facility>LOCAL0</facility>
    <encoder>
      <pattern>%jsonMsg%n</pattern>
    </encoder>
  </appender>

  <!-- Additional KeepAlive appender to trigger periodic keep alives via the Syslog appender.
      This appender should not be referenced by any logger. -->
  <appender name="keepAliveSyslogAppender" class="com.xorlab.sgappliance.shared.logback.KeepAliveAppender">
    <!-- Optional config showing their default values -->
    <!--
    <intervalHours>1</intervalHours>
    <intervalMinutes>60</intervalMinutes>
    <intervalSeconds>3600</intervalSeconds>
    <intervalMilliseconds>3600000</intervalMilliseconds>
    <logType>NOOP</logType>
    <message>noop</message>
    <level>DEBUG</level>
    -->
    <appender-ref ref="syslogAppender"/>
  </appender>

  <!-- Reference the keepAliveSyslogAppender, NOT the syslogAppender -->
  <logger name="audit">
    <appender-ref ref="keepAliveSyslogAppender"/>
  </logger>
</included>
```

Click **Publish**. The logging configuration becomes active within about one minute.