.. _operate-logs:

=======================
Logs and monitoring
=======================

The TOA server logs through SLF4J with Logback as the backend. The
default configuration ships in ``logback-spring.xml`` (packaged inside
the server jar) and writes simultaneously to:

* **stdout** - so the service integrates cleanly with ``journalctl``
  on Linux and the Event Viewer / NSSM logs on Windows.
* **a rotating file** at ``./logs/toa-server.log`` (relative to the
  working directory) - so a long-running process keeps a structured
  on-disk audit trail without depending on the system journal.

File rotation
=============

The file appender uses Logback's ``SizeAndTimeBasedRollingPolicy`` -
it rolls when **either** the daily date boundary is crossed **or**
the active file exceeds the size limit, whichever comes first.
Rotated files are gzipped and named, e.g.::

   toa-server.log
   toa-server.log.2026-04-14.0.gz
   toa-server.log.2026-04-14.1.gz
   toa-server.log.2026-04-13.0.gz

Defaults:

================================================ ===============
Property                                         Default
================================================ ===============
``logging.file.name``                            ``./logs/toa-server.log``
``logging.logback.rollingpolicy.max-file-size``  ``50MB``
``logging.logback.rollingpolicy.total-size-cap`` ``1GB``
``logging.logback.rollingpolicy.max-history``    ``30`` (days)
================================================ ===============

All four are standard Spring Boot logging properties - the server
just plumbs them into the Logback rolling policy via
``<springProperty>`` substitutions, so any deployment knob that takes
Spring Boot configuration (``application.properties``,
``config/toa-server.yml``, JVM args ``-Dlogging.file.name=...``,
environment variables ``LOGGING_FILE_NAME``, ...) overrides them.

Per-package levels
==================

The application package defaults to ``INFO``. Bump it for
troubleshooting without restarting the stack:

.. code-block:: yaml

   logging:
     level:
       root: INFO
       com.lightcomp.tahiti.office.addon: DEBUG
       # Drill into a specific subsystem if needed:
       com.lightcomp.tahiti.office.addon.damis: TRACE

Spring Boot picks up ``logging.level.*`` changes on a context refresh;
for an interactive session, hitting the ``/actuator/loggers`` endpoint
(when actuator is enabled) flips levels at runtime without restart.

Key events to look for
======================

==================================================== =================================================
Log line                                             What just happened
==================================================== =================================================
``Created toa-server.dataRoot at <path>``            First-start filesystem setup.
``Domain '<code>' storage at <path>``                Per-domain storage initialised on startup.
``Loaded N templates for domain '<code>' ...``       cmserver XML parsed; catalog is live.
``Downloaded and loaded N templates ...``            URL-based template refresh succeeded.
``Scheduled refresh failed for domain ...``          URL refresh failed; previous catalog kept.
``Data retention sweep deleted N date folder(s) ...``Retention sweep removed old imports.
``Data retention sweep failed: ...``                 Sweep aborted; investigate file permissions /
                                                     I/O errors. The next pass (24 h later) retries.
``DamisClient: ...``                                 Communication with the storage server.
==================================================== =================================================

A failed import upload that rolls back atomically does **not** appear
as a single log line; look for an exception traceback inside the
``ImportController`` or ``DomainStorage`` logger.

Disabling file logging
======================

Set ``logging.file.name`` to an empty value, or remove it from the
configuration. With no ``logging.file.name`` Spring Boot still loads
``logback-spring.xml`` but the rolling appender will fail to open the
file - cleaner to drop the file appender entirely by replacing
``logback-spring.xml`` with a console-only variant, or by setting:

.. code-block:: yaml

   logging:
     file:
       name:    # explicitly empty

and accepting that the file appender is then misconfigured. For
production deployments where stdout is captured by systemd, leaving
``logging.file.name`` empty is fine - the rolling appender just opens
no file.

Health and metrics
==================

Spring Boot Actuator ships in the server jar with a deliberately
narrow exposure - only ``/actuator/health`` and ``/actuator/info``
are reachable over HTTP:

``GET /actuator/health``
    Returns ``200 {"status":"UP"}`` when the server is fully wired up.
    This is the right URL for a reverse-proxy upstream liveness probe
    (nginx ``proxy_pass``, HAProxy ``option httpchk``, AWS target
    group health check). Use it as ``/healthz`` behind your proxy so
    the actuator URL stays internal.

``GET /actuator/info``
    Returns the Maven build-info and git commit metadata stamped into
    the jar at build time, e.g.::

        {
          "build": {
            "artifact": "toa-server",
            "name":     "TOAServer",
            "version":  "0.9.0",
            "time":     "2026-04-15T23:14:11.443Z"
          },
          "git": {
            "branch":     "release",
            "commit": {
              "id":   "a3f0c4b...",
              "time": "2026-04-15T22:10:02Z"
            }
          },
          "java": { "version": "21.0.3", ... },
          "os":   { "name": "Linux", "version": "...", ... }
        }

    Useful for verifying a deployment landed cleanly without ssh-ing
    onto the box.

To expose more endpoints (``loggers``, ``metrics``, ``env``, ...),
extend ``management.endpoints.web.exposure.include`` in
``application.properties`` or ``config/toa-server.yml``. Think
carefully about the trust boundary first - some of these endpoints
leak operational detail (config values, beans, environment
variables) and should not be reachable from the public reverse
proxy. Either bind the actuator port separately
(``management.server.port=8081``) and firewall it, or front it with
HTTP basic auth.