lwac 0.2.0

data/lib/lwac/shared/serialiser.rb

@@ -0,0 +1,86 @@
+
+require 'yaml'
+
+
+module LWAC
+
+
+
+  # This class wraps three possible serialisation systems, providing a common interface to them all.
+  #
+  # This is largely ripped from SimpleRPC, with some minor modifications.
+  class Serialiser
+
+    SUPPORTED_METHODS = %w{marshal json msgpack yaml}.map{|s| s.to_sym}
+
+    # Create a new Serialiser with the given method.  Optionally provide a binding to have
+    # the serialisation method execute within another context, i.e. for it to pick up
+    # on various libraries and classes (though this will impact performance somewhat).
+    #
+    # Supported methods are:
+    #
+    # :marshal:: Use ruby's Marshal system.  A good mix of speed and generality.
+    # :yaml:: Use YAML.  Very slow but very general
+    # :msgpack:: Use MessagePack gem.  Very fast but not very general (limited data format support)
+    # :json::  Use JSON.  Also slow, but better for interoperability than YAML.
+    #
+    def initialize(method = :marshal, binding=nil)
+      @method   = method
+      @binding  = nil
+      raise "Unrecognised serialisation method" if not SUPPORTED_METHODS.include?(method)
+
+      # Require prerequisites and handle msgpack not installed-iness.
+      case method
+        when :msgpack
+          begin 
+            gem "msgpack", "~> 0.5"
+          rescue Gem::LoadError => e
+            $stderr.puts "The :msgpack serialisation method requires the MessagePack gem (msgpack)."
+            $stderr.puts "Please install it or use another serialisation method."
+            raise e
+          end
+          require 'msgpack'
+          @cls = MessagePack
+        when :yaml
+          require 'yaml'
+          @cls = YAML
+        when :json
+          require 'json'
+          @cls = JSON
+        else
+          # marshal is alaways available
+          @cls = Marshal
+      end
+    end
+
+    # Serialise to a string
+    def dump(obj)
+      return eval("#{@cls.to_s}.dump(obj)", @binding) if @binding
+      return @cls.send(:dump, obj)
+    end
+
+    # Deserialise from a string
+    def load(bits)
+      return eval("#{@cls.to_s}.load(bits)", @binding) if @binding
+      return @cls.send(:load, bits)
+    end
+
+    # Load an object from disk
+    def load_file(fn)
+      return File.open(fn, 'r'){ |f| Marshal.load(f) }            if @method == :marshal
+      return YAML.load_file(File.read(fn))                        if @method == :yaml
+      return File.open(fn, 'r'){ |f| MessagePack.load( f ) }      if @method == :msgpack  # efficientify me
+      return File.open(fn, 'r'){ |f| JSON.load( f.read ) }        if @method == :json
+    end
+
+    # Write an object to disk
+    def dump_file(obj, fn)
+      return File.open(fn, 'w'){ |f| Marshal.dump(obj, f) }         if @method == :marshal
+      return YAML.dump(obj, File.open(fn, 'w')).close               if @method == :yaml
+      return File.open(fn, 'w'){ |f| MessagePack.dump(obj, f ) }    if @method == :msgpack
+      return File.open(fn, 'w'){ |f| JSON.dump( obj, f) }           if @method == :json
+    end
+  end
+
+
+end

data/limits.md

@@ -0,0 +1,114 @@
+Limits and Performance
+======================
+LWAC was designed to maximise throughput to the web, and as such easily stretches certain system resources.  Extracting the best performance requires knowledge of some of the limits of your underlying system, as well as the architecture of LWAC.  This guide should cover each of the points, and explain which need attention for which conditions.
+
+Throughput
+----------
+The system is capable of downloading around 2.5 million pages per hour per client when resource speed is not an issue.  This slows to roughly 100,000 per hour per client when using real-world (year-old) URL lists.  This equals roughly 10-100 million words per hour in practice.
+
+Most speed issues are caused by the slow response of servers, for which parallelism is the only practical solution.  It's worth noting that the tool can download at around 20Mbps/client in a sustained manner---this most certainly breaks netiquette and may be sufficient to overload some hosts if you have many links pointing to the same servers.
+
+Network
+-------
+LWAC transfers large batches of data between its client and server tools, as well as to the web.  To ensure reliability, these transfers occur at different times, however, they are both subject to various limitations.
+
+
+### Client-Server Communication
+
+#### Batch Size
+Increasing the size of a batch will have a number of effects.
+
+ 1. More data will be queued up in RAM on both the client and the server.  The server will, at most, `hold cache_size * number_of_clients` links in memory.  The client will store at most its batch size.  Generally this is not an issue, as any modern system can store millions of Link objects in memory.
+ 2. Transfer between client and server will lock out other clients until complete, so smaller batches allow for better client load-balancing.
+
+In my experience, sizes of 1000-10,000 are suitable for smaller corpora, and/or low client specifications.  Even if your web pages are small, there is overhead in managing the cache prior to sending it to the server, so batch sizes in excess of around 20,000 start slowing down (changing the client cache policy can help this).
+
+
+#### Client Competition
+Clients compete with one another for server time, and follow this algorithm to do so:
+
+ 1. Start worker servers
+ 2. Maintain work:
+   * If the link pool is empty, connect to the server to get more links
+   * When N MB of data have been downloaded, contact the server to upload
+ 3. When the server has no links to give, wait and back off
+
+The server can support an unlimited number of clients, but beyond a point they will start locking one another out and efficiency drops off.  This point is highly dependent on:
+  
+  * Network speeds
+  * The batch size, concurrency and other [client settings](client_config.html)
+
+Since the server guarantees data consistency in the case of clients disconnecting, I recommend connecting progressively more clients until the point of maximum efficiency is reached for your setup.
+
+
+### Web connection
+LWAC places significant stress on the connection to the web, and can trigger things such as DDOS protection and traffic shaping schemes.  Steps should be adjusted to avoid this, if possible, such as by placing clients on different parts of the network.
+
+
+#### Proxies/single points of failure
+Proxies can be configured in the curl settings (`client_policy` section of the [server config](server_config.html)), however, they are subject to a number of effects that are generally undesirable for sampling (such as caching and header rewriting), and present a single point of failure which handles all of the stress.
+
+Unfortunately there is currently no method to set a different proxy on each client (this is due in a later version).
+
+#### DNS
+DNS lookup is considered an integral part of fetching web data, and is thus repeated every time a client downloads a link.  If this places undue stress on one's DNS provider, a local cache can vastly reduce outgoing traffic with relatively little risk of damaging the quality of resultant data.
+
+
+
+File System
+-----------
+The filesystem is used extensively in LWAC both as backing store and as a cache.  Many filesystems, especially those on virtual servers, impose significant performance overheads when dealing with small files or certain types of access.  It is important than LWAC is adjusted if this is the case.
+
+### Server
+The server's use of the filesystem is twofold:
+
+ * Corpus backing store
+ * Metadata database (read only beyond initial import)
+
+#### Max Files per Dir
+Many filesystems impose a fairly low limit on the number of files that will fit in one directory.  Since one file per datapoint is used in a corpus, they may be spanned over many directories.  See the [server config](server_config.html) for the relevant configuration properties.
+
+#### Corpus Dir Size
+Over time the corpus directory will grow very large.  It's possible to copy all but the current sample out of this directory whilst the server is running, though a better policy might simply be to place the corpus on a large disk or RAID volume.
+
+
+#### SQLite3 performance (pragmas)
+SQLite3 is largely retained in RAM during use, however, its disk access can be controlled through the use of `PRAGMA` statements.  If disk or memory usage is a particular problem, these can be adjusted to specify new limits, as mentioned in the [server config](server_config.html).
+
+### Client
+The client uses disks infrequently or never, depending on the configuration used, using a single cache file:
+ 
+ * Datapoint cache
+
+#### Open Socket Limit
+Most operating systems impose limits on the number of sockets that may be open at any one time.  Since the client is heavily multithreaded, it is capable of exceeding these limits with relative ease.
+
+On unix systems, the limit can be read using the command `ulimit -a`, where it is typically listed as the number of file descriptors allowed (minus one for the cache file and one for each log).
+
+#### Cache Filesize
+The file caching system is based on a single file, which will grow to the size of the sum of all data downloaded in one batch.  In testing with HTML data, this generally means about 10MB for every thousand links.
+
+The client's cache system uses repeated `fseek` calls to look up data.  If your filesystem is very bad at seeking, it may be wiser to use a memory cache instead.
+
+Memory Usage
+------------
+LWAC was designed for large samples, and as such its memory usage is minimal, static (O(1) complexity w.r.t. total corpus size), and configurable.
+
+### Server
+The server requires enough memory to store:
+
+ * Lists of failed links (which accumulate if clients drop out during a batch, but are soon re-used).  A thousand links uses under 100KB of storage in RAM.
+ * Datapoints currently being checked in (see `check_in_rate` in the [client config](client_config.html) to set this in MB)
+ * SQLite3 or MySQL cache (see above)
+
+This means that the server should always be using less than a few hundred megabytes of RAM, and much of that is ruby/libsqlite3/libcurl.
+
+### Client
+The client typically uses more RAM:
+
+ * Lists of links to download (max will be the batch size).
+ * Data downloaded from the web if using a memory cache (set `cache_file` in the [client config](client_config.html) to use a disk cache, or set `max_body_size` in the [server config](server_config.html))
+ * Data being accumulated for upload to the server (see `check_in_rate` in the [client config](client_config.html))
+ * Working data for a large number of download threads (at most equal to the number of threads multiplied by the `max_body_size`)
+
+A client with a large batch size (tens of thousands of links), downloading large files (such as PDFs), and using a memory cache, may use gigabytes of RAM.  The same client with a disk cache will use only a couple of hundred MB, mostly comprising ruby, libcurl, and marilyn/eventmachine.

data/log_config.md

@@ -0,0 +1,30 @@
+Logger Configuration
+====================
+LWAC uses a more flexible extension of ruby's standard log libraries and outputs in a fairly standard format.  Each tool's config file contains its own logging section, though they share a common format.
+
+Configuration 
+-------------
+
+ * `progname`                   --- The name of the program to output in the log file (printed on each line)
+ * `logs{}`                     --- A hash containing all other logs that a user wishes to use.  The `LOG_NAME` below is arbitrary and used to refer to the log in summary output.
+    * `logs/LOG_NAME/dev`       --- The device to use for this log.  This can either be a filename, or STDOUT/STDERR.
+     * `logs/LOG_NAME/level`    --- The level to log at.  This is one of the symbols `:debug`, `:warn`, `:info`, `:error`, or `:fatal`
+
+
+Sample Config
+-------------
+The configuration below outputs three logs, one to stdout for basic information whilst the program runs, one with errors only to a file, and another with basic progress to another file.
+
+    :logging:
+      :progname: Server
+      :logs:
+        :default:
+          :dev: STDOUT
+          :level: :info
+        :errors:
+          :dev: 'logs/server.err'
+          :level: :warn                                              
+        :file_log:
+          :dev: 'logs/server.log'
+          :level: :info
+

data/monitoring.md

@@ -0,0 +1,13 @@
+Monitoring/Maintenance
+======================
+LWAC should require little maintenance beyond initial deployment.  It is heavily network-dependent, and as such its libraries should be kept up-to-date for security purposes.
+
+
+Disk Space
+----------
+As the corpus grows it may be necessary to move data off the server's working disk.  Any samples that are not currently open may be moved whislt the server is running---this basically means all but the last entry in the corpus.
+
+Process Monitoring
+------------------
+LWAC is as prone to failure as any other long-running process, and should ideally be monitored during its sampling runs, especially if they last many months.  Many tools are available for this (such as [monit](http://mmonit.com/monit/), [Ubic](https://github.com/berekuk/Ubic), [God](http://godrb.com/) or [bluepill](https://github.com/arya/bluepill)), and any should suffice in monitoring both client and server processes.  
+

data/resources/schemata/mysql/links.sql

@@ -0,0 +1,7 @@
+-- Describe LINKS
+CREATE TABLE links (
+    id    INT NOT NULL AUTO_INCREMENT,
+    uri   VARCHAR(1024) NOT NULL,
+    PRIMARY KEY  ( id )
+);
+

data/resources/schemata/sqlite/links.sql

@@ -0,0 +1,5 @@
+-- Describe LINKS
+CREATE TABLE links (
+    "id"    INTEGER PRIMARY KEY,
+    "uri"   TEXT NOT NULL
+);

data/server_config.md

@@ -0,0 +1,242 @@
+Server Configuration
+====================
+The server's configuration file is a valid ruby Hash object, expressed in YAML.  As such, it starts with a single line containing three dashes, and follows a key-value structure throughout.  It may loosely be separated into a number of sections, forming the top level of this tree.
+
+For help interpreting this document, see [Reading Config Documentation](config_docs.html)
+
+Storage
+-------
+Storage is defined by the `/storage/` key, and contains details on the corpus and its metadata database.
+
+### Corpus Details
+
+ * `root`            --- The root directory of the corpus, relative to the server binary.
+ * `state_file`      --- The name of the file where server state will be stored.  This contains a list of incomplete links for the current sample.
+ * `sample_subdir`   --- The name of the directory within the corpus where samples will be stored.
+ * `sample_filename` --- The filename where summary details on a particular sample are stored.
+ * `files_per_dir`   --- How many files to store in each directory below the `sample_subdir`.  This is set to avoid overloading filesystems that have finite inode tables.
+ * `serialiser`      --- The serialisation method used to write to disk.  Supported methods are `:marshal`, `:yaml` or `:json`.  `:marshal` is fastest and recommended unless you desperately need to access the corpus using languages other than ruby.
+
+For example:
+
+    :storage:                       
+      :root: corpus                   
+      :state_file: state          
+      :sample_subdir: samples         
+      :sample_filename: sample    
+      :files_per_dir: 1000            
+      :serialiser:  :marshal          
+      :database: 
+         ...
+
+
+### Database Details
+The database is configured in `/storage/database` and consists of two main blocks:
+
+ * `engine` --- Either `:sqlite` for the SQLite3 database engine or `:mysql` for mysql.  You must install the appropriate dependency for the engine you select.
+ * `engine_conf{}` --- Configuration parameters for a given engine.  See below for examples of each.
+ * `table`             --- The table name where links to be downloaded are stored
+ * `fields`            --- Contains information on the links table's fields
+ * `fields/id`         --- The field name containing the link ID
+ * `fields/uri`        --- The field name contain the URI to request from a remote server.
+
+For example:
+
+    :table: links                   
+    :fields:                        
+      :id: id                         
+      :uri: uri                       
+    :engine: :mysql
+    :engine_conf:                       
+      ...
+
+
+#### SQLite3
+The SQLite3 engine is rather heavily optimised for read speed from the database, and is recommended if you want speed or have a smaller corpus.  Its configuration parameters are thus:
+
+ * `database/transaction_limit` --- How many queries to run per transaction.  Larger numbers speed up access at the expense of data security.
+ * `database/pragma{}`          --- A key-value list of pragma statements to configure the SQLite3 database.  These configure the database, and take the form of a list of key-value strings.  A full list of SQLite3 pragma statements is available on [their website](http://www.sqlite.org/pragma.html)
+ * `transaction_limit` --- The number of calls to make per transaction.  May provide a minor speed increase if large, but most database access is read only anyway.
+ * `filename` --- The position of the database file, relative to `pwd`
+
+For example:
+
+    :engine: :mysql              
+    :engine_conf:
+      :filename: corpus/links.db      
+      :transaction_limit: 100         
+      :pragma:                        # Custom pragmas.  See SQLite's docs.
+        "locking_mode": "EXCLUSIVE"     # Do not allow others to access the db when the server is running
+        "cache_size": 20000             # Allow a large cache
+        "synchronous": 0                # Asynchronous operations speed things up a lot
+        "temp_store": 2                 # Use temp storage
+
+#### MySQL
+The MySQL engine's configuration parameters are largely defined by the gem.  Full documentation is available on the [github page](https://github.com/brianmario/mysql2), and common parameters are listed below:
+
+ * `username` --- The uername to log in with
+ * `password` --- The password to use when connecting to the mysql server
+ * `host` --- The hostname at which the mysql server is listening (omit this if using a socket)
+ * `port` --- The port on which the mysql server is listening (omit this if using a socket)
+ * `socket` --- The filepath of a socket over which to talk to the mysql server
+ * `database` --- The name of the database where the links table will be stored
+ * `encoding` --- The character encoding to use.  'utf8' is _strongly_ recommended.
+
+For example:
+
+    :engine: :sqlite
+    :engine_conf:                       # Options from https://github.com/brianmario/mysql2
+      :username: lwac
+      :password: lwacpass
+      # :host: localhost
+      # :port: 3345
+      :socket: /var/run/mysqld/mysqld.sock
+      :database: lwac
+      :encoding: 'utf8'
+      :read_timeout: 10                 #seconds
+      :write_timeout: 10                #seconds
+      :connect_timeout: 10              #seconds
+      :reconnect: true                  #/false
+      :local_infile: true               #/false
+
+
+Sampling Policy
+---------------
+The sampling policy used by the server is defined by three parameters, *count*, *duration* and *alignment*.  
+
+ * `sample_limit` --- Sample at most this number of samples.  Note that the IDs start from 0, so the last sample will have the ID `sample_limit - 1`.  The server will quit when trying to open the `n+1`th sample.
+ * `sample_time` --- A sample's *duration* is the minimum time a sample may take.  For example, if this is a daily sample, it should be set to 84600 (the number of seconds in a day) in order to sample once at midnight each day.
+ * `sample_alignment` --- A sample's *alignment* defines whereabouts within each sample time the sample may start.  Using the above example, setting this to 7200 would cause samples to begin at 2am each day.
+
+Note that if a sample takes more than `sample_time` to run, it will overlap and cancel the next sample.  This is to prevent misalignment with the other datapoints in the sample, and is preferrable in many analyses to a series of messily-timed run-on samples.  The code that selects the samples thus follows this algorithm:
+
+ * Round down to the last valid sample time (`time = Time.at(((Time.now.to_i / @config[:sample_time]).floor * @config[:sample_time]) + @config[:sample_alignment])`)
+ * While `time < Time.now`
+   * increment the prospective time by the `sample_time`
+
+If you wish to edit the sample computation algorithm, it resides in `lib/server/consistency_manager.rb`, under the method `compute_next_sample_time`.
+
+For example:
+
+    :sampling_policy:               
+      :sample_limit:  0               
+      :sample_time: 60
+      :sample_alignment: 0
+
+
+
+Client Policy
+-------------
+This section describes the properties each client must inherit from its server.  It describes things such as how the client appears to external websites, and how it normalises and packages its data before upload to the server.
+
+ * `dry_run` --- Boolean.  Set to `true` to disable web access on the client, so that it samples empty datapoints.
+ * `max_body_size` --- Stop downloading when this number of bytes have been downloaded.  Used to prevent aberrantly large files from filling RAM or disk storage.
+ * `fix_encoding` --- Boolean. Should the encoding be normalised to `target_encoding`?
+ * `target_encoding` --- The name of an encoding to normalise to.  Default is 'UTF-8', but anything supported by Ruby's String#encode method will work
+ * `encoding_options` --- Options hash passed to String#encode, may include:
+   * `encoding_options\invalid` --- If value is `:replace` , replaces undefined chars with the `:replace` char
+   * `encoding_options\undef` --- If value is `:replace` , replaces undefined chars with the `:replace` char
+   * `encoding_options\replace` --- The char to use in replacement, defaults to uFFFD for unicode and '?' for other targets
+   * `encoding_options\fallback{}` --- A key-value table of characters to replace
+   * `encoding_options\xml` --- Either `:text` or `:attr`.  If `:text`, replaces things with hex entities, if `:attr`, it also quotes the entities "&amp;quot;"
+   * `encoding_options\cr_newline` --- Boolean. Replaces LF(\n) with CR(\r) if true
+   * `encoding_options\lf_newline` --- Boolean. Replaces LF(\n) with CRLF(\r\n) if true
+   * `encoding_options\universal_newline` --- Boolean.  Replaces CRLF(\r\n) and CR(\r) with LF(\n) if true
+
+Clients use cURL to download links, using the `curb` library, and may thus be configured with custom request parameters and other options.  The options below are applied by setting properties on the cURL object, and as such anything may be provided as a key that is in the [curb documentation](https://rubygems.org/gems/curb), such as 'verbose' or control over SSL.  By default, SSL options are overridden to accept connections without verifying certificates.
+
+ * `curl_workers{}` --- Defines properties of the CURl workers that contact web servers.
+   * `max_redirect` --- How many HTTP redirects should be followed before giving up?
+   * `useragent` --- The user agent to show to the remote server
+   * `follow_location` --- Should the agent follow location headers?
+   * `timeout` --- Overall timeout, in seconds, for the whole request.
+   * `connect_timeout` --- TCP connect timeout
+   * `dns_cache_timeout` --- DNS lookup timeout
+
+MIME type handling can be controlled in a rudimentary manner to prevent superfluous saving of binary data.  This is controlled using the `Content-type` field of the response headers, and takes the form of a whitelist or blacklist based on regular expressions.  Any link that is 'denied' has its body content wiped and a flag set in its datapoint metadata, but otherwise remains intact. It is configured by the structure called `:mimes`.
+
+ * `mimes{}` --- Defines mime-type acceptance handling
+   * `policy` --- Either `:whitelist` to only accept the items matching the list, or `:blacklist` to only decline the items on the list.
+   * `ignore_case` --- Should the regexp matching be case-insensitive?
+   * `list[]` --- A list of regular expressions.  If one matches, depending on white/blacklist configuration, the body will be blanked.
+
+For example:
+
+    :client_policy:
+      :dry_run: false
+      :fix_encoding: true
+      :target_encoding: UTF-8
+      :encoding_options:
+        :invalid: :replace
+        :undef: :replace                         
+        #:replace: '?'                            
+        #:fallback:                               
+          #'from': 'to'
+          #'from2': 'to2'
+        #:xml: :attr                              
+        #:cr_newline: true                        
+        #:crlf_newline:                           
+        :universal_newline: true
+      :max_body_size:  20971520
+      :mimes:
+        :policy: :whitelist
+        :ignore_case: true
+        :list:
+          - ^text\/?.*$       # text-only mimes
+         #- ^.+$              # anything with a valid content-type
+      :curl_workers:
+        :max_redirects: 5
+        :useragent: ! '"Mozilla/5.0 (Windows; U; Windows NT 6.0; en-US; rv:1.9.2.11) Gecko/20101012 Firefox/3.6.11"'
+        :enable_cookies: true
+        # :headers: "Header: String"
+        :verbose: false 
+        :follow_location: true
+        :timeout: 60
+        :connect_timeout: 10
+        :dns_cache_timeout: 10
+        :ftp_response_timeout: 10
+
+Client Management
+-----------------
+The server's responsibilities for managing clients as they connect and process work mean that it must present meaningful time limits on these connections (lest clients crash or misbehave).  These settings govern the rate at which clients are presumed to work, before the server starts re-assigning their work to other clients.
+
+
+The client is given only a finite time to complete its work before the server will assume it has died and re-assign its links elsewhere.  This is controlled by two parameters---one for clients that have not been deen before, and one that modifies the dynamic timeout computed by the server.
+
+ * `time_per_link` --- How long, in seconds, a new client is given per link to download a batch.  Clients typically download fairly fast, so this should be quite low (below 5).
+ * `dynamic_time_overestimate` --- How much to multiply the client's last performance by when computing a timeout i.e. value of "1.2" will give 20% overhead.
+
+These next to parameters define how long clients are told to wait when they contact the server but find no work available (for example, no sample is open right now).
+
+ * `empty_client_backoff` --- If no links are available but a sample is open, tell clients to retry after this time.
+ * `delay_overestimate` --- When a sample is closed, clients are told to wait until after the sample opening time.  A small amount is added to this to prevent clients from hitting the final seconds before the sample is open.  This should be less than `empty_client_backoff` for it to make any difference.  I recommend below 10 seconds.
+
+For example:
+
+    :client_management:
+      :time_per_link: 5
+      :dynamic_time_overestimate: 1.3
+      :empty_client_backoff: 60
+      :delay_overestimate: 10
+
+
+Server
+------
+These settings govern the network properties of the server, as used for data transfer to and from clients.  Settings here are passed to [SimpleRPC](http://stephenwattam.com/projects/simplerpc/), for which full documentation is available in the ruby gem.  Only the salient configuration options are listed here.
+
+ * `hostname`  --- The hostname or IP address of an interface on which to listen
+ * `port`       --- The port on which to listen for this interface
+ * `password`   --- Optional.  The password to use for auth (must match client config)
+ * `secret`     --- Optional.  The encryption key to use when sending the password (must match client config)
+
+For example:
+
+    :server:
+      :hostname:
+      :port: 27401
+      :password: lwacpass
+      :secret: egrniognhre89n34ifnui4n8gf490
+
+Logging
+-------
+The logging system is the same for client, server, and export tools and shares a configuration with them.  For details, see [configuring logging](log_config.html)