diff --git a/doc/source/admin_guide.rst b/doc/source/admin_guide.rst index f21dd78e56..401693c043 100644 --- a/doc/source/admin_guide.rst +++ b/doc/source/admin_guide.rst @@ -939,3 +939,42 @@ ago, and you've already cleaned up any orphans with `swift-orphans`, you can run `swift-oldies -a 48` to find any Swift processes still around that were started more than 2 days ago and then investigate them accordingly. + + + +------------------- +Custom Log Handlers +------------------- + +Swift supports setting up custom log handlers for services by specifying a +comma-separated list of functions to invoke when logging is setup. It does so +via the `log_custom_handlers` configuration option. Logger hooks invoked are +passed the same arguments as Swift's get_logger function (as well as the +getLogger and LogAdapter object): + +============== =============================================== +Name Description +-------------- ----------------------------------------------- +conf Configuration dict to read settings from +name Name of the logger received +log_to_console (optional) Write log messages to console on stderr +log_route Route for the logging received +fmt Override log format received +logger The logging.getLogger object +adapted_logger The LogAdapter object +============== =============================================== + +A basic example that sets up a custom logger might look like the +following: + + +.. code-block:: python + + def my_logger(conf, name, log_to_console, log_route, fmt, logger, + adapted_logger): + my_conf_opt = conf.get('some_custom_setting') + my_handler = third_party_logstore_handler(my_conf_opt) + logger.addHandler(my_handler) + +See :ref:`custom-logger-hooks-label` for sample use cases. + diff --git a/doc/source/associated_projects.rst b/doc/source/associated_projects.rst index 304d8b0f3a..63f8898084 100644 --- a/doc/source/associated_projects.rst +++ b/doc/source/associated_projects.rst @@ -59,6 +59,13 @@ Alternative API * `Swift3 `_ - Amazon S3 API emulation. +.. _custom-logger-hooks-label: + +Custom Logger Hooks +------------------- + +* `swift-sentry `_ - Sentry exception reporting for Swift + Other ----- diff --git a/doc/source/deployment_guide.rst b/doc/source/deployment_guide.rst index fae53d7584..205e74f30e 100644 --- a/doc/source/deployment_guide.rst +++ b/doc/source/deployment_guide.rst @@ -220,20 +220,22 @@ The following configuration options are available: [DEFAULT] -================== ========== ============================================= -Option Default Description ------------------- ---------- --------------------------------------------- -swift_dir /etc/swift Swift configuration directory -devices /srv/node Parent directory of where devices are mounted -mount_check true Whether or not check if the devices are - mounted to prevent accidentally writing - to the root device -bind_ip 0.0.0.0 IP Address for server to bind to -bind_port 6000 Port for server to bind to -workers 1 Number of workers to fork -disable_fallocate false Disable "fast fail" fallocate checks if the - underlying filesystem does not support it. -================== ========== ============================================= +=================== ========== ============================================= +Option Default Description +------------------- ---------- --------------------------------------------- +swift_dir /etc/swift Swift configuration directory +devices /srv/node Parent directory of where devices are mounted +mount_check true Whether or not check if the devices are + mounted to prevent accidentally writing + to the root device +bind_ip 0.0.0.0 IP Address for server to bind to +bind_port 6000 Port for server to bind to +workers 1 Number of workers to fork +disable_fallocate false Disable "fast fail" fallocate checks if the + underlying filesystem does not support it. +log_custom_handlers None Comma-separated list of functions to call + to setup custom log handlers. +=================== ========== ============================================= [object-server] @@ -326,21 +328,23 @@ The following configuration options are available: [DEFAULT] -================== ========== ============================================ -Option Default Description ------------------- ---------- -------------------------------------------- -swift_dir /etc/swift Swift configuration directory -devices /srv/node Parent directory of where devices are mounted -mount_check true Whether or not check if the devices are - mounted to prevent accidentally writing - to the root device -bind_ip 0.0.0.0 IP Address for server to bind to -bind_port 6001 Port for server to bind to -workers 1 Number of workers to fork -user swift User to run as -disable_fallocate false Disable "fast fail" fallocate checks if the - underlying filesystem does not support it. -================== ========== ============================================ +=================== ========== ============================================ +Option Default Description +------------------- ---------- -------------------------------------------- +swift_dir /etc/swift Swift configuration directory +devices /srv/node Parent directory of where devices are mounted +mount_check true Whether or not check if the devices are + mounted to prevent accidentally writing + to the root device +bind_ip 0.0.0.0 IP Address for server to bind to +bind_port 6001 Port for server to bind to +workers 1 Number of workers to fork +user swift User to run as +disable_fallocate false Disable "fast fail" fallocate checks if the + underlying filesystem does not support it. +log_custom_handlers None Comma-separated list of functions to call + to setup custom log handlers. +=================== ========== ============================================ [container-server] @@ -422,25 +426,27 @@ The following configuration options are available: [DEFAULT] -================== ========== ============================================= -Option Default Description ------------------- ---------- --------------------------------------------- -swift_dir /etc/swift Swift configuration directory -devices /srv/node Parent directory or where devices are mounted -mount_check true Whether or not check if the devices are - mounted to prevent accidentally writing - to the root device -bind_ip 0.0.0.0 IP Address for server to bind to -bind_port 6002 Port for server to bind to -workers 1 Number of workers to fork -user swift User to run as -db_preallocation off If you don't mind the extra disk space usage in - overhead, you can turn this on to preallocate - disk space with SQLite databases to decrease - fragmentation. -disable_fallocate false Disable "fast fail" fallocate checks if the - underlying filesystem does not support it. -================== ========== ============================================= +=================== ========== ============================================= +Option Default Description +------------------- ---------- --------------------------------------------- +swift_dir /etc/swift Swift configuration directory +devices /srv/node Parent directory or where devices are mounted +mount_check true Whether or not check if the devices are + mounted to prevent accidentally writing + to the root device +bind_ip 0.0.0.0 IP Address for server to bind to +bind_port 6002 Port for server to bind to +workers 1 Number of workers to fork +user swift User to run as +db_preallocation off If you don't mind the extra disk space usage in + overhead, you can turn this on to preallocate + disk space with SQLite databases to decrease + fragmentation. +disable_fallocate false Disable "fast fail" fallocate checks if the + underlying filesystem does not support it. +log_custom_handlers None Comma-separated list of functions to call + to setup custom log handlers. +=================== ========== ============================================= [account-server] @@ -536,6 +542,9 @@ cors_allow_origin This is a list of hosts that Access-Control-Allow-Origin header in addition to what the container has set. +log_custom_handlers None Comma separated list of functions + to call to setup custom log + handlers. ============================ =============== ============================= [proxy-server] @@ -808,3 +817,5 @@ Swift is set up to log directly to syslog. Every service can be configured with the `log_facility` option to set the syslog log facility destination. We recommended using syslog-ng to route the logs to specific log files locally on the server and also to remote log collecting servers. +Additionally, custom log handlers can be used via the custom_log_handlers +setting.