From 1ae7af86d5d4898788ff64b46e887a06c47e69ea Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sat, 13 Aug 2011 01:43:21 -0400 Subject: - Added a Logging chapter to the narrative docs (based on the Pylons logging docs, thanks Phil). --- docs/narr/logging.rst | 388 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 388 insertions(+) create mode 100644 docs/narr/logging.rst (limited to 'docs/narr/logging.rst') diff --git a/docs/narr/logging.rst b/docs/narr/logging.rst new file mode 100644 index 000000000..120944fac --- /dev/null +++ b/docs/narr/logging.rst @@ -0,0 +1,388 @@ +.. _logging_chapter: + +Logging +======= + +:app:`Pyramid` allows you to make use of the Python standard library +:mod:`logging` module. This chapter describes how to configure logging and +how to send log messages to loggers that you've configured. + +.. warning:: This chapter assumes you've used a :term:`scaffold` to create a + project which contains ``development.ini`` and ``production.ini`` files + which help configure logging. All of the scaffolds which ship along with + :app:`Pyramid` do this. If you're not using a scaffold, or if you've used + a third-party scaffold which does not create these files, the + configuration information in this chapter will not be applicable. + +Logging Configuration +--------------------- + +A :app:`Pyramid` project created from a :term:`scaffold` is configured to +allow you to send messages to `Python standard library logging package +`_ loggers from within your +application. In particular, the :term:`PasteDeploy` ``development.ini`` and +``production.ini`` files created when you use a scaffold include a basic +configuration for the Python :mod:`logging` package. + +PasteDeploy ``.ini`` files use the Python standard library `ConfigParser +format `_; this the same +format used as the Python `logging module's Configuration file format +`_. The +application-related and logging-related sections in the configuration file +can coexist peacefully, and the logging-related sections in the file are used +from when you run ``paster serve``. + +The ``paster serve`` command calls the `logging.fileConfig function +`_ using the specified +ini file if it contains a ``[loggers]`` section (all of the +scaffold-generated ``.ini`` files do). ``logging.fileConfig`` reads the +logging configuration from the ini file upon which ``paster serve`` was +invoked. + +Default logging configuration is provided in both the default +``development.ini`` and the ``production.ini`` file. The logging +configuration in the ``development.ini`` file is as follows: + +.. code-block:: ini + :linenos: + + # Begin logging configuration + + [loggers] + keys = root, {{package_logger}} + + [handlers] + keys = console + + [formatters] + keys = generic + + [logger_root] + level = INFO + handlers = console + + [logger_{{package_logger}}] + level = DEBUG + handlers = + qualname = {{package}} + + [handler_console] + class = StreamHandler + args = (sys.stderr,) + level = NOTSET + formatter = generic + + [formatter_generic] + format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s + + # End logging configuration + +The ``production.ini`` file uses the ``WARN`` level in its logger +configuration, but it is otherwise identical. + +The name ``{{package_logger}}`` above will be replaced with the name of your +project's :term:`package`, which is derived from the name you provide to your +project. For instance, if you do: + +.. code-block:: text + :linenos: + + paster create -t pyramid_starter MyApp + +The logging configuration will literally be: + +.. code-block:: ini + :linenos: + + # Begin logging configuration + + [loggers] + keys = root, myapp + + [handlers] + keys = console + + [formatters] + keys = generic + + [logger_root] + level = INFO + handlers = console + + [logger_myapp] + level = DEBUG + handlers = + qualname = myapp + + [handler_console] + class = StreamHandler + args = (sys.stderr,) + level = NOTSET + formatter = generic + + [formatter_generic] + format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s + + # End logging configuration + +In this logging configuration: + +- a logger named ``root`` is created that logs messages at a level above + or equal to the ``INFO`` level to stderr, with the following format: + + .. code-block:: text + + 2007-08-17 15:04:08,704 INFO [packagename] + Loading resource, id: 86 + +- a logger named ``myapp`` is configured that logs messages sent at a level + above or equal to ``DEBUG`` to stderr in the same format as the root + logger. + +The ``root`` logger will be used by all applications in the Pyramid process +that ask for a logger (via ``logging.getLogger``) that has a name which +begins with anything except your project's package name (e.g. ``myapp``). +The logger with the same name as your package name is reserved for your own +usage in your Pyramid application. Its existence means that you can log to a +known logging location from any Pyramid application generated via a scaffold. + +Pyramid and many other libraries (such as Beaker, SQLAlchemy, Paste) log a +number of messages to the root logger for debugging purposes. Switching the +root logger level to ``DEBUG`` reveals them: + +.. code-block:: ini + + [logger_root] + #level = INFO + level = DEBUG + handlers = console + +Some scaffolds configure additional loggers for additional subsystems they +use (such as SQLALchemy). Take a look at the ``production.ini`` and +``development.ini`` files rendered when you create a project from a scaffold. + +Sending Logging Messages +------------------------ + +Python's special ``__name__`` variable refers to the current module's fully +qualified name. From any module in a package named ``myapp``, the +``__name__`` builtin variable will always be something like ``myapp``, or +``myapp.subpackage`` or ``myapp.package.subpackage`` if your project is named +``myapp``. Sending a message to this logger will send it to the ``myapp`` +logger. + +To log messages to the package-specific logger configured in your ``.ini`` +file, simply create a logger object using the ``__name__`` builtin and call +methods on it. + +.. code-block:: python + :linenos: + + import logging + log = logging.getLogger(__name__) + + def myview(request): + content_type = 'text/plain' + content = 'Hello World!' + log.debug('Returning: %s (content-type: %s)', content, content_type) + request.response.content_type = content_type + return request.response + +This will result in the following printed to the console, on ``stderr``: + +.. code-block:: text + + 16:20:20,440 DEBUG [myapp.views] Returning: Hello World! + (content-type: text/plain) + +Filtering log messages +---------------------- + +Often there's too much log output to sift through, such as when switching +the root logger's level to ``DEBUG``. + +An example: you're diagnosing database connection issues in your application +and only want to see SQLAlchemy's ``DEBUG`` messages in relation to database +connection pooling. You can leave the root logger's level at the less verbose +``INFO`` level and set that particular SQLAlchemy logger to ``DEBUG`` on its +own, apart from the root logger: + +.. code-block:: ini + + [logger_sqlalchemy.pool] + level = DEBUG + handlers = + qualname = sqlalchemy.pool + +then add it to the list of loggers: + +.. code-block:: ini + + [loggers] + keys = root, myapp, sqlalchemy.pool + +No handlers need to be configured for this logger as by default non root +loggers will propagate their log records up to their parent logger's +handlers. The root logger is the top level parent of all loggers. + +This technique is used in the default ``development.ini``. The root logger's +level is set to ``INFO``, whereas the application's log level is set to +``DEBUG``: + +.. code-block:: ini + + # Begin logging configuration + + [loggers] + keys = root, myapp + + [logger_myapp] + level = DEBUG + handlers = + qualname = helloworld + +All of the child loggers of the ``myapp`` logger will inherit the ``DEBUG`` +level unless they're explicitly set differently. Meaning the ``myapp.views``, +``myapp.models`` (and all your app's modules') loggers by default have an +effective level of ``DEBUG`` too. + +For more advanced filtering, the logging module provides a `Filter +`_ object; however it cannot be used +directly from the configuration file. + +Advanced Configuration +---------------------- + +To capture log output to a separate file, use a `FileHandler +`_ (or a `RotatingFileHandler +`_): + +.. code-block:: ini + + [handler_filelog] + class = FileHandler + args = ('%(here)s/myapp.log','a') + level = INFO + formatter = generic + +Before it's recognized, it needs to be added to the list of Handlers: + +.. code-block:: ini + + [handlers] + keys = console, myapp, filelog + +and finally utilized by a logger. + +.. code-block:: ini + + [logger_root] + level = INFO + handlers = console, filelog + +These final 3 lines of configuration directs all of the root logger's output +to the ``myapp.log`` as well as the console. + +Request logging with Paste's TransLogger +---------------------------------------- + +Paste provides the `TransLogger +`_ middleware for logging +requests using the `Apache Combined Log Format +`_. TransLogger combined +with a FileHandler can be used to create an ``access.log`` file similar to +Apache's. + +Like any standard middleware with a Paste entry point, TransLogger can be +configured to wrap your application in the ``[app:main]`` section of the ini +file: + +.. code-block:: ini + + [filter:translogger] + paste.filter_app_factory = egg:Paste#translogger + setup_console_handler = False + + [pipeline:main] + pipeline = translogger + myapp + +This is equivalent to wrapping your app in a TransLogger instance via the +bottom the ``main`` function of your project's ``__init__`` file: + +.. code-block:: python + + ... + app = config.make_wsgi_app() + from paste.translogger import TransLogger + app = TransLogger(app, setup_console_handler=False) + return app + +TransLogger will automatically setup a logging handler to the console when +called with no arguments, so it 'just works' in environments that don't +configure logging. Since we've configured our own logging handlers, we need +to disable that option via ``setup_console_handler = False``. + +With the filter in place, TransLogger's logger (named the 'wsgi' logger) will +propagate its log messages to the parent logger (the root logger), sending +its output to the console when we request a page: + +.. code-block:: text + + 00:50:53,694 INFO [myapp.views] Returning: Hello World! + (content-type: text/plain) + 00:50:53,695 INFO [wsgi] 192.168.1.111 - - [11/Aug/2011:20:09:33 -0700] "GET /hello + HTTP/1.1" 404 - "-" + "Mozilla/5.0 (Macintosh; U; Intel Mac OS X; en-US; rv:1.8.1.6) Gecko/20070725 + Firefox/2.0.0.6" + +To direct TransLogger to an ``access.log`` FileHandler, we need to add that +FileHandler to the wsgi logger's list of handlers: + +.. code-block:: ini + + # Begin logging configuration + + [loggers] + keys = root, myapp, wsgi + + [logger_wsgi] + level = INFO + handlers = handler_accesslog + qualname = wsgi + propagate = 0 + + [handler_accesslog] + class = FileHandler + args = ('%(here)s/access.log','a') + level = INFO + formatter = generic + +As mentioned above, non-root loggers by default propagate their log records +to the root logger's handlers (currently the console handler). Setting +``propagate`` to 0 (false) here disables this; so the ``wsgi`` logger directs +its records only to the ``accesslog`` handler. + +Finally, there's no need to use the ``generic`` formatter with TransLogger as +TransLogger itself provides all the information we need. We'll use a +formatter that passes-through the log messages as is: + +.. code-block:: ini + + [formatters] + keys = generic, accesslog + +.. code-block:: ini + + [formatter_accesslog] + format = %(message)s + +Then wire this new ``accesslog`` Formatter into the FileHandler: + +.. code-block:: ini + + [handler_accesslog] + class = FileHandler + args = ('%(here)s/access.log','a') + level = INFO + formatter = accesslog -- cgit v1.2.3 From bfdbcf4c25e28216060834b648a022045d88146b Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sat, 13 Aug 2011 01:55:45 -0400 Subject: mention pyramid_exclog --- docs/narr/logging.rst | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) (limited to 'docs/narr/logging.rst') diff --git a/docs/narr/logging.rst b/docs/narr/logging.rst index 120944fac..375ab820c 100644 --- a/docs/narr/logging.rst +++ b/docs/narr/logging.rst @@ -265,7 +265,7 @@ To capture log output to a separate file, use a `FileHandler level = INFO formatter = generic -Before it's recognized, it needs to be added to the list of Handlers: +Before it's recognized, it needs to be added to the list of handlers: .. code-block:: ini @@ -283,7 +283,15 @@ and finally utilized by a logger. These final 3 lines of configuration directs all of the root logger's output to the ``myapp.log`` as well as the console. -Request logging with Paste's TransLogger +Logging Exceptions +------------------ + +To log (or email) exceptions generated by your :app:`Pyramid` application, +use the :term:`pyramid_exclog` package. Details about its configuration are +in its `documentation +`_. + +Request Logging with Paste's TransLogger ---------------------------------------- Paste provides the `TransLogger @@ -377,7 +385,7 @@ formatter that passes-through the log messages as is: [formatter_accesslog] format = %(message)s -Then wire this new ``accesslog`` Formatter into the FileHandler: +Then wire this new ``accesslog`` formatter into the FileHandler: .. code-block:: ini -- cgit v1.2.3 From 3d338ea5737b7c113b17120b40684e2694cf3fa9 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 22 Aug 2011 02:16:55 -0400 Subject: - Use [app:main] instead of a pipeline in all scaffolds and tutorials and narrative docs. - Break out awkward description of PasteDeploy entry points from project chapter into its own Paste chapter. --- docs/narr/logging.rst | 26 ++++++++++++++++++++------ 1 file changed, 20 insertions(+), 6 deletions(-) (limited to 'docs/narr/logging.rst') diff --git a/docs/narr/logging.rst b/docs/narr/logging.rst index 375ab820c..8abcba3c7 100644 --- a/docs/narr/logging.rst +++ b/docs/narr/logging.rst @@ -301,22 +301,36 @@ requests using the `Apache Combined Log Format with a FileHandler can be used to create an ``access.log`` file similar to Apache's. -Like any standard middleware with a Paste entry point, TransLogger can be -configured to wrap your application in the ``[app:main]`` section of the ini -file: +Like any standard middleware with a Paste entry point, TransLogger can be +configured to wrap your application using ``.ini`` file syntax. First, +rename your Pyramid ``.ini`` file's ``[app:main]`` section to +``[app:mypyramidapp]``, then add a ``[filter:translogger]`` section, then use +a ``[pipeline:main]`` section file to form a WSGI pipeline with both the +translogger and your application in it. For instance, change from this: .. code-block:: ini + [app:main] + use = egg:MyProject + +To this: + +.. code-block:: ini + + [app:mypyramidapp] + use = egg:MyProject + [filter:translogger] paste.filter_app_factory = egg:Paste#translogger setup_console_handler = False [pipeline:main] pipeline = translogger - myapp + mypyramidapp -This is equivalent to wrapping your app in a TransLogger instance via the -bottom the ``main`` function of your project's ``__init__`` file: +Using PasteDeploy this way to form and serve a pipeline is equivalent to +wrapping your app in a TransLogger instance via the bottom the ``main`` +function of your project's ``__init__`` file: .. code-block:: python -- cgit v1.2.3 From 012b9762cd0b114b6afbf2d6356554b51706804a Mon Sep 17 00:00:00 2001 From: michr Date: Fri, 23 Sep 2011 18:48:28 -0700 Subject: fixed up all the warning dealing ..note and ..warn added a hide toc for glossary to prevent warnings --- docs/narr/logging.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'docs/narr/logging.rst') diff --git a/docs/narr/logging.rst b/docs/narr/logging.rst index 8abcba3c7..3e39151a3 100644 --- a/docs/narr/logging.rst +++ b/docs/narr/logging.rst @@ -7,7 +7,9 @@ Logging :mod:`logging` module. This chapter describes how to configure logging and how to send log messages to loggers that you've configured. -.. warning:: This chapter assumes you've used a :term:`scaffold` to create a +.. warning:: + + This chapter assumes you've used a :term:`scaffold` to create a project which contains ``development.ini`` and ``production.ini`` files which help configure logging. All of the scaffolds which ship along with :app:`Pyramid` do this. If you're not using a scaffold, or if you've used -- cgit v1.2.3 From 0078b214ca0d64a631674a95b002dfd82e2ba963 Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Tue, 4 Oct 2011 15:16:36 -0500 Subject: Fixed the translogger example and link. --- docs/narr/logging.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/narr/logging.rst') diff --git a/docs/narr/logging.rst b/docs/narr/logging.rst index 3e39151a3..9625723ba 100644 --- a/docs/narr/logging.rst +++ b/docs/narr/logging.rst @@ -297,7 +297,7 @@ Request Logging with Paste's TransLogger ---------------------------------------- Paste provides the `TransLogger -`_ middleware for logging +`_ middleware for logging requests using the `Apache Combined Log Format `_. TransLogger combined with a FileHandler can be used to create an ``access.log`` file similar to @@ -323,7 +323,7 @@ To this: use = egg:MyProject [filter:translogger] - paste.filter_app_factory = egg:Paste#translogger + use = egg:Paste#translogger setup_console_handler = False [pipeline:main] -- cgit v1.2.3 From cfb2b5596b8ef366aeef3bce5b61eafc7a2f175d Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Thu, 6 Oct 2011 03:05:29 -0400 Subject: remove all reference to the paster command-line utility --- docs/narr/logging.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/narr/logging.rst') diff --git a/docs/narr/logging.rst b/docs/narr/logging.rst index 3e39151a3..b18fefae0 100644 --- a/docs/narr/logging.rst +++ b/docs/narr/logging.rst @@ -32,13 +32,13 @@ format used as the Python `logging module's Configuration file format `_. The application-related and logging-related sections in the configuration file can coexist peacefully, and the logging-related sections in the file are used -from when you run ``paster serve``. +from when you run ``pserve``. -The ``paster serve`` command calls the `logging.fileConfig function +The ``pserve`` command calls the `logging.fileConfig function `_ using the specified ini file if it contains a ``[loggers]`` section (all of the scaffold-generated ``.ini`` files do). ``logging.fileConfig`` reads the -logging configuration from the ini file upon which ``paster serve`` was +logging configuration from the ini file upon which ``pserve`` was invoked. Default logging configuration is provided in both the default @@ -89,7 +89,7 @@ project. For instance, if you do: .. code-block:: text :linenos: - paster create -t pyramid_starter MyApp + pcreate -s starter MyApp The logging configuration will literally be: -- cgit v1.2.3 From f75a3f07b0a5699f99b89d93b4e3a66beea21ac1 Mon Sep 17 00:00:00 2001 From: Chris Davies Date: Thu, 1 Dec 2011 01:57:41 -0500 Subject: https://docs.pylonsproject.org to http://docs.pylonsproject.org as readthedocs.org doesn't support https --- docs/narr/logging.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/logging.rst') diff --git a/docs/narr/logging.rst b/docs/narr/logging.rst index 5377d0c66..f9f72270f 100644 --- a/docs/narr/logging.rst +++ b/docs/narr/logging.rst @@ -291,7 +291,7 @@ Logging Exceptions To log (or email) exceptions generated by your :app:`Pyramid` application, use the :term:`pyramid_exclog` package. Details about its configuration are in its `documentation -`_. +`_. Request Logging with Paste's TransLogger ---------------------------------------- -- cgit v1.2.3 From d3ce2b6187977608ff0c460ae47aebd04b216679 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sat, 10 Dec 2011 22:39:47 -0500 Subject: update startup chapter against new scaffolding --- docs/narr/logging.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/narr/logging.rst') diff --git a/docs/narr/logging.rst b/docs/narr/logging.rst index f9f72270f..044655c1f 100644 --- a/docs/narr/logging.rst +++ b/docs/narr/logging.rst @@ -16,6 +16,8 @@ how to send log messages to loggers that you've configured. a third-party scaffold which does not create these files, the configuration information in this chapter will not be applicable. +.. _logging_config: + Logging Configuration --------------------- -- cgit v1.2.3 From 0487d5e05dd61d6d7482212d40fb5884e06f582a Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Tue, 12 Jun 2012 11:18:37 -0500 Subject: docs reference setup_logging instead of fileConfig --- docs/narr/logging.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) (limited to 'docs/narr/logging.rst') diff --git a/docs/narr/logging.rst b/docs/narr/logging.rst index 044655c1f..f4c38abb6 100644 --- a/docs/narr/logging.rst +++ b/docs/narr/logging.rst @@ -14,7 +14,7 @@ how to send log messages to loggers that you've configured. which help configure logging. All of the scaffolds which ship along with :app:`Pyramid` do this. If you're not using a scaffold, or if you've used a third-party scaffold which does not create these files, the - configuration information in this chapter will not be applicable. + configuration information in this chapter may not be applicable. .. _logging_config: @@ -36,10 +36,11 @@ application-related and logging-related sections in the configuration file can coexist peacefully, and the logging-related sections in the file are used from when you run ``pserve``. -The ``pserve`` command calls the `logging.fileConfig function +The ``pserve`` command calls the :func:`pyramid.paster.setup_logging` +function, a thin wrapper around the `logging.fileConfig `_ using the specified ini file if it contains a ``[loggers]`` section (all of the -scaffold-generated ``.ini`` files do). ``logging.fileConfig`` reads the +scaffold-generated ``.ini`` files do). ``setup_logging`` reads the logging configuration from the ini file upon which ``pserve`` was invoked. -- cgit v1.2.3 From 78080559e7add3203fbba64c03f2ae7d348cebb9 Mon Sep 17 00:00:00 2001 From: David Beitey Date: Thu, 28 Feb 2013 10:44:57 +1000 Subject: Update & clarify logging documentation Ensure that ``handlers`` is highlighted to be modified when adding an access log handler. --- docs/narr/logging.rst | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) (limited to 'docs/narr/logging.rst') diff --git a/docs/narr/logging.rst b/docs/narr/logging.rst index f4c38abb6..f4d1d051d 100644 --- a/docs/narr/logging.rst +++ b/docs/narr/logging.rst @@ -350,7 +350,7 @@ called with no arguments, so it 'just works' in environments that don't configure logging. Since we've configured our own logging handlers, we need to disable that option via ``setup_console_handler = False``. -With the filter in place, TransLogger's logger (named the 'wsgi' logger) will +With the filter in place, TransLogger's logger (named the ``wsgi`` logger) will propagate its log messages to the parent logger (the root logger), sending its output to the console when we request a page: @@ -364,14 +364,18 @@ its output to the console when we request a page: Firefox/2.0.0.6" To direct TransLogger to an ``access.log`` FileHandler, we need to add that -FileHandler to the wsgi logger's list of handlers: +FileHandler to the list of handlers (named ``accesslog``), and ensure that the +``wsgi`` logger is configured and uses this handler accordingly: .. code-block:: ini # Begin logging configuration - [loggers] - keys = root, myapp, wsgi + [loggers] + keys = root, myapp, wsgi + + [handlers] + keys = console, accesslog [logger_wsgi] level = INFO @@ -387,20 +391,19 @@ FileHandler to the wsgi logger's list of handlers: As mentioned above, non-root loggers by default propagate their log records to the root logger's handlers (currently the console handler). Setting -``propagate`` to 0 (false) here disables this; so the ``wsgi`` logger directs -its records only to the ``accesslog`` handler. +``propagate`` to ``0`` (``False``) here disables this; so the ``wsgi`` logger +directs its records only to the ``accesslog`` handler. Finally, there's no need to use the ``generic`` formatter with TransLogger as TransLogger itself provides all the information we need. We'll use a -formatter that passes-through the log messages as is: +formatter that passes-through the log messages as is. Add a new formatter +called ``accesslog`` by include the following in your configuration file: .. code-block:: ini [formatters] keys = generic, accesslog -.. code-block:: ini - [formatter_accesslog] format = %(message)s -- cgit v1.2.3 From 32c508a8d8870e877dd6d98e717e55b56457de8a Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sat, 16 Feb 2013 21:50:53 +0200 Subject: use cross-references to fix some links Also fix grammar, and add a bit of consistency regarding formatting. --- docs/narr/logging.rst | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) (limited to 'docs/narr/logging.rst') diff --git a/docs/narr/logging.rst b/docs/narr/logging.rst index f4d1d051d..bef9d119c 100644 --- a/docs/narr/logging.rst +++ b/docs/narr/logging.rst @@ -28,19 +28,17 @@ application. In particular, the :term:`PasteDeploy` ``development.ini`` and ``production.ini`` files created when you use a scaffold include a basic configuration for the Python :mod:`logging` package. -PasteDeploy ``.ini`` files use the Python standard library `ConfigParser -format `_; this the same -format used as the Python `logging module's Configuration file format -`_. The -application-related and logging-related sections in the configuration file +PasteDeploy ``.ini`` files use the Python standard library :mod:`ConfigParser +format `; this is the same format used as the Python +:ref:`logging module's Configuration file format `. +The application-related and logging-related sections in the configuration file can coexist peacefully, and the logging-related sections in the file are used from when you run ``pserve``. The ``pserve`` command calls the :func:`pyramid.paster.setup_logging` -function, a thin wrapper around the `logging.fileConfig -`_ using the specified -ini file if it contains a ``[loggers]`` section (all of the -scaffold-generated ``.ini`` files do). ``setup_logging`` reads the +function, a thin wrapper around the :func:`logging.config.fileConfig` +using the specified ``.ini`` file if it contains a ``[loggers]`` section +(all of the scaffold-generated ``.ini`` files do). ``setup_logging`` reads the logging configuration from the ini file upon which ``pserve`` was invoked. -- cgit v1.2.3 From ea87985307731d1ad8597a8e37b7fb9c7950f11f Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sat, 16 Feb 2013 22:32:07 +0200 Subject: missing word --- docs/narr/logging.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/logging.rst') diff --git a/docs/narr/logging.rst b/docs/narr/logging.rst index f4d1d051d..6492bf371 100644 --- a/docs/narr/logging.rst +++ b/docs/narr/logging.rst @@ -334,7 +334,7 @@ To this: mypyramidapp Using PasteDeploy this way to form and serve a pipeline is equivalent to -wrapping your app in a TransLogger instance via the bottom the ``main`` +wrapping your app in a TransLogger instance via the bottom of the ``main`` function of your project's ``__init__`` file: .. code-block:: python -- cgit v1.2.3 From 5e63681b1ee7da70e3249509f639b04701e76669 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sat, 16 Feb 2013 21:32:36 +0200 Subject: better to use a cross-reference --- docs/narr/logging.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/narr/logging.rst') diff --git a/docs/narr/logging.rst b/docs/narr/logging.rst index f4d1d051d..36f41562a 100644 --- a/docs/narr/logging.rst +++ b/docs/narr/logging.rst @@ -22,8 +22,8 @@ Logging Configuration --------------------- A :app:`Pyramid` project created from a :term:`scaffold` is configured to -allow you to send messages to `Python standard library logging package -`_ loggers from within your +allow you to send messages to :mod:`Python standard library logging package +` loggers from within your application. In particular, the :term:`PasteDeploy` ``development.ini`` and ``production.ini`` files created when you use a scaffold include a basic configuration for the Python :mod:`logging` package. -- cgit v1.2.3 From 37607c3a9382de7c3757799791a91b80e2d9888d Mon Sep 17 00:00:00 2001 From: Catalin Iacob Date: Sun, 31 Mar 2013 14:33:24 +0200 Subject: Consistently link middleware term to the glossary --- docs/narr/logging.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/narr/logging.rst') diff --git a/docs/narr/logging.rst b/docs/narr/logging.rst index 3b903be4d..b3bfb8a1e 100644 --- a/docs/narr/logging.rst +++ b/docs/narr/logging.rst @@ -298,14 +298,14 @@ Request Logging with Paste's TransLogger ---------------------------------------- Paste provides the `TransLogger -`_ middleware for logging -requests using the `Apache Combined Log Format +`_ :term:`middleware` for +logging requests using the `Apache Combined Log Format `_. TransLogger combined with a FileHandler can be used to create an ``access.log`` file similar to Apache's. -Like any standard middleware with a Paste entry point, TransLogger can be -configured to wrap your application using ``.ini`` file syntax. First, +Like any standard :term:`middleware` with a Paste entry point, TransLogger can +be configured to wrap your application using ``.ini`` file syntax. First, rename your Pyramid ``.ini`` file's ``[app:main]`` section to ``[app:mypyramidapp]``, then add a ``[filter:translogger]`` section, then use a ``[pipeline:main]`` section file to form a WSGI pipeline with both the -- cgit v1.2.3 From 392a6c7df93b67d6889680133fda0f744970d61f Mon Sep 17 00:00:00 2001 From: Antti Haapala Date: Sun, 17 Nov 2013 00:11:37 +0200 Subject: Removed extra indentation from some examples (:linenos: should be indented with the same indentation as the rest of the code block) --- docs/narr/logging.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/logging.rst') diff --git a/docs/narr/logging.rst b/docs/narr/logging.rst index b3bfb8a1e..75428d513 100644 --- a/docs/narr/logging.rst +++ b/docs/narr/logging.rst @@ -179,7 +179,7 @@ file, simply create a logger object using the ``__name__`` builtin and call methods on it. .. code-block:: python - :linenos: + :linenos: import logging log = logging.getLogger(__name__) -- cgit v1.2.3 From 7dd856ffed7df4bec637c29f4529cabc07e5e191 Mon Sep 17 00:00:00 2001 From: LiJunjie Date: Mon, 16 Jun 2014 14:36:30 +0800 Subject: Correct handler name for logger_wsgi --- docs/narr/logging.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/logging.rst') diff --git a/docs/narr/logging.rst b/docs/narr/logging.rst index 75428d513..71029bb33 100644 --- a/docs/narr/logging.rst +++ b/docs/narr/logging.rst @@ -377,7 +377,7 @@ FileHandler to the list of handlers (named ``accesslog``), and ensure that the [logger_wsgi] level = INFO - handlers = handler_accesslog + handlers = accesslog qualname = wsgi propagate = 0 -- cgit v1.2.3 From ad76ef6ab78847ef86abf97868a32e9604aaab7e Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Fri, 8 Aug 2014 23:28:13 -0500 Subject: Link to logging configuration in the Startup chapter. The Startup chapter describes the application's .ini file. The Logging chapter describes how to configure logging with the .ini file. --- docs/narr/logging.rst | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'docs/narr/logging.rst') diff --git a/docs/narr/logging.rst b/docs/narr/logging.rst index 71029bb33..783fca932 100644 --- a/docs/narr/logging.rst +++ b/docs/narr/logging.rst @@ -294,6 +294,15 @@ use the :term:`pyramid_exclog` package. Details about its configuration are in its `documentation `_. +.. index:: + single: TransLogger + single: middleware; TransLogger + pair: configuration; middleware + single: settings; middleware + pair: .ini; middleware + +.. _request_logging_with_pastes_translogger: + Request Logging with Paste's TransLogger ---------------------------------------- -- cgit v1.2.3 From 4a63f6ac8f19d21eebf23bd8c9f833f2b676287b Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Fri, 8 Aug 2014 23:30:04 -0500 Subject: Add index entries for .ini files vis settings. --- docs/narr/logging.rst | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'docs/narr/logging.rst') diff --git a/docs/narr/logging.rst b/docs/narr/logging.rst index 783fca932..68da0813c 100644 --- a/docs/narr/logging.rst +++ b/docs/narr/logging.rst @@ -16,6 +16,11 @@ how to send log messages to loggers that you've configured. a third-party scaffold which does not create these files, the configuration information in this chapter may not be applicable. +.. index: + pair: settings; logging + pair: .ini; logging + pair: logging; configuration + .. _logging_config: Logging Configuration -- cgit v1.2.3 From dcc6b4aceb140a5b6e03b1d3b0f32d925cbe879c Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Sun, 10 Aug 2014 21:31:01 -0500 Subject: Some improvements to the paste.translogger related docs. Synchronizes with Waitress docs. --- docs/narr/logging.rst | 36 +++++++++++++++++++++--------------- 1 file changed, 21 insertions(+), 15 deletions(-) (limited to 'docs/narr/logging.rst') diff --git a/docs/narr/logging.rst b/docs/narr/logging.rst index 71029bb33..8f6c74fd4 100644 --- a/docs/narr/logging.rst +++ b/docs/narr/logging.rst @@ -297,12 +297,14 @@ in its `documentation Request Logging with Paste's TransLogger ---------------------------------------- -Paste provides the `TransLogger -`_ :term:`middleware` for -logging requests using the `Apache Combined Log Format -`_. TransLogger combined -with a FileHandler can be used to create an ``access.log`` file similar to -Apache's. +The term:`WSGI` design is modular. Waitress logs error conditions, debugging +output, etc., but not web traffic. For web traffic logging Paste provides the +`TransLogger `_ +:term:`middleware`. TransLogger produces logs in the `Apache Combined Log +Format `_. But +TransLogger does not write to files, the Python logging system must be +configured to do this. The Python FileHandler_ logging handler can be used +alongside TransLogger to create an ``access.log`` file similar to Apache's. Like any standard :term:`middleware` with a Paste entry point, TransLogger can be configured to wrap your application using ``.ini`` file syntax. First, @@ -343,10 +345,12 @@ function of your project's ``__init__`` file: app = TransLogger(app, setup_console_handler=False) return app -TransLogger will automatically setup a logging handler to the console when -called with no arguments, so it 'just works' in environments that don't -configure logging. Since we've configured our own logging handlers, we need -to disable that option via ``setup_console_handler = False``. + +.. note:: + TransLogger will automatically setup a logging handler to the console when + called with no arguments, so it 'just works' in environments that don't + configure logging. Since our logging handlers are configured we disable + the automation via ``setup_console_handler = False``. With the filter in place, TransLogger's logger (named the ``wsgi`` logger) will propagate its log messages to the parent logger (the root logger), sending @@ -361,9 +365,9 @@ its output to the console when we request a page: "Mozilla/5.0 (Macintosh; U; Intel Mac OS X; en-US; rv:1.8.1.6) Gecko/20070725 Firefox/2.0.0.6" -To direct TransLogger to an ``access.log`` FileHandler, we need to add that -FileHandler to the list of handlers (named ``accesslog``), and ensure that the -``wsgi`` logger is configured and uses this handler accordingly: +To direct TransLogger to an ``access.log`` FileHandler, we need the following +to add a FileHandler (named ``accesslog``) to the list of handlers, and ensure +that the ``wsgi`` logger is configured and uses this handler accordingly: .. code-block:: ini @@ -395,7 +399,7 @@ directs its records only to the ``accesslog`` handler. Finally, there's no need to use the ``generic`` formatter with TransLogger as TransLogger itself provides all the information we need. We'll use a formatter that passes-through the log messages as is. Add a new formatter -called ``accesslog`` by include the following in your configuration file: +called ``accesslog`` by including the following in your configuration file: .. code-block:: ini @@ -405,7 +409,9 @@ called ``accesslog`` by include the following in your configuration file: [formatter_accesslog] format = %(message)s -Then wire this new ``accesslog`` formatter into the FileHandler: + +Finally alter the existing configuration to wire this new +``accesslog`` formatter into the FileHandler: .. code-block:: ini -- cgit v1.2.3 From c4c45446f79d6647aa6a90fc1f45def1319f7ac2 Mon Sep 17 00:00:00 2001 From: Bert JW Regeer Date: Wed, 10 Sep 2014 11:15:21 -0600 Subject: Change helloworld to myapp Fix a typo in the documentation. Closes #1408 --- docs/narr/logging.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/logging.rst') diff --git a/docs/narr/logging.rst b/docs/narr/logging.rst index 71029bb33..74d9f260e 100644 --- a/docs/narr/logging.rst +++ b/docs/narr/logging.rst @@ -242,7 +242,7 @@ level is set to ``INFO``, whereas the application's log level is set to [logger_myapp] level = DEBUG handlers = - qualname = helloworld + qualname = myapp All of the child loggers of the ``myapp`` logger will inherit the ``DEBUG`` level unless they're explicitly set differently. Meaning the ``myapp.views``, -- cgit v1.2.3 From 0e4dcf9f85babd94dcd9fc59513d257b4aba8d40 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 22 Jan 2015 03:46:27 -0800 Subject: apply changes from #1538 and #1539 --- docs/narr/logging.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) (limited to 'docs/narr/logging.rst') diff --git a/docs/narr/logging.rst b/docs/narr/logging.rst index c16673ae6..921883091 100644 --- a/docs/narr/logging.rst +++ b/docs/narr/logging.rst @@ -254,16 +254,15 @@ level unless they're explicitly set differently. Meaning the ``myapp.views``, ``myapp.models`` (and all your app's modules') loggers by default have an effective level of ``DEBUG`` too. -For more advanced filtering, the logging module provides a `Filter -`_ object; however it cannot be used -directly from the configuration file. +For more advanced filtering, the logging module provides a +:class:`logging.Filter` object; however it cannot be used directly from the +configuration file. -Advanced Configuration +Advanced Configuration ---------------------- -To capture log output to a separate file, use a `FileHandler -`_ (or a `RotatingFileHandler -`_): +To capture log output to a separate file, use :class:`logging.FileHandler` (or +:class:`logging.handlers.RotatingFileHandler`): .. code-block:: ini @@ -317,8 +316,9 @@ output, etc., but not web traffic. For web traffic logging Paste provides the :term:`middleware`. TransLogger produces logs in the `Apache Combined Log Format `_. But TransLogger does not write to files, the Python logging system must be -configured to do this. The Python FileHandler_ logging handler can be used -alongside TransLogger to create an ``access.log`` file similar to Apache's. +configured to do this. The Python :class:`logging.FileHandler` logging +handler can be used alongside TransLogger to create an ``access.log`` file +similar to Apache's. Like any standard :term:`middleware` with a Paste entry point, TransLogger can be configured to wrap your application using ``.ini`` file syntax. First, -- cgit v1.2.3 From 274412c9977bb0d31f8b92080ce5b8489a3e9fd3 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 18 Oct 2015 02:32:22 -0700 Subject: minor grammar, rewrap 79 cols, .rst syntax fixes --- docs/narr/logging.rst | 310 +++++++++++++++++++++++++------------------------- 1 file changed, 152 insertions(+), 158 deletions(-) (limited to 'docs/narr/logging.rst') diff --git a/docs/narr/logging.rst b/docs/narr/logging.rst index 921883091..9c6e8a319 100644 --- a/docs/narr/logging.rst +++ b/docs/narr/logging.rst @@ -4,17 +4,17 @@ Logging ======= :app:`Pyramid` allows you to make use of the Python standard library -:mod:`logging` module. This chapter describes how to configure logging and -how to send log messages to loggers that you've configured. +:mod:`logging` module. This chapter describes how to configure logging and how +to send log messages to loggers that you've configured. .. warning:: - This chapter assumes you've used a :term:`scaffold` to create a - project which contains ``development.ini`` and ``production.ini`` files - which help configure logging. All of the scaffolds which ship along with - :app:`Pyramid` do this. If you're not using a scaffold, or if you've used - a third-party scaffold which does not create these files, the - configuration information in this chapter may not be applicable. + This chapter assumes you've used a :term:`scaffold` to create a project + which contains ``development.ini`` and ``production.ini`` files which help + configure logging. All of the scaffolds which ship with :app:`Pyramid` do + this. If you're not using a scaffold, or if you've used a third-party + scaffold which does not create these files, the configuration information in + this chapter may not be applicable. .. index: pair: settings; logging @@ -26,30 +26,29 @@ how to send log messages to loggers that you've configured. Logging Configuration --------------------- -A :app:`Pyramid` project created from a :term:`scaffold` is configured to -allow you to send messages to :mod:`Python standard library logging package -` loggers from within your -application. In particular, the :term:`PasteDeploy` ``development.ini`` and -``production.ini`` files created when you use a scaffold include a basic -configuration for the Python :mod:`logging` package. +A :app:`Pyramid` project created from a :term:`scaffold` is configured to allow +you to send messages to :mod:`Python standard library logging package +` loggers from within your application. In particular, the +:term:`PasteDeploy` ``development.ini`` and ``production.ini`` files created +when you use a scaffold include a basic configuration for the Python +:mod:`logging` package. PasteDeploy ``.ini`` files use the Python standard library :mod:`ConfigParser -format `; this is the same format used as the Python +format `. This is the same format used as the Python :ref:`logging module's Configuration file format `. The application-related and logging-related sections in the configuration file can coexist peacefully, and the logging-related sections in the file are used from when you run ``pserve``. -The ``pserve`` command calls the :func:`pyramid.paster.setup_logging` -function, a thin wrapper around the :func:`logging.config.fileConfig` -using the specified ``.ini`` file if it contains a ``[loggers]`` section -(all of the scaffold-generated ``.ini`` files do). ``setup_logging`` reads the -logging configuration from the ini file upon which ``pserve`` was -invoked. +The ``pserve`` command calls the :func:`pyramid.paster.setup_logging` function, +a thin wrapper around the :func:`logging.config.fileConfig` using the specified +``.ini`` file, if it contains a ``[loggers]`` section (all of the +scaffold-generated ``.ini`` files do). ``setup_logging`` reads the logging +configuration from the ini file upon which ``pserve`` was invoked. Default logging configuration is provided in both the default -``development.ini`` and the ``production.ini`` file. The logging -configuration in the ``development.ini`` file is as follows: +``development.ini`` and the ``production.ini`` file. The logging configuration +in the ``development.ini`` file is as follows: .. code-block:: ini :linenos: @@ -135,46 +134,44 @@ The logging configuration will literally be: In this logging configuration: -- a logger named ``root`` is created that logs messages at a level above - or equal to the ``INFO`` level to stderr, with the following format: +- a logger named ``root`` is created that logs messages at a level above or + equal to the ``INFO`` level to stderr, with the following format: - .. code-block:: text + .. code-block:: text - 2007-08-17 15:04:08,704 INFO [packagename] - Loading resource, id: 86 + 2007-08-17 15:04:08,704 INFO [packagename] Loading resource, id: 86 - a logger named ``myapp`` is configured that logs messages sent at a level - above or equal to ``DEBUG`` to stderr in the same format as the root - logger. + above or equal to ``DEBUG`` to stderr in the same format as the root logger. The ``root`` logger will be used by all applications in the Pyramid process -that ask for a logger (via ``logging.getLogger``) that has a name which -begins with anything except your project's package name (e.g. ``myapp``). -The logger with the same name as your package name is reserved for your own -usage in your Pyramid application. Its existence means that you can log to a -known logging location from any Pyramid application generated via a scaffold. - -Pyramid and many other libraries (such as Beaker, SQLAlchemy, Paste) log a -number of messages to the root logger for debugging purposes. Switching the +that ask for a logger (via ``logging.getLogger``) that has a name which begins +with anything except your project's package name (e.g., ``myapp``). The logger +with the same name as your package name is reserved for your own usage in your +:app:`Pyramid` application. Its existence means that you can log to a known +logging location from any :app:`Pyramid` application generated via a scaffold. + +:app:`Pyramid` and many other libraries (such as Beaker, SQLAlchemy, Paste) log +a number of messages to the root logger for debugging purposes. Switching the root logger level to ``DEBUG`` reveals them: -.. code-block:: ini +.. code-block:: ini - [logger_root] - #level = INFO - level = DEBUG - handlers = console + [logger_root] + #level = INFO + level = DEBUG + handlers = console -Some scaffolds configure additional loggers for additional subsystems they -use (such as SQLALchemy). Take a look at the ``production.ini`` and +Some scaffolds configure additional loggers for additional subsystems they use +(such as SQLALchemy). Take a look at the ``production.ini`` and ``development.ini`` files rendered when you create a project from a scaffold. Sending Logging Messages ------------------------ Python's special ``__name__`` variable refers to the current module's fully -qualified name. From any module in a package named ``myapp``, the -``__name__`` builtin variable will always be something like ``myapp``, or +qualified name. From any module in a package named ``myapp``, the ``__name__`` +builtin variable will always be something like ``myapp``, or ``myapp.subpackage`` or ``myapp.package.subpackage`` if your project is named ``myapp``. Sending a message to this logger will send it to the ``myapp`` logger. @@ -183,75 +180,75 @@ To log messages to the package-specific logger configured in your ``.ini`` file, simply create a logger object using the ``__name__`` builtin and call methods on it. -.. code-block:: python +.. code-block:: python :linenos: - import logging - log = logging.getLogger(__name__) + import logging + log = logging.getLogger(__name__) def myview(request): - content_type = 'text/plain' - content = 'Hello World!' - log.debug('Returning: %s (content-type: %s)', content, content_type) - request.response.content_type = content_type + content_type = 'text/plain' + content = 'Hello World!' + log.debug('Returning: %s (content-type: %s)', content, content_type) + request.response.content_type = content_type return request.response -This will result in the following printed to the console, on ``stderr``: +This will result in the following printed to the console, on ``stderr``: -.. code-block:: text +.. code-block:: text 16:20:20,440 DEBUG [myapp.views] Returning: Hello World! - (content-type: text/plain) + (content-type: text/plain) Filtering log messages ---------------------- -Often there's too much log output to sift through, such as when switching -the root logger's level to ``DEBUG``. +Often there's too much log output to sift through, such as when switching the +root logger's level to ``DEBUG``. -An example: you're diagnosing database connection issues in your application +For example, you're diagnosing database connection issues in your application and only want to see SQLAlchemy's ``DEBUG`` messages in relation to database connection pooling. You can leave the root logger's level at the less verbose ``INFO`` level and set that particular SQLAlchemy logger to ``DEBUG`` on its own, apart from the root logger: -.. code-block:: ini +.. code-block:: ini - [logger_sqlalchemy.pool] - level = DEBUG - handlers = - qualname = sqlalchemy.pool + [logger_sqlalchemy.pool] + level = DEBUG + handlers = + qualname = sqlalchemy.pool -then add it to the list of loggers: +then add it to the list of loggers: -.. code-block:: ini +.. code-block:: ini - [loggers] - keys = root, myapp, sqlalchemy.pool + [loggers] + keys = root, myapp, sqlalchemy.pool -No handlers need to be configured for this logger as by default non root -loggers will propagate their log records up to their parent logger's -handlers. The root logger is the top level parent of all loggers. +No handlers need to be configured for this logger as by default non-root +loggers will propagate their log records up to their parent logger's handlers. +The root logger is the top level parent of all loggers. This technique is used in the default ``development.ini``. The root logger's level is set to ``INFO``, whereas the application's log level is set to ``DEBUG``: -.. code-block:: ini +.. code-block:: ini - # Begin logging configuration + # Begin logging configuration - [loggers] + [loggers] keys = root, myapp - [logger_myapp] - level = DEBUG - handlers = - qualname = myapp + [logger_myapp] + level = DEBUG + handlers = + qualname = myapp All of the child loggers of the ``myapp`` logger will inherit the ``DEBUG`` level unless they're explicitly set differently. Meaning the ``myapp.views``, -``myapp.models`` (and all your app's modules') loggers by default have an +``myapp.models``, and all your app's modules' loggers by default have an effective level of ``DEBUG`` too. For more advanced filtering, the logging module provides a @@ -264,39 +261,38 @@ Advanced Configuration To capture log output to a separate file, use :class:`logging.FileHandler` (or :class:`logging.handlers.RotatingFileHandler`): -.. code-block:: ini +.. code-block:: ini - [handler_filelog] - class = FileHandler - args = ('%(here)s/myapp.log','a') - level = INFO - formatter = generic + [handler_filelog] + class = FileHandler + args = ('%(here)s/myapp.log','a') + level = INFO + formatter = generic -Before it's recognized, it needs to be added to the list of handlers: +Before it's recognized, it needs to be added to the list of handlers: -.. code-block:: ini +.. code-block:: ini - [handlers] + [handlers] keys = console, myapp, filelog -and finally utilized by a logger. +and finally utilized by a logger. -.. code-block:: ini +.. code-block:: ini - [logger_root] - level = INFO + [logger_root] + level = INFO handlers = console, filelog -These final 3 lines of configuration directs all of the root logger's output +These final three lines of configuration direct all of the root logger's output to the ``myapp.log`` as well as the console. Logging Exceptions ------------------ -To log (or email) exceptions generated by your :app:`Pyramid` application, -use the :term:`pyramid_exclog` package. Details about its configuration are -in its `documentation -`_. +To log or email exceptions generated by your :app:`Pyramid` application, use +the :term:`pyramid_exclog` package. Details about its configuration are in its +`documentation `_. .. index:: single: TransLogger @@ -307,40 +303,40 @@ in its `documentation .. _request_logging_with_pastes_translogger: -Request Logging with Paste's TransLogger +Request Logging with Paste's TransLogger ---------------------------------------- -The term:`WSGI` design is modular. Waitress logs error conditions, debugging -output, etc., but not web traffic. For web traffic logging Paste provides the +The :term:`WSGI` design is modular. Waitress logs error conditions, debugging +output, etc., but not web traffic. For web traffic logging, Paste provides the `TransLogger `_ :term:`middleware`. TransLogger produces logs in the `Apache Combined Log Format `_. But -TransLogger does not write to files, the Python logging system must be -configured to do this. The Python :class:`logging.FileHandler` logging -handler can be used alongside TransLogger to create an ``access.log`` file -similar to Apache's. +TransLogger does not write to files; the Python logging system must be +configured to do this. The Python :class:`logging.FileHandler` logging handler +can be used alongside TransLogger to create an ``access.log`` file similar to +Apache's. Like any standard :term:`middleware` with a Paste entry point, TransLogger can -be configured to wrap your application using ``.ini`` file syntax. First, +be configured to wrap your application using ``.ini`` file syntax. First rename your Pyramid ``.ini`` file's ``[app:main]`` section to -``[app:mypyramidapp]``, then add a ``[filter:translogger]`` section, then use -a ``[pipeline:main]`` section file to form a WSGI pipeline with both the +``[app:mypyramidapp]``, then add a ``[filter:translogger]`` section, then use a +``[pipeline:main]`` section file to form a WSGI pipeline with both the translogger and your application in it. For instance, change from this: -.. code-block:: ini +.. code-block:: ini [app:main] use = egg:MyProject To this: -.. code-block:: ini +.. code-block:: ini [app:mypyramidapp] use = egg:MyProject - [filter:translogger] - use = egg:Paste#translogger + [filter:translogger] + use = egg:Paste#translogger setup_console_handler = False [pipeline:main] @@ -351,41 +347,40 @@ Using PasteDeploy this way to form and serve a pipeline is equivalent to wrapping your app in a TransLogger instance via the bottom of the ``main`` function of your project's ``__init__`` file: -.. code-block:: python +.. code-block:: python ... app = config.make_wsgi_app() - from paste.translogger import TransLogger - app = TransLogger(app, setup_console_handler=False) - return app - + from paste.translogger import TransLogger + app = TransLogger(app, setup_console_handler=False) + return app .. note:: TransLogger will automatically setup a logging handler to the console when - called with no arguments, so it 'just works' in environments that don't - configure logging. Since our logging handlers are configured we disable + called with no arguments, so it "just works" in environments that don't + configure logging. Since our logging handlers are configured, we disable the automation via ``setup_console_handler = False``. With the filter in place, TransLogger's logger (named the ``wsgi`` logger) will -propagate its log messages to the parent logger (the root logger), sending -its output to the console when we request a page: +propagate its log messages to the parent logger (the root logger), sending its +output to the console when we request a page: -.. code-block:: text +.. code-block:: text 00:50:53,694 INFO [myapp.views] Returning: Hello World! - (content-type: text/plain) + (content-type: text/plain) 00:50:53,695 INFO [wsgi] 192.168.1.111 - - [11/Aug/2011:20:09:33 -0700] "GET /hello - HTTP/1.1" 404 - "-" + HTTP/1.1" 404 - "-" "Mozilla/5.0 (Macintosh; U; Intel Mac OS X; en-US; rv:1.8.1.6) Gecko/20070725 - Firefox/2.0.0.6" + Firefox/2.0.0.6" To direct TransLogger to an ``access.log`` FileHandler, we need the following to add a FileHandler (named ``accesslog``) to the list of handlers, and ensure that the ``wsgi`` logger is configured and uses this handler accordingly: -.. code-block:: ini +.. code-block:: ini - # Begin logging configuration + # Begin logging configuration [loggers] keys = root, myapp, wsgi @@ -393,44 +388,43 @@ that the ``wsgi`` logger is configured and uses this handler accordingly: [handlers] keys = console, accesslog - [logger_wsgi] - level = INFO + [logger_wsgi] + level = INFO handlers = accesslog - qualname = wsgi - propagate = 0 - - [handler_accesslog] - class = FileHandler - args = ('%(here)s/access.log','a') - level = INFO - formatter = generic - -As mentioned above, non-root loggers by default propagate their log records -to the root logger's handlers (currently the console handler). Setting -``propagate`` to ``0`` (``False``) here disables this; so the ``wsgi`` logger + qualname = wsgi + propagate = 0 + + [handler_accesslog] + class = FileHandler + args = ('%(here)s/access.log','a') + level = INFO + formatter = generic + +As mentioned above, non-root loggers by default propagate their log records to +the root logger's handlers (currently the console handler). Setting +``propagate`` to ``0`` (``False``) here disables this; so the ``wsgi`` logger directs its records only to the ``accesslog`` handler. Finally, there's no need to use the ``generic`` formatter with TransLogger as -TransLogger itself provides all the information we need. We'll use a -formatter that passes-through the log messages as is. Add a new formatter -called ``accesslog`` by including the following in your configuration file: - -.. code-block:: ini +TransLogger itself provides all the information we need. We'll use a formatter +that passes through the log messages as is. Add a new formatter called +``accesslog`` by including the following in your configuration file: - [formatters] - keys = generic, accesslog +.. code-block:: ini - [formatter_accesslog] - format = %(message)s + [formatters] + keys = generic, accesslog + [formatter_accesslog] + format = %(message)s -Finally alter the existing configuration to wire this new -``accesslog`` formatter into the FileHandler: +Finally alter the existing configuration to wire this new ``accesslog`` +formatter into the FileHandler: -.. code-block:: ini +.. code-block:: ini - [handler_accesslog] - class = FileHandler - args = ('%(here)s/access.log','a') - level = INFO - formatter = accesslog + [handler_accesslog] + class = FileHandler + args = ('%(here)s/access.log','a') + level = INFO + formatter = accesslog -- cgit v1.2.3