{ "info": { "author": "Kevin L. Mitchell", "author_email": "kevin.mitchell@rackspace.com", "bugtrack_url": null, "classifiers": [ "Development Status :: 4 - Beta", "Environment :: Web Environment", "Framework :: Paste", "Intended Audience :: System Administrators", "License :: OSI Approved :: Apache Software License", "Operating System :: OS Independent", "Programming Language :: Python", "Topic :: Internet :: WWW/HTTP :: WSGI :: Middleware" ], "description": "====================================\nApache-compatible Logging Middleware\n====================================\n\nBark is a piece of WSGI middleware that performs logging, using log\nformat strings compatible with Apache.\n\nInstalling Bark\n===============\n\nBark can be easily installed like many Python packages, using `PIP`_::\n\n pip install bark\n\nYou can install the dependencies required by Bark by issuing the\nfollowing command::\n\n pip install -r .requires\n\nFrom within your Bark source directory.\n\nIf you would like to run the tests, you can install the additional\ntest dependencies in the same way::\n\n pip install -r .test-requires\n\nAdding and Configuring Bark\n===========================\n\nBark is intended for use with PasteDeploy-style configuration files.\nIt is a filter, and should be placed at the head of the WSGI pipeline,\nso that the log format can access the information necessary to\ngenerate the logs.\n\nThe filter section of the PasteDeploy configuration file will also\nneed to contain enough information to tell Bark how to generate the\nlog file(s). The simplest example of Bark configuration would be::\n\n [filter:bark]\n use = egg:bark#bark\n log1.filename = /var/log/bark.log\n log1.format = %h %l %u %t \"%r\" %s %b\n\nThe ``use`` configuration option is interpreted by PasteDeploy. Bark\nunderstands a ``config`` option, which instructs Bark to additionally\nread a named INI-style configuration file. (Configuration options\nappearing in the PasteDeploy configuration file will override those\noptions appearing in this alternate configuration file.)\n\nAll other configuration options are given dotted names in the\nPasteDeploy configuration file; the first element before the '.'\ncorresponds to a section in the alternate configuration file, and the\nremainder of the name is the full name of the option. For instance,\nexpressing the configuration shown above in an alternate configuration\nfile would result in::\n\n [log1]\n filename = /var/log/bark.log\n format = %h %l %u %t \"%r\" %s %b\n\nThe corresponding PasteDeploy configuration would look like the\nfollowing example, assuming that the alternate configuration was\nstored in \"/etc/bark/bark.ini\"::\n\n [filter:bark]\n use = egg:bark#bark\n config = /etc/bark/bark.ini\n\nIf it was desired to use this configuration file, but to override the\nlog file name--e.g., for a test instance of the application--all\nthat's needed is a PasteDeploy configuration as follows::\n\n [filter:bark]\n use = egg:bark#bark\n config = /etc/bark/bark.ini\n log1.filename = /var/log/bark-test.log\n\nStructure of the Configuration File\n-----------------------------------\n\nEach section in Bark's configuration describes a single log stream\n(with the exception of the ``[proxies]`` section; see below). Each\nsection must have a ``format`` configuration option, which must have\nan Apache-compatible format string. Each section also has a ``type``\noption, which expresses the type of the log stream; this defaults to\nthe \"file\" log stream type. Any other options in this section are\npassed to a handler factory for the log stream type; most handlers\nhave other mandatory arguments, such as the ``filename`` option for\nthe \"file\" log stream type.\n\nWhen the Bark middleware processes a request, each of the configured\nlog streams will be sent a message formatted according to the\nconfigured format string. (Note that there is no guarantee of\nordering of these log messages; the ordering could, in principle, be\ndifferent for each request.) The Bark middleware should be the first\nfilter in the processing pipeline, particularly if the \"%D\" or \"%T\"\nconversions are used in the format string. (These conversions format\nthe total time taken for the request to be processed by the\napplication.)\n\nAvailable Handlers\n------------------\n\nBark ships with 13 defined log stream types, documented below along\nwith the configuration options recognized or required by each. Note\nthat most of these log stream types actually derive from handlers\ndefined by the Python standard ``logging`` library.\n\n``null``\n~~~~~~~~\n\nThe ``null`` log stream type has no recognized configuration options.\nLog messages for this log stream type are discarded without being\nrecorded anywhere. This could be used to temporarily disable a log\nstream. (As with all log stream types, unrecognized configuration\noptions only generate a warning, logged via the Python standard\nlogging library.)\n\n``stdout``\n~~~~~~~~~~\n\nThe ``stdout`` log stream type has no recognized configuration\noptions, and log messages are simply emitted to the program's standard\noutput stream.\n\n``stderr``\n~~~~~~~~~~\n\nThe ``stderr`` log stream type, similar to the ``stdout`` log stream\ntype, has no recognized configuration options, and log messages are\nsimply emitted to the program's standard error stream.\n\n``file``\n~~~~~~~~\n\nThe ``file`` log stream type is used for logging messages to a\nspecified file. It has the following recognized configuration\noptions:\n\n``filename``\n Required. The name of the file to which log messages should be\n emitted.\n\n``mode``\n Optional. A string representing the opening mode for the file\n stream. Defaults to \"a\".\n\n``encoding``\n Optional. The name of the character encoding to use when writing\n messages to the file stream.\n\n``delay``\n Optional. A boolean value indicating when the file stream should\n be opened. If \"false\" (the default), the file stream will be\n opened immediately, whereas if \"true\", the file stream will not be\n opened until the first log message is emitted.\n\n``watched_file``\n~~~~~~~~~~~~~~~~\n\nThe ``watched_file`` log stream type is identical to the ``file`` log\nstream type, including the recognized configuration options. It adds\nthe behavior of closing and reopening the file if the file has changed\nsince the last log message was written. This may be used to support\nexternal log file rotation systems, such as logrotate.\n\n``filename``\n Required. The name of the file to which log messages should be\n emitted.\n\n``mode``\n Optional. A string representing the opening mode for the file\n stream. Defaults to \"a\".\n\n``encoding``\n Optional. The name of the character encoding to use when writing\n messages to the file stream.\n\n``delay``\n Optional. A boolean value indicating when the file stream should\n be opened. If \"false\" (the default), the file stream will be\n opened immediately, whereas if \"true\", the file stream will not be\n opened until the first log message is emitted.\n\n``rotating_file``\n~~~~~~~~~~~~~~~~~\n\nThe ``rotating_file`` log stream type is similar to the ``file`` log\nstream type, in that log messages are emitted to a file. However,\n``rotating_file`` log streams watch the size of the file, and rotate\nthe file (under control of the ``backupCount`` configuration option)\nwhen the file approaches a configured maximum size.\n\n``filename``\n Required. The name of the file to which log messages should be\n emitted.\n\n``mode``\n Optional. A string representing the opening mode for the file\n stream. Defaults to \"a\".\n\n``maxBytes``\n The maximum size the file should be allowed to grow to.\n\n``backupCount``\n The maximum number of previous versions of the log file to\n maintain in the rotation process. Log files beyond\n ``backupCount`` are deleted.\n\n``encoding``\n Optional. The name of the character encoding to use when writing\n messages to the file stream.\n\n``delay``\n Optional. A boolean value indicating when the file stream should\n be opened. If \"false\" (the default), the file stream will be\n opened immediately, whereas if \"true\", the file stream will not be\n opened until the first log message is emitted.\n\n``timed_rotating_file``\n~~~~~~~~~~~~~~~~~~~~~~~\n\nThe ``timed_rotating_file`` log stream type is similar to the ``file``\nlog stream type--in that log messages are emitted to a file--and to\nthe ``rotating_file`` log stream type--in that log files are rotated.\nHowever, the rotation occurs at a defined time interval, rather than\naccording to a maximum size for the file. For a full explanation of\nhow this log stream type is configured, see the Python documentation\nfor `TimedRotatingFileHandler`_.\n\n``filename``\n Required. The name of the file to which log messages should be\n emitted.\n\n``when``\n A string indicating how to interpret the ``interval``\n configuration value. See the documentation for\n `TimedRotatingFileHandler`_ for a full discussion of the possible\n values of this configuration option. Defaults to \"h\".\n\n``interval``\n The length of the interval, as modified by ``when``. For\n instance, if this value is \"3\" and ``when`` is set to \"h\", then\n the file will be rotated every 3 hours.\n\n``backupCount``\n The maximum number of previous versions of the log file to\n maintain in the rotation process. Log files beyond\n ``backupCount`` are deleted.\n\n``encoding``\n Optional. The name of the character encoding to use when writing\n messages to the file stream.\n\n``delay``\n Optional. A boolean value indicating when the file stream should\n be opened. If \"false\" (the default), the file stream will be\n opened immediately, whereas if \"true\", the file stream will not be\n opened until the first log message is emitted.\n\n``utc``\n Optional. A boolean value indicating whether to use UTC-based\n times for time interval determination. If \"false\" (the default),\n the local time will be used, whereas if \"true\", UTC will be used.\n\n``socket``\n~~~~~~~~~~\n\nThe ``socket`` log stream type causes a log message to be submitted\nvia a TCP socket to a server listening on a configured host and port.\nThe log message will be sent as a pickled dictionary, derived from a\n``logging.LogRecord`` instance. This is compatible with the standard\n`SocketHandler`_.\n\n``host``\n Required. The host to which to submit the log message.\n\n``port``\n Required. The TCP port number on the host to which to submit the\n log message.\n\n``datagram``\n~~~~~~~~~~~~\n\nThe ``datagram`` log stream type causes a log message to be submitted\nvia a UDP datagram to a server listening on a configured host and\nport. The log message will be sent as a pickled dictionary, derived\nfrom a ``logging.LogRecord`` instance. This is compatible with the\nstandard `DatagramHandler`_.\n\n``host``\n Required. The host to which to submit the log message.\n\n``port``\n Required. The UDP port number on the host to which to submit the\n log message.\n\n``syslog``\n~~~~~~~~~~\n\nThe ``syslog`` log stream type causes a log message to be submitted to\na SysLog server, listening on a specified address.\n\n``address``\n Optional. The address of the SysLog server. For local servers\n listening on a UNIX datagram socket, this may be a path name for\n that socket. For servers listening on a UDP port, this must be\n the host name and port number of the server, separated by a colon.\n If not given, defaults to \"localhost:514\".\n\n``facility``\n Optional. The name of a SysLog facility, such as \"user\",\n \"local0\", etc. Defaults to \"user\".\n\n``nt_event_log``\n~~~~~~~~~~~~~~~~\n\nThe ``nt_event_log`` log stream type causes a log message to be\nsubmitted to the NT event log. See the documentation for the\n`NTEventLogHandler`_ for more information.\n\n``appname``\n Required. The application name to log under.\n\n``dllname``\n Optional. Should give the fully qualified pathname of a .dll or\n .exe which contains message definitions to hold in the log.\n Defaults to ``win32service.pyd``.\n\n``logtype``\n Optional. One of \"Application\", \"System\", or \"Security\".\n Defaults to \"Application\".\n\n``smtp``\n~~~~~~~~\n\nThe ``smtp`` log stream type causes a log message to be emitted via an\nemail to a specified destination address or list of addresses.\nCompatible with `SMTPHandler`_.\n\n``mailhost``\n Required. The hostname for the mail server. If a non-standard\n SMTP port is used, separate it from the hostname with a colon.\n\n``fromaddr``\n Required. The email address the email should appear to come from.\n\n``toaddrs``\n Required. A comma-separated list of email addresses to which the\n mail should be sent.\n\n``subject``\n Required. The text to include in the \"Subject\" header of the\n email message.\n\n``credentials``\n Optional. A username and password (separated by a colon) to use\n to authenticate with the SMTP server. If not provided, no\n authentication exchange is performed.\n\n``http``\n~~~~~~~~\n\nThe ``http`` log stream type causes a log message to be emitted via a\nGET or POST request to web server. Compatible with `HTTPHandler`_.\n\n``host``\n Required. The hostname of the web server. If a non-standard port\n number must be specified, separate it from the hostname with a\n colon.\n\n``url``\n Required. The URL to which to submit the log message.\n\n``method``\n Optional. The HTTP method to use to submit the log message. May\n be either \"GET\" or \"POST\". Defaults to \"GET\".\n\nProxy Configuration\n-------------------\n\nThe \"%a\" format string conversion specification allows for Bark to log\nthe IP address of a client connection. However, what happens if the\nconnection is redirected through a proxy? Proxies usually embed\ninformation about the original client connection in a request header,\nsuch as the \"X-Forwarded-For\" header, so the information is available.\nHowever, to prevent a user from spoofing the originating IP address,\nthis header must be validated.\n\nBark includes a proxy validation system, which can be configured\nthrough the special ``[proxies]`` section of the configuration. This\nsection contains one required configuration setting, namely,\n``header``; this configuration tells Bark which header to use (e.g.,\n\"X-Forwarded-For\").\n\nIf ``header`` is the only configuration value set, then that header\nwill be trusted for all connections, which is obviously a security\nproblem. To combat this, the list of trusted proxy IP addresses may\nbe specified through the ``proxies`` configuration value, which must\nbe a comma-separated list of IP addresses (note: not hostnames!).\n\nEach proxy may be further restricted as to the IP addresses of the\nclients it may introduce. To do this, use the IP address of the proxy\nas a configuration key; the value must be a comma-separated list of IP\naddresses or CIDR expressions which that proxy is permitted to\nintroduce clients from.\n\nFor more advanced users, there are some advanced ways of expressing\nproxies and permitted client addresses. By default, no proxy may\nintroduce a client from an internal address (e.g., 10.0.5.23), but is\nallowed to introduce a client from any public address; this may be\nmodified by using the \"internal()\" modifier, which allows internal\naddresses, or the \"restrict()\" modifier, which requires that an IP\naddress be specifically permitted to a proxy to allow it to introduce\na client from that address. For instance, consider the following\nconfiguration::\n\n [proxies]\n header = x-forwarded-for\n proxies = 10.5.21.1\n\nIn this configuration, the proxy 10.5.21.1 may introduce a client\nfrom, say, 207.97.209.147; however, a client from 10.3.15.127 may not\nbe introduced. If we wish to allow this proxy to introduce\n10.3.15.127, we would need the following configuration::\n\n [proxies]\n header = x-forwarded-for\n proxies = internal(10.5.21.1)\n\nIf, on the other hand, the proxy 10.5.21.1 should only be able to\nintroduce clients from 10.3.15.0/24, and not be permitted to introduce\na client from 207.97.209.147, this is the configuration we would\nneed::\n\n [proxies]\n header = x-forwarded-for\n proxies = restrict(10.5.21.1)\n 10.5.21.1 = 10.3.15.0/24\n\nNote that one cannot simply add an internal IP range to a\nnon-restricted proxy entry. That is, this configuration would **not**\nallow clients from 10.3.15.0/24 to be introduced via 10.5.21.1::\n\n [proxies]\n header = x-forwarded-for\n proxies = 10.5.21.1\n 10.5.21.1 = 10.3.15.0/24\n\nThere is one more important point in the configuration of proxies. It\nis possible to prohibit proxies from introducing certain IP addresses,\nby using the \"restrict()\" modifier on the CIDR list. (The converse,\n\"accept()\", exists, but is no different from listing a bare address.)\nFor instance, we can use \"internal(10.5.21.1)\" to allow the\nintroduction of clients from local addresses, but prohibit clients\nfrom being introduced from some of those ranges. For instance, let's\nallow 10.5.21.1 to introduce internal clients, but prohibit\nintroduction of clients from the ranges 10.5.0.0/16 and 10.3.15.0/24::\n\n [proxies]\n header = x-forwarded-for\n proxies = internal(10.5.21.1)\n 10.5.21.1 = restrict(10.5.0.0/16), restrict(10.3.15.0/24)\n\nModifications to the request environment\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nIf Bark's proxy system is enabled, and a client is introduced from a\nproxy, the ``REMOTE_ADDR`` key in the WSGI environment is *not*\naltered; rather, the verified client's IP address will be present in\nthe WSGI environment key ``bark.useragent_ip``. Additionally, a\ncomma-separated list of the verified proxies will be present in a\ndictionary stored in the WSGI environment key ``bark.notes``; the\ndictionary key containing this list of proxy IP addresses is\n``remoteip-proxy-ip-list``. (The ``bark.notes`` dictionary is\nprovided for the \"%n\" format string conversion, and is provided for\ncompatibility with Apache's method of presenting this information. To\ninclude this data in a log message, one would use\n\"%{remoteip-proxy-ip-list}n\" in the format string.) The proxy\nverification system *does* alter the proxy header, however; the header\nmay be removed if all IP addresses listed are valid proxies, otherwise\nit will contain a comma-separated list of those IP addresses which\ncould not be validated as proxies.\n\nLog Format Strings\n==================\n\nAll log streams must have a ``format`` configuration value, as\ndescribed above. This format string is compatible with the `Apache\nlog module`_, with some minor differences. For instance, the \"%l\",\n\"%L\", \"%R\", and \"%X\" conversions always format as a \"-\", since those\nvalues are generally not available in WSGI; additionally, the \"%k\"\nconversion always formats as a \"0\", since again keep-alive information\nis generally not available in WSGI. Bark also adds the \"%w\"\nconversion, which allows formatting of any WSGI environment variable.\nAs an example, the conversion \"%{wsgi.version}w\" would format as \"(1,\n0)\". Finally, note that all the modifiers permitted for Apache\nconversions are recognized by Bark; however, the modifiers \"<\" and \">\"\nhave no meaning.\n\nExtending Bark\n==============\n\nBark uses the ``pkg_resources`` package (part of setuptools) to look\nup conversions and log stream types. This allows for easily extending\nBark to allow for new conversions or log stream types.\n\nAdding New Conversions\n----------------------\n\nTo add a new conversion, subclass the ``bark.conversions.Conversion``\nabstract class. The subclass must define a ``convert()`` method,\ntaking as arguments a ``webob.Request`` object, a ``webob.Response``\nobject, and arbitrary data (more on this argument in a moment). The\nreturn value of the ``convert()`` method must be the string to\nsubstitute for the conversion.\n\nSome conversions need to initialize data before the request is\nprocessed; examples are \"%D\" and \"%T\", which time the processing of a\nrequest, and \"%t\", which formats the start time of a request. For\nextension conversions that require such preparation, override the\n``prepare()`` method. This method takes a single argument--a\n``webob.Request`` object--and return a dictionary containing arbitrary\ndata. This return value will be presented to the ``convert()`` method\nas its third argument. (The default implementation of ``prepare()``\nsimply returns an empty dictionary.)\n\nThe conversion must then be listed as a member of the\n``bark.conversion`` entry point group. Of course, single characters\nmay be used, as for the standard conversions; however, it is\nencouraged to use descriptive names for extension conversions. An\nextension to Bark's parsing of format strings allows for\nmulticharacter conversion names to be specified by enclosing them in\nparentheses. As an example, consider defining an entry point for\nBark's existing ``TimeConversion`` class, under the multicharacter\nname \"time\"; the entry point would be defined as follows::\n\n 'bark.conversion': [\n 'time = bark.conversions:TimeConversion',\n ]\n\nTo specify that this time conversion be used with an ISO-8601\ncompliant time format, the format conversion would be:\n\"%{%Y-%m-%dT%H:%M:%SZ}(time)\".\n\nAdding New Log Stream Types\n---------------------------\n\nTo add a new log stream type, create a factory for configuring the log\nstream type. This factory could be a function which returns a\ncallable of one argument, or it could be a class with ``__init__()``\nconforming to the factory function interface and ``__call__()`` taking\na single argument; in either case, what matters is that the return\nvalue of calling the factory must be a callable of one argument. This\ncallable will be passed a string--the formatted message--and must emit\nthe string to the appropriate log message handler.\n\nAll of these log stream type factories are passed a minimum of two\narguments: the name of the log stream type (e.g., \"null\", \"file\",\netc.) and the name of the configuration file section in which it is\nused. (All the predefined log stream types ignore this argument, but\nextension stream types are welcome to make use of it.) All remaining\narguments will be drawn from the configuration, and arguments which\nhave no defined default will be required configuration options.\n\nWhen a log stream type factory is called, all the arguments will be\npassed as simple string values, straight from the configuration.\nHowever, it is possible to designate certain arguments as being\ncertain types, in which case those arguments will be converted before\ncalling the factory. For instance, consider the socket factory, which\nis defined as follows::\n\n @arg_types(port=int)\n def socket_handler(name, logname, host, port):\n return wrap_log_handler(logging.handlers.SocketHandler(host, port))\n\nThe decorator ``@bark.handlers.arg_types()`` takes keyword arguments,\nmapping argument names to callables which can convert a string into\nthe expected value. If this callable raises a ``ValueError``, as the\n``int`` callable may, that error will be logged and that log stream\nwill be skipped. This can also be used to validate argument values,\nsuch as with the special ``bark.handlers.choice()`` class, which\ndemands that the string be one of the ones specified; if it does not\nmatch, ``choice()`` raises a ``ValueError``.\n\nFinally, note the ``bark.handlers.wrap_log_handler()`` function; this\nfunction takes an instance of a ``logging.Handler`` class and returns\na callable which uses that class to emit a log message via that\nhandler. All of the standard log stream types, with the exception of\nthe ``null`` log stream type, use standard ``logging.Handler``\ninstances to perform the actual logging.\n\nOnce a log stream type factory has been created, it then must be\nlisted as a member of the ``bark.handler`` entry point group. The\nname will then be recognized as a valid log stream type.\n\n.. _PIP: http://www.pip-installer.org/en/latest/index.html\n.. _TimedRotatingFileHandler: http://docs.python.org/2/library/logging.handlers.html#timedrotatingfilehandler\n.. _SocketHandler: http://docs.python.org/2/library/logging.handlers.html#sockethandler\n.. _DatagramHandler: http://docs.python.org/2/library/logging.handlers.html#datagramhandler\n.. _NTEventLogHandler: http://docs.python.org/2/library/logging.handlers.html#nteventloghandler\n.. _SMTPHandler: http://docs.python.org/2/library/logging.handlers.html#smtphandler\n.. _HTTPHandler: http://docs.python.org/2/library/logging.handlers.html#httphandler\n.. _Apache log module: http://httpd.apache.org/docs/2.4/mod/mod_log_config.html#formats", "description_content_type": null, "docs_url": null, "download_url": "UNKNOWN", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "https://github.com/klmitch/bark", "keywords": null, "license": "Apache License (2.0)", "maintainer": null, "maintainer_email": null, "name": "bark", "package_url": "https://pypi.org/project/bark/", "platform": "UNKNOWN", "project_url": "https://pypi.org/project/bark/", "project_urls": { "Download": "UNKNOWN", "Homepage": "https://github.com/klmitch/bark" }, "release_url": "https://pypi.org/project/bark/0.1.0/", "requires_dist": null, "requires_python": null, "summary": "WSGI logging middleware", "version": "0.1.0" }, "last_serial": 786708, "releases": { "0.1.0": [ { "comment_text": "", "digests": { "md5": "4ca8d5d4aacb9906ef40b0a69d8b0fe3", "sha256": "580859304590b04e2c92f1bcc95f72517b6f8e9c057159baa5477c7e167a6493" }, "downloads": -1, "filename": "bark-0.1.0.tar.gz", "has_sig": false, "md5_digest": "4ca8d5d4aacb9906ef40b0a69d8b0fe3", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 54012, "upload_time": "2013-01-11T21:20:39", "url": "https://files.pythonhosted.org/packages/c6/61/8d1d367d57cd6237a7cdd7d62d5468c7aa03797c4dbbba39573541cad6da/bark-0.1.0.tar.gz" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "4ca8d5d4aacb9906ef40b0a69d8b0fe3", "sha256": "580859304590b04e2c92f1bcc95f72517b6f8e9c057159baa5477c7e167a6493" }, "downloads": -1, "filename": "bark-0.1.0.tar.gz", "has_sig": false, "md5_digest": "4ca8d5d4aacb9906ef40b0a69d8b0fe3", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 54012, "upload_time": "2013-01-11T21:20:39", "url": "https://files.pythonhosted.org/packages/c6/61/8d1d367d57cd6237a7cdd7d62d5468c7aa03797c4dbbba39573541cad6da/bark-0.1.0.tar.gz" } ] }