engine.conf.spec file

Taken from solutions/TA-vmware/1.0/package/default/engine.conf.spec

# ${copyright}
#
# This file contains possible attribute / value pairs for configuring the behavior of a given
# engine instance. This file is used in the Splunk App for VMware Forwarder Appliance.
#
# To learn more about configuration files (including precedence) please see the documentation
# located at http://www.splunk.com/base/Documentation/latest/Admin/Aboutconfigurationfiles

#******************************************************************************
# This describes the format for the special [default] engine.conf stanza
#******************************************************************************

[default]
* This stanza is optional and defines default settings that are either global in nature or
values that should be applied to all other stanzas in the given engine.conf file.
* Note: There should be at most 1 [default] stanza in any given engine.conf file.
* Be careful when specifying settings in this stanza - these will affect all other stanzas
in this file, which can lead to unintended side-effects.

#******************************************************************************
# The possible attribute / value pairs for the [default] stanza and their
# default values are as follows:
#******************************************************************************

fa = <Unique name of this FA instance>
* Optional. If left unspecified, the default value is the FA's IP address.
* This is the name given to a specific FA; it should be set to a unique value for each FA
across the entire solution.
* This setting is intended to only be used in the [default] stanza, not in regular stanzas.
* This setting determine the value of the "fa" field that is set in all events generated by
the engine instances running in the FA.
* Since this is really just a string label, it can be any value (a unique name, short / long
DNS hostname, IP address, etc.)

appFunctionMetrics = (ON|OFF)
* Optional. Only one of the two values can be specified.
* This setting determines whether or not detailed internal performance metrics are gathered
by the engine and is most useful for detailed debugging and performance profiling of the
engine's internal operation. The data contains information about key internal functions
and important VMware API (SDK) functions. When enabled, the data is captured and sent to
the front-end (Splunk App for VMware) for additional analysis.
* This setting is typically used in the [default] stanza, not in regular stanzas. It can be
used in regular stanzas if there is a specific target VC machine or ESX/i host that only you
want to gather data about (but not other ones).
* The default value is "OFF", so no data will be gathered.
* This setting causes additional data to be forwarded to the _internal index (with
sourcetype=vmware:_internal) and therefore uses some additional storage. However, these
events do not count towards daily licensing volume.

customInvSourceWhitelist = <regex>
* Optional. The perl compatible regular expression that matches the inventory data sources you
wish to *include* during data collection. If your PCRE skills are rusty, just remember
that source names should be separated by "|" (with no surrounding spaces) and you should be
fine.
* This setting is used to provide very low-level, fine-grained control over the amount and
kind of inventory data gathered. It is used in conjunction with the "inventoryLevel"
setting (see below). The engine will only gather the inventory sources whose names match
the terms of the regex.
* This setting is intended to be used only in the [default] stanza, not in regular stanzas.
As a result, it can be applied to either VC machines or ESX/i hosts, as determined by which
regular stanzas specify the "inventoryLevel" setting.
* Generally speaking, you should *not* attempt to use this setting unless you are a Splunk for
VMware expert and understand exactly how the custom source list will affect the front-end
(Splunk App for VMware). The list of potential sources is very large, and it will be very
easy to make the solution appear to break.
* NOTE: This setting is *only* applied when the "inventoryLevel=Custom" setting is placed in a
stanza (see below). It is ignored for all other cases (i.e. stanzas that do not have the
"inventoryLevel" setting specified, or when it is set to "Required").
* Valid inventory source names map directly to objects in the VMware API Reference. The
list of valid source names is too large to list here. Please see the VMware API Reference
documentation for more information:
http://www.vmware.com/support/developer/vc-sdk/visdk41pubs/ApiReference/index.html
Look at the "Managed Object Types" and "Data Object Types" sections of the doc to see the
available source names (can be found on the left side of the page).
* If this setting is not specified or it is left blank (no value), but "inventoryLevel=Custom"
is set in a stanza, all sources are included in inventory collection in that stanza by
default.
* Because sources can be specified with a regex, it is possible to capture many sources at
once. For example, if you want to collect all HostSystem-related inventory objects, most
of them can be captured by including the string "Host" in the regex, which will match all
source names that contain the string "Host".
* If both customInvSourceWhitelist and customInvSourceBlacklist are specified, a source is
collected only when it matches the customInvSourceWhitelist regex but does *not* match
the customInvSourceBlacklist regex.
* We recommend not using this setting at all and leaving "inventoryLevel" unspecified in
stanzas so that "all" inventory data is collected. If you filter out certain inventory
sources, certain views in the front-end (Splunk App for VMware) will appear to break.

customInvSourceBlacklist = <regex>
* Optional. The perl compatible regular expression that matches the inventory data sources you
wish to *exclude* during data collection. If your PCRE skills are rusty, just remember
that source names should be separated by "|" (with no surrounding spaces) and you should be
fine.
* This setting is used to provide very low-level, fine-grained control over the amount and
kind of inventory data gathered. It is used in conjunction with the "inventoryLevel"
setting (see below). The engine will not gather the inventory sources whose names match
the terms of the regex.
* This setting is intended to be used only in the [default] stanza, not in regular stanzas.
As a result, it can be applied to either VC machines or ESX/i hosts, as determined by which
regular stanzas specify the "inventoryLevel" setting.
* Generally speaking, you should *not* attempt to use this setting unless you are a Splunk for
VMware expert and understand exactly how the custom source list will affect the front-end
(Splunk App for VMware). The list of potential sources is very large, and it will be very
easy to make the solution appear to break.
* NOTE: This setting is *only* applied when the "inventoryLevel=Custom" setting is placed in a
stanza (see below). It is ignored for all other cases (i.e. stanzas that do not have the
"inventoryLevel" setting specified, or when it is set to "Required").
* Valid inventory source names map directly to objects in the VMware API Reference. The
list of valid source names is too large to list here. Please see the VMware API Reference
documentation for more information:
http://www.vmware.com/support/developer/vc-sdk/visdk41pubs/ApiReference/index.html
Look at the "Managed Object Types" and "Data Object Types" sections of the doc to see the
available source names (can be found on the left side of the page).
* If this setting is not specified, but "inventoryLevel=Custom" is set in a stanza, no sources
will be excluded from inventory collection in that stanza by default.
* If this setting is specified and left blank (no value), but inventoryLevel=Custom is set
in a stanza, *all* sources will be excluded from inventory collection in that stanza by
default. In other words, dont ever leave this setting blank.
* Because sources can be specified with a regex, it is possible to capture many sources at
once. For example, if you want exclude all HostSystem-related inventory objects from
collection, most of them can be specified by including the string "Host" in the regex,
which will match all source names that include the string "Host".
* If both customInvSourceWhitelist and customInvSourceBlacklist are specified, a source is
collected only when it matches the customInvSourceWhitelist regex but does *not* match
the customInvSourceBlacklist regex.
* We recommend not using this setting at all and leaving "inventoryLevel" unspecified in
stanzas so that "all" inventory data is collected. If you filter out certain inventory
sources, certain views in the front-end (Splunk App for VMware) will appear to break.

hierarchyExpiration = <seconds>
* Optional. If left unspecified, the default value is 900 (15 minutes).
* This is an advanced setting and typically should not be changed from the default value.
Specifying a time above 30 minutes (1800 seconds) can cause certain hierarchy-based
summary indexes in the front-end App to produce incorrect results.
* This setting is primarily used to set the time window over which the engine gathers the
entire hierarchy data snapshot plus any wait time. If a hierarchy snapshot completes in
less than the specified time value, hierarchy collection will wait until the total time
(execution + wait time) is equal to or greater than the specified value before starting
again.
* When the time window expires, the engine will allow a new, full snapshot of the hierarchy
data to start gathering. It can be useful in large environments where the engine may
take a long time to gather the entire hierarchy. In these cases, the time expiration
window should be set to a value that is slightly longer than the amount of time
HierarchyDiscovery takes to gather the entire hierarchy from the entire environment.
* This setting is intended to be used only in the [default] stanza, not in regular stanzas.
As a result, it can be applied to either VC machines or ESX/i hosts, as determined by which
regular stanzas specify the "action=HierarchyDiscovery" setting.
* Note: If you set the expiration window to a value that is too small relative to the
hierarchy size, hierarchy data collection will "snap" to the next available time window.
For example, if the window is set to 15 minutes, but collection takes 20 minutes, hierarchy
data collection will not start again until the 30 minute mark. While this does not cause
immediate problems, it is best to set the window correctly to most efficiently gather the
data as fast as possible. This is particularly important if the VMware environment is
undergoing a lot of changes over a short period of time or there is a strong desire to
gather data and see changes as close to real-time as possible. However, setting the
expiration window too small can cause other problems, such as creating contention for engine
execution time, and that can lead gaps in other kinds of data that the same engine instance
is supposed to gather. As a result, we do *not* recommend setting this value to be lower
than 5 minutes because it can cause too much data collection and other problems, even in
small environments.
* This setting can also be used as a coarse-grained way to control the amount of hierarchy data
that the solution collects. If your hierarchy doesn't change very often, or you are willing
to live with using older data (vs. closer to real-time) as a way to keep licensing costs low,
then you can set this value higher. By setting the value higher, the engine will gather data
less frequency - i.e. a bigger time window means that new, full hierarchy updates are
collected less often. However, note that the amount of hierarchy data collected is small
relative to other kinds of data (e.g. logs, inventory, performance). Therefore, from a
practical standpoint, there may be little savings from limiting hierarchy data and it is
normally better to fine-tune other data sources first.

hierarchyTimeSlot = <seconds>
* Optional. If left unspecified, the default value is 10 seconds.
* This is the amount of time that HierarchyDiscovery will pull hierarchy data before stopping
and letting another discovery module run.
* This setting is intended to only be used in the [default] stanza, not in regular stanzas.
As a result, it can be applied to either VC machines or ESX/i hosts, as determined by which
regular stanzas specify the "action=HierarchyDiscovery" setting.
* If the VMware environment is large, it may make sense to increase this value substantially.
From a Splunk for VMware Solution perspective, the size of an environment is measured by the
number of ESX/i hosts and VMs managed by VC instances. Note that the number of ESX/i hosts
under management by VCs may be much larger than the subset of hosts that the VMware Solution
is supposed to monitor (as configured in one or more engine.conf files). See the user
documentation for a more detailed discussion of what a "large" environment looks like.
* Generally, the time slot value can be increased when an engine instance is dedicated to
hierarchy data collection because there is less risk of starving other data collection
actions (e.g. inventory, performance, etc.)
* We recommend that this value be set smaller than the "interval" setting's value.

inventoryExpiration = <seconds>
* Optional. If left unspecified, the default value is 900 (15 minutes).
* This is the amount of time that InventoryDiscovery will run before starting a new, full
update of the inventory data.
* This is an advanced setting and typically should not be changed from the default value.
Specifying a time above 2 hours (7200 seconds) can cause certain inventory-based
summary indexes in the front-end App to produce incorrect results.
* This setting is primarily used to set the time window over which the engine gathers the
entire inventory data set one time and only getting changes to existing objects. When the
time window expires, the engine will mark all inventory objects as "stale" and start to get
a new, full update. It is especially useful in large environments where the engine may take
a long time to gather the entire inventory. In the typical case, the time expiration
window should be set to a value that is slightly longer than the amount of time
InventoryDiscovery takes to gather the entire inventory from the target VC machine or ESX/i
host.
* This setting is intended to only be used in the [default] stanza, not in regular stanzas.
As a result, it can be applied to either VC machines or ESX/i hosts, as determined by which
regular stanzas specify the "action=InventoryDiscovery" setting.
* Note: If you set the expiration window to a value that is too small relative to the
inventory size, inventory collection can "back up" because the engine will start updating
existing inventory data while also still trying to gather new inventory objects. This can
cause problems, the biggest of which is contention for engine execution time, and that can
lead gaps in other kinds of data that the same engine instance is supposed to gather. As a
result, we do *not* recommend setting this value to be lower than 15 minutes because it can
cause too much data collection and other problems, even in small environments.
* This setting can also be used as a coarse-grained way to control the amount of inventory data
that the solution collects. If your inventory doesn't change very often, or you are
willing to live with using older data (vs. closer to real-time) as a way to keep licensing
costs low, then you can set this value higher. By setting the value higher, the engine will
gather data less frequency - i.e. a bigger time window means that new, full inventory updates
are collected less often.

#******************************************************************************
# This describes the format for a regular engine.conf stanza
#******************************************************************************

[<server spec>]
* The stanza name (<server_spec>) should not contain underscores ("_").
* Each stanza in engine.conf defines the specific data collection and other behaviors that
the engine should use for each vCenter Server (VC) and / or ESX/i host that it interacts with.
* Each stanza in a given engine.conf file *must* have a unique name. The exact value used
for the stanza name is not terribly important, as long as it is unique.
* The attributes defined under each stanza heading are used to set specific properties for
a given VMware entity targeted by the stanza (i.e. a VC machine or ESX/i host) . Note: A
stanza can only target one VMware machine at a time as defined by the url setting (see below).
* For recommendations on how best to structure your engine.conf file(s) and define stanzas
appropriately for different kinds and sizes of VMware environments, please refer to the user
documentation.
* Note: it is common practice to repeat target machines (VCs or ESX/i hosts) in stanzas but use
different "action" settings (see below) in order to closely control the data gathering
behavior of an engine instance.

#******************************************************************************
# The possible attribute / value pairs for regular engine.conf stanzas and their
# default values are as follows:
#******************************************************************************

url = <URL>
* The URL to connect to; it is the same value as the variable VI_URL in the VMware SDK.
* The value has the following format: https://<host name or ip address>/sdk/webService
* This setting determines which target VC machine or ESX/i host that the engine will connect
to and gather data from.
* This setting is intended to only be used in regular stanzas, not in the [default] stanza.
It can be used to target both VC machines and ESX/i hosts for data collection.

username = <username>
* The username to login to the url; it is the same value as the variable VI_USERNAME in
the VMware SDK.
* This setting is not needed if you have created a credentials.conf file and it contains a
stanza that includes the VC or ESX/i host specified by the given stanza.
* This setting is generally intended to only be used in regular stanzas, but it can also be
placed in the [default] stanza if all stanzas are supposed to use the same username
setting. It can be applied to either VC or ESX/i host stanzas.

password = <password>
* The password to login to the url; it is the same value as variable VI_PASSWORD in the
VMware SDK.
* This setting is not needed if you have created a credentials.conf file and it contains a
stanza that includes the VC or ESX/i host specified by the given stanza.
* This setting is generally intended to only be used in regular stanzas, but it can also be
placed in the [default] stanza if all stanzas are supposed to use the same password
setting. It can be applied to either VC or ESX/i host stanzas.

host = <name>
* Optional, but we recommend setting this for all stanzas that target VC machines and
"unmanaged" ESX/i hosts. An unmanaged ESX/i host is one that is not managed by any VC
instance.
* This setting is intended to only be used in regular stanzas, not in the [default] stanza.
It can be applied to either VC or ESX/i host stanzas.
* For a VC machine or an unmanaged ESX/i host, this setting is important because it becomes
the value of the "host" field for all data events generated by the engine. Since this is
really just a string label, it can be any value (a unique name, short / long DNS hostname,
IP address, etc.)
* For VC machines, this should be set to the "VC instance name" - i.e. the name of the root
node in the VC's "Hosts and Clusters" view as seen in the vSphere Client.
* For unmanaged ESX/i hosts, this value should be the same as the first name in /etc/hosts
in the ESX/i host. With the requrement satisfied, it is best to set this value to a label
that is similar to the host's fully qualified domain name (if it were present in DNS).
* If left unspecified for a VC machine or an unmanaged ESX/i host, the default value is the
host name or IP address used in the url setting.
* For a "managed" ESX/i host (one that is managed by a VC instance), this setting is ignored.
Instead, the value of the "host" field is set automatically based on the name of the host
as shown in the "Hosts and Clusters" tree view within VC.

action = <module-list>
* Optional. The list of modules (delimited by commas) to run against the specified machine
(as determined by the url setting). Each module gets a particular kind of data from VMware
and sends it to the relevant Splunk indexer(s) as determined by outputs.conf.
* This setting is typically given values based on the kind of machine to get data from (e.g. a
VC machine or an ESX/i host). Even if this value is not present, the TimeDiscovery action
will be performed.
* This setting is generally intended to only be used in regular stanzas, but it can also be
placed in the [default] stanza if all stanzas are supposed to use the same action setting.
Putting this setting in the [default] stanza would be unusual because it is typically most
useful to get different kinds of data from different kinds of machines, which implies that
most "action" settings will be different from stanza to stanza (e.g. VC machines provide
different kinds of data vs. ESX/i hosts). The obvious exception to this is when a given
engine instance (and its engine.conf file) only covers one or two actions that are common
across all of the stanzas. For example, this might happen when an engine instance is
dedicated to getting hierarchy data, and therefore all stanzas would have the setting
"action=HierarchyDiscovery". It can be applied to either VC or ESX/i host stanzas.
* The only time that the action setting should be unspecified or set to blank (no value), is
when telling the Engine how to reach a particular VC instance but gather no data. This
should only be done when an engine.conf file tells the engine to get performance data from
an ESX/i host (using the PerfDiscovery action) and doesn't actually need to get other kinds
of data from VC.
* Available discovery actions are:
- InventoryDiscovery
- HierarchyDiscovery
- PerfDiscovery
- EventDiscovery
- TaskDiscovery
- LogDiscovery
* Note: Each action may have some special constraints, as follows:
a) InventoryDiscovery: For inventory, there are no special constraints other than paying
careful attention to inventory collection times and setting inventoryExpiration
appropriately (see above for a description).
- Note: In almost all circumstances, this action should only be applied to VC or
unmanaged ESX/i host stanzas (i.e. ESX/i hosts that are not managed by any VC).
Inventory data for managed ESX/i hosts is collected via VC.
b) HierarchyDiscovery: For hierarchy, there is 1 special constraint beyond paying careful
attention to hierarchy collection timing by setting the hierarchyExpiration and / or
hierarchyTimeSlot appropriately (see above for descriptions). In order to make the
solution work properly, all stanzas with "action=HierarchyDiscovery" *must* be run by the
same engine instance. Therefore, all stanzas with hierarchy actions must be located in a
single engine.conf file. This is currently needed in order to ensure that all hierarchy
data is captured in a single "snapshot". In a future release, multiple concurrent
hierarchy snapshots will be supported and this restriction will be removed. But for now,
it is important not to place HierarchyDiscovery actions in different engine.conf files.
- Note: Under normal circumstances, this action should be applied to every VC and ESX/i
host (managed and unmanaged) to be monitored by the solution.
c) PerfDiscovery: In order to make the solution handle performance data properly, if a
stanza gets performance data from a managed ESX/i host, a stanza for its associated VC
machine *must* also be placed in the same engine.conf file. The "action" field in the VC
stanza can be missing or blank if no other kinds of data need to be gathered from the given
VC in the given engine instance. That is, what matters is that the engine knows how to
reach the host's associated VC (using the url setting).
Here are some clarifying examples:
- Example 1: Assume that VC #1 manages ESX/i host "A" (i.e. it is a "managed" host) and
there is already a stanza to get data from VC #1 in the engine.conf file. In this case,
there is no need to do anything special. Simply specify the "A" ESX/i host's stanza
normally (with "action=PerfDiscovery,...") and the solution will work properly.
- Example 2: Assume that VC #1 manages ESX/i host "A" but there is no stanza to get data
from VC #1 in the engine.conf file because a different engine instance is getting VC
inventory data (and thus the inventory data gathering configuration is in a different
engine.conf file). In this case, you *must* place a stanza for VC #1 in the engine.conf
file anyway and the solution will work properly. In this case, the VC #1 stanza can have
"action=" or simply be left unspecified.
- Note: Under normal circumstances, this action should be applied to every ESX/i host
(managed or unmanaged) to be monitored for performance data. It should also be applied to
every VC to be monitored by the solution and used in conjunction with the
perfManagedEntityWhitelist setting to limit the amount of performance data collected from
VC (see description below).
d) EventDiscovery: For VMware events, there are no special constraints. Note: Under normal
circumstances, this action should only be applied to VC or unmanaged ESX/i host stanzas
(i.e. ESX/i hosts that are not managed by any VC). VMware event data for managed ESX/i
hosts is collected via VC.
e) TaskDiscovery: For VMware tasks, there are no special constraints. Note: Under normal
circumstances, this action should be applied to every VC and ESX/i host (managed and
unmanaged) to be monitored by the solution.
f) LogDiscovery: For ESX/i host logs, there are no special constraints. Note: Under normal
circumstances, this action should only be applied to ESX/i host stanzas (managed or
unmanaged). VC log data is collected via the vCenter Server Add-on solution component.
For more information about this topic, please see the user documentation explanation of
special constraints on engine.conf files.

disabledAction = <module-list>
* Optional. The list of modules (delimited by commas) to disable.
* This value has higher priority than the action setting.
* This setting is intended to only be used in regular stanzas, not in the [default] stanza.
It can be applied to either VC or ESX/i host stanzas.
* This setting is rarely used. It is really only useful when a set of actions has been
specified in the [default] stanza (which is unusual) and this setting is used to selectively
turn off some of the default actions.

interval = <seconds>
* Optional. This is the amount of time (in seconds) that the Engine waits in-between invoking
different actions in a given stanza. If this value is not present, a default value of 3
seconds will be used.
* For example, if an Engine.conf stanza shows "Action=InventoryDiscovery, HierarchyDiscovery",
then the engine will invoke InventoryDiscovery (which will run until it hits a stopping
point), then the engine will then wait 3 seconds before it calls HierarchyDiscovery.
* This setting is generally intended to only be used in regular stanzas, but it can also be
placed in the [default] stanza if all stanzas are supposed to use the same interval setting.
Putting this setting in the [default] stanza would be unusual because it is typically most
useful to get different kinds of data at different intervals, which implies that most
"interval" settings will be different from stanza to stanza based on the action, which
determines the type of data to collect (e.g. task data is collected at a different interval
vs. performance data). The obvious exception to this is when a given engine instance (and
its engine.conf file) only covers one or two actions that have a common interval across all
of the stanzas. For example, this might happen when an engine instance is dedicated to
getting hierarchy data at a common interval (e.g. 3 seconds), and therefore all stanzas
would have the setting "interval=3". It can be applied to either VC or ESX/i host stanzas.

invBlacklist = <regex>
* Optional. The perl compatible regular expression that matches the managed entities to
filter out of inventory collection. If your PCRE skills are rusty, just remember that
entity names should be separated by "|" (with no surrounding spaces) and you should be
fine.
* This setting is used to provide high-level control over the amount of inventory data to
be collected. When combined with other inventory data controls (e.g. inventoryLevel),
this can provide decent control over the amount and kinds of inventory data that the
engine should collect. Both the invBlacklist and inventoryLevel can be specified at the
same time. By default, inventory collection covers all of the major managed entities
and their children. The invBlacklist is first applied (to eliminate large parts of the
inventory tree at the managed entity level), and then the inventoryLevel will be applied
(to select only specific sources out of what is left).
* This setting is generally intended to be only used in regular stanzas, but it can also be
placed in the [default] stanza if all stanzas are supposed to use the same blacklist
setting. It can be applied to either VC or ESX/i host stanzas. It should only be used in
stanzas where the "action=InventoryDiscovery" setting is specified.
* Managed entities are key high-level inventory objects. Most other inventory objects are
lower-level children of a managed entity. If a given managed entity is filtered out using
the blacklist, then its children are also filtered out. For example, if HostSystems are
blacklisted from inventory data collection, then related child objects like vNICs and
vHBAs will also be filtered out.
* Valid managed entities are:
- ClusterComputeResource
- ComputeResource
- Datacenter
- Folder
- HostSystem
- ResourcePool
- VirtualMachine
* If this value is not present, all of the above managed entities are collected.
* We recommend leaving this setting unspecified so that inventory data for all types of
managed entities are gathered. If you filter out certain types of managed entities,
certain views in the front-end (Splunk App for VMware) will appear to break.

inventoryLevel = (All | Required | Custom)
* Optional. Only one of the three values can be specified.
* This setting is used to provide fine-tune controls on the amount of inventory data to
be collected. When combined with other inventory data controls (e.g. invBlacklist), this
can provide decent control over the amount and kinds of inventory data that the engine
should collect. Both the invBlacklist and inventoryLevel can be specified at the
same time. By default, inventory collection covers all of the major managed entities and
their children. The invBlacklist is first applied (to eliminate large parts of the
inventory tree at the managed entity level), and then the inventoryLevel will be applied
(to select only specific sources out of what is left).
* This setting is generally intended to be used only in regular stanzas, but it can also be
placed in the [default] stanza if all stanzas are supposed to use the same inventoryLevel
setting. It can be applied to either VC or ESX/i host stanzas. It should only be used in
stanzas where the "action=InventoryDiscovery" setting is specified.
* The default value is "All", and data about all available inventory sources will be gathered.
* If set to "Required", only a small set of predefined sources are collected - i.e. the sources
that are needed to populate all of the views in the front-end (Splunk App for VMware).
* If set to "Custom", the customInvSourceWhitelist and customInvSourceBlacklist settings
are used to determine exactly which sources will be gathered (see above).
* We recommend leaving this setting unspecified so that all inventory data is gathered. If
you choose a custom level and forget to specify certain required types of inventory data,
certain views in the front-end (Splunk App for VMware) will appear to break.

perfManagedEntityWhitelist = <regex>
* Optional. The perl compatible regular expression that matches the managed entities
types you wish to gather performance data about. If your PCRE skills are rusty, just
remember that entity names should be separated by "|" (with no surrounding spaces) and you
should be fine.
* This setting is used to provide high-level control over the amount of performance data
to collect. It is used to select specific managed entities and add them to the performance
data collection action. When combined with mid-level performance data type controls (e.g.
perfTypeWhitelist), this can provide fairly fine-grained control over the amount and kinds
of performance data that the engine should collect. Both whitelists can be specified at
the same time. The managed entity list is applied first (to select specific managed
entities), and then the performance data type list is applied (to select the types of
performance data on the given managed entities to collect).
* This setting is generally intended to be used only in regular stanzas, but it can also be
placed in the [default] stanza if all stanzas are supposed to use the same whitelist
setting. It can be applied to either VC or ESX/i host stanzas. It should only be used
in stanzas where the "action=PerfDiscovery" setting is specified.
* The allowed entity names are:
- ClusterComputeResource
- HostSystem
- ResourcePool
- VirtualApp
- VirtualMachine
* If this setting is not present, or no value is provided, all of the above managed
entities are collected.
* We recommend setting perfManagedEntityWhitelist to the value "ClusterComputeResource"
when getting performance data from VC (i.e. in a stanza with a url setting pointed at a
VC machine) and to simply omit this setting for stanzas that get data from ESX/i hosts.
If you forget to specify certain types of performance data, certain views in the
front-end (Splunk App for VMware) will appear to break.

perfTypeWhitelist = <regex>
* Optional. The perl compatible regular expression that matches the type of performance
data you wish to collect. If your PCRE skills are rusty, just remember that performance
data type names should be separated by "|" (with no surrounding spaces) and you should be
fine.
* This setting is used to provide mid-level control over the types of performance data to
collect. It is used to select specific types of performance data and add them to the
performance data collection action. When combined with managed high-level managed entity
controls (e.g. perfManagedEntityWhitelist), this can provide fairly fine-grained control
over the amount and kinds of performance data that the engine should collect. Both
whitelists can be specified at the same time. The managed entity list is applied first
(to select specific managed entities), and then the performance data type list is applied
(to select the types of performance data on the given managed entities to collect).
* This setting is generally intended to be used only in regular stanzas, but it can also be
placed in the [default] stanza if all stanzas are supposed to use the same whitelist
setting. It can be applied to either VC or ESX/i host stanzas. It should only be used
in stanzas where the "action=PerfDiscovery" setting is specified.
* The allowed performance type values include:
- cpu
- disk
- net
- mem
- power
- vmop
- dStore (datastore)
- clSvcs (clusterServices)
- mAgent (managementAgent)
- sAdapt (storageAdapter)
- sPath (storagePath)
- resCpu (rescpu)
- vDisk (virtualDisk)
- vcDbg (vcDebugInfo)
- vcRes (vcResources)
- sys (system)
* If this value is not present, all of the above performance types are collected.
* We recommend leaving this setting unspecified so that all types of performance data are
gathered. If you forget to specify certain types of performance data, certain views in
the front-end (Splunk App for VMware) will appear to break.

vmPerfCounterWhitelist = <list>
* Optional. Valid values are PCRE for abbreviated performance counters.
counters. Engine Builder will by default only collect metrics needed for threshold pages,
but if this is left blank, all perf counters will be collected.

hostPerfCounterWhitelist = <list>
* Optional. Valid values are PCRE for abbreviated host system performance
counters. Engine Builder will by default only collect metrics needed for threshold pages,
but if this is left blank, all perf counters will be collected.

perfLevel = <level>
* Optional. Valid levels are 1, 2, 3, or 4 (note: only one "level" value can be set at a
time.) The default level is 4.
* This setting is used to provide high-level control over the amount of performance data
gathered from VC machines.
* This setting is generally intended to be used only in regular stanzas, but it can also be
placed in the [default] stanza if all stanzas are supposed to use the same perfLevel
setting. It can only be applied to VC stanzas. It should only be used in stanzas where
the "action=PerfDiscovery" setting is specified.
* It defines the amount of performance data that the engine will gather by "level". Each
performance metric in VMware has an associated "level". This is explained in the VMware
API Reference:
http://www.vmware.com/support/developer/vc-sdk/visdk41pubs/ApiReference/vim.HistoricalInterval.html#level
The higher the level, the more performance metrics that will be gathered.
* This setting can only be used in a VC stanza (i.e. in a stanza with a url setting pointed
at a VC machine) because only VC machines classify performance metrics by level. In other
kinds of stanzas, the setting will be ignored.
* Each level value includes all of the metrics with lower level values. For example, if
the <level> is set to "2", the engine will collect all level 1 and 2 performance counters.
* This setting does NOT affect the amount of data collected by vSphere itself; it only
affects the amount of performance data that the engine collects from VC and ESX/i hosts
using the "level" mechanism that they already understand.

perfInstanceData = (ON|OFF)
* Optional. Only one of the two values can be specified.
* This setting is used to provide high-level control over the amount of performance data to
collect. It is used to specify whether instance data should be collected or not. Instance
identifies specific devices reporting a type of metric. For example, vmnic0 stands for a
virtual Ethernet adapter. For the definition of instance data, please see
http://pubs.vmware.com/vsphere-50/topic/com.vmware.wssdk.pg.doc_50/PG_Ch16_Performance.18.2.html .
* If the setting is "OFF", engine will not collect instance data, but still collect aggregate
data. When combined with entity controls (e.g. perfManagedEntityWhitelist)
and data type controls (e.g. perfTypeWhitelist), this can provide fairly fine-grained
control over the amount and kinds of performance data that the engine should collect.
* This setting is generally intended to be used only in regular stanzas, but it can also be
placed in the [default] stanza if all stanzas are supposed to use the same whitelist
setting. It can be applied to either VC or ESX/i host stanzas. It should only be used
in stanzas where the "action=PerfDiscovery" setting is specified.
* The default value is "OFF". If this setting is not present, or no value is provided,
only aggregate data is collected.

perfInstanceDataPerfTypeBlacklist = (All|None|<perftype-list>)
* Optional. This value can be set to "All", "None", or a perftype-list. The perftype-list is a
list of perftype delimited by "|". Here are the performance type that has performance data for
its instance and the meaning of instance.
- cpu : core of CPU
- disk : individual disk
- mAgent : individual managementAgent(hostd, vpxd, and so on)
- net : individual physical or virtual NICs and other network devices (such as virtual switch)
- sPath : specific storage path
- sys : the phsycial system resource
- vDisk : individual virtual disk
* This setting is used to adjust the type of instance data only when perfInstanceData is "ON".
If this value is set to "All", it is equivalent to set perfInstanceData to "OFF". In short,
perfInstanceData has higher priority than this field.
* This setting is generally intended to be used only in regular stanzas, but it can also be placed
in the [default] stanza if all stanzas are supposed to use the same setting. It can be applied to
either VC or ESX/i host stanzas. It should only be used in stanzas where the "action=PerfDiscovery"
setting is specified.
* The default value is "sys|cpu|mAgent" which reports performance data for disk related and network
instances.

eventHistory = <hours>
* Optional. The event history specifies the number of hours you wish to go back in time to
collect VMware events.
* This setting is generally intended to be used only in regular stanzas, but it can also be
placed in the [default] stanza if all stanzas are supposed to use the same eventHistory
setting. It can be applied to either VC or ESX/i host stanzas. It should only be used in
stanzas where the "action=EventDiscovery" setting is specified.
* Increasing the eventHistory value increases the amount of time the EventDiscovery
module takes on its first pass, which increases the time it takes for Splunk to start
processing data from VMware.
* If this value is not present, event collection starts at the time when the EventDiscovery
module begins running.

eventWhitelist = <regex>
* Optional. The perl compatible regular expression that matches the types of VMware event
data you wish to collect. If your PCRE skills are rusty, just remember that event names
should be separated by "|" (with no surrounding spaces) and you should be fine.
* This setting is generally intended to be used only in regular stanzas, but it can also be
placed in the [default] stanza if all stanzas are supposed to use the same whitelist
setting. It can be applied to either VC or ESX/i host stanzas. It should only be used in
stanzas where the "action=EventDiscovery" setting is specified.
* The value matches event types, which can be found in the VMware API Reference:
http://www.vmware.com/support/developer/vc-sdk/visdk41pubs/ApiReference/index.html
* If this value is not present, all available VMware event types will be collected.

logWhitelist = <regex>
* Optional. The perl compatible regular expression that matches log files to be collected.
If your PCRE skills are rusty, just remember that log file names should be separated by "|"
(with no surrounding spaces) and you should be fine.
* This setting is generally intended to be used only in regular stanzas, but it can also be
placed in the [default] stanza if all stanzas are supposed to use the same whitelist
setting. It can only be applied to ESX/i host stanzas. It should only be used in
stanzas where the "action=LogDiscovery" setting is specified.
* Valid values for an ESXi host are:
/var/log/vmware/hostd.log
/var/log/messages
/var/log/vmware/vpx/vpxa.log
* Valid values for an ESX host are:
/var/log/vmware/hostd.log
/var/log/messages
/var/log/vmware/vpx/vpxa.log
/var/log/vmkernel
/var/log/vmksummary.txt
/var/log/vmkwarning
* The value is matched against the full log file name and path on the ESX/i host. Since a
PCRE is used for matching, it is sufficient to simply give the short form of the log
name. For example, you can specify "hostd" to get the hostd.log file you do *not*
need to specify the full path.
* If this value is not present, all logs will be collected.

taskHistory = <hours>
* Optional. The task history specifies the number of hours you wish to go back in time to
collect tasks.
* This setting is generally intended to be used only in regular stanzas, but it can also be
placed in the [default] stanza if all stanzas are supposed to use the same taskHistory
setting. It can be applied to either VC or ESX/i host stanzas. It should only be used
in stanzas where the "action=TaskDiscovery" setting is specified.
* Increasing the taskHistory value increases the amount of time the TaskDiscovery
module takes on its first pass, which increases the time it takes for Splunk
to start processing data from VMware. Given that task collection is a relatively short
operation anyway, the added time should not have a big impact.
* If this value is not present, it defaults to 5 times the "interval" value (in seconds).

Installation and Configuration Guide

Related Answers

engine.conf.spec file

Comments