doc/admin/logs-table-management.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: admin
   4 title: "Logs table management"
   5 ...
   6
   7 {% comment %}
   8 Copyright (C) The Arvados Authors. All rights reserved.
   9
  10 SPDX-License-Identifier: CC-BY-SA-3.0
  11 {% endcomment %}
  12
  13 This page aims to provide insight about managing the ever growing API Server's logs table.
  14
  15 h3. Logs table purpose & behavior
  16
  17 This database table is accessed via "the @logs@ endpoint.":../api/methods/logs.html
  18
  19 This table currently serves several purposes:
  20
  21 * Audit logging, permitting admins and users to look up the time and details of past changes to Arvados objects.
  22 * Logging other system events, specifically "file uploads and downloads from keep-web.":restricting-upload-download.html#audit_logs
  23 * The source for cache-invalidation events, published through websockets to Workbench to refresh the view.  It can also be monitored by the Python SDK "events module.":../sdk/python/events.html
  24 * Prior to Arvados 2.7, it was used a staging area for stdout/stderr text coming from users' containers, permitting users to see what their containers are doing while they are still running (i.e., before those text files are written to Keep).  Starting with Arvados 2.7, this is superseded by a more efficient mechanism, so these logs are disabled by default.  See "2.7.0 upgrade notes":upgrading.html#v2_7_0 for details.
  25
  26 As a result, this table grows indefinitely, even on sites where policy does not require an audit log; making backups, migrations, and upgrades unnecessarily slow and painful.
  27
  28 h3. Configuration
  29
  30 To solve the problem mentioned above, the @AuditLogs@ section of @config.yml@ offers several options to limit the amount of log information stored on the table:
  31
  32 <pre>
  33     AuditLogs:
  34       # Time to keep audit logs. (An audit log is a row added
  35       # to the "logs" table in the PostgreSQL database each time an
  36       # Arvados object is created, modified, or deleted.)
  37       #
  38       # Currently, websocket event notifications rely on audit logs, so
  39       # this should not be set lower than 5 minutes.
  40       MaxAge: 336h
  41
  42       # Maximum number of log rows to delete in a single SQL transaction,
  43       # to prevent surprises and avoid bad database behavior
  44       # (especially the first time the cleanup job runs on an existing
  45       # cluster with a huge backlog) a maximum number of rows to
  46       # delete in a single transaction.
  47       #
  48       # If MaxDeleteBatch is 0, log entries will never be
  49       # deleted by Arvados. Cleanup can be done by an external process
  50       # without affecting any Arvados system processes, as long as very
  51       # recent (<5 minutes old) logs are not deleted.
  52       #
  53       # 100000 is a reasonable batch size for most sites.
  54       MaxDeleteBatch: 0
  55
  56       # Attributes to suppress in events and audit logs.  Notably,
  57       # specifying {"manifest_text": {}} here typically makes the database
  58       # smaller and faster.
  59       #
  60       # Warning: Using any non-empty value here can have undesirable side
  61       # effects for any client or component that relies on event logs.
  62       # Use at your own risk.
  63       UnloggedAttributes: {}
  64 </pre>
  65
  66
  67 h3. Additional consideration
  68
  69 Depending on the local installation's audit requirements, the cluster admins should plan for an external backup procedure before enabling this feature, as this information is not replicated anywhere else.