unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



evmlogger.conf(4)					    evmlogger.conf(4)



NAME

  evmlogger.conf - EVM logger configuration file

SYNOPSIS



  eventlog {
	  name		eventlog_name
	  type		[formatted | binary]
	  show_template	template
	  logfile	log_path
	  alternate	log_path
	  maxsize	max_logsize
	  filter	log_filter_spec
	  include	filter_element
	  exclude	filter_element
	  suppress	 {
			  filter    supp_filter_spec
			  include   filter_element
			  exclude   filter_element
			  period    supp_period
			  threshold supp_threshold
			 }
	  }



  forward {
	  name	   forward_name
	  filter   forward_filter_spec
	  include  filter_element
	  exclude  filter_element
	  command  forward_command
	  maxqueue queue_limit
	  suppress    {
		       filter	 supp_filter_spec
		       include	 filter_element
		       exclude	 filter_element
		       period	 supp_period
		       threshold supp_thresh
		      }
	  }

  configdir directory








DESCRIPTION

  The evmlogger.conf file is the EVM logger configuration file.	This file is
  read when the	logger program,	evmlogger, starts, and when it reloads its
  configuration.

  The evmlogger.conf file is a text file that contains values used to config-
  ure the event	logger.	 The values direct the display,	forwarding, or
  storage of events. Any portion of a line from	an unquoted number sign	(#)
  to the end of	line is	a comment.  Blank lines	are ignored.

  Any number of	event logs and forwarders may be defined in a configuration
  file.	 The following keywords	are recognized:

  eventlog
      Introduces a group of keyword/value pairs, which define an event log.
      Events that match	the log's log_filter_spec are selected for handling
      by this log.

      name eventlog_name
	  The name used	to refer to the	event log.

      type log_type
	  The type of the log -- either	formatted or binary.  If the log_path
	  specifies a terminal device, such as /dev/console, the type is
	  automatically	set to formatted, and cannot be	forced to binary.  If
	  the log_path specifies a file, the default type is binary. Events
	  are written to formatted logs	as single lines	of text, and to
	  binary logs as raw EVM events.

      show_template template
	  The template used to format lines of text for	a formatted log.  If
	  no template is specified, the	event timestamp	and message are	writ-
	  ten.	See evmshow(1) for show-template syntax.

      logfile log_path
	  Pathname of the log file.  If	a log is a disk	file, the logger
	  creates the file if necessary.

	  If the log name ends in the characters .dated, the logger replaces
	  that suffix with the current date in the form	yyyymmdd.  A new file
	  is begun when	the first event	is written to the log each day.

      alternate	log_path
	  Specifies an alternate path to be used in cases where	the primary
	  log cannot be	used.  If the specified	logfile	becomes	unusable, the
	  logger switches to the alternate log file.

	  If the logger	is writing to the alternate log, and the error condi-
	  tion which caused it to switch has been cleared, you can make	it
	  revert to the	primary	path by	using the evmreload -l command.

      maxsize max_logsize
	  The maximum size, in kilobytes, that the log file may	reach.	If
	  adding an event to the file would cause this size to be exceeded,
	  the logger begins a new file,	adding the suffix _n to	the name of
	  the new file,	where _n is a sequential generation number.

      filter log_filter_spec
	  Event	selection filter specification.	 Events	passing	this filter
	  are selected for logging to this event log; all others are ignored.
	  See EvmFilter(5) for a description of	filter syntax.

      include filter_element
	  Modifies the current log_filter_spec.	 See the description of	the
	  include and exclude keywords below.

      exclude filter_element
	  Modifies the current log_filter_spec.	 See the description of	the
	  include and exclude keywords below.

      suppress
	  The suppression facility minimizes resource waste by limiting	the
	  number of identical events appearing in the log.  A description of
	  the event suppression	group follows.

	  Before being written to the log, each	incoming event is matched
	  against the suppression group's supp_filter_spec.  An	event that
	  passes the filter is then compared with other	events that have been
	  posted during	the last period	minutes, ignoring the timestamp,
	  last_timestamp, PID, PPID, event-id and repeat-count data items.
	  If a matching	event is found,	and at least threshold instances of
	  the event have been written to the log during	the period, the
	  logger does not log the event	-- instead, it inserts or updates the
	  repeat_count and last_timestamp data items in	the last-logged
	  instance of the event.  The suppression is indicated by the string
	  [n times] appearing in the message text when the event is
	  displayed, where n is	the repeat_count.

	  Once an individual event becomes eligible for	suppression, the
	  suppression is canceled automatically	after the greater of four
	  hours	or the supp_period, and	is reinstated when the suppression
	  conditions occur again.  Suppression is canceled automatically when
	  a change of logfile occurs.

	  Suppression directives are ignored for formatted logs.

	  The following	keywords are recognized	in a suppression group:

	  filter supp_filter_spec
	      Events selected by this filter are eligible for suppression
	      consideration.  See EvmFilter(5) for the filter syntax.

	  include filter_element
	      Modifies the current supp_filter_spec.  See the description of
	      the include and exclude keywords below.

	  exclude filter_element
	      Modifies the current supp_filter_spec.  See the description of
	      the include and exclude keywords below.

	  period supp_period
	      The period, in minutes, over which events	are counted for
	      suppression consideration.

	  threshold supp_threshold
	      The number of instances of an event that will be logged during
	      supp_period before suppression begins.

  forward
      Events meeting the filter	specifications are to be forwarded using the
      command specified.

      name forward_name
	  A name used to identify the forwarding definition.

      filter forward_filter_spec
	  Event	forwarding filter specification.  Events passing this filter
	  are selected for forwarding as specified by the forward_command.
	  See EvmFilter(5) for the filter syntax.

      include filter_element
	  Modifies the current forward_filter_spec.  See the description of
	  the include and exclude keywords below.

      exclude filter_element
	  Modifies the current forward_filter_spec.  See the description of
	  the include and exclude keywords below.

      command forward_command
	  When an incoming event is selected for handling by this forwarder,
	  and is not eligible for suppression, the logger executes this	com-
	  mand,	piping the event into the command's stdin stream.

      maxqueue queue_limit
	  This keyword limits the number of events that	can be queued by a
	  forwarder while a previous event is being handled by command.	 If
	  the maximum number of	events is already queued when a	new event
	  arrives, the event is	ignored	by this	forwarder.  If not specified,
	  this keyword has a default value of 100.  If a value greater than
	  1000 is specified, the logger	automatically limits it	to 1000.

	  See evmlogger(8) for details of event	queuing.

      suppress
	  Event	suppression as applied to forwarding is	similar	to event log
	  suppression, but limits the number of	identical events that will be
	  forwarded over the suppression period.  In this case,	events which
	  are eligible for suppression are simply ignored by the forwarder.
	  This feature is intended to reduce the chance	of a large volume of
	  mail being sent during a period of high event	activity.

  configdir directory
      This keyword specifies the path of a directory tree that holds zero or
      more secondary configuration files. The directory	tree is	searched when
      the logger is started and	each time its configuration is reloaded.

      Configuration file names must end	with .conf, and	must not begin with a
      dot (.).	Files must be owned by bin or root and their file permissions
      must restrict writing to owner or	group. Symbolic	links and subdirec-
      tory hierarchies can be used to reference	configuration files that phy-
      sically are located elsewhere.

      After installing,	removing or modifying a	secondary configuration	file,
      you must run the evmreload -l command to notify the logger of the
      change and request a configuration reload.

      Any number of configdir entries may be specified in the primary confi-
      guration file, but configdir is not a valid keyword in a secondary con-
      figuration file.

  The include and exclude keywords can appear multiple times in	an eventlog,
  forward or suppress specification, allowing you to build and maintain	a
  filter in simple single-line increments.  Each filter_element	must be	a
  valid	filter string, conforming to the syntax	described in the EvmFilter(5)
  reference page.  The logger assembles	a complete filter string by surround-
  ing the initial filter with parentheses and appending	the filter_elements
  to it, separating each with a	logical	OR (for	include) or AND	NOT (for
  exclude) operator.  For example:

       filter	 "[priority >= 200]"
       include	 "[name	*.mylog]"
       exclude	 "[name	*.oldlog]"

  The previous filter lines are	equivalent to this more	complex	single filter
  line:

       filter	 "([priority >=	200]) OR [name *.mylog]	AND NOT	[name *.oldlog]"

  The first line selects all events with a priority of 200 or greater, the
  next modifies	this by	selecting all events from mylog	regardless of their
  priorities, and the last line	excludes all oldlog events regardless of
  their	priorities.

  If you prefer, you can omit the filter command, and build the	complete
  filter string	from include and exclude lines.

  Keywords may be entered in a case-insensitive	manner.	 The allowable
  strings and the minimum number of characters is shown	in the following
  table.  A minimum of zero (0)	indicates that all characters are required.

  _______________________
  Keyword	  Minimum
  _______________________
  alternate	  3
  command	  4
  configdir	  7
  eventlog	  0
  exclude	  3
  filter	  4
  forward	  4
  include	  3
  logfile	  3
  maxqueue	  4
  maxsize	  3
  name		  0
  period	  0
  show_template	  4
  suppress	  4
  threshold	  0
  type		  0
  _______________________

NOTES

   1.  The logger only allows a	single instance	of each	forwarding command to
       execute at one time and queues any events that arrive while an
       instance	is already running. The	forwarder ignores events that arrive
       while the queue is full.	To minimize the	chances	of queuing or missing
       events, you should avoid	using the forwarding facility to run commands
       that may	take significant time to execute.

   2.  If you specify a	forwarding command that	may itself cause events	to be
       posted (for instance, mail commands may post syslog events that will
       be routed to EVM), the forwarding filter	explicitly should exclude
       those events. Otherwise,	it is possible that an infinite	event loop
       will occur.

   3.  If you are concerned with allowing your file to be used on other	sys-
       tems that support EVM in	the future, you	should use the built-in	macro
       @SYS_VP@	in place of the	first two components (sys.unix)	of the name
       of any system event.  This will make it unnecessary to change the file
       if the other system uses	a different event name prefix.

EXAMPLES

  This example initiates an instance of	the evmlogger command with the fol-
  lowing configuration:

   1.  Binary events are written to a file in the /var/evm/evmlog directory
       named evmlog.xxx	where xxx is the current year, month, and day -- for
       example,	/var/evm/evmlog/evmlog.19981217. An alternate log path is
       specified in case of write failures to the primary path.

   2.  A new generation	of the log is started automatically if the size
       exceeds 256 Kbytes.

   3.  All events with a priority of at	least 200 are selected for logging.

   4.  Duplicate events	are suppressed.

   5.  Events with a priority of at least 600 are displayed on the system
       console as formatted events, showing the	timestamp, the priority	and
       the event's message.

   6.  Events with a priority of at least 600 are also mailed to root.

   7.  A maximum of 20 events will be queued for forwarding to root when an
       instance	of the forwarding command is already running.

       eventlog
       {
	   name	       evmlog
	   logfile     /var/evm/evmlog/evmlog.dated
	   type	       binary
	   maxsize     256  # Kbytes

	   alternate  /altlogs/evmlog/evmlog.dated

	   # Log all events with priority >= 200:
	   filter      "[prio >= 200]"

	   # Suppress logging of duplicate events:
	   suppress
	   {   filter	   "[name *]"
	       period	   30  # minutes
	       threshold   3   # No. of	instances before suppression
	   }

       }

       # Log high-priority events to the system	console:
       eventlog	{
	   name		       console_log
	   logfile	       /dev/console
	   filter	       "[prio >= 600]"
	   type		       formatted
	   show_template       "@timestamp [@priority] @@"
       }

       # Forward details of high-priority events to root:
       forward {
	   name	     priority_alert
	   # Don't forward mail	events through mail (see note above):
	   filter    "[prio >= 600] & ![name @SYS_VP@.syslog.mail]"

	   suppress
	   {   filter	   "[name *]"
	       period	   120	# minutes
	       threshold   1	# No. of duplicates before suppression
	   }

	   # This evmshow command writes a subject line	as the first line of
	   # output, followed by a detailed display of the contents of the
	   # event.  The resulting message is distributed by mail(1).

	   command   "evmshow -d -t 'Subject: EVM ALERT	[@priority]: @@' \
			      |	mail root"
       }







FILES

  /etc/evmlogger.conf
      Location of the EVM logger configuration file.

  /var/evm/adm/config/logger
      Default location of the secondary	EVM logger configuration files.

SEE ALSO

  Commands: evmget(1), evmshow(1), evmd(8), evmlogger(8), evmreload(8)

  Event	Management: EVM(5)

  EVM Events: EvmEvent(5)

  Event	Filter:	EvmFilter(5)