Return-Path: X-Original-To: apmail-couchdb-commits-archive@www.apache.org Delivered-To: apmail-couchdb-commits-archive@www.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id BBA1110203 for ; Wed, 24 Jul 2013 12:25:08 +0000 (UTC) Received: (qmail 85995 invoked by uid 500); 24 Jul 2013 12:24:45 -0000 Delivered-To: apmail-couchdb-commits-archive@couchdb.apache.org Received: (qmail 85922 invoked by uid 500); 24 Jul 2013 12:24:45 -0000 Mailing-List: contact commits-help@couchdb.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@couchdb.apache.org Delivered-To: mailing list commits@couchdb.apache.org Received: (qmail 84572 invoked by uid 99); 24 Jul 2013 12:24:38 -0000 Received: from tyr.zones.apache.org (HELO tyr.zones.apache.org) (140.211.11.114) by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 24 Jul 2013 12:24:38 +0000 Received: by tyr.zones.apache.org (Postfix, from userid 65534) id A07DE8B3508; Wed, 24 Jul 2013 12:24:38 +0000 (UTC) Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit From: kxepal@apache.org To: commits@couchdb.apache.org Date: Wed, 24 Jul 2013 12:24:39 -0000 Message-Id: <39132f8215b14dfcad55a6b1cbe0c0b4@git.apache.org> In-Reply-To: <0d2ddf82c5604c60b1a85317061cfc81@git.apache.org> References: <0d2ddf82c5604c60b1a85317061cfc81@git.apache.org> X-Mailer: ASF-Git Admin Mailer Subject: [02/50] [abbrv] git commit: updated refs/heads/1781-reorganize-and-improve-docs to fa11c25 Group external processes configuration. Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/af75771f Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/af75771f Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/af75771f Branch: refs/heads/1781-reorganize-and-improve-docs Commit: af75771f1d7696e22b940f12c15b56441757435b Parents: 4208966 Author: Alexander Shorin Authored: Wed Jul 17 08:38:17 2013 +0400 Committer: Alexander Shorin Committed: Wed Jul 24 10:48:36 2013 +0400 ---------------------------------------------------------------------- share/doc/build/Makefile.am | 9 +- share/doc/src/config/externals.rst | 179 ++++++++++++++++++++++ share/doc/src/config/index.rst | 3 +- share/doc/src/config/os-daemons.rst | 126 --------------- share/doc/src/config/update-notification.rst | 64 -------- 5 files changed, 183 insertions(+), 198 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/couchdb/blob/af75771f/share/doc/build/Makefile.am ---------------------------------------------------------------------- diff --git a/share/doc/build/Makefile.am b/share/doc/build/Makefile.am index 2c820e4..a211b31 100644 --- a/share/doc/build/Makefile.am +++ b/share/doc/build/Makefile.am @@ -58,14 +58,13 @@ html_files = \ html/_sources/config/compaction.txt \ html/_sources/config/couchdb.txt \ html/_sources/config/daemons.txt \ + html/_sources/config/externals.txt \ html/_sources/config/http.txt \ html/_sources/config/index.txt \ html/_sources/config/log.txt \ - html/_sources/config/os-daemons.txt \ html/_sources/config/query-servers.txt \ html/_sources/config/replicator.txt \ html/_sources/config/stats.txt \ - html/_sources/config/update-notification.txt \ html/_sources/config/uuids.txt \ html/_sources/config/vendor.txt \ html/_sources/config/intro.txt \ @@ -117,14 +116,13 @@ html_files = \ html/config/compaction.html \ html/config/couchdb.html \ html/config/daemons.html \ + html/config/externals.html \ html/config/http.html \ html/config/index.html \ html/config/log.html \ - html/config/os-daemons.html \ html/config/query-servers.html \ html/config/replicator.html \ html/config/stats.html \ - html/config/update-notification.html \ html/config/uuids.html \ html/config/vendor.html \ html/config/intro.html \ @@ -174,14 +172,13 @@ src_files = \ ../src/config/compaction.rst \ ../src/config/couchdb.rst \ ../src/config/daemons.rst \ + ../src/config/externals.rst \ ../src/config/http.rst \ ../src/config/index.rst \ ../src/config/log.rst \ - ../src/config/os-daemons.rst \ ../src/config/query-servers.rst \ ../src/config/replicator.rst \ ../src/config/stats.rst \ - ../src/config/update-notification.rst \ ../src/config/uuids.rst \ ../src/config/vendor.rst \ ../src/config/intro.rst \ http://git-wip-us.apache.org/repos/asf/couchdb/blob/af75771f/share/doc/src/config/externals.rst ---------------------------------------------------------------------- diff --git a/share/doc/src/config/externals.rst b/share/doc/src/config/externals.rst new file mode 100644 index 0000000..4f0d4e9 --- /dev/null +++ b/share/doc/src/config/externals.rst @@ -0,0 +1,179 @@ +.. Licensed under the Apache License, Version 2.0 (the "License"); you may not +.. use this file except in compliance with the License. You may obtain a copy of +.. the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +.. License for the specific language governing permissions and limitations under +.. the License. + +.. highlight:: ini + +================== +External Processes +================== + +.. _config/os_daemons: + +``[os_daemons]`` :: OS Daemons +============================== + +This is a simple feature that allows users to configure CouchDB so that it +maintains a given OS level process alive. If the process dies for any reason, +CouchDB will restart it. If the process restarts too often, then CouchDB will +mark it has halted and not attempt to restart it. The default max restart rate +is ``3`` times in the last ``5`` seconds. These parameters are +:ref:`adjustable `. + +Commands that are started in this manner will have access to a simple +API over stdio to request configuration parameters or to add log +statements to CouchDB's logs. + +To configure an OS process as a CouchDB os_daemon, create a section +in your `local.ini` like such:: + + [os_daemons] + daemon_name = /path/to/command -with args + +This will make CouchDB bring up the command and attempt to keep it +alive. To request a configuration parameter, an `os_daemon` can write +a simple JSON message to stdout like such:: + + ["get", "os_daemons"]\n + +which would return:: + + {"daemon_name": "/path/to/command -with args"}\n + +Or:: + + ["get", "os_daemons", "daemon_name"]\n + +which would return:: + + "/path/to/command -with args"\n + +There's no restriction on what configuration variables are visible. +There's also no method for altering the configuration. + +If you would like your OS daemon to be restarted in the event that +the configuration changes, you can send the following messages:: + + ["register", $(SECTION)]\n + +When anything in that section changes, your OS process will be +rebooted so it can pick up the new configuration settings. If you +want to listen for changes on a specific key, you can send something +like:: + + ["register", $(SECTION), $(KEY)]\n + +In this case, CouchDB will only restart your daemon if that exact +section/key pair changes, instead of anything in that entire section. + +Logging commands look like:: + + ["log", $(JSON_MESSAGE)]\n + +Where ``$(JSON_MESSAGE)`` is arbitrary JSON data. These messages are +logged at the 'info' level. If you want to log at a different level +you can pass messages like such:: + + ["log", $(JSON_MESSAGE), {"level": $(LEVEL)}]\n + +Where ``$(LEVEL)`` is one of "debug", "info", or "error". + +When implementing a daemon process to be managed by CouchDB you +should remember to use a method like checking the parent process +id or if stdin has been closed. These flags can tell you if +your daemon process has been orphaned so you can exit cleanly. + +There is no interactivity between CouchDB and the running process, but +you can use the OS Daemons service to create new HTTP servers and +responders and then use the new proxy service to redirect requests and +output to the CouchDB managed service. For more information on proxying, +see :ref:`http-proxying`. For further background on the OS Daemon service, see +`CouchDB Externals API`_. + +.. _CouchDB Externals API: http://davispj.com/2010/09/26/new-couchdb-externals-api.html + + +.. _config/os_daemons_settings: + +``[os_daemon_settings]`` :: OS Daemons settings +=============================================== + +.. _config/os_daemons_settings/max_retries: + +``max_retries`` :: Maximum restart retries +------------------------------------------ + +Specifies maximum attempts to run :ref:`os_daemon ` before +mark him halted:: + + [os_daemon_settings] + max_retries = 3 + + +.. _config/os_daemons_settings/retry_time: + +``retry_time`` :: Delay between restart attempts +------------------------------------------------ + +Delay in seconds between :ref:`os_daemon ` restarts:: + + [os_daemon_settings] + retry_time = 5 + + + +.. _update-notifications: +.. _config/update-notification: + +``[update_notification]`` :: Update notifications +================================================= + +CouchDB is able to spawn OS processes to notify them about recent databases +updates. The notifications are in form of JSON messages sent as a line of text, +terminated by ``CR`` (``\n``) character, to the OS processes through `stdout`:: + + [update_notification] + ;unique notifier name=/full/path/to/exe -with "cmd line arg" + index_updater = ruby /usr/local/bin/index_updater.rb + + +The update notification messages are depend upon of event type: + +- **Database created**: + + .. code-block:: javascript + + {"type":"created","db":"dbname"} + + +- **Database updated**: this event raises when any document gets updated for + specified database: + + .. code-block:: javascript + + {"type":"updated","db":"dbname"} + + +- **Design document updated**: for design document updates there is special + event raised in additional to regular db update one: + + .. code-block:: javascript + + {"type":"ddoc_updated","db":"dbname","id":"_design/ddoc_name"} + + +- **Database deleted**: + + .. code-block:: javascript + + {"type":"deleted","db":"dbname"} + +.. note:: New line (``\n``) trailing character was removed from examples. http://git-wip-us.apache.org/repos/asf/couchdb/blob/af75771f/share/doc/src/config/index.rst ---------------------------------------------------------------------- diff --git a/share/doc/src/config/index.rst b/share/doc/src/config/index.rst index 0a877a1..5e5d4ef 100644 --- a/share/doc/src/config/index.rst +++ b/share/doc/src/config/index.rst @@ -24,16 +24,15 @@ Configuring CouchDB auth compaction query-servers + externals proxying attachments couchdb daemons log - os-daemons replicator stats - update-notification uuids vendor http://git-wip-us.apache.org/repos/asf/couchdb/blob/af75771f/share/doc/src/config/os-daemons.rst ---------------------------------------------------------------------- diff --git a/share/doc/src/config/os-daemons.rst b/share/doc/src/config/os-daemons.rst deleted file mode 100644 index 8f8611d..0000000 --- a/share/doc/src/config/os-daemons.rst +++ /dev/null @@ -1,126 +0,0 @@ -.. Licensed under the Apache License, Version 2.0 (the "License"); you may not -.. use this file except in compliance with the License. You may obtain a copy of -.. the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT -.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the -.. License for the specific language governing permissions and limitations under -.. the License. - -.. highlight:: ini - -.. _config/os_daemons: - -``[os_daemons]`` :: OS Daemons -============================== - -This is a simple feature that allows users to configure CouchDB so that it -maintains a given OS level process alive. If the process dies for any reason, -CouchDB will restart it. If the process restarts too often, then CouchDB will -mark it has halted and not attempt to restart it. The default max restart rate -is ``3`` times in the last ``5`` seconds. These parameters are -:ref:`adjustable `. - -Commands that are started in this manner will have access to a simple -API over stdio to request configuration parameters or to add log -statements to CouchDB's logs. - -To configure an OS process as a CouchDB os_daemon, create a section -in your `local.ini` like such:: - - [os_daemons] - daemon_name = /path/to/command -with args - -This will make CouchDB bring up the command and attempt to keep it -alive. To request a configuration parameter, an `os_daemon` can write -a simple JSON message to stdout like such:: - - ["get", "os_daemons"]\n - -which would return:: - - {"daemon_name": "/path/to/command -with args"}\n - -Or:: - - ["get", "os_daemons", "daemon_name"]\n - -which would return:: - - "/path/to/command -with args"\n - -There's no restriction on what configuration variables are visible. -There's also no method for altering the configuration. - -If you would like your OS daemon to be restarted in the event that -the configuration changes, you can send the following messages:: - - ["register", $(SECTION)]\n - -When anything in that section changes, your OS process will be -rebooted so it can pick up the new configuration settings. If you -want to listen for changes on a specific key, you can send something -like:: - - ["register", $(SECTION), $(KEY)]\n - -In this case, CouchDB will only restart your daemon if that exact -section/key pair changes, instead of anything in that entire section. - -Logging commands look like:: - - ["log", $(JSON_MESSAGE)]\n - -Where ``$(JSON_MESSAGE)`` is arbitrary JSON data. These messages are -logged at the 'info' level. If you want to log at a different level -you can pass messages like such:: - - ["log", $(JSON_MESSAGE), {"level": $(LEVEL)}]\n - -Where ``$(LEVEL)`` is one of "debug", "info", or "error". - -When implementing a daemon process to be managed by CouchDB you -should remember to use a method like checking the parent process -id or if stdin has been closed. These flags can tell you if -your daemon process has been orphaned so you can exit cleanly. - -There is no interactivity between CouchDB and the running process, but -you can use the OS Daemons service to create new HTTP servers and -responders and then use the new proxy service to redirect requests and -output to the CouchDB managed service. For more information on proxying, -see :ref:`http-proxying`. For further background on the OS Daemon service, see -`CouchDB Externals API`_. - -.. _CouchDB Externals API: http://davispj.com/2010/09/26/new-couchdb-externals-api.html - - -.. _config/os_daemons_settings: - -``[os_daemon_settings]`` :: OS Daemons settings -=============================================== - -.. _config/os_daemons_settings/max_retries: - -``max_retries`` :: Maximum restart retries ------------------------------------------- - -Specifies maximum attempts to run :ref:`os_daemon ` before -mark him halted:: - - [os_daemon_settings] - max_retries = 3 - - -.. _config/os_daemons_settings/retry_time: - -``retry_time`` :: Delay between restart attempts ------------------------------------------------- - -Delay in seconds between :ref:`os_daemon ` restarts:: - - [os_daemon_settings] - retry_time = 5 - http://git-wip-us.apache.org/repos/asf/couchdb/blob/af75771f/share/doc/src/config/update-notification.rst ---------------------------------------------------------------------- diff --git a/share/doc/src/config/update-notification.rst b/share/doc/src/config/update-notification.rst deleted file mode 100644 index 9f4b1ef..0000000 --- a/share/doc/src/config/update-notification.rst +++ /dev/null @@ -1,64 +0,0 @@ -.. Licensed under the Apache License, Version 2.0 (the "License"); you may not -.. use this file except in compliance with the License. You may obtain a copy of -.. the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT -.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the -.. License for the specific language governing permissions and limitations under -.. the License. - -.. highlight:: ini - -.. TODO: move `update-notification` reference to special article about this - feature - -.. _update-notifications: -.. _config/update-notification: - -``[update_notification]`` :: Update notifications -================================================= - -CouchDB is able to spawn OS processes to notify them about recent databases -updates. The notifications are in form of JSON messages sent as a line of text, -terminated by ``CR`` (``\n``) character, to the OS processes through `stdout`:: - - [update_notification] - ;unique notifier name=/full/path/to/exe -with "cmd line arg" - index_updater = ruby /usr/local/bin/index_updater.rb - - -The update notification messages are depend upon of event type: - -- **Database created**: - - .. code-block:: javascript - - {"type":"created","db":"dbname"} - - -- **Database updated**: this event raises when any document gets updated for - specified database: - - .. code-block:: javascript - - {"type":"updated","db":"dbname"} - - -- **Design document updated**: for design document updates there is special - event raised in additional to regular db update one: - - .. code-block:: javascript - - {"type":"ddoc_updated","db":"dbname","id":"_design/ddoc_name"} - - -- **Database deleted**: - - .. code-block:: javascript - - {"type":"deleted","db":"dbname"} - -.. note:: New line (``\n``) trailing character was removed from examples.