unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

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



EvmEvent(5)							  EvmEvent(5)



NAME

  EvmEvent - The structure of an EVM Event

DESCRIPTION

  An EVM event is a self-contained data	structure, which can be	manipulated
  and accessed using EVM API functions.	 Application code can:

    +  Create, duplicate and destroy an	event

    +  Set and retrieve	the values of standard data items contained within
       the event

    +  Add variable data items to the event, and set and retrieve their
       values

    +  Post the	event to the EVM daemon	for distribution to subscribers

    +  Read events from	an open	file descriptor

    +  Write events to an open file descriptor

  Command line utilities are provided that allow users access to these capa-
  bilities.

  The Contents of an Event


  The event structure includes two types of data items:

   1.  Standard	data items, with predefined names

   2.  Variable	data items, with names and types defined at the	time they are
       added to	the event

  When you create an event you can include as many data	items as you like.
  When you post	the event, the API functions automatically add the standard
  items	which pertain to the current environment, such as the host name	and
  timestamp.

  Standard Data	Items


  Standard data	items are those	which are commonly required in an event, and
  which	are understood and may be acted	upon by	EVM.  The following table is
  a list of the	standard data items that may be	contained in an	event.	The
  identifier is	the keyword used to post, display, or format the item.





  __________________________________________________________
  Data item/Id		Description
  __________________________________________________________
  Event	Name


  NAME

			Names the event. Must match a name
			in the daemon's	template database if
			the event is to	be posted.

  Time Posted
  TIMESTAMP

			UNIX system time when the first
			occurrence of this event was gen-
			erated.

  Repeat Count
  REPEAT_COUNT

			Number of instances of the same
			event that have	been combined into a
			single stored event.  The Time
			Posted and Last	Timestamp items
			indicate when the first	and last
			instances of the event were posted.

  Last Timestamp
  LAST_TIMESTAMP

			If Repeat Count	is present and non-
			zero, the system time when the
			latest occurrence of this event	was
			generated.

  Event	Identifier
  EVENT_ID

			Identifies the event.  See the
			description following this table.

  Host Name
  HOST_NAME		Name of	the posting node.

  Host IP Address
  HOST_IP		IP address of the posting node.

  Cluster Event
  CLUSTER_EVENT

			In a cluster environment, a value of
			EvmTRUE	indicates that the event was
			posted on behalf of the	cluster, not
			the individual node, and will be
			distributed to every node in the
			cluster.

  Cluster Name
  CLUSTER_NAME

			In a cluster environment, the name
			of the posting cluster.

  Cluster IP Address
  CLUSTER_IP

			In a cluster environment, the IP
			address	of the posting cluster.

  Cluster Member ID
  MEMBER_ID

			In a cluster environment, the node's
			cluster	ID.

  Kernel Only
  KERNEL_ONLY

			If present and EvmTRUE for an event
			generated in the kernel, the event
			will not be propagated from the	ker-
			nel to user space.

  Process ID
  PID

			PID of the process which posted	the
			event.

  Parent Process ID


  PPID

			PID of the parent of the process
			which posted the event.

  User name
  USER_NAME

			Name of	the owner of the posting
			process.

  Priority
  PRIORITY

			Indicates the importance of the
			event.	Does not affect	the order of
			event distribution.  See the
			description following this table.

  I18N catalog
  I18N_CATALOG

			Name of	I18N catalog file for inter-
			nationalized events.

  I18N message set id
  I18N_SET_ID

			Identifies the message set within
			the I18N message catalog.

  I18N message id
  I18N_MSG_ID		I18N message id	for the	event.

  Format
  FORMAT

			Event format text.  See	the
			EvmEventFormat(3) and evmtemplate(4)
			reference pages	for a description of
			the format string.

  Reference
  REF			Reference to event explanation text.
  __________________________________________________________

  Event	Name


  The event name is the	primary	means of identifying an	event.	It must	be
  present for an event to be posted.  Although it can be any syntactically-
  valid	string,	the name should	generally identify the posting facility	and
  indicate what	happened.

  The event name is an ASCII character string, made up of a dot-separated
  series of components,	with the left-most component representing the top of
  a notational hierarchy. Component substrings may include any combination of
  letters, digits and underbar characters. There is no restriction on the
  number of components that can	be included in an event	name.  An event	tem-
  plate	must contain at	least two components.  An event	must contain at	least
  three	components to be accepted for posting.

  The naming scheme provides an	open-ended way to identify events, letting
  you provide detail to	any level.  Careful naming gives the system adminis-
  trator an intuitive and precise way to select	events for viewing and moni-
  toring and facilitates the identification of the system components which
  issue	events and the recognition of patterns that warn of problems.  The
  more detail included in the event name, the more precise the specification
  criteria can be.




  Event	Identifier


  The event identifier data item is a numeric quantity,	assigned to an event
  by the EVM daemon as the event is posted.  In	combination with the host and
  timestamp data items,	the value can be used to produce a unique identity
  for an event.

  The daemon assigns identifiers according to the following rules:

    +  Each posted event receives an unsigned integer event identification
       number, with a value greater by one than	that of	the previous event
       posted through the same EVM daemon.

    +  The event identifier of the first event posted after the	daemon is
       started or restarted is zero.

    +  The event identifier wraps back to zero after it	has reached its	max-
       imum value.

    +  If a daemon receives an event that already contains an identifier, it
       does not	generate a new identifier for the event. This may happen if
       the event is a cluster event posted in another node.

    +  New event identifiers are assigned only to events which the daemon
       validates and accepts for distribution.

    +  If an event is accepted and does	not already contain an identifier, a
       new identifier is assigned to it	even if	there are no subscribers for
       the event.

  Event	Priority


  EVM uses an event's priority value solely for	filtering, sorting and
  presentation purposes	- it does not use it to	prioritize the distribution
  sequence. The	priority is an integer value in	the range 0-700, with zero
  being	the least significant priority.	 This table indicates the event
  priority, the	default	action taken by	evmlogger for that priority, and a
  description of the priority.

  _______________________________________________________________
		      Default
  _______________________________________________________________
  EVM Priority/Name   Notification	  Description
  700

  Emergency	      Log, mail	to root

					  A dangerous situation
					  has been detected and
					  immediate action either
					  is required or has been
					  taken.
  600 -	699

  Alert		      Log, mail	to root

					  A dangerous situation
					  is imminent and immedi-
					  ate action either is
					  required or has been
					  taken.
  500 -	599





  Critical	      Log, mail	to root

					  A failure has	been
					  detected that	renders
					  some part of the system
					  inoperable.
  400 -	499

  Error		      Log

					  A non-critical failure
					  has been detected in or
					  by some component of
					  the system or	applica-
					  tion.
  300 -	399

  Warning	      Log

					  Some aspect of the sys-
					  tem or application
					  requires attention.
  200 -	299

  Notice	      Log

					  Notification of an
					  expected operational
					  event	that the com-
					  ponent is designed to
					  deal with.
  100 -	199

  Information	      None

					  A normal operational
					  event	- for example, an
					  application has started
					  or terminated	normally.
					  Events in this range
					  typically will not be
					  saved	in the system EVM
					  log file.
  1 - 99

  Debug		      None

					  Program debug	informa-
					  tion.	Events in this
					  range	may be monitored
					  for informational pur-
					  poses, but typically
					  will not be saved in
					  the system EVM log
					  file.
  0

  None		      Application

					  Priority 0 should be
					  used for events that
					  are specifically
					  intended to be sub-
					  scribed to by	programs,
					  and are not expected to
					  be interesting to
					  administrators.
  _______________________________________________________________

  Catalog Name and Message Set Id


  If you plan to internationalize your events, you will	need to	supply an
  I18N catalog file containing the format strings for all of the events, and
  include the name of the file in the event. You also can break	the file into
  multiple message sets, and give the message set id in	the event - but	note
  that all messages pertaining to a particular event must belong to the	same
  set. If all events described in a single template file use messages from
  the same catalog or message set or both, you will probably want to supply
  these	items as global	values,	so that	you need only to specify them once.







  Cluster event


  You should set the cluster event data	item only if your application is
  cluster-aware, and is	posting	the event on behalf of the cluster, rather
  than an individual node.  Cluster events are distributed to all nodes	in
  the cluster.

  Formatting an	Event for Display


  Although an event is an opaque binary	structure, it can be formatted into a
  human-readable string	by using the evmshow(1)	command	or by calling the
  EvmEventFormat(3) function.  Formatting is essential for human-oriented
  output, but may not be necessary for an application program that will	sim-
  ply extract any variable data	the event contains, and	take the necessary
  action.

  The starting point for formatting an event is	the format data	item.  A for-
  mat is a text	string that may	contain	a simple piece of text,	the names of
  standard data	items, or the names of variables whose values are to be	sub-
  stituted into	the text, or any combination of	these.

  You include variable names for substitution by preceding them	with a $
  character - for example $temp.  You include standard data items by preced-
  ing their names with @ - for example,	@timestamp.

  The EvmEventFormat(3)	routine	automatically converts data items or vari-
  ables	into displayable form, regardless of their types.

  You can escape the special meaning of	a $ or @ characters in the format
  text by preceding it with a backslash	(\). To	include	a literal backslash
  in the text, use a double backslash.

  If an	event does not include a format	data item, formatting it will result
  in a default text string that	includes the event name	and any	variables the
  event	may contain.

  If the event includes	a repeat count,	then the repeat	count is prepended to
  the output in	the form [repeat_counttimes].

  Variable Data	Items


  You can use variable data items in your events to provide data that may be
  different each time the event	is posted.

  You can give the variable any	name you like -	the name is a string that is
  carried with the event, and can be used by a subscriber to extract the data
  in its original form.	 A variable name can be	made up	of any combination of
  upper	or lower case alphanumeric characters and the underscore character.
  By convention, names beginning with an underscore are	reserved for system
  use.

  EVM's	variable data items have these properties:

    +  A name

    +  A type

    +  A value

    +  A size (implicit	for most types)

    +  An I18N message id (for string variables	only)

  The following	table shows the	variable types that EVM	supports:

  __________________________________________________________
  Type Identification	Remarks
  __________________________________________________________
  EvmTYPE_BOOLEAN	8-bit integer
  EvmTYPE_CHAR		8-bit character
  EvmTYPE_INT16		16-bit signed integer
  EvmTYPE_INT32		32-bit signed integer
  EvmTYPE_INT64		64-bit signed integer
  EvmTYPE_UINT8		8-bit unsigned integer
  EvmTYPE_UINT16	16-bit unsigned	integer
  EvmTYPE_UINT32	32-bit unsigned	integer
  EvmTYPE_UINT64	64-bit unsigned	integer
  EvmTYPE_FLOAT		32-bit floating	point value
  EvmTYPE_DOUBLE	64-bit floating	point value
  EvmTYPE_STRING	Null-terminated	character string
  EvmTYPE_OPAQUE

			Binary data - cannot be	interpreted
			directly. The size must	be specified
			explicitly.
  __________________________________________________________

RESTRICTIONS

  Data types EvmTYPE_FLOAT and EvmTYPE_DOUBLE cannot be	used for events
  posted within	the kernel.

SEE ALSO

  Commands: evmshow(1)

  Routines: EvmEventFormat(3)

  Files: evmtemplate(4)

  Event	Management: EVM(5)