Professional Documents
Culture Documents
5.5.0
Administration and Configuration Guide
© 2009 Quest Software, Inc. ALL RIGHTS RESERVED.
This guide contains proprietary information protected by copyright. The software described in this guide is furnished
under a software license or nondisclosure agreement. This software may be used or copied only in accordance with
the terms of the applicable agreement. No part of this guide may be reproduced or transmitted in any form or by any
means, electronic or mechanical, including photocopying and recording for any purpose other than the purchaser's
personal use without the written permission of Quest Software, Inc.
If you have any questions regarding your potential use of this material, contact:
Quest Software World Headquarters
LEGAL Dept
5 Polaris Way
Aliso Viejo, CA 92656
www.quest.com
email: legal@quest.com
Refer to our Web site for regional and international office information.
Trademarks
Quest, Quest Software, the Quest Software logo, AccessManager, ActiveRoles, Aelita, Akonix, AppAssure,
Benchmark Factory, Big Brother, BusinessInsight, ChangeAuditor, ChangeManager, DeployDirector,
DirectoryAnalyzer, DirectoryTroubleshooter, DS Analyzer, DS Expert, ERDisk, Foglight, GPOADmin, Imceda,
IntelliProfile, InTrust, Invirtus, iToken, I/Watch, JClass, Jint, JProbe, LeccoTech, LiteSpeed, LiveReorg, LogADmin,
MessageStats, Monosphere, NBSpool, NetBase, NetControl, Npulse, NetPro, PassGo, PerformaSure, Quest Central,
Quest vToolkit, Quest vWorkSpace, ReportADmin, RestoreADmin, SelfServiceADmin, SharePlex, Sitraka,
SmartAlarm, Spotlight, SQL LiteSpeed, SQL Navigator, SQL Watch, SQLab, Stat, StealthCollect, Storage Horizon,
Tag and Follow, Toad, T.O.A.D., Toad World, vAutomator, vControl, vConverter, vFoglight, vOptimizer Pro, vPackager,
vRanger, vRanger Pro, vSpotlight, vStream, vToad, Vintela, Virtual DBA, VizionCore, Vizioncore vAutomation Suite,
Vizioncore vBackup, Vizioncore vEssentials, Vizioncore vMigrator, Vizioncore vReplicator, Vizioncore vTraffic,
Vizioncore vWorkflow, WebDefender, Webthority, Xaffire, and XRT are trademarks and registered trademarks of Quest
Software, Inc in the United States of America and other countries. Other trademarks and registered trademarks used
in this guide are property of their respective owners.
Disclaimer
The information in this document is provided in connection with Quest products. No license, express or implied, by
estoppel or otherwise, to any intellectual property right is granted by this document or in connection with the sale of
Quest products. EXCEPT AS SET FORTH IN QUEST'S TERMS AND CONDITIONS AS SPECIFIED IN THE
LICENSE AGREEMENT FOR THIS PRODUCT, QUEST ASSUMES NO LIABILITY WHATSOEVER AND DISCLAIMS
ANY EXPRESS, IMPLIED OR STATUTORY WARRANTY RELATING TO ITS PRODUCTS INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR
NON-INFRINGEMENT. IN NO EVENT SHALL QUEST BE LIABLE FOR ANY DIRECT, INDIRECT,
CONSEQUENTIAL, PUNITIVE, SPECIAL OR INCIDENTAL DAMAGES (INCLUDING, WITHOUT LIMITATION,
DAMAGES FOR LOSS OF PROFITS, BUSINESS INTERRUPTION OR LOSS OF INFORMATION) ARISING OUT OF
THE USE OR INABILITY TO USE THIS DOCUMENT, EVEN IF QUEST HAS BEEN ADVISED OF THE POSSIBILITY
OF SUCH DAMAGES. Quest makes no representations or warranties with respect to the accuracy or completeness of
the contents of this document and reserves the right to make changes to specifications and product descriptions at any
time without notice. Quest does not make any commitment to update the information contained in this document.
Retrieving Data.....................................................................................................................................................725
Merging Host Objects....................................................................................................................................................725
Managing Host Aliasing Rules .............................................................................................................................727
Creating Host Aliasing Rules................................................................................................................................735
Index..................................................................................................................................................................821
10 Foglight
Administration and Configuration Guide
Introduction to this Guide
This chapter provides information about what is contained in the Administration and
Configuration Guide. It also provides information about the Foglight documentation
suite and Quest Software.
About Foglight
Foglight is an application management solution that reduces or eliminates service
disruptions to unify IT and the business. Unlike other solutions, it provides a correlated,
360 degree view of your applications from end user to database and from service levels
to infrastructure—to source the root cause of every incident impacting your business
and fix them quickly. Foglight correlates data from multiple perspectives into a single
version of the truth to provide deep insight into the service relationships that exist
between end users, the business and infrastructure components. Its unique adaptive
technology rapidly adjusts to change for improved application performance and service
levels, reduced operational cost and risk, and enhanced visibility for all stakeholders.
numbers that are used by Foglight, or manage and install Foglight licenses or support
bundles using the Setup & Support dashboards.
Chapter 4, Managing Users and Security—Explains the security concepts and their
entities used in Foglight such as users, groups, and roles. It contains step-by-step
instructions on how to use these entities in order to effectively manage security in
Foglight using the Users & Security dashboards.
Chapter 5, Managing Cartridges—Contains information on how to install and
manage cartridges, and download agent packages. Use this chapter to learn about
cartridge-related concepts in Foglight and to find out how to install and manage
cartridges using the Cartridges dashboards.
Chapter 6, Managing Agents—Includes conceptual and hands-on information about
collection agents and explains their purpose in Foglight. It contains instructions on how
to manage agents on monitored hosts, deploy agent packages and create agent instances,
and to edit agent properties when required using the Agents dashboards.
Chapter 7, Working with Foglight Rules and Registry—Discusses the concepts of
rules and registry variables and their relations with the topology model in Foglight. It
includes step-by-step instructions on how to efficiently create, edit, and manage
Foglight rules and registry variables using the Rules & Registry dashboards. It also
contains several real-life examples that can help you understand their usage.
Chapter 8, Using Schedules—Explains the concept of schedules in Foglight and their
usage in rules, agent blackouts, and derived metrics. It contains instructions on how to
create and manage schedules to their best potential using the Schedules dashboards.
Chapter 9, Working with Data—Provides conceptual information about the topology
model, collected metrics, and their data types. Additionally, it instructs you how to add
custom data types to the topology model, create derived metrics, assign threshold levels
to metrics, and manage the periods of time in which Foglight samples or purges data,
using the Data dashboards.
Chapter 10, Working with Foglight Tooling—Provides insight into advanced
administration tasks such as building custom agents or using queries to retrieving data
from the data model. It contains detailed instructions on how to upload agent scripts,
build and deploy and script agents, and to drill through topology to retrieve data using
the Foglight query language, all using the Tooling dashboards.
Chapter 11, Using the Query Language—Discusses the Foglight query language
contains instructions on how to use it. Foglight uses a query language to set the scope
for rules and derived metrics, to create rule conditions and expressions, to reference
expressions in messages, and to create derived metric expressions.
14 Foglight
Administration and Configuration Guide
• PDF: The complete Foglight documentation set is available in Adobe PDF from
SupportLink. The PDF documentation can also be found in the Documentation
folder on the Foglight DVD. The following subset is available from the computer
Foglight is installed on: Administration and Configuration Guide, User Guide,
Command-Line Reference Guide, Web Component Guide and the Web
Component Tutorial. In addition, the cartridges ship with PDF guides. To view
the installed PDF guides, in Windows go to Start > Programs > Quest Software
> Foglight 5.5.0 > Documentation. The default location of the documentation
after installation is <foglight_home>/docs. Adobe Reader is required.
• HTML: Release Notes are provided in HTML format.
Introduction to this Guide 15
Foglight Documentation Suite
• Videos: Tutorial videos are not provided with the product, but are available on
SupportLink. They provide an easy and accessible way to learn about key
features and help you get started with Foglight.
Text Conventions
The following table summarizes how text styles are used in this guide:
Convention Description
Interface Bold text is used for interface options that you select (such as
menu items) as well as keyboard commands.
Email info@quest.com
Refer to our web site for regional and international office information.
The Administration module allows you to use Foglight in a way that best implements
your business logic. It offers a set of dashboards that allow you to manage Foglight
cartridges, agents, data, rules, and security.
This section gives an introduction to the Administration dashboards in the Foglight
browser interface. It also describes the process of logging into the browser interface and
the Welcome page.
Note Foglight displays dynamic data that is updated regularly. For this reason it is not
recommended that you use your browser’s Back and Forward buttons, as this may cause
cached views to be displayed or result in an error message.
ID Speed Total
Alarm A
CPU Memory Alarm C
Alarm B
Host A
Model A
Host B
Alarm D
CPU Memory Alarm F
Alarm E
ID Speed Total
Legend
Model Node Property Metric Alarm
Foglight makes use of a topology model to describe the logical and physical
relationships between data nodes. Hierarchy in topology models provides the context
Getting Started with the Administration Module 21
About Models and Scope in Foglight
for metrics and properties. Foglight stores context information only once. The
relationship between nodes, metrics, properties, and other nodes propagates the context
across multiple data elements.
Foglight stores metrics and properties next to one another. Unlike properties, that
describe nodes and are typically static in nature, metrics change over time as Foglight
collects them. For example, in a host model, CPU ID is a property that describes a CPU
node while CPU Utilization is a metric that can change between sampling periods. If the
CPU ID changes, Foglight adds a new node to the collection model with the new CPU
ID and associates any collected metrics such as CPU Utilization with the newly-created
node.
In Foglight, the Data dashboards illustrate the collection model and the data nodes that
Foglight creates as it collects performance metrics from monitored hosts. The Data
dashboard shows how nodes are organized and helps you identify paths to underlying
objects that you can use in Foglight queries and dashboards. Similar to directory paths, a
path in the topology model traverses the collection model through a series of nodes,
properties, metrics, and events that are separated by forward slashes '/'. For example, a
path that retrieves the current average CPU utilization for a host can look like the
following:
HostModel/hosts/<host_name>/cpus/processors/<processor>/utilization/current/
average
For complete information about the Data dashboard, see the Foglight User Guide. For
details on how to create dashboards, see the Web Component Tutorial.
Foglight allows you to create rules and apply them to the data that you collect from
multiple sources in your monitoring environment. Rules are scope-specific which
means that they are associated with one or more topology types against which they run.
Foglight uses agents and cartridges to collect data from monitored hosts. It creates a
dynamic data model while collecting data and uses that data to populate views and
dashboards. The Administration Module allows you to manage Foglight data collectors,
topology and rules that implement your business logic. It also lets you manage security
by granting user permissions to various Foglight entities.
22 Foglight
Administration and Configuration Guide
Logging in to Foglight
Foglight browser interface runs inside a Web browser. The browser interface supports
most Web browsers, such as Internet Explorer and Mozilla Firefox. For information on
which browser versions are supported, see the System Requirements and Platform
Support Guide. Before you log in, you need to ensure that your Foglight Management
Server and any Foglight agent instances are up and running, adjust browser settings, and
log into Foglight, as described below.
To log in to Foglight:
Note In order to complete this procedure, your user account must belong to a group with the
Administrator role. For more information about users, groups, and roles, see “Managing
Users and Security” on page 197.
1 Ensure that your Foglight Management Server and each of your Foglight Agent
Manager instances are up and running.
For example, on Windows platforms, you can start the Foglight Management
Server by choosing Start > Programs > Quest Software > Foglight 5.5.0 >
Start Foglight; to start the Foglight Agent Manager, you can start its process
either by issuing the fglam command (Unix or Windows) or starting its Windows
service (Windows only).
For details on starting the Foglight Management Server and Foglight Agent
Manager, see the Installation and Setup Guide. For complete information about
fglam and other command-line tools that come with Foglight, see the Command-
Line Reference Guide.
Note If you are using the Foglight Client instead of the Foglight Agent Manager, see
“Starting the Foglight Client” on page 808 for information on how to start the Foglight
Client.
You can start the browser interface by opening a Web browser instance and
navigate to the URL that uses the following syntax:
http://localhost:8080/console
Where localhost is the name of the machine that has a running instance of the
Foglight Management Server.
Note The above URL uses the default HTTP port number, 8080. For more information
about default port assignments, see Chapter 3, “Default port assignments” on
page 107.
• Navigation panel shows the dashboards that the current user can access.
For more information about users and security in Foglight, see Chapter 4,
“Managing Users and Security”.
• Display area contains the current dashboard. When you log into Foglight
the Welcome page appears in the display area. Once you select a
dashboard on the navigation panel, the display area refreshes to show the
selected dashboard.
• Action panel includes any actions that you can perform in the selected
dashboard.
For more information about the Welcome page in the display area, see
“Welcome Page” on page 26 in Introducing the Browser Interface.
• If your Foglight server does not have a valid license, one of the following
views appears in the display area, depending on your user permissions.For
more information about user permissions and security in Foglight, see
Chapter 4, “Managing Users and Security” on page 197.
Getting Started with the Administration Module 25
Logging in to Foglight
Note Your administrator may have configured Foglight so that the actual displays are different
from those in this section. The following information is intended only as a general guide.
Welcome Page
The first time that you log in to Foglight, the Welcome page appears in the display area.
Figure 2
The appearance of the Welcome page depends on your user permissions. If your user
account belongs to group that has the Administrator role, this is what you see when you
Getting Started with the Administration Module 27
Introducing the Browser Interface
log into Foglight for the first time. If you do not have the Administrator role, and you
have the Operator role, a slightly different version of the Welcome page appears in the
display area.
The Welcome page lists several tasks that you can perform by clicking an entry in the
list. Some of these tasks are common administrative tasks that you typically perform
upon logging in to Foglight. Clicking a task link on the Welcome page shows an
administrative dashboard related to the selected task in the display area. Most
dashboards that can be accessed from this page can be also be accessed from the
navigation panel.
For example, clicking Configure Email Settings on the Welcome page shows the Email
Configuration dashboard in the display area. Selecting this option is equivalent to
choosing Administration > Setup & Support > Email Configuration under
Dashboards on the navigation panel.
The Welcome page shows the following tasks:
• Extend Your Monitoring Reach: Generate a configuration plan for your
monitoring environment by completing a configuration interview, and execute it
step-by-step. For more information about this dashboard, see Chapter 2,
“Extending Your Monitoring Reach” on page 67.
• View Your Enterprise Health: Observe the overall health of your system by
viewing existing alarms, the state of your domains, services, and monitored hosts.
Clicking this link shows the View Your Enterprise Health page containing
additional links to the dashboards that show more details about each aspect of
your system health.
28 Foglight
Administration and Configuration Guide
Figure 3
• View, acknowledge and clear recent alarms: View the state of all alarms
across the entire Foglight installation so you can take immediate action on the
alarm. The alarm count by time is also shown, so that alarm storms or outage
events can be identified. This link takes you to the Alarms dashboard.
Choosing this option is equivalent to clicking Alarms under Homes on the
navigation panel. For more information about this dashboard, see the Foglight
User Guide.
• View Enterprise health organized by monitoring domain: View an end-to-
end summary of top-level views for all domains, organized by domain so you
can drill down to view a high-level summary of their managed instances. This
link takes you to the Domains dashboard. Choosing this option is equivalent to
clicking Domains under Homes on the navigation panel. For more
information about this dashboard, see the Foglight User Guide.
• View the health of critical services: Choose a level of service as a focal point
by subscribing to services of interest and viewing the service dependencies.
This link takes you to the Service Operations Console. Choosing this option is
equivalent to clicking Service Operations Console under Homes For more
information about this dashboard, see the Foglight User Guide.
• View the health of monitored hosts in your enterprise: View a high-level
summary of host performance on all monitored hosts such as on alarms and
CPU, memory, disk, and network utilization for active hosts. This link takes
you to the Hosts dashboard. Choosing this option is equivalent to clicking
Hosts under Homes on the navigation panel. For more information about this
dashboard, see the Foglight User Guide.
• Configure Email Settings: Configure Foglight to direct outgoing mail and
reports through your mail server. This link takes you to the Email Configuration
Getting Started with the Administration Module 29
Introducing the Browser Interface
Tip Clicking Even More in the lower-right corner shows the links to the default Home
pages: About Foglight, Administration, Agents, Alarms, Domains, Hosts, Main,
Reports, and Service Operations Console. Choosing these options is equivalent to
clicking the appropriate link on the navigation panel, under Homes.
• Administer Foglight: Get a quick insight into the system complexity and its
health. This link takes you to the Administration dashboard. This dashboard is
a good starting point for your daily administration tasks. Choosing this option
is equivalent to clicking Administration under Homes on the navigation
panel. For more information about this dashboard, see “Using a Single Pane of
Glass for Your Administration Needs” on page 37.
30 Foglight
Administration and Configuration Guide
Administration Dashboards
Each Foglight module contains a set of dashboards that you can configure and use to
monitor your environment in real time. You can access them from the navigation pane
on the left of the display area.
Figure 4
The Administration module includes a set of dashboards that allow you to manage
agents, cartridges, users, and other entities. You can find them on the navigation panel
under Dashboards > Administration.
Figure 5
The following table lists the nodes that appear in the Administration module, common
tasks that are associated with each node, and references to other topics in this manual
that contain information about each node or task.
32 Foglight
Administration and Configuration Guide
If your user account belongs to a group that have the required roles, you can use the
Foglight Administration module to carry out administration tasks. The table below lists
in more detail the administrative tasks you can perform in Foglight.
Note For more information about roles and security in Foglight, see Chapter 4, “Managing Users
and Security” on page 197.
Manage agents
Add thresholds
Users & Security List, add, edit, or delete users Chapter 4, “Managing
Users and Security” on
List, add, edit, or delete groups page 197
Note To complete the following procedure, your user account must belong to a group with the
Administrator role. For more information about users, groups, and roles, see “Managing
Users and Security” on page 197.
You have successfully logged into Foglight and located the dashboards that are
available in the Administration module. From here, you can proceed to “Accessing the
Administration Dashboard” on page 57.
Getting Started with the Administration Module 37
Using a Single Pane of Glass for Your Administration Needs
Figure 7
For in-depth information about the content of the Administration dashboard, and the
data that appears in each view, see “About the Administration Dashboard” on page 38.
For details on how to access this dashboard and perform some of the common
administration tasks, see “Accessing the Administration Dashboard” on page 57
The following table lists the entries in the Navigation view and identifies the dashboards
or views that they link to.
For instructions on how to use this view to complete administration tasks, see step 3 on
page 59 in Accessing the Administration Dashboard.
Explore
Agents
Cartridges
Data
Schedules
Server Log Log Analyzer Lists server log entries. For more
Overview information about this dashboard, see the
Foglight User Guide.
Script Editor Script Editor Allows you to query the Foglight database.
For more information, see “Retrieving Data
with Queries and Scripts” on page 721.
Tasks
Create
44 Foglight
Administration and Configuration Guide
Configure
Getting Started with the Administration Module 45
Using a Single Pane of Glass for Your Administration Needs
Active Agents
The number on the right of Agent Instances in the Current Statistics view is the number
of current agent instances.
46 Foglight
Administration and Configuration Guide
Use this drill-down to find out which agent instances are not connected. For instructions
on drilling down to other Administration dashboard from the Current Statistics view, see
“Accessing the Administration Dashboard” on page 57. For more information about
Foglight agents, see Chapter 6, “Managing Agents” on page 277.
Installed Cartridges
The number on the right of Installed Cartridges in the Current Statistics view is the
number of Foglight cartridges in your system.
Getting Started with the Administration Module 47
Using a Single Pane of Glass for Your Administration Needs
Figure 9
Use this drill-down to view the list of all cartridges that exist in your monitoring
environment. For instructions on drilling down to other Administration dashboard from
the Current Statistics view, see “Accessing the Administration Dashboard” on page 57.
For more information about Foglight cartridges, see Chapter 5, “Managing Cartridges”
on page 249.
48 Foglight
Administration and Configuration Guide
Rules
The number on the right of Rules in the Current Statistics view is the number of rules
that exist in your monitoring environment.
Figure 11
This number includes the rules that come with the Foglight Management Server, any
installed cartridges, and also any rules that you create. It gives you an idea of how much
business logic is running on your server. That number is proportional to the number of
cartridges you deploy. Clicking the Rules entry drills down to the Manage Rules
dashboard.
Figure 12
This number is a good general indicator of the environment complexity. The more rules
you have, the more work the server is doing to analyze the data and generate alarms. For
instructions on drilling down to other Administration dashboard from the Current
Getting Started with the Administration Module 49
Using a Single Pane of Glass for Your Administration Needs
Statistics view, see “Accessing the Administration Dashboard” on page 57. For more
information about Foglight rules, see Chapter 7, “Working with Rules” on page 406.
Users
The numbers on the right of Users in the Current Statistics view are the numbers of
Foglight users.
Figure 13
This number tells you how many users are currently logged in, and how many have
logged in total. It also gives you an idea how many people are accessing Foglight. If the
users experience slow response, that might be caused by a large number of users and
you might want to consider using a federation to separate users actions from data
processing. For more information about the federation feature in Foglight, see the
Federation Field Guide.
Clicking the Users entry drills down to the Manage Users dashboard.
Figure 14
For instructions on drilling down to other Administration dashboard from the Current
Statistics view, see “Accessing the Administration Dashboard” on page 57. For more
information about the concept of security in Foglight rules, see Chapter 4, “Managing
Users and Security” on page 197.
50 Foglight
Administration and Configuration Guide
Server Version
The text on the right of Server Version in the Current Statistics view is the version
number of your Foglight Management Server installation, followed by its build version.
Figure 15
Clicking the Server Version entry drills down to the Foglight Configuration dashboard.
This dashboard contains the settings that are configured in the <foglight_home>/config/
foglight.config file.
Figure 16
The Server view in the Foglight Configuration dashboard contains the server and build
version. For instructions on drilling down to other Administration dashboards from the
Current Statistics view, see “Accessing the Administration Dashboard” on page 57. For
more information about this view, see Chapter 3, “Server” on page 99.
Server OS
The text on the right of Server OS in the Current Statistics view identifies the operating
system of the computer on which the Foglight Management Server is installed.
Getting Started with the Administration Module 51
Using a Single Pane of Glass for Your Administration Needs
Figure 17
Clicking the Server OS entry drills down to the Foglight Configuration dashboard. This
dashboard contains the settings that are configured in the <foglight_home>/config/
foglight.config file. It allows you to view these settings if you do not have access to the
file system in which the Foglight Management Server is installed.
Figure 18
The Server view in the Foglight Configuration dashboard contains the operating system
version. For instructions on drilling down to other Administration dashboard from the
Current Statistics view, see “Accessing the Administration Dashboard” on page 57. For
more information about this view, see Chapter 3, “Server” on page 99.
install a Foglight license either using the command line, or the Manage Licenses
dashboard. For complete information about license management in Foglight, see
Chapter 3, “Managing Licenses” on page 133.
Figure 19
This view displays the license status of the following Foglight capabilities and indicates
if they are enabled or disabled.
• Cartridge Installation
• Configuration Management
• Data Archiving Trending
• High Availability
• LDAP Integration
• Performance Calendars
• Request Trace Analysis
Figure 20
For instructions on drilling down to other Administration dashboards from the License
Information view, see “Accessing the Administration Dashboard” on page 57. For
complete information about license management in Foglight, see Chapter 3, “Managing
Licenses” on page 133.
54 Foglight
Administration and Configuration Guide
Installed Licenses
The number on the right of Installed Licenses in the License Information view is the
total number of all installed Foglight licenses that exist in your system, including
current and expired licenses. Ensuring that your Foglight license is valid and up to date
can prevent unwanted behavior that can be caused by expired licenses.
Figure 22
Expired Licenses
The number on the right of Expired Licenses in the License Information view is the
number of expired licenses that exist in your system. Expired Foglight licenses can
cause unwanted behavior and this can be prevented by ensuring that your Foglight
licenses are valid and up to date.
Figure 23
logical units, where each unit acts as a data source, managed by a Foglight Management
Server instance (Federated Server), and a Federation Server, that manages the operation
of those units, merging their data into a central model.
In most cases the Federation Server has a different performance profile from Federated
Server instances. While a Federated Server focuses on data processing as well as
serving user requests, the Federation Server synchronizes with child models, and returns
data on demand. As a result, the master (Federation server) requires more memory than
its children. Knowing whether you're looking at a master or a child is critical.
Figure 25
For instructions on drilling down to other Administration dashboards from the License
Information view, see “Accessing the Administration Dashboard” on page 57. For
complete information about license management in Foglight, see Chapter 3, “Managing
Licenses” on page 133. For more information about the federation feature in Foglight,
see the Federation Field Guide.
56 Foglight
Administration and Configuration Guide
Federation Mode
The text on the right of Federation Mode in the Federation view identifies whether the
current Foglight Management Server installation is a child (Federated Server) or a
master (Federation Server) in a federated system. If this setting shows Child/
Standalone, as illustrated below, that is an indication that your monitoring
environment is not federated.
Figure 27
Number of Children
The number on the right of Number of Children in the Federation view is the number of
children of the current Foglight Management Server installation in a federated system.
If this setting shows zero ‘0’, combined with the Federation Mode value of Child/
Standalone, as illustrated below, that is a good indicator that your monitoring
environment is not federated.
Figure 28
For each audited activity, this view displays the following information:
Getting Started with the Administration Module 57
Using a Single Pane of Glass for Your Administration Needs
• Time Range. The date and time at which the audited activity is performed.
• User Name. The name of the user who initiated the audited activity.
• Service Name. The name of the service that carried out the audited activity.
• Operation Name (Name). The name of the operation that carried out the audited
activity.
Using the table control button in the upper-right , the contents of this table can be
filtered or printed to a file, as required.
Figure 30
Caution If you previously show or hide one or more columns in the audit log table, this layout is
reflected in the export file. For example, if you display only the time range and the
operation name, only those columns appear in the export file.
In addition to the Audited Activities view, the audited activities also appear in the View
Audit Information dashboard. For more information, see Chapter 3, “Viewing Audit
Information” on page 150.
Figure 31
The procedure below shows you how to navigate to the Administration dashboard and
to use it to drill down to other dashboards in the Administration module. For more in-
depth information about each of the views on the Administration dashboard, see “About
the Administration Dashboard” on page 38.
To access the Administration dashboard:
For complete information about the Agent Status dashboard, see Chapter 6,
“Installing and Managing Agent Instances on a Monitored Host” on page 292.
Getting Started with the Administration Module 61
Using a Single Pane of Glass for Your Administration Needs
For complete information about the Manage Rules dashboard, see Chapter 7,
“Managing Rules” on page 408.
To return to the Administration dashboard, click Administration in the
breadcrumb trail.
• To find out more about the server configuration, that exist in your
environment, in the Current Statistic view, click Server Version or Server
OS.
The Foglight Configuration dashboard appears in the display area.
Getting Started with the Administration Module 63
Using a Single Pane of Glass for Your Administration Needs
The License Information view lists the numbers of installed and expired licenses
and the licenses that are to expire within the next 30 days.
To find out more about your Foglight licenses, click an entry in the License
Information view.
The Manage Licenses dashboard appears in the display area.
The Federation view shows the federation mode of the Foglight Management
Server and the number of its children in the topology model.
To find out more about the federation configuration, click an entry in the
Federation view.
The Foglight Server Topology view appears in the display area.
The Audited Activities view lists log entries that show information about
operations performed on the Foglight Management Server. For example, this list
includes information about agent activation, agent package deployment, user
authentication, and other types of tasks.
From here, you can proceed to configuring Foglight as required. To find out about the
features that are offered by the Administration module, see “Administration
Dashboards” on page 31.
2
Extending Your Monitoring Reach
After an initial Foglight setup, use the Extend Your Monitoring Reach dashboards to
configure the hosts, databases, or JavaEE applications that you plan to monitor. For
other types of monitoring environments, see the respective cartridge documentation.
Note In order to complete each of the procedures in this chapter, your user account must belong
to a group with the Administration role. For more information about users, groups, and roles,
see “Managing Users and Security” on page 197.
Note Foglight supports the monitoring of a wide range of platforms. The Extend Your Monitoring
Reach workflow supports the configuration of the standard host, database, and JavaEE
monitoring only. Other Application Monitoring Technology Platforms are also available but
cannot be configured using this workflow. These platforms are listed below. Refer to their
respective documentation for configuration instructions.
• .NET
• Oracle E-Business
• PeopleSoft
• SAP
• Siebel
• VMWare
A generated configuration plan lists the tasks that you need to complete to start
monitoring your environment. These tasks typically involve installing agent manager
components on monitored hosts, installing cartridges, and creating agent instances.
Each task includes a link to its respective action or a dashboard in the browser interface
that you can navigate to in order to complete the task.
Tip In small- and mid-size organizations, use the Extend Your Monitoring Reach dashboard
immediately after the installation to quickly configure your monitoring environment, and to add
any cartridges and agents, based on your monitoring needs. If your business requirements
change at a later time, individual agents and cartridges can be modified using the Agents or
Cartridges dashboards.
plan to monitor host resources, databases, and JavaEE applications, with different
administrators looking after different parts of the monitored system, you can create
several configuration plans, each describing a particular component or a group of
components. If your monitoring needs change, you can return to Extend Your
Monitoring Reach at any time, and create additional configuration plans, as required.
Configuration plans consist of steps. Each step can have one or more tasks associated
with it. The type and range of steps depends on the complexity of your monitoring
environment. For example, if you intend to monitor host and databases resources, your
configuration plan includes six steps: a step for installing Foglight Agent Manager on
monitored hosts, a step for installing the appropriate cartridges on the Foglight
Management Server, and separate steps setting up host, database, and JavaEE
monitoring, as illustrated below.
Figure 1
For complete instructions on using the Extend Your Monitoring Reach dashboard, refer
to the following sections:
• “Accessing the Extend Your Monitoring Reach Dashboard” on page 70
• “Completing Configuration Interviews” on page 72
• “Viewing Configuration Plans” on page 84
• “Completing Configuration Tasks” on page 89
70 Foglight
Administration and Configuration Guide
Note Foglight supports the monitoring of a wide range of platforms. The Extend Your Monitoring
Reach workflow supports the configuration of the standard host, database, and JavaEE
monitoring only. Other Application Monitoring Technology Platforms are also available but
cannot be configured using this workflow. These platforms are listed below. Refer to their
respective documentation for configuration instructions.
• .NET
• Oracle E-Business
• PeopleSoft
• SAP
• Siebel
• VMWare
You can navigate between the steps in the wizard using the navigation buttons that
appear in the bottom-left corner of the display area, or the bread crumb trail at the top.
The navigation buttons allow you to move between the steps (Previous and Next) or to
skip steps in the wizard if required (Skip).
Extending Your Monitoring Reach 73
Completing Configuration Interviews
Figure 2
Note This procedure continues from “Accessing the Extend Your Monitoring Reach Dashboard”
on page 70.
Option Monitors
3 Specify the host machines running the hosts, databases, or JavaEE applications
that you want to monitor.
a In the List Hosts to Monitor view, click one of the following options to select
one or more hosts:
Import host names Pointing to a plain text file that contains a list of host
from a file names.
76 Foglight
Administration and Configuration Guide
Select hosts already Selecting the hosts from the Host Model. Any
being monitored by monitored host that already has the Foglight Agent
Foglight Manager installed is present in the Host Model.
The Foglight Agent Manager component is used to
manage agent instances and their communication
with the Foglight Management Server.
Tip Foglight Management Server installs include an
embedded Foglight Agent Manager. The embedded
Foglight Agent Manager on the Foglight
Management Server starts up and stops with the
server. This agent manager instance can be used to
deploy agents and monitor the host on which the
Foglight Management Server is installed, if required.
To monitor additional hosts in your environment, you
must install an agent manager component separately
on each host computer. For more information about
installing agent managers on monitored hosts, see
the Foglight Installation and Setup Guide.
Select hosts from the Using a list generated by the Cartridge for
latest discovery task Discovery.
table Note This option requires a previous discovery task
which uses the Cartridge for Discovery. For more
information about this cartridge, see your Cartridge
for Discovery documentation.
For example, to add existing hosts from the host model, click Select hosts
already being monitored by Foglight, and in the Add Hosts from Host
Model dialog box that appears, select the hosts that you want to monitor,
followed by clicking Add.
Extending Your Monitoring Reach 77
Completing Configuration Interviews
The Add Hosts dialog box closes and the Specified Host Names table
refreshes, showing the list of the newly-selected monitored hosts.
There are three technology types that you can monitor: Host, Database, and/or
JavaEE monitoring. The flow of the configuration interview depends on the
technology types selected in step 2. For example, if you choose standard host and
JavaEE monitoring in step 2, without selecting the database monitoring option,
the flow takes you through the steps for standard host and JavaEE monitoring,
without prompting you for information about database monitoring.
a Host monitoring only. In the Select Hosts For Standard Host Monitoring
view that appears, ensure that the hosts that you want to monitor appear,
followed by clicking Next.
In the refreshed display area, select one or more database hosts that you want
to monitor, followed by clicking Next.
If you selected multiple databases, the display area refreshes for each database
type. For example, selecting SQL Server and Oracle prompts for specifying
SQL Server database hosts, followed by specifying Oracle hosts.
80 Foglight
Administration and Configuration Guide
Tip Configuring databases with Foglight requires the appropriate database cartridges.
The configuration plan that you are about to generate includes the instructions for
installing these cartridges on the Foglight Management Server and their
configuration. For additional information, you can also refer to the cartridge
documentation.
5 Observe the Configuration Interview Complete view that appears when you
finish specifying the details about your monitoring configuration.
Tip Specifying a name of the configuration plan instead of using the provided date and
time helps you quickly find it in the list of existing configuration plans at a later time.
6 Save your changes to the configuration plan and view its contents.
In the Configuration Interview Complete view, click Take me to my
configuration plan.
Tip Another way to access the configuration plan is by selecting it in the Configuration
Plans view. For more information about accessing the Configuration Plans view, see
“Viewing Configuration Plans” on page 84.
Configuration plans consist of steps. Each step can have one or more tasks
associated with it. The type and range of steps depends on the complexity of your
monitoring environment. For example, if you intend to monitor host and
databases resources, your configuration plan includes three steps: a step for
installing the appropriate OS and database cartridges on the Foglight
Management Server, a step for setting up host monitoring, and lastly, a step for
database monitoring. Additionally, if you previously installed the Foglight Agent
Manager on all of the selected hosts, the configuration plan does not include a
step for installing the Foglight Agent Manager, as illustrated above. Similarly, if
you previously installed all of the required cartridges, the configuration plan does
not include the step for installing cartridges. In the above illustration, that step
appears as Step 1: Install Cartridges, indicating that one or more cartridges need
to be installed.
From here, you can follow the instructions in the configuration plan and to set up your
monitoring environment. For information on completing individual tasks, see
“Completing Configuration Tasks” on page 89.
84 Foglight
Administration and Configuration Guide
Important The appearance of the above steps depends on their completion prior to completing the
configuration interview. For example, if you installed the Foglight Agent Manager
component on all of the monitored hosts, the Set Up FglAM step does not appear in the
configuration plan.
Extending Your Monitoring Reach 85
Viewing Configuration Plans
Each configuration task includes a link to the specific dashboards that you can navigate
to carry out the task. Tasks also include a brief description of their state and, in some
cases, additional information about the task.
Figure 3
Note This procedure continues from “Accessing the Extend Your Monitoring Reach Dashboard”
on page 70.
86 Foglight
Administration and Configuration Guide
The view contains the following columns that provide additional information
about each list:
• Name: Contains the name of the completed configuration
• Created Time: Contains the time at which the configuration was generated.
• Monitoring Types: Indicates one or more monitoring types for each
configuration plan: host , database , and/or JavaEE application
monitoring.
Tip To delete a configuration plan, select the check box on the left of the date the list was
saved in the Configuration Plans view, followed by clicking Delete. In the Delete
Extending Your Monitoring Reach 87
Viewing Configuration Plans
The content of a configuration plan and its complexity depends on the range of
monitoring components that exist in the selected configuration. The list
contains one or more steps, and each step can have one or more tasks
associated with it.
A configuration plan can contain up to six steps: a step for installing the
Foglight Agent Manager on monitored hosts, along with additional steps for
each type of monitoring, as indicated in the configuration interview: host,
database, and/or JavaEE.
From here, you can start completing the tasks in the order they are listed. For
instructions, see “Completing Configuration Tasks” on page 89.
Extending Your Monitoring Reach 89
Completing Configuration Tasks
Figure 4
Note This procedure continues from “Viewing Configuration Plans” on page 84.
1 In the configuration task list, locate the task that you want to complete.
Important Tasks in a task list are listed in sequential order. In some cases, a task may
depend on one or more preceding tasks. Therefore, it is important that you complete
the tasks in the order they are listed. Failing to do so may prevent you from
successfully configuring your monitoring environment.
2 Read the task description and ensure you fully understand the task that you are
about to complete.
For example:
Extending Your Monitoring Reach 91
Completing Configuration Tasks
In the above example, the task requires that you deploy agent packages using the
Agent Hosts dashboard or using the task controls.
92 Foglight
Administration and Configuration Guide
Tip The check mark indicates that a task is marked as complete while the action of
marking a task does not check if the completion is successful. Similarly, when a task is
complete, the check mark indicator does not appear unless you mark it as complete. It
is used as a user-initiated flag, indicating that the task is marked as complete. As such,
marking an incomplete task as complete, and similarly, marking a complete task as
incomplete does not create any errors. These flags are simply used to help you
Extending Your Monitoring Reach 93
Completing Configuration Tasks
Once you get started with the Administration module, you can use the Setup & Support
dashboards to view Foglight configuration and to set it up.
Note In order to complete each of the procedures in this chapter, your user account must belong
to a group with the Administration role. For more information about users, groups, and roles,
see “Managing Users and Security” on page 197.
Note Foglight Client is an older version of the agent manager. Foglight supports both types of
agent manager components, Foglight Client and Foglight Agent Manager. For more about
the Foglight Client, see “Appendix: Foglight Client Reference” on page 807.
For each agent manager instance, the list shows the host’s IP address, login time, request
name, and request time.
To view the connection status:
Federation
Foglight federation allows for partitioning a monitoring environment into logical units,
where each unit is served by a separate instance of the Foglight Management Server
(federated server), while the operation of those servers is managed by a central Foglight
Management Server (federation server). The federated servers can be used to collect
data from different types of environments, while the federation server can access the
Setting Up Foglight 99
Viewing Foglight Configuration
data from one or more federated servers. For information on how to set up a federated
environment, see the Installation and Setup Guide.
The Federation view displays the following settings:
• Federation Mode. The Federation Mode setting indicates if the Foglight
Management Server whose configuration items you are viewing runs in
federation mode.
• Number of Children. The number of children of the Foglight Management
Server whose configuration items you are viewing. If the server does not run in
federation mode, or has no children, the number is zero ‘0’.
Server
The Server view displays the following settings:
100 Foglight
Administration and Configuration Guide
Federation Configuration
This view contains information about federation settings. The federation settings are
defined in the file <foglight_home>/config/federation.config. For more information
about this file, see the Installation and Setup Guide.
The Federation Configuration view displays the following settings:
• Connection URLs. The JNDI-provider URLs for federated servers. These URLs
should use the JNDI JNP port (see “Ports” on page 106), as configured in
<foglight_home>/config/foglight.config on the corresponding federated server.
This setting is defined by the JndiURLs parameter in the file <foglight_home>/
config/federation.config.
• Max Alarm Update Delay (millis). The maximal delay in milliseconds that is
allowed for the federation server to check all federated servers for alarm changes.
This setting is defined by the MaxAlarmUpdateDelay parameter.
• Max System Time Difference (millis). The maximal acceptable difference in
system time between federated servers and the federation server, in milliseconds.
This setting is defined by the MaxSystemTimeDifference parameter.
Setting Up Foglight 101
Viewing Foglight Configuration
• Topology Queries. A list of one or more topology queries that identify topology
objects that are be merged with the federated topology model. This setting is
defined by the TopologyQueries parameter.
• Topology Refresh Period (millis). The number of milliseconds between major
topology refresh operations. A major topology refresh operation involves re-
fetching all relevant topology objects from all federated servers and merging
them into the local topology model. This setting is defined by the
TopologyRefreshPeriod parameter.
Figure 3
Database
This view contains information about database settings. The database settings are
defined in the file <foglight_home>/config/foglight.config. For more information
about this file, see the Installation and Setup Guide.
The Database view displays the following settings:
• Host. The name of the database host. This setting is defined by the
foglight.database.host parameter.
• Port. The port number used by the database. This setting is defined by the
foglight.database.port parameter.
• Type. The type of the database. Possible values are mysql or oracle. This
setting is defined by the foglight.database.type parameter.
• Hibernate Dialect. The name of the component that defines the database
hibernate dialect.
• Database Name. The name of the database. This setting is defined by the
foglight.database.name parameter.
102 Foglight
Administration and Configuration Guide
JVM
The JVM view displays the following settings:
• Name. The name of the Java Virtual Machine (JVM) of the computer in which
the Foglight Management Server is running.
• Version. The version number of the JVM.
• Vendor. The name of the JVM vendor.
• Architecture (bit). The bit architecture of the JVM.
Figure 5
The JVM settings that appear in this view are not the full set. By default, the Foglight
launcher sets a number of additional JVM settings. To see all of the JVM parameters,
look for them under VM Options in the log file for the current session,
Setting Up Foglight 103
Viewing Foglight Configuration
OS
The OS view displays the following settings:
• Type. The name and version of the operating system on which the Foglight
Management Server is running.
• Patch. The patch level of the operating system on which the Foglight
Management Server is running.
104 Foglight
Administration and Configuration Guide
Figure 6
WCF
The WCF view displays the following settings:
• Version. The version number of the Web Component Framework (WCF) that is
included with Foglight.
• Build. The build version of the Web Component Framework (WCF) that is
included with Foglight.
Figure 7
Important In some situations you need to create or receive email alerts that contain a URL to the
browser interface. To ensure the URL points to the computer on which the Foglight
Management Server is running, ensure that the CATALYST_URL registry variable
contains the correct computer name and port number.
For information on how to look up Foglight registry variables, see Chapter 7, “Managing
Registry Variables” on page 365.
• From. The default email address used by Foglight from which emails are sent .
This setting is defined by the global value of the mail.from Foglight registry
variable.
• SMTP Host. The default email host name used by Foglight from which emails
are sent when required. This setting is defined by the global value of the
mail.host Foglight registry variable.
• SMTP Port. The default port number of the email server used by Foglight from
which emails are sent when required. This setting is defined by the global value
of the mail.port Foglight registry variable.
• Recipient. The default email address used by Foglight to which emails are sent
when required. This setting is defined by the global value of the
mail.recipient Foglight registry variable.
• Socket Timeout. The default socket timeout for sending emails to specified email
recipients.
Important The mail.socket.timeout variable does not come with Foglight. To configure the
global socket timeout, you need to create this variable and set it to a desired value. For
instructions, see step 3 in Chapter 7, “To configure email actions in Foglight:” on
page 474.
• User. The default user name for logging into the email server that is used by
Foglight to which emails are sent when required. This setting is defined by the
global value of the mail.user Foglight registry variable.
106 Foglight
Administration and Configuration Guide
Figure 8
Ports
This view lists ports used by Foglight.
Figure 9
• JavaEE Agent
• Cluster Mcast Port
• HA JNDI RMI Port
• HA JNDI JNP Port
• HA JRMP Invoker Port
• HA Pooled Invoker Port
• HA JNDI UDP Group Port
• HTTP Port
• HTTPS SSL Port
• JNDI RMI Port
• JNDI JNP Port
• JRMP INVOKER Port
• ORB (IIOP) Port
• ORB (IIOP) SSL Port
For complete information about the above ports, such as their default numbers or
communication points involved, see Default port assignments below.
Firewall Impact?
Communication
Default Number
Listens On
Direction
Used By
Name
Description: Port for the Remote Method Invocation (RMI) naming service.
Firewall Impact?
Communication
Default Number
Listens On
Direction
Used By
Name
1100 HA JNDI Foglight Foglight No From HA
JNP Port Management Management Foglight
Server Server Management
Server Primary
to HA Foglight
Management
Server
Secondary and
the other way
around
Note Foglight does not
support a firewall
between two server
instances.
Description: Port for the bootstrap JNP service when Foglight is running in the
High Availability (HA) mode. For more information about the HA mode, see the
Installation and Setup Guide.
Firewall Impact?
Communication
Default Number
Listens On
Direction
Used By
Name
Description: Port for the Remote Method Invocation (RMI) naming service when
Foglight is running in HA mode. It can be used to observe the network traffic
between the Foglight Management Server and other computers on the same
network. If it finds another JBoss server, it checks the partition name to see if the
JBoss server is a primary or a secondary server. For more information about the HA
mode, see the Installation and Setup Guide.
Firewall Impact?
Communication
Default Number
Listens On
Direction
Used By
Name
1102 HA JNDI Foglight Foglight No From HA
UDP Group Management Management Foglight
Port Server Server Management
Server Primary
to HA Foglight
Management
Server
Secondary and
the other way
around
Description: Port for the UDP group when Foglight is running in the HA mode. For
more information about the HA mode, see the Installation and Setup Guide.
Firewall Impact?
Communication
Default Number
Listens On
Direction
Used By
Name
Firewall Impact?
Communication
Default Number
Listens On
Direction
Used By
Name
4446 HA Pooled Foglight Foglight No From HA
Invoker Management Management Foglight
Port Server Server Management
Server Primary
to HA Foglight
Management
Server
Secondary and
the other way
around
Description: Pooled invoker port when Foglight is running in the HA mode. For
more information about the HA mode, see the Installation and Setup Guide.
Description: Port for the RMI/JRMP invoker when Foglight is running in the HA
mode. For more information about the HA mode, see the Installation and Setup
Guide.
Firewall Impact?
Communication
Default Number
Listens On
Direction
Used By
Name
Firewall Impact?
Communication
Default Number
Listens On
Direction
Used By
Name
8443 HTTPS Foglight Browser Yes From the
SSL Port Management interface and browser
Server Foglight interface to the
Agent Foglight
Manager Management
Server and
from the
Foglight Agent
Manager to the
Foglight
Management
Server
Firewall Impact?
Communication
Default Number
Listens On
Direction
Used By
Name
Description: Port used by the JavaEE Agent. For more information about the
JavaEE Agent, see your JavaEE cartridge documentation.
Tip In addition to the Email Configuration dashboard, email configuration parameters can be
viewed in the Mail (Global Settings) view of the Foglight Configuration dashboard. For more
information, see “Mail (Global Settings)” on page 104.
Alternatively, you can specify an email setting directly in the Foglight registry. For
detailed information, see “Viewing and configuring email settings” on page 467.
Caution Configuring email actions in the Foglight registry instead of using the Email
Configuration dashboard is recommended for advanced Foglight users.
For detailed information on how to configure email actions in Foglight, see the
following sections:
• “Accessing the Email Configuration Dashboard” on page 120
• “Editing Email Parameters” on page 123
• “Testing Email Configuration” on page 129
Tip Configure the email alias addresses listed below to receive alarm-related emails from
Foglight.
The Email Configuration dashboard appears in the display area, showing the
current email settings.
Setting Up Foglight 123
Configuring Email Actions
From here, you can proceed to edit the email parameters. For instructions, see “Editing
Email Parameters” on page 123.
If your email settings are static in nature, you can specify those values by typing it in a
dwell that appears when you click .
Figure 10
However, if your email settings are likely to change, use the registry editor to associate
them with performance calendars or topology types. For that purpose, the Email
Configuration dashboard contains links to the registry editor.
Tip If you are configuring email actions for a larger distributed environment with several
administrators, each looking after a different host, you can associate the recipient’s email
address with a particular host object instance. For an example illustrating such a business
scenario, see Chapter 7, “Example: Assigning Host-Specific Email Addresses of Foglight
System Administrators” on page 400.
When you finish configuring your settings in the registry editor, use the bread crumb
trail to return to the Email Configuration dashboard.
Setting Up Foglight 125
Configuring Email Actions
Figure 11
Link to the
registry editor
For complete information on how to edit registry values using the registry editor, see
Chapter 7, “Editing Registry Variables” on page 381.
Important To enable Foglight to send emails, at minimum, you need to specify the name or IP
address of the email server, Mail Server (Name or IP), and the user account from which
emails are sent, Email Sender Address. It is also important to specify the email
addresses of Foglight administrators to ensure they receive alarm-related emails such
as the Operating System Notifications parameter.
Foglight stores the email action parameters as registry variables. For information about
email parameters and their corresponding registry variables, see “Accessing the Email
Configuration Dashboard” on page 120.
126 Foglight
Administration and Configuration Guide
Note This procedure continues from “Accessing the Email Configuration Dashboard” on
page 120.
Note The appearance of the dwell depends on the data type of the parameter that you are
specifying. For example, configuring a text-based string shows a text box in the
dwell while the control for editing a Boolean value (such as Is Run in Debug Mode)
appears as a check box.
Tip To delete a parameter value, on the Email Configuration dashboard, in the row
containing the parameter whose value you want to delete, in the Clear column, click
. In the Confirm Delete dialog box that appears, click Yes.
3 Static values only. Specify the parameter value as instructed in the dwell and
click Save.
The Email Configuration dashboard refreshes, showing the newly-configured
value in the Value column.
Setting Up Foglight 127
Configuring Email Actions
4 Dynamic values only. Use the registry editor to specify the email settings that are
likely to change over time, or need to be scoped to particular object instances.
a In the dwell, click Use the advanced registry variable editor for routing
based on schedules or specific monitored objects.
The display area refreshes, showing the Edit Registry Variable view in the
Email Configuration dashboard.
Tip The registry editor shows the settings of the registry variable that is associated with
the configuration parameter that you are about to edit. For example, choosing to
edit the Mail Server (Name or IP) parameter in the registry editor, shows the
settings of the mail.host variable in the Edit Registry Variable view.
128 Foglight
Administration and Configuration Guide
b Use the Edit Registry Variable view to specify your custom settings.
For complete instructions on how to add performance calendars, registry
references, or to scope the variable to topology types or objects, see “Editing
Registry Variables” on page 381.
When you finish with updating the variable in the Edit Registry Variable
view, click Save and use the bread crumb trail at the top to return to the Email
Configuration dashboard.
The Email Configuration dashboard refreshes, showing the newly-configured
value in the Value column.
Setting Up Foglight 129
Configuring Email Actions
When you finish specifying the email parameters, you can proceed with testing your
email configuration. For instructions, see “Testing Email Configuration” on page 129.
Figure 12
Note This procedure continues from “Editing Email Parameters” on page 123.
The following screen capture shows the Email Server Configuration view that
illustrates a basic configuration, with the mandatory parameters set.
Setting Up Foglight 131
Configuring Email Actions
3 Use your email address as the destination address to test the email configuration.
In the Test Configuration dialog box, in the Additional Addresses box, type
your email address, then click Send Test Email.
Foglight accesses the mail server using the email configuration parameters and
sends a test email to the specified destination address. The Successful dialog box
appears, indicating a success of the email configuration.
132 Foglight
Administration and Configuration Guide
Managing Licenses
You can manage Foglight licenses using any of the following interfaces:
• Manage Licenses dashboard. Allows you install or delete Foglight licenses, and
to view licensing capabilities for each license. For details, refer to any of the
following sections as required:
• “Accessing the Manage Licenses Dashboard” on page 133
• “Installing Licenses” on page 134
• “Viewing License Capabilities” on page 136
• “Deleting Licenses” on page 138
• Command line. The fglcmd interface includes commands for installing, listing, or
removing Foglight licenses. For complete information, see the Command-Line
Reference Guide.
Note This procedure continues from “Logging in to Foglight” on page 22 or “Accessing the
Administration Dashboard” on page 57.
3 To sort the list by license serial number or expiry date, click Serial Number or
Expiry Date as required.
4 To filter the list of licenses, in the area that shows the list of installed licenses, use
the Filter by Serial Number, Expire After, and Expire Before boxes as
required.
To clear the filters, click Clear Filters.
From here, you can proceed to any of the following procedures:
• “Installing Licenses” on page 134
• “Viewing License Capabilities” on page 136
• “Deleting Licenses” on page 138
Installing Licenses
The Install License area in the Manage Licenses dashboard allows you to install licenses
on the Foglight Management Server. You can use it to install a license file that is
accessible from the local machine or the Foglight Management Server machine.
Alternatively, you can install a license using the command line using the
license:import command that comes with the fglcmd interface. For details, see the
Command-Line Reference Guide.
Setting Up Foglight 135
Managing Licenses
To install a license:
Note This procedure continues from “Accessing the Manage Licenses Dashboard” on page 133.
1 To navigate to the license file that you can access with your local machine,
complete one of the following steps in the Install License area of the Manage
License dashboard.
• Ensure that the File on Local Computer box is selected. Then click Browse,
and navigate to the license file in the file browser that appears.
The file browser closes and the File on Local Computer box refreshes to
show the absolute path and name of the license file.
or
• Select the File on Local Computer option, and in the box to the right, type the
absolute path and name of the license file
Note Use the back slash character ‘\’ as a directory separator on Windows platforms;
on Unix platforms, use the forward slash ‘/’.
Windows example:
C:\temp\foglight.license
2 To navigate to the license file that is accessible by the machine on which the
Foglight Management Server is running, complete the following steps.
a Select the File on Server box.
b In the File on Server box, type the path and name of the license file. Use
either an absolute path or a path relative to the installation directory of the
Foglight Management Server.
Note Use the back slash character ‘\’ as a directory separator.
For example, both of the following file paths point to the same license file:
C:\Quest_Software\Foglight\license\foglight.license
license\foglight.license
3 Click Install License.
A message appears, indicating that the license installation was successful.
136 Foglight
Administration and Configuration Guide
Once the Foglight Management Server reads the license file, it stores it internally in the
database and no longer requires the physical file.
Cartridge Installation
Configuration Management
High Availability
LDAP Integration
Performance Calendars
Additionally, Cartridge License Name in the same area lists the cartridges that are
licensed with your current Foglight license.
Setting Up Foglight 137
Managing Licenses
Alternatively, you can review licensing capabilities using the license:list command
that comes with the fglcmd interface. For details, see the Command-Line Reference
Guide.
To view license capabilities:
Note This procedure continues from “Accessing the Manage Licenses Dashboard” on page 133.
1 In the Manage Licenses dashboard, in the area that lists installed licenses, select a
license whose capabilities you want to view.
The Licensed Capability Summary area lists the capabilities of the selected
license and the cartridges that are included in the license.
In the Licensed Capability Summary area, an icon appears to the right of each
capability, indicating if the capability is enabled or disabled.
Capability is enabled.
Capability is disabled.
Cartridge License Name lists those cartridges that are licensed with the selected
Foglight license.
2 Additionally, in the license list under the Licensed Capability Summary area,
the Capabilities column shows icons of those capabilities for which each license
is enabled:
138 Foglight
Administration and Configuration Guide
• To find out which Foglight cartridges are licensed for a license, point to the
Cartridge Installation icon ( ).
A tooltip appears, indicating the cartridges that are covered by the selected
license.
Deleting Licenses
The license list pane allows you to delete any license currently enabled on Foglight.
Alternatively, you can delete a license using the license:remove command that
comes with the fglcmd interface. For details, see the Command-Line Reference Guide.
To delete a license:
Note This procedure continues from “Accessing the Manage Licenses Dashboard” on page 133.
1 In the Manage Licenses dashboard, in the area that lists installed licenses, select a
row containing the license that you want to delete.
2 Click Delete Selected.
The License Confirmation dialog box appears.
Setting Up Foglight 139
Managing Support Bundles
3 To proceed with license deletion, in the License Confirmation dialog box, click
Yes.
The License Confirmation dialog box closes. The list of installed licenses
refreshes and a message indicating that the delete process was successful appears
above the list.
You can create a server support bundle using the Manage Support Bundles
dashboard or the support:bundle command that comes with the fglcmd
interface.
For information about managing server support bundles using the Manage
Support Bundles dashboard, see the following sections:
• “Accessing the Manage Support Bundles Dashboard” on page 140
• “Creating Server Support Bundles” on page 141
• “Retrieving Server Support Bundles” on page 144
• “Viewing the Content of Server Support Bundles” on page 145
For information about the support:bundle command, see the Command-Line
Reference Guide.
• Foglight Agent Manager support bundles. Contain diagnostic information about
the Foglight Agent Manager. Foglight saves each support bundle in the
<foglight_agent_mgr_home>/state/default/support directory on the machine
hosting the Foglight Agent Manager.
The Manage Support Bundles dashboard does not include interface for creating
Foglight Agent Manager support bundles. To create one, use the
support-bundle command. For complete information about this command, see
the Command-Line Reference Guide.
For information about the support bundle content, see “Viewing the Content of a
Foglight Agent Manager Support Bundle” on page 148.
The Manage Support Bundles dashboard appears in the display area, showing the
list of existing support bundles.
3 To sort the list by name, description, creation date, or user name, click the Name,
Description, Created, or Created By column headings as required.
4 To filter the list of support bundles, in the area that shows the list of installed
licenses, use the Name, Description, Created, or Created By boxes as required.
To clear the filters, click Clear Filters.
From here, you can proceed to any of the following procedures:
• “Creating Server Support Bundles” on page 141
• “Retrieving Server Support Bundles” on page 144
• “Viewing the Content of Server Support Bundles” on page 145
Alternatively, you can delete a license using the support:bundle command that
comes with the fglcmd interface. For details, see the Command-Line Reference Guide.
Depending on the type of browser you are running and its settings, you might be able to
retrieve a copy of an existing server support bundle as a file download. For more
information, see “Retrieving Server Support Bundles” on page 144
To create a server support bundle:
Note This procedure continues from “Accessing the Manage Support Bundles Dashboard” on
page 140.
When Foglight finishes generating the support bundle, your Web browser
displays a dialog box that allows you to open or save the support bundle.
Setting Up Foglight 143
Managing Support Bundles
Note The appearance of the above dialog box may be different, depending on the type
and version of your Web browser.
In addition to the bundle name, the Support Bundle Inventory view shows the
bundle description, the date and time at which it was created, and the name of the
user who created it.
144 Foglight
Administration and Configuration Guide
Note This procedure continues from “Accessing the Manage Support Bundles Dashboard” on
page 140.
Note The appearance of the above dialog may be different, depending on the type and
version of your Web browser.
Note This procedure continues from “Retrieving Server Support Bundles” on page 144.
1 Locate the server support bundle whose content you want to view by completing
one of the following steps.
• If you have access to the computer that is hosting the Foglight Management
Server, server support bundles are stored in the <foglight_home>/support/
<user_name> directory.
or
• If you do not have access to the computer that is hosting the Foglight
Management Server, retrieve the support bundle using the Support Bundle
Inventory view.
For instructions, see “Retrieving Server Support Bundles” on page 144.
2 Extract the contents of the ZIP file containing the server support bundle to a local
directory.
3 Observe the file structure.
Each server support bundle consists of a number of files. The following list
illustrates a file collection sample that may appear in a server support bundle.
Note The list below does not include the entire list of files that are contained in server
support bundle. It is a partial listing that illustrates the directory structure and
describes some of the common files that appear in the support bundle.
146 Foglight
Administration and Configuration Guide
DirectoryListing_*.txt A full file listing for all files under the FMS
home directory
config/
logs/
server/
default/
conf/
deploy/
jbossweb-
tomcat55.sar/
Note This procedure continues from “Managing Support Bundles” on page 139.
1 Locate the Foglight Agent Manager support bundle whose content you want to
view.
2 Extract the contents of the ZIP file containing the support bundle to a local
directory.
3 Observe the file structure.
Each support bundle consists of the following files and directories:
agentstate/
<cartridge_name>/
<cartridge_version>/
config/
<agent_type>/
<agent_type>ConfigDefs.xml Property
configuration
definitions for the
agent package
<agent_type>ProcedureDefs.xml Procedure
definitions for the
agent package
common/
jvminfo.txt Java VM
information
mbean-info.txt MBean
information
glueconfig/
log.config Log
configuration
process.config Process
configuration
vm.config VM
configuration
logs/
FglAM-<yyyy>-<mm>-<dd>T<hh>-<mm>-<ss>.log Successful
startup logs
<cartridge_name>/
<cartridge_version>/
<agent_type>/
system/
<os>-system-info.txt OS information
3 Observe the audited entries. Each entry contains specific information about the
date and time at which the audited action is performed, name of the user who
initiated the action, name of the service that carried out the action, and the
operation name.
152 Foglight
Administration and Configuration Guide
4 Optional. Reduce the number of columns that appear in the audit log table.
a In the audit log table, in the Operation Name (Name) column, click the
Show/Hide columns button.
Show/Hide columns
Since all of the four columns appear in the View Audit Information dashboard
by default, all of the check boxes that correspond to the columns appear
selected.
b To hide a column, in the Show columns dialog box, clear the corresponding
check box.
or
To show a column, select the corresponding check box.
For example, to display only the time range and the operation name, ensure
that the Time Range and Operation Name (Name) check boxes are selected,
and clear the User Name and Service Name check boxes.
c Click Apply.
Setting Up Foglight 153
Viewing Audit Information
The audit log table refreshes, showing only the selected columns.
Show/Hide columns
b In the Show Columns dialog box, under Actions, click one of the following
links:
154 Foglight
Administration and Configuration Guide
Note The appearance of the above dialog box may be different, depending on the type
and version of your Web browser.
Important If you previously show or hide one or more columns in the audit log table, this
layout is reflected in the export file. For example, if you display only the time range and
the operation name, only those columns appear in the export file.
Note This procedure continues from “Accessing the View Audit Information Dashboard” on
page 151.
1 In the View Audit Information dashboard, click the time range control in the
upper-right corner of the display area.
The Zonar appears with the Timeline tab open, indicating the time range for
which the audit entries are displayed.
2 Change the date and time range for which the audit entries are displayed.
• To change the time range for the current date, on the Timeline tab of the
Zonar, drag the edges of the selected time period.
156 Foglight
Administration and Configuration Guide
or
• To change the date and the time range, in the Zonar , open the Calendar tab
and select a desired range.
The table with audit entries refreshes, showing different registry values for
different date and time periods.
For complete information about the Zonar, see the Foglight User Guide.
Note This procedure continues from “Accessing the View Audit Information Dashboard” on
page 151.
1 In the View Audit Information dashboard, locate the row in the log table
containing the entry whose details you want to view.
2 Observe the following columns for the selected entry:
• Time Range: Displays the date and time at which the specified action
occurred.
Setting Up Foglight 157
Backing Up, Upgrading, and Restoring Foglight
• User Name: Displays the user name for the user who caused the action to be
performed.
• Service Name: Displays the name of the Foglight service that performed the
action.
• Operation Name (Name): Displays the operation that was performed by
Foglight. If applicable, the name of the item that was changed is also displayed
in this column.
Backing Up Foglight
The term “backing up” refers to making copies of data that can be used to restore your
system after a data loss event. For details of the Foglight recovery procedure, see
“Restoring Foglight” on page 178.
This section outlines the Foglight backup process, which includes:
• Archiving the Foglight configuration file, scripts, and installed cartridges.
• Backing up the entire database (MS SQL, MySQL, or Oracle).
• Verifying the settings of environment variables (Oracle).
• Saving the archive in a safe location separate from the original. The process is
similar for Windows and Unix systems.
The following table shows the possible ways of backing up Foglight, some of which
include the backup of the file system, and in some cases the system registry (on
Windows). Each option shows a sequence of actions that can be performed to back up
Foglight.
158 Foglight
Administration and Configuration Guide
The procedures below contain detailed information on how to back up the Foglight
installation directory and the database, without backing up the file system or the system
registry (on Windows).
To back up Foglight on a Windows system:
1 Select Stop Foglight from the Start menu to shut down the Foglight
Management Server.
Setting Up Foglight 161
Backing Up, Upgrading, and Restoring Foglight
If you are running Foglight as a Windows service, stop the Foglight Management
Server service.
Important If you are using an external database and intend to upgrade Foglight after
backing it up, you should leave the database running. Doing so allows the installer to
successfully upgrade the database.
Note Failing to shut down the Foglight Management Server correctly may result in errors.
2 Verify that the Foglight Management Server is stopped. Use the following syntax:
ps -u <userid>
If no fms process is listed, then the Foglight Management Server is stopped.
162 Foglight
Administration and Configuration Guide
3 Back up the entire Foglight installation directory. For instructions, see “To back
up the Foglight installation directory on a Unix system:” on page 162.
4 Back up the entire database used by the Foglight Management Server:
• If your system contains an Oracle database, see “To back up an Oracle
database used by the Foglight Management Server:” on page 168 for
instructions.
• If your system contains a MySQL database, see “To back up a MySQL
database using MySQL commands:” on page 170 for instructions.
• If your system contains an MS SQL database, see “To back up an MS SQL
database used by the Foglight Management Server:” on page 163 for
instructions.
The Foglight backup on a Unix system is now complete.
To back up the Foglight installation directory on a Unix system:
1 cd to the directory one level above the Foglight installation directory.
2 Create an archive including all files in the Foglight installation directory. Use the
following syntax:
tar cvf <tarfile> <installation_dir>
A .tar file is created in the current directory.
Note The archive must include the ./config, ./cartridge, ./support, ./licence, and ./scripts
directories and all their content.
directory, and choose Send to > Compressed (zipped) Folder from the shortcut
menu that appears.
A Foglight.zip file appears in the current directory.
The backup of the Foglight installation directory on a Windows system is now
complete.
To back up an MS SQL database used by the Foglight Management Server:
1 Log in to the MS SQL Server machine.
2 Start the Microsoft SQL Server Management Studio.
You can do that by choosing Start > All Programs > Microsoft SQL Server
2005 > SQL Server Management Studio.
The Microsoft SQL Server Management Studio window appears, with the
Connect to Server dialog box open.
Server name: Ensure that this option is set to the name of the computer on
which the MS SQL server is installed.
Authentication: Select the authentication method that you want to use for
connecting to the database server. You can use your Windows user account
(Windows Authentication) or a SQL server account obtained from your
database administrator (SQL Server Authentication), as required. The
available authentication modes are set at installation time. For more
information, see your database administrator, or refer to the MS SQL Server
documentation.
SQL Server Authentication only. User name: Type your SQL Server user
name.
SQL Server Authentication only. Password: Type your SQL Server user
password.
Tip To ensure that the SQL Server remembers your password the next time you
attempt to log in, select the Remember password check box.
Tip For additional information about these settings, see your MS SQL documentation.
Tip The Foglight database, represented by the foglight node in the Object Explorer tree,
is installed on the MS SQL Server during the Foglight Management Server installation.
For additional information, see the Installation and Setup Guide.
For complete information about the settings in this dialog box, see your MS
SQL Server documentation.
c Record the name and location of the backup file, appearing in the General
page, under Destination.
Tip You will need this information when restoring the database from the backup file.
For information on how to restore an MS SQL database, see “Restoring Foglight”
on page 178.
d Visually inspect the values associated with the PATH and LD_LIBRARY_PATH
& ORACLE_HOME variables.
On Unix systems, use the echo command to print out each environment variable
(for example: echo $PATH).
3 Export the Oracle database. Use the following syntax in the Oracle command
shell:
cd $ORACLE_HOME/bin
exp <db_usr>/<db_pwd>@<ORACLE_SID>
file=<export_filename>.dbdump
A .dbdump file is created.
The backup of the Oracle database is now complete.
To back up a MySQL database using MySQL commands:
1 Log in to the MySQL server machine.
2 Export the MySQL database. Use the following syntax in the MySQL command
shell:
mysqldump -u [database_user] –p -P[database_port_number]
–h [database_hostname_or_ip] [database_name] >
[backupfile_name].sql
Setting Up Foglight 171
Backing Up, Upgrading, and Restoring Foglight
Where:
• database_user is the name of the database user, as configured by the
foglight.database.user parameter in <foglight_home>/config/
foglight.config.
• database_port_number is the database port number, as configured by the
foglight.database.port parameter in <foglight_home>/config/
foglight.config.
• database_hostname_or_ip is the name of the computer on which the
database is installed, or its IP address, as configured by the
foglight.database.host parameter in <foglight_home>/config/
foglight.config.
• database_name is the database name, as configured by the
foglight.database.name parameter in <foglight_home>/config/
foglight.config.
• backupfile_name is the name of the backup SQL file.
3 After the backup SQL file is created, stop the MySQL database by issuing the
shutdownDb.bat command from the <foglight_home>/bin directory.
4 Verify that the database is down by verifying that the database process,
mysqld.exe, is no longer running using the Task Manager.
The backup of the MySQL database is now complete.
Note Foglight Management Server ships with the InnoDB Hot Backup® tool. You can use
this tool to back up an embedded MySQL database as an alternative to the above
procedure. For information on how to use this tool, see “To back up an embedded
MySQL database using the InnoDB Hot Backup tool:” on page 171.
To back up an embedded MySQL database using the InnoDB Hot Backup tool:
1 Create a directory structure that will contain the backup files.
You can create a master directory with two subdirectories: one that stores
configuration files that will be used by the InnoDB Hot Backup tool, and another
one, that stores the backup files. For example:
• <foglight_home>/backup/config
• <foglight_home>/backup/data
Where foglight_home contains the path to the Foglight installation directory. For
example, its default location on Windows is C:\Quest_Software\Foglight.
2 Create two configuration files for the InnoDB Hot Backup tool, each containing
the information about
172 Foglight
Administration and Configuration Guide
When you are done, save the files in the config directory that you have created in
step 1.
3 Open a Command Prompt window (Windows) or a terminal window (Unix or
Linux), and navigate to the directory in which Foglight stores the MySQL
executable files, <foglight_home>/Foglight/mysql/bin.
4 Complete one of the following steps, depending on the type of backup you want
to create.
• To create an uncompressed backup, issue the following command:
C:\Quest_Software\Foglight\mysql\bin>ibbackup
..\..\backup\config\my.cnf
..\..\backup\config\backup.cnf
Setting Up Foglight 173
Backing Up, Upgrading, and Restoring Foglight
Contents of ..\..\backup\config\my.cnf:
innodb_data_home_dir got value
...
Contents of ..\..\backup\config\backup.cnf:
innodb_data_home_dir got value
...
ibbackup: Found checkpoint at lsn 0 282033535
ibbackup: Starting log scan from lsn 0 282033152
...
ibbackup: Progress in MB: 100 200
080922 15:29:54 ibbackup: Full backup completed!
Note The above example illustrates the process of backing up a MySQL database on
Windows, which uses the back slash character as a directory separator. On Unix
platforms, use the forward slash to separate directories.
or
• To create a compressed backup, issue the following command:
C:\Quest_Software\Foglight\mysql\bin>ibbackup
--compress ..\..\backup\config\my.cnf
..\..\backup\config\backup.cnf
InnoDB Hot Backup version 3.0.0; Copyright 2002-2005
Innobase Oy
License A11983 is granted to Quest Software, Inc.
Contents of ..\..\backup\config\my.cnf:
innodb_data_home_dir got value
174 Foglight
Administration and Configuration Guide
...
Contents of ..\..\backup\config\backup.cnf:
innodb_data_home_dir got value
...
ibbackup: Found checkpoint at lsn 0 282084809
ibbackup: Starting log scan from lsn 0 282084352
...
ibbackup: Progress in MB: 100 200
ibbackup: A copied database page was modified at
0282085337
ibbackup: Scanned log up to lsn 0 282085565
ibbackup: Was able to parse the log up to lsn 0
282085565
ibbackup: Maximum page number for a log record 11925
Directory of C:\Quest_Software\Foglight\backup\data
The backup directory contains one data file, ibdata1, and a log file,
ibbackup_logfile. The backup process copies different database pages at different
times. The log file, ibbackup_logfile, specifies the order in which the pages are
backed up. Applying the log file to the backup data associates each database page
with a sequence in the log file, and creates one or more log files for each data file,
Setting Up Foglight 175
Backing Up, Upgrading, and Restoring Foglight
allowing you to successfully restore the database from the backup data when
required.
6 Apply the log file to the backup data by issuing the following command:
Note The example below illustrates the process of backing up a MySQL database on
Windows, which uses the back slash character as a directory separator. On Unix
platforms, use the forward slash to separate directories.
C:\Quest_Software\Foglight\mysql\bin>ibbackup --apply-log
C:\Quest_Software\Foglight\backup\config\backup.cnf.txt
Note The code line above illustrates the process of applying logs to an uncompressed
backup. If you are applying logs to a compressed backup, use the --uncompress
option. For example:
C:\Quest_Software\Foglight\mysql\bin>ibbackup
--apply-log --uncompress
C:\Quest_Software\Foglight\backup
\config\backup.cnf
For more information about the command-line options for creating compressed and
uncompressed backups, see step 4 on page 172.
InnoDB Hot Backup version 3.0.0; Copyright 2002-2005
Innobase Oy
License A11983 is granted to Quest Software, Inc.
Contents of C:\Quest_Software\Foglight\backup\config\
backup.cnf:
innodb_data_home_dir got value
C:\Quest_Software\Foglight\backup\data
innodb_data_file_path got value ibdata1:10M:autoextend
datadir got value C:\Quest_Software\Foglight\backup\data
innodb_log_group_home_dir got value
C:\Quest_Software\Foglight\backup\data
innodb_log_files_in_group got value 2
innodb_log_file_size got value 134217728
Directory of C:\Quest_Software\Foglight\backup\data
Upgrading Foglight
The Foglight Management Server installer checks for an existing version 5.x installation
of the Management Server in the target directory. If an existing 5.x installation is found
in the directory, you are prompted to choose whether you want to install a new version
of the Foglight Management Server, or to upgrade that instance of the Management
Server.
If you would like to install a new instance of the same version, you must select the New
Install option in the installer and choose a different (and empty) installation folder. You
cannot re-install the Management Server into the same directory as an existing
installation of the same version.
When running in the upgrade mode, the installer upgrades all files in the target directory
and upgrades the database. All product files in the target directory are overwritten;
however, any customizations already made are retained.
Caution Before upgrading Foglight to a newer version, it is necessary to back up the previous
Foglight installation directory and the database used by the existing Foglight
Management Server (for instructions, see “Backing Up Foglight” on page 157).
If you are using an external database and intend to upgrade Foglight after backing it up,
you should shut down the Foglight Management Server, but leave the database running.
Doing so allows the installer to successfully upgrade the database.
178 Foglight
Administration and Configuration Guide
For complete instructions on how to upgrade the Foglight Management Server refer to
the Foglight Upgrade Field Guide and Cartridge Upgrade Field Guide.
Note If you encounter any errors during the upgrade process, you can stop the procedure and
restore the previous Foglight installation (see “Restoring Foglight” on page 178), provided
that it has been correctly backed up.
Restoring Foglight
“Restoring” a physical backup means reconstructing it and making it available to users.
This section outlines how to restore an old Foglight installation. The process is similar
for Windows and Unix systems.
Note In order to restore a previous Foglight installation, you must have a backed up copy of that
version. For information about how to back up a Foglight system, see “Backing Up Foglight”
on page 157.
You can do that by choosing Start > All Programs > Microsoft SQL Server
2005 > SQL Server Management Studio.
The Microsoft SQL Server Management Studio window appears, with the
Connect to Server dialog box open.
SQL Server Authentication only. User name: Type your SQL Server user
name.
SQL Server Authentication only. Password: Type your SQL Server user
password.
Tip To ensure that the SQL Server remembers your password the next time you
attempt to log in, select the Remember password check box.
Tip For additional information about these settings, see your MS SQL documentation.
Tip The Foglight database, represented by the foglight node in the Object Explorer tree,
is installed on the MS SQL Server during the Foglight Management Server installation.
For additional information, see the Installation and Setup Guide.
b Review the backup settings in the Delete Object dialog box, and if required,
make additional modifications.
For complete information about the settings in this dialog box, see your MS
SQL Server documentation.
c In the Delete Object dialog box, click OK.
After a few moments, the Delete Object dialog box closes, indicating a
success. Additionally, in the Microsoft SQL Server Management Studio
window, in the Object Explorer pane, the Databases node refreshes, no
longer showing the foglight node.
Setting Up Foglight 183
Backing Up, Upgrading, and Restoring Foglight
The Restore Database dialog box includes two pages, each showing a
different collection of settings: General and Options. On its appearance, the
dialog box shows the General page. To switch between the General and
Options pages, select the appropriate page in the Select a page pane in the
upper-left.
Setting Up Foglight 185
Backing Up, Upgrading, and Restoring Foglight
b In the Restore Database dialog box, ensure that the General page is selected.
c Specify the database name.
In the Restore Database dialog box, in the General page, under Destination
for restore, in the To database box, type foglight.
d Specify the location of the database file, as recorded during the database
backup procedure.
For details, see To back up an MS SQL database used by the Foglight
Management Server:, step 5, sub-step c on page 168.
Tip The default location and name of this file is C:\Program Files\Microsoft SQL
Server\MSSQL.1\MSSQL\Backup\foglight.bak.
In the Restore Database dialog box, in the General page, under Source for
restore, select From device and click the browse button on the right .
The Specify Backup dialog box appears
In the Specify Backup dialog box, click Add. In the Locate Backup File
dialog box that appears, select the backup file, followed by clicking OK.
186 Foglight
Administration and Configuration Guide
The Locate Backup File dialog box closes and the Specify Backup dialog
box refreshes, showing the name and location of the selected backup file.
Setting Up Foglight 187
Backing Up, Upgrading, and Restoring Foglight
e Select the database backup sets from the selected backup file.
In the Restore Database dialog box, in the General page, under Source for
restore, in the Select the backup sets to restore table, in the row containing
the backup set, select the check box in the Restore column.
Setting Up Foglight 189
Backing Up, Upgrading, and Restoring Foglight
f Review the remaining settings in the Restore Database dialog box, and if
required, make additional modifications.
For complete information about the settings in this dialog box, see your MS
SQL Server documentation.
g In the Restore Database dialog box, click OK.
The MS SQL restore command restores the Foglight database from the
selected backup file. After a few moments, the Microsoft SQL Server
Management Studio message box appears, indicating that the restore of the
MS SQL database is complete.
190 Foglight
Administration and Configuration Guide
a Log into the MySQL database and execute the following command:
mysql -u root
b Execute the following SQL statement:
DROP DATABASE <database name>
3 After running mysql -u root, execute the following SQL statement:
CREATE DATABASE <database name>
4 After running mysql -u root, run the SQL script created by the backup. Use
the following syntax:
SOURCE <path to .sql file>
Note The .sql file is the backup file you must create in order to restore your MySQL
database (see “To back up a MySQL database using MySQL commands:” on
page 170).
or
• Execute the drop user command from the command line using the following
syntax:
drop USER <db_usr> cascade;
3 Create the new schema using the following syntax:
sqlplus <dbadmin_usr>/<dbadmin_pwd>@<ORACLE_SID>
SQL> @ <path_to_sql_script>/oracle_create_db.sql
192 Foglight
Administration and Configuration Guide
4 Import the database export file into the Oracle database using the following
syntax:
cd $ORACLE_HOME/bin
imp<db_usr>/<db_pwd>@<ORACLE_SID>
file=<export_filename>.dbdump full=yes
Note The “.dbdump” is the backup file you must create in order to restore your Oracle
database (see “To back up an Oracle database used by the Foglight Management
Server:” on page 168).
Your database files are now successfully restored to their original location.
Note Moving the embedded MySQL database outside of the Foglight directory structure is not
supported. If you need to move your embedded database, you have one of the following
two options:
• Move the entire Foglight Management Server directory structure to a new location
or
• Move from the embedded database to an external database.
purged after reaching a certain age. For more information about retention policies, see
“Managing Retention Policies” on page 666.
This chapter introduces you to the concepts and terms related to managing security in
Foglight and looks into security-related components that you can manage using the
Administration module. It also takes you through the process of creating and managing
users, groups, and roles in Foglight.
Note In order to complete each of the procedures in this chapter, your user account must belong
to a group with the Security role. For more information, see “Managing Groups” on
page 210.
Figure 1
Managing Users
There are three types of users in Foglight:
• Internal. Internal users include the users that are created after the installation.
When you create an internal user in Foglight, you assign a user name and
password to that user. There are restrictions surrounding password formatting.
See “Configuring Password Settings” on page 227 for details.
• Built In. Built-in users include the users that come with Foglight. There is
currently one default account that is included with Foglight. Unless you specify a
different user name at installation time, that user name is foglight. This account
has full access to all of Foglight features
Note Built-in groups cannot be deleted.
• External. After being validated by Foglight, external users are mapped from one
of the LDAP-compatible directory services supported by Foglight (Active
Directory, Sun Java Systems Directory Server, and OpenLDAP). For more
information about configuring Foglight to use an external directory service, see
“Configuring Directory Services” on page 231.
200 Foglight
Administration and Configuration Guide
Roles are assigned to a user through groups: when a user belongs to a group, the roles
that are assigned to that group are also assigned to the user. A user can belong to one or
more groups. For more information about groups, see “Managing Roles” on page 219.
If you belong to a group that includes the Security role, the Manage Users dashboard
allows you to manage user accounts, add users to groups, and manage user passwords.
For more information on how to use the Manage Users dashboard, see the following
sections:
• “Accessing the Manage Users Dashboard” on page 200
• “Creating Users” on page 203
• “Adding Users to Groups” on page 204
• “Changing Passwords” on page 206
• “Forcing Password Changes” on page 207
• “Unlocking Passwords” on page 207
• “Deleting Internal Users” on page 209
Note Roles are not assigned directly to users. Instead, they are made available to users through
the groups to which they belong. See “Managing Groups” on page 210 for complete
information assigning roles and adding users to groups.
2 On the navigation panel, under Dashboards, choose Administration > Users &
Security > Manage Users.
The Manage Users dashboard appears in the display area, showing a list of all
existing users:
3 To sort the list by name, group, role, or type, click the Name, Groups, Roles
(Read Only), or Type column headings as required.
4 To filter the list of users, use one or more of the following boxes at the top of the
Manage Users list:
• Name: Type the user name for which you want to filter.
• Groups: Type the group name for which you want to filter.
• Roles: Type the role name for which you want to filter.
For example, to list only the users whose name starts with “demo”, in the Name
box, type demo.
The Manage Users list refreshes, showing the list of those users whose name
matches the filter pattern.
202 Foglight
Administration and Configuration Guide
Creating Users
Use the Create User button on the Manage Users dashboard to add a user account to
Foglight, as outlined below.
Alternatively, use the security:createuser fglcmd command to create a user. For
more information, see the Command-Line Reference Guide.
To create a user:
Note This procedure continues from “Accessing the Manage Users Dashboard” on page 200.
1 In the Manage Users dashboard, click the Create User button in the lower-left
corner.
The Create User dialog box appears.
2 Specify the name and password of the user that you want to create.
a In the Create User dialog box, in the Name box, type the user name.
For example: test.
b In the Password and Confirm Password boxes, type the user password.
Note The Password box is encrypted.
As you type the password into the Password and Confirm Password boxes,
asterisk ‘*’ characters appear.
Note Passwords must meet certain criteria. For example, by default, each password
must be between seven (7) and sixteen (16) characters long. For more
information, see “Configuring Password Settings” on page 227. If you specify a
password that is longer than sixteen (16) characters for an end-user, that user
cannot log into Foglight.
c Click Create.
The Create User dialog box closes and the Manage Users dashboard refreshes
to show the newly-created user account.
When you create users, their type appears as Internal on the listing.
Once you create a new user, you should ensure that the user changes their password
from the one you set in the Create User dialog box.
• If the user belongs to group that has a Security role which allows them to access
to the Manage Users dashboard, you can instruct the user to change the password
using the Change Password button on the Manage Users dashboard. For
instructions, see “Changing Passwords” on page 206.
• If the user has no access to the Manage Users dashboard, you can force a
password change the first time the user attempts to log into Foglight. For
instructions on how to force a password change, see “Forcing Password Changes”
on page 207.
1 In the Manage Users dashboard, select the row containing the user account whose
groups you want to edit.
2 Click the Edit Groups button in the lower-right corner.
The Edit Groups dialog box appears.
Note The dialog box lists default Foglight groups. If you previously added any groups, they
also appear in the dialog. For information on how to add groups, see “Creating
Groups” on page 214.
3 In the Edit Groups dialog box, select the groups to which you want the user to
belong by clicking the appropriate symbol to the left of the group name.
• : The user account is added or already belongs to this group.
• : The user account has been removed from or does not have access to this
group.
• : There is no change in group assignment.
For example, to add a user to the Foglight Administrators and Foglight Security
Administrators groups, ensure that the green plus sign appears to the left of the
Foglight Administrators and Foglight Security Administrators entries, and
that the red minus sign appears to the left of the other groups in the Edit Groups
dialog box.
4 Click Save.
206 Foglight
Administration and Configuration Guide
The Edit Groups dialog box closes and the Manage Users dashboard refreshes to
show the groups that you added to the user account.
Changing Passwords
Use the Change Password button on the Manage Users dashboard to change a user’s
password, as outlined below.
To change a user’s password:
1 In the Manage Users dashboard, select the row containing the user account whose
password you want to change.
2 Click the Change Password button at the bottom of the Manage Users
dashboard.
The Change Password dialog box appears.
b Click OK.
4 The Change Password dialog box closes and Foglight updates the user password
in the database.
1 Select the row containing the user whose password change you want to initiate
the next time they attempt to log in.
2 Click the Force Password-Change button at the bottom of the Manage Users
dashboard.
The Confirm Force Password-Change dialog box appears.
Unlocking Passwords
If a user attempts to log in with an incorrect password several times in a row, Foglight
locks the user’s account. You can configure the number of unsuccessful login attempts
208 Foglight
Administration and Configuration Guide
using the Configure Password Settings dashboard. For more information, see “Editing
Password Settings” on page 229.
By default any user passwords that become locked stay in that state for 15 minutes after
which Foglight unlocks them. To unlock a user account, use the Unlock button on the
Manage Users dashboard.
To unlock a user’s password:
Note This procedure continues from “Accessing the Manage Users Dashboard” on page 200.
• If possible, advise the user whose password has been locked to wait 15 minutes
from the moment the password was locked for Foglight to unlock the password
automatically.
or
Complete the following steps:
a Open the Manage Users dashboard
For instructions, see “Accessing the Manage Users Dashboard” on page 200.
b In the Manage Users dashboard, select the row containing the user account
whose password you want to change.
The Name column shows the following message for each user whose account
is locked: This user is locked!
c Click the Unlock button at the bottom of the Manage Users dashboard.
The Confirm Unlock dialog box appears, asking you to confirm the unlock
operation.
For more information about the types of groups that exist in Foglight, see “Managing
Groups” on page 210.
Alternatively, you can delete internal users using the security:deleteuser
command that comes with the fglcmd interface. For more information, see the
Command-Line Reference Guide.
To delete an internal user:
Note This procedure continues from “Accessing the Manage Users Dashboard” on page 200.
1 In the Manage Users dashboard, select the row containing the user account that
you want to delete.
2 Click the Delete button at the bottom of the Manage Users dashboard.
The Confirm Delete dialog box appears, asking you to confirm the delete
operation.
210 Foglight
Administration and Configuration Guide
Managing Groups
A group can contain users. Roles are assigned to groups. In turn, a role that is assigned
to a group is also assigned to each member of that group.
There are three types of roles in Foglight:
• Internal. Include the groups that are created using the Manage Groups dashboard
after the installation.
• Built In. Include the groups that come with Foglight. They are as follows:
• Cartridge Developers. Allows the users to modify core dashboards and system
modules.
• Foglight Administrators. Enables the users to access all of the dashboards that
come with the Administration module, with the exception of the Users &
Security dashboards. Additionally, it enables the users to use build-oriented
dashboards or build their own dashboards.
• Foglight Operators. Allows the users to have access to core and cartridge
dashboards, and to create new dashboards.
• Foglight Security Administrators. Provides access to all dashboards under the
Users & Security node in the Administration module.
Note Built-in groups cannot be deleted.
3 To sort the list by name, users, role, or type, click the Name, Users, Roles, or
Type column headings as required.
4 To filter the list of groups, use one or more of the following boxes at the top of the
Manage Users list:
• Name: Enter the group name for which you want to filter.
• Users: Enter the user name for which you want to filter.
• Roles: Enter the role name for which you want to filter.
• Type: Enter the type name for which you want to filter.
For example, to list only the groups whose name starts with “Foglight”, in the
Name box, type Foglight.
The Manage Groups list refreshes, showing the list of groups whose name
matches the filter pattern.
Managing Users and Security 213
Managing Groups
Creating Groups
Use the Create Group button on the Manage Groups dashboard to add a group to
Foglight, as outlined below.
Alternatively, you can create groups using the security:createuser command that
comes with the fglcmd interface. For more information, see the Command-Line
Reference Guide.
To create a group:
Note This procedure continues from “Accessing the Manage Groups Dashboard” on page 211.
1 In the Manage Groups dashboard, click the Create Group button in the lower-
left corner.
The Create Group dialog box appears.
When you create groups, their type appears as Internal on the listing.
Managing Users and Security 215
Managing Groups
1 In the Manage Groups dashboard, select the row containing the group to which
you want to add users.
2 Click the Edit Users button in the lower-right corner on the left of the Edit Roles
button.
The Edit Users dialog box appears.
Note The dialog box lists existing Foglight users. If you added any users, they also appear
in the dialog. For information on how to add users, see “Creating Users” on
page 203.
3 In the Edit Users dialog box, select the users that you want to add to the group by
clicking the appropriate symbol to the left of the group name.
• : The user account is added or already belongs to this group.
216 Foglight
Administration and Configuration Guide
• : The user account has been removed from or does not have access to this
group.
• : There is no change in user assignment.
For example, to add the default foglight user account to the group, ensure that the
green plus sign appears to the left of the foglight entry, and that the red minus
sign appears to the left of the other groups in the Edit Users dialog box.
4 Click Save.
The Edit Users dialog box closes and the Manage Groups dashboard refreshes to
show the users that you added to the group.
1 In the Manage Groups dashboard, select the row containing the group to which
you want to assign one or more roles.
2 Click the Edit Roles button in the lower-right corner.
The Edit Roles dialog box appears.
Managing Users and Security 217
Managing Groups
Note The dialog box lists existing Foglight roles. If you previously added any roles, they
also appear in the dialog. For information on how to add roles, see “Creating Roles”
on page 223.
3 In the Edit Roles dialog box, select the roles that you want to assign to the group
by clicking the appropriate symbol to the left of the group name.
• : The role is added or already belongs to this group.
• : The role has been removed from or does not have access to this group.
• : There is no change in role assignment.
For example, to add default Administrator and Security roles to the group, ensure
that the green plus sign appears to the left of Administrator and Security entries
and that the red minus sign appears to the left of the other entries in the Edit
Roles dialog box.
4 Click Save.
The Edit Roles dialog box closes and the Manage Groups dashboard refreshes to
show the users that you added to the group.
218 Foglight
Administration and Configuration Guide
For more information about the types of groups that exist in Foglight, see “Managing
Groups” on page 210.
Alternatively, you can delete groups using the security:deletegroup command that
comes with the fglcmd interface. For more information, see the Command-Line
Reference Guide.
To delete an internal group:
Note This procedure continues from “Accessing the Manage Groups Dashboard” on page 211.
1 In the Manage Groups dashboard, select the row containing the group that you
want to delete.
2 Click the Delete button at the bottom of the Manage Groups dashboard.
A message box appears, asking you to confirm the delete operation.
The message box closes and Foglight deletes the user account.
4 Observe the Manage Groups dashboard.
The user account that you deleted no longer appears in the list.
Managing Roles
Roles are assigned to groups. A role that is assigned to a group is also assigned to each
member of that group.
There are two types of roles in Foglight:
• Built-In. They dictate what actions users can perform. That is, when a role is
assigned to a group, it enables the members of that group to use specific features
or components for which access is controlled.
Built-In roles are also used in Foglight to determine which dashboards appear and
are accessible to each user. See the Foglight User Guide for information about the
relationship between roles and dashboards.
Note The Built-In roles cannot be deleted.
the Schema Browser. This role is for users who design dashboards using these
advanced dashboard tools.
• Dashboard User. This role is similar to the Console User role, but with
additional access to any additional dashboards associated with the user. This
role also includes permission to create new dashboards, new reports, and to
edit the dashboard environment.
• General Access. This role is for pre-5.2 cartridges installed on a version 5.2 or
later Foglight Management Server. The role will be added to the appropriate
views so that dashboards from the cartridge will appear in the Foglight
interface.
Note The General Access role is not assigned to users, and cannot be used to log in.
• Operator. This is the base level role for monitoring in Foglight. Users assigned
this role have access to the core dashboard set such as Hosts, Alarms, Services,
and Report Manager, with the ability to create new dashboards. This role also
has access to any non-core cartridge dashboard, such as the OS Cartridge. This
is the recommended default for new users.
• Security. This role provides access to all dashboards under Users and Security
in the Administration Module.
• Internal. Users with the Security role can create Internal roles.
New roles do not have any permission. They depend on how they are grouped
with built-in roles to determine their behavior. For example, a new role can be
created and applied to a group along with the Console User role to create a
locked-down user group. This means users in this group would only have access
to the dashboards specifically made available to the new role, and are able to log
in to the web console.
Roles are assigned to a user through groups: when a user belongs to a group, the roles
that are assigned to that group are also assigned to the user. A user can belong to one or
more groups.
If you belong to a group that includes the Security role, the Manage Roles dashboard
allows you to create and manage roles, and assign roles to groups. For more information
on how to use the Manage Groups dashboard, see the following sections:
• “Accessing the Manage Roles Dashboard” on page 221
• “Creating Roles” on page 223
• “Editing Groups for a Role” on page 224
• “Deleting Internal Roles” on page 225
Managing Users and Security 221
Managing Roles
3 To sort the list by name, groups, or type, click the Name, Groups, or Type
column headings as required.
4 To filter the list of roles, use one or more of the following boxes at the top of the
Manage Roles list:
• Name: Type the role name for which you want to filter.
• Groups: Type the group name for which you want to filter.
222 Foglight
Administration and Configuration Guide
• Type: Type the type name for which you want to filter.
For example, to list only the roles whose name starts with “Dashboard”, in the
Name box, type Dashboard.
The Manage Roles list refreshes, showing the list of roles whose name matches
the filter pattern.
Creating Roles
Use the Create Role button on the Manage Roles dashboard to add a role to Foglight, as
outlined below.
To create a role:
Note This procedure continues from “Accessing the Manage Roles Dashboard” on page 221.
1 In the Manage Roles dashboard, click the Create Role button in the lower-left
corner.
The Create Role dialog box appears.
224 Foglight
Administration and Configuration Guide
When you create roles, their type appears as Internal on the listing.
1 In the Manage Roles dashboard, select the row containing the role whose groups
you want to edit.
2 Click the Edit Groups button in the bottom of the Manage Roles dashboard.
The Edit Groups dialog box appears.
Managing Users and Security 225
Managing Roles
Note The dialog box lists existing Foglight groups. If you previously added any groups,
they also appear in the dialog. For information on how to add groups, see “Creating
Groups” on page 214.
3 In the Edit Groups dialog box, select the users to which you want to assign the
role by clicking the appropriate symbol to the left of the group name.
• : The group is added to this role.
• : The group has no access to the role.
• : There is no change in group assignment.
For example, to assign the role to the Foglight Administrators and Foglight
Security Administrators groups, ensure that the green plus sign appears to the left
of the Foglight Administrators and Foglight Security Administrators entries,
and that the red minus sign appears to the left of the other groups in the Edit
Groups dialog box.
4 Click Save.
The Edit Groups dialog box closes and the Manage Roles dashboard refreshes to
show the groups to which you assigned the role.
You can only delete those roles that you add to Foglight after the installation. Their type
appears as Internal on the Manage Users dashboard. You cannot delete any of the
groups accounts that are included with Foglight. Their type appears as Built In.
Figure 4
For more information about the types of roles that exist in Foglight, see “Managing
Roles” on page 219.
To delete an internal role:
Note This procedure continues from “Accessing the Manage Roles Dashboard” on page 221.
1 In the Manage Roles dashboard, select the row containing the role that you want
to delete.
2 Click the Delete button at the bottom of the Manage Roles dashboard.
A message box appears, asking you to confirm the delete operation.
Note This procedure continues from “Accessing the Configure Password Settings Dashboard” on
page 228.
1 In the Configure Password Settings dashboard, click the Edit button in the lower-
left corner.
The Configure Password Settings dashboard refreshes, showing a box to the right
of each setting.
At the same time, any internal Foglight users, such as the built-in foglight/foglight
user, or any accounts that you create manually using the Manage Users dashboard, are
unaffected during LDAP authentication interruptions.
You can track user login credentials using the Manage Users dashboard. This dashboard
lists the users who have logged in to Foglight using their external account credentials.
For more information, see “Managing Users” on page 199.
For details about configuring LDAP directory services with Foglight, refer to the
following sections:
• “Accessing the Configure Directory Services Dashboard” on page 232
• “Editing Directory Settings” on page 234
• “Example: Integrating Foglight LDAP Directory Services with Microsoft
Windows Active Directory” on page 238
From here, you can proceed to “Editing Directory Settings” on page 234.
234 Foglight
Administration and Configuration Guide
Examples
Secondary ldap://backupldapserver.example.com:389/
LDAP server
URL
Is Role false
attribute a DN
Match on true
User DN
JAAS com.quest.nitro.service.security.auth.spi.NitroExte
LoginModule ndedLdapLoginModule
Name
Caution Do not change this setting.
Name of fgl-web-console
JAAS
security Caution Do not change this setting.
domain
236 Foglight
Administration and Configuration Guide
Maximum 15
level of group
nesting
Account is false
anonymous
Note This procedure continues from “Accessing the Configure Directory Services Dashboard” on
page 232.
1 Obtain all of the service account information required to edit the settings on the
Configure Directory Services dashboard.
2 Obtain the correct configurations for each setting.
3 In the Configure Directory Services dashboard, click the Edit button in the lower-
left corner.
The Configure Directory Services dashboard refreshes, showing a box to the right
of each setting.
Managing Users and Security 237
Configuring Directory Services
Getting started
To get started with this example, you need to ensure that you have access to the
following components:
• Administrative access to the Active Directory domain.
Important If you are using Quest ActiveRoles Server, you can disregard this requirement.
• An LDAP browser. You can use any LDAP browser, such as:
• Softerra’s LDAP browser, used in this example. For more information about
this browser, visit, http://www.ldapbrowser.com.
• Active Directory Service Interfaces Editor (ADSI Edit).
• Native LDAP command-line.
• Any other LDAP browser.
Managing Users and Security 239
Configuring Directory Services
• A running Foglight Management Server, and a user account that includes the
Security role. For more information about roles in Foglight, see “Managing
Roles” on page 219.
Note If you already have access to the Domain Controller connect string, AD account, its
distinguished name, as well as the user and group containers to search against (or you
want to use the defaults that appear in the screen captures in “Gathering LDAP information
from the external directory” on page 239) you can skip to“Configuring Foglight LDAP
settings” on page 243.
Important The above settings are used for illustration purposes only. It is quite likely that your
environment uses different settings for the domain controller, active directory domain,
and the fully qualified domain name. If you are using this example to configure LDAP
directory services, substitute the above settings with the values that exist in your
environment.
Note The Softerra LDAP browser used in this example asks for the user’s distinguished name
(DN) instead of just a username.
The LDAP configuration strings include the CN (canonical name) and DN (distinguished
name) designators. These designators are very important when it comes to entering
information into the Configure Directory Services dashboard in the Foglight browser
interface. Reading from the top of the domain tree, the administrator
(CN=administrator) appears in the users container (CN=Users), which is inside the
2k3.dom domain (DC=2k3, DC=dom). The distinguished name (DN) is telling the LDAP
search tool where to look for the account inside the LDAP data store, which the tool
uses to authenticate itself with the Active Directory server..
240 Foglight
Administration and Configuration Guide
Figure 5
3 Record the DN for the Administrator's account (or any account that you choose to
use in this example).
For example:
DN=administrator,CN=Users,DC=2k3,DC=dom
4 Obtain information about the containers against which the users and groups can
be searched. The goal here is to keep the searches against AD to a small subset of
the entire tree. This helps in two ways:
• It keeps searches fast by not asking the query to request every object from the
remote directory. That way, AD only looks for users and groups in one or two
organization units (OU).
• It allows an AD administrator to create an OU for Foglight security groups and
users for the purpose of delegating administration tasks, if needed.
The illustration below shows the properties of the Users OU. The highlighted text
string represents a setting that you will need when configuring the directory
settings in Foglight. In this example, we will also use the Builtin OU
(CN=Builtin) since by default this OU includes security groups we want to pull
into Foglight.
242 Foglight
Administration and Configuration Guide
Figure 6
For example:
• CN of the Builtin folder (containing default groups):
CN=Builtin,DC=2k3,DC=dom
• CN of the Users folder (containing other users and groups in AD):
CN=Users,DC=2k3,DC=dom (as shown in the above screen capture)
We now have the information needed for the configuration of directory services in
Foglight. Here is a list of the text strings that need to be used in the LDAP
configuration, retrieved from the LDAP browser.
• LDAP connection string to the Domain Controller, as recorded in step 2:
Ldap://dc1.2k3.dom:389/
• DN of the account for connecting to AD using Softerra’s LDAP browser, as
recorded in step 3:
DN=administrator,CN=Users,DC=2k3,DC=dom
Managing Users and Security 243
Configuring Directory Services
Important The above settings are used for illustration purposes only. It is quite likely that your
environment uses a different settings for the domain controller, active directory domain,
and the fully qualified domain name. If you are using this example to configure LDAP
directory services, substitute the above settings with the values that exist in your
environment.
3 In the Configure Directory Services dashboard, click the Edit button in the lower-
left corner.
The Configure Directory Services dashboard refreshes, showing a box to the right
of each setting.
Managing Users and Security 245
Configuring Directory Services
4 Edit the settings in the Configure Directory Services dashboard using the values
listed in the table below.
246 Foglight
Administration and Configuration Guide
The third group namespace Leave blank unless you need Yes
want to specify another OU
Important The above settings illustrate a working virtual machine setup with Active
Directory and Foglight 5 installed. It is very important to note that the LDAP query
suffix reads “,CN=Users,DC=2k3,DC=dom”. The first comma ',' in that text string is
very important and must be present in the configuration string.
Additionally, the following parameter values reflect the settings that are used for
illustration purposes only: Nearest LDAP server, Distinguished name of the service
account, LDAP query suffix, the scope(s) to search for groups, the second
group namespace, and the LDAP context for user searching. It is quite likely that
your environment uses a different settings for the domain controller, active directory
domain, and the fully qualified domain name. If you are using this example to configure
LDAP directory services, substitute the above settings with the values that are
applicable to your environment.
Figure 7
Logging back as Foglight (or a user with the Security role) allows you to associate
Active Directory users with applicable Foglight groups and roles. The easiest thing to
do is to associate a user or group from Active Directory with a given Foglight role or
group and then attempt to login as that user. There are many ways to manage groups,
roles and users in Active Directory. Consult your Windows Security Administrator
should ensure your company policies are followed. For information on managing
groups and roles in Foglight, see “Managing Groups” on page 210 and “Managing
Roles” on page 219.
5
Managing Cartridges
This chapter introduces you to Foglight cartridges and provides information on how to
install and manage cartridges. It contains the following sections:
Note In order to complete each of the procedures in this chapter, your user account must belong
to a group with the Administration role. For more information about users, groups, and roles,
see “Managing Users and Security” on page 197.
See “Managing Agents” on page 277 for more information about agents.
• Agent adapters. Agent adapters are components that allow agents to
communicate with the Foglight Management Server.
• Monitoring policy. A monitoring policy contains information and settings that
help Foglight analyze the data that the agents collect, such as rules, registry
variables, schedules, and derived metrics. The items included in the monitoring
policy are specific to each type of cartridge.
• Dashboards. Dashboards display information collected from your monitored
environment, such as metrics. Each dashboard is a top-level view from which you
can drill down to more detailed views.
The dashboards included with a cartridge allow the information collected by the
agents to be displayed in a unified view.
Each cartridge may include one or more dashboards.
Tip The Cartridges dashboards can be used to manage cartridges on the Foglight Management
Server. Unlike the Cartridge Inventory dashboard, that you can use to install, enable, or
remove individual cartridge components; the Extend Your Monitoring Reach dashboard,
accessible from the Welcome page, includes additional functionality that allows you to
complete configuration interviews and create interactive configuration plans that identify the
required cartridges, and to install them. Extend Your Monitoring Reach can be used as an
alternative when installing cartridges for host, database or JavaEE monitoring in small- and
mid-size organizations. If your business requirements change over time, the collection of
active cartridges can be modified using the Cartridges dashboards, or by returning to the
Extend Your Monitoring Reach dashboard. This chapter describes the Cartridges
dashboards; for information about the Extend Your Monitoring Reach dashboard, see
Chapter 2, “Extending Your Monitoring Reach” on page 67.
252 Foglight
Administration and Configuration Guide
Tip Use the Cartridge Inventory dashboard to install and enable Foglight cartridges. Unlike the
Cartridge Inventory dashboard, that you can use to install, enable, or remove individual
cartridge components; the Extend Your Monitoring Reach dashboard, accessible from the
Welcome page, includes additional functionality that allows you to complete configuration
interviews and create interactive configuration plans that identify the required cartridges, and
to install them. Extend Your Monitoring Reach can be used as an alternative when installing
cartridges for host, database or JavaEE monitoring in small- and mid-size organizations. If
your business requirements change over time, the collection of active cartridges can be
modified using the Cartridge Inventory dashboard, or by returning to Extend Your Monitoring
Managing Cartridges 253
Installing and Managing Cartridges
Reach. For information about the Extend Your Monitoring Reach dashboard, see Chapter 2,
“Extending Your Monitoring Reach” on page 67.
Note This procedure continues from “Logging in to Foglight” on page 22 or “Accessing the
Administration Dashboard” on page 57.
or
• To view cartridge information and any dependencies with other cartridges,
click the Cartridge Name column in the row containing the cartridge about
which you want to view information.
The View Cartridge Details view appears in your Web browser.
256 Foglight
Administration and Configuration Guide
Installing Cartridges
Installation is the first step in adding a cartridge to the Foglight Management Server. A
cartridge file has the extension .car. Installing the CAR file causes the Management
Server to be aware of all cartridges in the CAR file.
Managing Cartridges 259
Installing and Managing Cartridges
Use the Cartridge Inventory dashboard to install a single cartridge at a time. To install
multiple cartridges at the same time, use the cartridge:install command. For
complete information about this command, see the Command-Line Reference Guide.
You can only install those cartridges that are listed in your Foglight license. Trying to
install a non-licensed cartridge results in error. For information on how to find out
whether your license includes a particular cartridge, see Chapter 3, “Viewing License
Capabilities” on page 136.
A cartridge must also be enabled before it is added to the Management Server. You can
enable a cartridge upon or after installation. See “Enabling Cartridges” on page 261 for
instructions on enabling cartridges after installation.
To install a cartridge:
Note This procedure continues from “Accessing the Cartridge Inventory Dashboard” on
page 252.
1 In the Cartridge Inventory dashboard, in the Install Cartridge area, complete one
of the following steps:
• If the CAR resides in a location that you can access from your local computer,
specify the path and name of the CAR file.
Ensure that the File on Local Computer option is selected. Click Browse and
navigate to the CAR file using the file browser that appears.
The File on Local Computer box refreshes, showing the full path to the CAR
file.
or
• If the CAR file resides on the computer hosting the Foglight Management
Server specify its path and name.
Select the File on Server option, and in the box to its right, type the path and
file name. The path should be relative to the Foglight Management Server
installation directory.
For example, if the name of the CAR file is OSCartridge-WindowsXP-
5.5.0.car, and it resides in the <foglight_home>/cartridge directory on the
Foglight Management Server computer, in the File on Server box, type the
following:
cartridge/OSCartridge-WindowsXP-5_2_3.car
Note Use the back slash character ‘\’ as a directory separator on Windows platforms;
on Unix platforms, use the forward slash ‘/’.
260 Foglight
Administration and Configuration Guide
2 Optional. To enable the cartridge immediately after its installation, select the
Enable on install check box.
Alternatively, you can enable the cartridge at a later time. To do that, ensure that
the Enable on install check box is cleared, and follow the instructions in
“Enabling Cartridges” on page 261 after the cartridge installation.
3 Click Install Cartridge.
A status bar appears in the Cartridge Inventory dashboard, indicating the
installation progress.
Enabling Cartridges
Enabling a cartridge completes the process of adding it to the Foglight Management
Server by making the cartridge’s components available for use by the Management
Server.
A cartridge can be in one of the following states:
• Enabled
• Enabled, pending dependency
• Disabled
• Partially enabled
Use the Enable Selected button on the Cartridge Inventory dashboard to enable one or
more cartridges, as outlined below.
To enable a cartridge:
2 Click the Enable Selected button at the bottom of the Cartridge Inventory
dashboard.
If the operation succeeds, the Cartridge Operation Result message box appears.
3 In the Cartridge Inventory dashboard, observe the Status column of the cartridges
that you enabled.
The Status column of each newly-enabled cartridge contains an icon ( )
indicating that the operation was successful.
Disabling Cartridges
A cartridge can be in one of the following states:
• Enabled
• Enabled, pending dependency
• Disabled
• Partially enabled
Disabling a cartridge causes its components to no longer be available for use by the
Foglight Management Server. A disabled cartridge remains installed on the
Management Server.
For example, you could disable a cartridge to temporarily disable its functionality but
keep the .car file installed on the Management Server.
Note If you are installing a new version of a cartridge, Foglight will detect and automatically
disable the older version.
Use the Disable Selected button on the Cartridge Inventory dashboard to disable one or
more cartridges, as outlined below.
To disable a cartridge:
Note This procedure continues from “Accessing the Cartridge Inventory Dashboard” on
page 252.
1 In the Cartridge Inventory dashboard, in the cartridge table, select one or more
enabled cartridges that you want to disable.
The Status column contain icons that indicate if a cartridge is enabled ,
enabled pending dependency , partially enabled , or disabled .
Tip To select multiple cartridges, press the CTRL or SHIFT key while selecting the rows
containing the cartridges that you want to disable.
Managing Cartridges 263
Installing and Managing Cartridges
2 Click the Disable Selected button at the bottom of the Cartridge Inventory
dashboard.
The Cartridge Confirmation dialog box appears.
The list of cartridges that appears in the Cartridge Confirmation dialog box
reflects your cartridge selection.
3 In the Cartridge Confirmation dialog box, click OK.
The Cartridge Confirmation dialog box closes. If the operation is successful, a
message appears above the cartridge list.
4 In the Cartridge Inventory dashboard, observe the Status column of the cartridges
that you disabled.
The Status column of each newly-disabled cartridge contains an icon ( )
indicating that the operation was successful.
Uninstalling Cartridges
Uninstalling a cartridge removes the files for that cartridge from the directory for the
Foglight Management Server.
264 Foglight
Administration and Configuration Guide
A CAR file can contain multiple cartridges. When you remove all of the cartridges that
come in a CAR file, the CAR file will be deleted.
Caution If you remove a cartridge while the agents that were included in that cartridge are
deployed and actively collecting data, it can cause communication problems between
the agents and the Foglight Management Server.
For example, the agents may not be able to connect to the Management Server. If they
are still able to connect, the Management Server will likely not be able to recognize the
data that they send.
To remove a cartridge:
1 In the Cartridge Inventory dashboard, select one or more cartridges that you want
to remove.
The Status column contain icons that indicate if a cartridge is enabled ,
enabled pending dependency , partially enabled , or disabled .
Tip To select multiple cartridges, press the CTRL or SHIFT key while selecting the rows
containing the cartridges that you want to remove.
2 Click the Uninstall Selected button in the lower-left corner of the Cartridge
Inventory dashboard.
The Cartridge Confirmation dialog box appears.
The list of cartridges that appears in the Cartridge Confirmation dialog box
reflects your cartridge selection.
Managing Cartridges 265
Downloading Agent Components
Note The list of agent components that are available for installation depends on the nature
of your monitoring environment and the type and range of installed cartridges, and
may not be identical to the one shown in the above screen capture.
If the row containing an agent installer shows the Manual Installer icon ( ) in
the Manual Installer column ( ), this indicates that you need to run the agent
installer manually on the monitored host after downloading it to the monitored
host. For complete information on how to manually install an agent component,
see your cartridge documentation.
3 Newly-installed cartridges. In the Components for Download list, in the upper-
right corner, click .
The list of components refreshes, showing any components that come with
newly-installed cartridges that are available for download.
4 View information about one or more agent components.
Move the mouse pointer over the Name column in the row containing the
component about which you want to view information.
A dwell appears, showing the component information.
268 Foglight
Administration and Configuration Guide
5 To sort the list of components, click any of the Name, Cartridge Name,
Component Name, OS, Architecture, or the Manual Installer icon ( ) column
headings as required.
6 To filter the list of cartridges, use one or more of the following boxes above the
component table:
• Name: Type the component name for which you want to filter.
• Cartridge Name: Type the cartridge name for which you want to filter.
• Component Name: Type the component name for which you want to filter.
• OS: Type the OS name for which you want to filter.
• Architecture: Type the architecture name for which you want to filter.
• Installer Type: Click and select All Installers or Manual Installers as
required.
For example, to list only the agent components that can be installed on monitored
hosts that are running AIX, in the OS box, type aix.
The Components for Download dashboard refreshes, showing the list of
components whose name matches the filter pattern.
To clear the filters, click Clear Filters.
The Components for Download dashboard list refreshes, showing the list of all
components.
From here, you can proceed to “Downloading agent components using the browser
interface” on page 268.
Note This procedure continues from “Accessing the Components for Download dashboard” on
page 266.
1 In the Components for Download dashboard, click the Name column of the row
containing the agent component that you want to download.
Your Web browser displays a dialog box that allows you to open or save the agent
component.
Note The appearance of the above dialog may be different, depending on the type and
version of your Web browser.
command-line utilities to retrieve files from URLs. For more information, see
“Using a URL to download agent components” on page 274.
The Components for Download view appears in the Web browser, showing a list
of agent components that are available for download.
Note The list of agent components that are available for installation depends on the nature
of your monitoring environment and the type and range of installed cartridges, and
may not be identical to the one shown in the above screen capture.
If the row containing an agent installer shows the Manual Installer icon in the
Manual Installer column , this indicates that you need to run the agent installer
manually on the monitored host after downloading it to the monitored host. For
complete information on how to manually install an agent component, see your
cartridge documentation.
2 View information about one or more agent components.
Move the mouse pointer over the Name column in the row containing the
component about which you want to view information.
A dwell appears, showing the component information.
272 Foglight
Administration and Configuration Guide
3 To sort the list of components, click any of the Name, Cartridge Name,
Component Name, OS, or Architecture column headings as required.
From here, you can proceed to “Downloading agent components remotely using the
Components for Download view” on page 272.
Downloading agent components remotely using the Components for Download view
Use the Name column on the Components for Download view to remotely download
agent components, as instructed below.
To download an agent component:
Note This procedure continues from “Accessing the Components form Download view” on
page 270.
1 In the Components for Download view, click the Name column of the row
containing the agent component that you want to download.
The Selected Installer Details view appears in the Web browser, showing the
details about the selected agent component.
Managing Cartridges 273
Downloading Agent Components
2 View the details about the selected agent component and proceed with the
download.
Click Download Installer.
Your Web browser displays a dialog box that allows you to open or save the agent
component.
274 Foglight
Administration and Configuration Guide
Note The appearance of the above dialog may be different, depending on the type and
version of your Web browser.
Where:
host is the name of the computer on which the Foglight Management Server is
running.
port is the HTTP port number used by the Foglight Management Server. The
default port number is 8080. For more information about port assignments, see
Chapter 3, “Ports”.
file_name is the name of the file that you want to download.
For example:
http://HostA:8080/console/installer/
listInstaller!downloadFile.action?downloadId=fglam-windows-ia32.exe
Your Web browser displays a dialog box that allows you to open or save the
agent component.
Note The appearance of the above dialog may be different, depending on the type and
version of your Web browser.
command http://host:port/console/installer/download-
installer.action?downloadId=file_name
Where:
command is the name of the command-line utility that you are using to
download the agent component.
host is the name of the computer on which the Foglight Management Server is
running.
port is the HTTP port number used by the Foglight Management Server. The
default port number is 8080. For more information about port assignments, see
Chapter 3, “Ports”.
file_name is the name of the file that you want to update.
For example, if you are using the wget utility to retrieve the Foglight Agent
Manager installer Windows XP-based HostA, use the following command:
wget http://HostA:8080/console/installer/download-
installer.action?downloadId=fglam-windows-ia32.exe
Important The wget utility illustrated above is a command-line tool that can be used to
retrieve a file from a URL using the standard Internet protocols. This
command does not come with Foglight. For more information about this
command, visit http://www.gnu.org/software/wget/.
The command shows the progress of the download operation, resulting in the
the desired file being copied to the current directory.
6
Managing Agents
This chapter introduces you to Foglight agents and provides information on how to
install and manage them. It contains the following sections:
Note In order to complete each of the procedures in this chapter, your user account must belong
to a group with the Administration role. For more information about users, groups, and roles,
see “Managing Users and Security” on page 197.
Tip The Agents dashboards can be used to manage agents on monitored hosts. Unlike the
Agents dashboards, that you can use to create and activate individual agent instances, the
Extend Your Monitoring Reach dashboard, accessible from the Welcome page, includes
additional functionality that allows you to complete configuration interviews and create
interactive configuration plans that identify the required agents, and to add them. Extend Your
Monitoring Reach can be used as an alternative when creating agents for host, database or
JavaEE monitoring in small- and mid-size organizations. If your business requirements
change over time, the collection of active agents can be modified using the Agents
dashboards, or by returning to the Extend Your Monitoring Reach dashboard. This chapter
describes the Agents dashboards. For information about the Extend Your Monitoring Reach
dashboard, see Chapter 2, “Extending Your Monitoring Reach” on page 67.
Each cartridge that you install on the Foglight Management Server includes one or more
agent types. When you install a cartridge and deploy its agent package that include those
types to one or more monitored hosts, you can create agent instances and initiate their
data collection.
Agents collect data from your monitored environment and send it to the Management
Server. Agents can monitor the availability and performance of network services,
operating systems, log files, file systems, disk space and utilization, top processes,
custom applications, application servers, and Web servers. Foglight also includes
internal agents that monitor Foglight components and services.
The Foglight Agent Manager component, installed on each monitored host, is used to
manage agent instances and their communication with the Foglight Management Server.
Foglight Management Server installs include an embedded Foglight Agent Manager.
The embedded Foglight Agent Manager on the Foglight Management Server starts up
and stops with the server. This agent manager instance can be used to deploy agents and
monitor the host on which the Foglight Management Server is installed, if required. To
monitor additional hosts in your environment, you must install an agent manager
Managing Agents 279
Managing Agent Properties by Type
component separately on each host computer. For more information about installing
agent managers on monitored hosts, see the Foglight Installation and Setup Guide.
Note Some monitoring environments use the Foglight Client, which is an older version of the
agent manager. While Foglight supports both types of agent managers, some commands
and dashboards may display slightly different type of information. This chapter contains
samples of command-line output and screen captures that illustrate a monitoring
environment that uses the Foglight Agent Manager. For information on those interfaces in
environments that use the Foglight Client, see “Appendix: Foglight Client Reference” on
page 807.
List property
Lists that come with an agent type are type-specific and as such global in nature,
which means that any changes to them affect all instances of that agent type. To
override this behavior, you can create an instance-specific list by cloning a global
list and assigning the cloned list to one or more agent instances. Any changes to
this list affect only those agent instances to which the list is assigned.
Examples of situations in which you may want to clone a list include the
following scenarios:
• You want a set of default agent properties to use different lists at different
times. For example, you may want to create a clone of a list and configure it to
have different settings during testing.
• You want to use lists with different settings in different agent instances.
You can view and edit type-specific agent properties using the Agent Properties
dashboard. For complete information, refer to the following sections:
• “Accessing the Agent Properties Dashboard” on page 280
• “Editing Type-Specific Agent Properties” on page 283
You can edit instance-specific agent properties using the Agent Status dashboard. For
more information, see “Editing Agent Properties by Agent Instance” on page 296.
Note If you remove an agent after deploying it, its properties will be unavailable in the Agent
Properties dashboard.
Note For a sample screen capture of this dashboard in a monitoring environment that
uses the Foglight Client, see “Agent Properties dashboard” on page 811.
Agent Manager and the SPI adapter. Other agents come with their own agent
adapter. For example, the Java EE cartridge has its own agent adapter.
• The Properties view lists the agent properties for the agent type selected in
the Namespace > Type view.
3 Select an agent type.
On the Agent Properties dashboard, in the Namespace > Type view, ensure the
Legacy Agents node is expanded, then select an agent type.
The Properties view refreshes, showing the agent properties for the selected
agent type.
List property
Primary
properties
For complete information about any agent properties that appear in the Agent
pane, refer to your cartridge documentation.
From here, you can proceed to any of the following sections:
• “Editing Type-Specific Agent Properties” on page 283.
• “Viewing the Properties of the FglAMAdaper Agent” on page 290
Figure 1
List property
Primary
properties
For more information on agent properties in Foglight, see “Managing Agent Properties
by Type” on page 279.
You can edit a primary property simply by specifying the desired value or option for the
selected agent type. Editing list-based properties is somewhat different in that it allows
you to either edit an existing list, or copy a list and make edits to it.
For instructions on how to edit agent properties, see the following sections:
• “Editing primary type-specific properties” on page 284
• “Cloning lists in secondary properties” on page 285
• “Editing lists in secondary properties” on page 287
• “Removing cloned lists from secondary properties” on page 289
Note This procedure continues from “Accessing the Agent Properties Dashboard” on page 280.
1 On the Agent Properties dashboard, in the Properties view, locate the primary
property that you want to edit.
Note Use caution when modifying type-specific agent properties, as these settings can
apply to multiple agents.
Primary
properties
The name and value of the edited property appears red on the Properties view to
indicate the change. Additionally, the Save and Cancel buttons appear enabled in
the lower-right corner of the Properties view.
When you clone a list, its selection of rows and fields remains unchanged. You can alter
it at a later time, if required. For more information, see “Editing lists in secondary
properties” on page 287.
Use the Clone button in the Properties view to clone the lists that are assigned to
secondary agent properties, as outlined below.
To clone a secondary property:
Note This procedure continues from “Accessing the Agent Properties Dashboard” on page 280.
1 On the Agent Properties dashboard, in the Properties view, locate the secondary
property that you want to clone.
2 Click the Clone button to the right of the box that contains the property value.
A dialog box appears.
Note This procedure continues from “Accessing the Agent Properties Dashboard” on page 280.
1 In the Agent Properties dashboard, in the Properties view, locate the secondary
property that you want to edit.
2 Click the Edit button to the right of the box that contains the property value.
Caution Secondary agent properties can apply to multiple agents. If you want to edit a
cloned list that is instance-specific, ensure that you select that list in the property
box before clicking the Edit button.
Note The appearance of the list depends on its complexity and contents.
• To add a row to the list, in the dialog box, click Add Row.
In the dialog box, a new editable row appears.
Managing Agents 289
Managing Agent Properties by Type
Note This procedure continues from “Accessing the Agent Properties Dashboard” on page 280.
1 On the Agent Properties dashboard, in the Properties view, locate the list that
you want to delete.
In the Agent pane, the Delete button appears enabled, indicating that the selected
list is cloned and can be removed.
290 Foglight
Administration and Configuration Guide
2 Click Delete.
Caution Secondary agent properties can apply to multiple agents. If you want to edit a
cloned list that is instance-specific, ensure that you select that list in the property
box before clicking the Edit button.
Note This procedure continues from “Accessing the Agent Properties Dashboard” on page 280.
1 On the Agent Properties dashboard, in the Namespace > Type view, expand the
FglAM node and click FglAMAdapter.
Managing Agents 291
Managing Agent Properties by Type
Note Some monitoring environments use the Foglight Client, which is an older version of the
agent manager. While Foglight supports both types of agent managers, some commands
and dashboards may display slightly different type of information. This chapter contains
samples of command-line output and screen captures that illustrate a monitoring
environment that uses the Foglight Agent Manager. For information on those interfaces in
environments that use the Foglight Client, see “Appendix: Foglight Client Reference” on
page 807.
For information about the types of adapters that your agents require in order to
communicate with the Foglight Management Server, see your cartridge documentation.
For information on how to install and configure the Foglight Agent Manager, see the
Foglight Installation and Setup Guide.
The Agent Status dashboard allows you to view information about agents as well as
perform agent-related operations, such as deploy agent packages, activate and
deactivate Foglight agents, start and stop data collection for an agent, on a single host.
Tip Some Agents dashboards can be used to manage individual agent instances. Unlike these
dashboards, that you can use to deploy agent packages and create new agent instances, the
Extend Your Monitoring Reach dashboard, accessible from the Welcome page, includes
Managing Agents 293
Installing and Managing Agent Instances on a Monitored Host
additional functionality that allows you to complete configuration interviews and create
interactive configuration plans that identify the required cartridges, and to install them. Extend
Your Monitoring Reach can be used as an alternative when adding agent instances for host,
database or JavaEE monitoring in small- and mid-size organizations. If your business
requirements change over time, the collection of active agent instances can be modified using
the Agents dashboards, or by returning to the Extend Your Monitoring Reach dashboard. This
section describes the Agents dashboards. For information about the Extend Your Monitoring
Reach dashboard, see Chapter 2, “Extending Your Monitoring Reach” on page 67.
Additionally, if you need to quickly deploy agent packages and create agent instances
on multiple hosts, you can use the Agent Hosts dashboard. For more information, see
“Deploying Agent Instances to Multiple Monitored Hosts” on page 342.
For information on how to use the Agent Status dashboard, see the following sections:
• “Accessing the Agent Status Dashboard” on page 293
• “Editing Agent Properties by Agent Instance” on page 296
• “Editing Agent Tags” on page 310
• “Deploying Agent Packages to a Monitored Host” on page 312
• “Creating Agent Instances on a Monitored Host” on page 320
• “Activating or Deactivating Agents” on page 327
• “Starting or Stopping Data Collection” on page 331
• “Deleting Agents” on page 337
• “Retrieving Agent Logs” on page 338
Tip Use the Agent Status dashboard to manage individual agent instances. Unlike the Agent
Status dashboard, that you can use to deploy agent packages and create new agent
instances, the Extend Your Monitoring Reach dashboard, accessible from the Welcome page,
includes additional functionality that allows you to complete configuration interviews and
create interactive configuration plans that identify the required agents, and to install them.
Extend Your Monitoring Reach can be used as an alternative when adding agent instances for
host, database or JavaEE monitoring in small- and mid-size organizations. If your business
requirements change over time, the collection of active agent instances can be modified using
the Agent Status dashboard, or by returning to Extend Your Monitoring Reach. For information
294 Foglight
Administration and Configuration Guide
about the Extend Your Monitoring Reach dashboard, see Chapter 2, “Extending Your
Monitoring Reach” on page 67.
Note This procedure continues from “Logging in to Foglight” on page 22 or “Accessing the
Administration Dashboard” on page 57.
Note For a sample screen capture of this dashboard in a monitoring environment that
uses the Foglight Client, see “Agent Status dashboard” on page 811.
3 To sort the list of agents by their active state, data collection state, agent
properties state, host name, agent name, name space, agent type, version number,
or agent tags, click the Active icon ( ), Collecting Data icon ( ), Property State
icon ( ), or Hostname, Agent Name, Namespace, Type, Version, or Tags
column headings, as required.
4 To filter the list of agents, use one or more of the following boxes at the top of the
Agent Status list: Hostname, Agent Name, Namespace, Type, Version, Build,
Tags, Status, and Properties.
Managing Agents 295
Installing and Managing Agent Instances on a Monitored Host
For example, to list only the agents whose name contains “Windows”, in the
Agent Name box, type Windows.
The Agent Status list refreshes, showing the agent instances whose name matches
the filter pattern.
There are two basic types of agent properties in Foglight: simple (primary) properties
and list-based (secondary) properties.
Figure 2
List property
Primary
properties
You can edit a primary property simply by specifying the desired value or option.
Editing list-based properties is somewhat different in that it allows you to either edit an
existing list, or copy a list and make edits to it.
For instructions on how to edit agent properties using the Agent Status dashboard, see
the following sections:
• “Deleting custom agent properties” on page 297
• “Choosing the edit scope” on page 300
• “Editing primary properties” on page 302
• “Cloning lists in secondary properties” on page 304
• “Editing lists in secondary properties” on page 305
• “Removing cloned lists from secondary properties” on page 309
Figure 3
Tip To select multiple agent instances, press the CTRL or SHIFT key while selecting the
rows containing the instances for which you want to choose the edit scope.
Note This procedure continues from “Accessing the Agent Status Dashboard” on page 293.
1 On the Agent Status dashboard, select the rows containing one or more agent
instances whose properties you want to edit.
Tip To select multiple agent instances, press the CTRL or SHIFT key while selecting the
rows containing the instances for which you want to choose the edit scope.
or
• Modify the properties for all Agent Type agents
Where Agent Type is the selected agent type.
The Property Scope area refreshes, showing the following message.
The Agent Properties area becomes enabled, allowing you to edit the agent
properties.
302 Foglight
Administration and Configuration Guide
Each agent type has a different collection of agent properties. The type and range
of agent properties that appear depend on the type of the selected agent instance.
For information on any agent-related properties, see your cartridge
documentation.
Note All text boxes in the Agent Properties area have a limit of 64 characters.
4 Multiple agent selections only. Select an agent instance or the default type
whose settings you want to use as the template, followed by editing the agent
properties in the Agent Properties area, as required.
From here, you can proceed to any of the following procedures:
• “Editing primary properties” on page 302
• “Cloning lists in secondary properties” on page 304
• “Editing lists in secondary properties” on page 305
• “Removing cloned lists from secondary properties” on page 309
Note This procedure continues from “Choosing the edit scope” on page 300.
Managing Agents 303
Installing and Managing Agent Instances on a Monitored Host
1 In the Agent Status dashboard, in the Agent Properties area, locate the primary
property that you want to edit.
Note Use caution when modifying type-specific agent properties, as these settings can
apply to multiple agents.
Primary
properties
The name and value of the edited property appear red in the display area,
indicating the change. Additionally, a Save button appears enabled at the bottom-
right corner.
3 Click Save, followed by clicking Back To Agent Status in the refreshed display
area.
304 Foglight
Administration and Configuration Guide
The Agent Status dashboard refreshes, showing the list of existing agent
instances. If you edited a primary property for a selected agent instance, assigning
it a custom value, the Property State column shows the Uses Custom Properties
icon in the agent’s row.
Note This procedure continues from “Choosing the edit scope” on page 300.
1 In the Agent Status dashboard, in the Agent Properties area, locate the secondary
property that you want to clone.
2 Click the Clone button to the right of the box that contains the property value.
A dialog box appears.
Managing Agents 305
Installing and Managing Agent Instances on a Monitored Host
3 In the dialog box, type the name of the cloned list and click OK.
The dialog box closes and the secondary property refreshes, with its value set to
the newly-cloned list. The property name and list name appear red in the Agent
Properties area to indicate the change.
4 Click Save, followed by clicking Back To Agent Status in the refreshed display
area.
The Agent Status dashboard refreshes, showing the list of existing agent
instances. If you edited a primary property for a selected agent instance, assigning
it a custom value, the Property State column shows the Uses Custom Properties
icon in the agent’s row.
Editing a list involves changing the value of its entries, adding new entries, or deleting
existing ones. This feature is useful in situations when you clone a list and need to use
its modified clones in certain agent configurations.
This is useful in situations when you want to use different lists at different times, or to
assign different versions of the same list to different agent instances of the same agent
type.
Use the Edit button in the Agent Properties area to edit lists that are assigned to
secondary agent properties, as outlined below.
Note This procedure continues from “Choosing the edit scope” on page 300.
1 In the Agent Status dashboard, in the Agent Properties area, locate the secondary
property that you want to edit.
2 Click the Edit button to the right of the box that contains the property value.
Caution Secondary agent properties can apply to multiple agents. If you want to edit a
cloned list that is instance-specific, ensure that you select that list in the property
box before clicking the Edit button.
Note The above dialog box shows a simple list entry consisting of two components,
one for each column in the list. The appearance of the dialog box depends on the
list complexity and its contents.
• To add a row to the list, in the dialog box, click Add Row.
In the dialog box, a new row appears, and a red marker indicates a change to
the table.
308 Foglight
Administration and Configuration Guide
Note This procedure continues from “Choosing the edit scope” on page 300.
1 In the Agent Status dashboard, in the Agent Properties area, locate the secondary
property that you want to edit.
In the Agent Properties area, the Remove button appears to the right of the Clone
button, indicating that the selected list is cloned and can be removed.
2 Click Delete.
Caution Secondary agent properties can apply to multiple agents. If you want to edit a
cloned list that is instance-specific, ensure that you select that list in the property
box before clicking the Edit button.
4 Click Save, followed by clicking Back To Agent Status in the refreshed display
area.
The Agent Status dashboard refreshes, showing the list of existing agent
instances. If you edited a primary property for a selected agent instance, assigning
it a custom value, the Property State column shows the Uses Custom Properties
icon in the agent’s row
Note This procedure continues from “Accessing the Agent Status Dashboard” on page 293.
1 In the Agent Status dashboard, select one or more rows containing the agent
instances that you want to tag.
Tip To select multiple agent instances, press the CTRL or SHIFT key while selecting the
rows containing the instances that you want to tag.
3 Edit agent tags and their association with the selected agent instances.
a To create a tag, in the Edit Tags dialog box, in the box to the left of the Add
Tag button, type a name for the tag, and click the Add Tag button.
In the Edit Tags dialog box, the Tags pane refreshes, showing the newly-
added tag.
b To associate the newly-created tag with the selected agent instance, in the Tags
pane, in the row containing the new tag, click the Apply To column and select
All.
Note You can associate multiple tags to an agent instance.
c To remove an existing tag association, in the row containing the selected tag,
click the Apply To column and select None.
4 Apply your changes by clicking the Apply button in the lower-right corner.
The Edit Tags dialog box closes and the Agent Status dashboard refreshes,
showing any tag-related changes in the Tags column.
312 Foglight
Administration and Configuration Guide
Note Any agents that you install must be compatible with the host’s OS and architecture.
Some agents (for example, the Java® EE Agent) are installed using an agent installer
that can be downloaded and run from the Components for Download dashboard. See
Chapter 5, “Downloading Agent Components” on page 265 for instructions.
There are two ways to deploy an agent package to the monitored host:
• Using the Agent Status dashboard. For instructions, see “Using the Agent Status
dashboard to deploy agent packages” on page 313.
• Agents that communicate with the Foglight Management Server through the
Foglight Agent Manager can be deployed using the command line. For
instructions, see “Using the command line to deploy agent packages” on
page 316.
The Agent Status dashboard allows you to deploy one agent package at a time. If you
need to perform a mass deployment of an agent package to multiple hosts, you can use
the Agent Hosts dashboard. For more information, see “Deploying Agent Packages to
Multiple Hosts” on page 345
Managing Agents 313
Installing and Managing Agent Instances on a Monitored Host
In some cases, agent deployment should be followed by editing the agent’s properties.
See “Editing Agent Properties by Agent Instance” on page 296. For information on
which properties to edit, refer to your cartridge documentation.
Note This procedure continues from “Accessing the Agent Status Dashboard” on page 293.
1 In the Agent Status dashboard, click the Deploy Agent Package button in the
lower-left corner.
The Deploy Agent Package dialog box appears.
Note In order to select the host, the Foglight Agent Manager must be up and running on
the monitored host.
Tip To deploy an agent package to multiple hosts, navigate to the Agent Hosts dashboard
by clicking Agent Hosts in the Deploy Agent Package dialog box. For more
information, see “Deploying Agent Instances to Multiple Monitored Hosts” on
page 342.
314 Foglight
Administration and Configuration Guide
2 Specify the monitored host to which you want to deploy the agent package.
In the Deploy Agent Package dialog box, click Host and select the monitored
host to which you want to deploy the agent package.
In the Deploy Agent Package dialog box, the list that appears in the Package
shows only those agent packages whose platform is compatible with the platform
of the host computer. For example, if the host runs a Windows OS, the Package
box contains only the agent packages that contain the agent processes that can run
under Windows.
4 Ensure that the agent package the you want to deploy is selected in the Package
box.
Note You can only deploy those agent packages whose cartridges have already been
installed on the Foglight Management Server.
5 Click Deploy.
The Deploy Agent Package dialog box refreshes, showing the status of the
deployment operation.
After a few moments, in the Deploy Agent Package dialog box, in the Status
column of the Progress table, a green check mark appears, indicating a success of
the deployment operation.
316 Foglight
Administration and Configuration Guide
possible to have several such installers within one Foglight Agent Manager, so installer
IDs are more complex than Foglight Agent Manager IDs.
For example, a Foglight Agent Manager installer ID can look like this:
tor012991.prod.quest.corp#cf238d96-3a56-45d6-a33e-b88bb7d4ff55#Fg
lAM:tor012991.prod.quest.corp/cf238d96-3a56-45d6-a33e-b88bb7d
4ff55/installer
In general, each remote installer is capable of handling an agent package of one type.
The type of agent package is specified in the respective cartridge manifest file, but is not
visible directly through the command line interface. However, agent package types
affect the results of the agent:packages command. Given a Foglight Agent Manager
ID as a parameter, the agent:packages command checks the installers that are
available on the Foglight Agent Manager and returns IDs for all agent packages that can
be handled by at least one installer on the Foglight Agent Manager.
C:\Quest_Software\Foglight\bin>fglcmd -usr foglight -pwd foglight
-cmd agent:packages -clientid
tor012991.prod.quest.corp#cf238d96-3a56-45d6-a33e-
b88bb7d4ff55
Note In Foglight, the Foglight Agent Manager is used to manage agent instances and their
communication with the Foglight Management Server. Some monitoring environments use
the Foglight Client, which is an older version of the agent manager. While Foglight supports
both types of agent managers, some may display slightly different type of information. This
section includes command-line examples that illustrate a monitoring environment that uses
the Foglight Agent Manager. For information on those interfaces in environments that use
the Foglight Client, see “Installer IDs” on page 819.
318 Foglight
Administration and Configuration Guide
Installer IDs are generally persistent. They do not change after restarting the Foglight
Management Server or Foglight Agent Manager instances. Nonetheless, changing
Foglight Agent Manager configuration may affect both Foglight Agent Manager and
Installer IDs. These IDs may change in future releases of Foglight.
When you ensure that the agent package that you want to deploy is available, use the
agent:deploy command to deploy that agent package.
Alternatively, you can deploy an agent package using the Agent Status dashboard. For
instructions, see “Using the Agent Status dashboard to deploy agent packages” on
page 313.
Important The procedure below assumes that you have configured the fglcmd package on the
computer you are using to deploy agent packages. For complete instructions, see the
Command-Line Reference Guide.
Note If you are running the commands below on a UNIX platform, you can use a back slash ‘\’ to
indicate a new line when running long commands.
2 List the agent packages that are available to the Foglight Agent Manager using
the following command syntax:
fglcmd -usr user_name -pwd password -cmd agent:packages
-clientname myhost.mydomain
An output similar to the following appears, listing one or more agent packages
that can be deployed to the specified host.
Client ID: myhost.mydomain#cf238d96-3a56-45d6-a3
3e-b88bb7d4ff55
Agent Package ID: OSCartridge-WindowsXP-5.5.0-OSCartrid
ge-Agent-WindowsXP-windows-/5\.1.*/-ia32,x86_64
Agent Package Cartridge Name: OSCartridge-WindowsXP
Agent Package Cartridge Version: 5.5.0
Agent Package OS: windows
Agent Package OS Version: /5\.1.*/
Managing Agents 319
Installing and Managing Agent Instances on a Monitored Host
Note For information on how to deploy an agent package in a monitoring environment that uses
the Foglight Client, see “Deploying agent packages” on page 814.
320 Foglight
Administration and Configuration Guide
Note This procedure continues from “Accessing the Agent Status Dashboard” on page 293.
Managing Agents 321
Installing and Managing Agent Instances on a Monitored Host
1 In the Agent Status dashboard, click the Create Agent button in the lower-left
corner.
The Create Agent dialog box appears.
Tip To create agent instances on multiple hosts, navigate to the Agent Hosts dashboard by
clicking Agent Hosts in the Create Agent dialog box. For more information, see
“Deploying Agent Instances to Multiple Monitored Hosts” on page 342.
2 Specify the monitored host that you want to monitor with the agent instance that
you are about to create.
Note In order to select the host, the Foglight Agent Manager must be up and running on
the monitored host.
In the Create Agent dialog box, click the Host box and select the monitored host
from the list that appears.
The Agent Type box refreshes, showing a list of agent types that can be created
on the selected host.
322 Foglight
Administration and Configuration Guide
The list of available agent types reflects the cartridges that have been installed
and enabled on the Foglight Management Server, and whose packages are
deployed to the monitored host. Each cartridge package deployed to the
monitored host includes one or more agent types.
3 Specify the agent type of the instance that you are about to create.
Note You can only create instances of those agent types that have already been deployed
to the monitored host.
In the Agent Type list, select the agent type. For example, to create a
Windows_System agent instance, in the Agent Type list, select
Windows_System.
4 Specify the name of the agent instance that you are about to create.
• To assign a specific name to the agent instance, in the Instance Name box,
type that name. For example, MyAgent.
• To assign a generic name, select the Generate Name check box.
A generic name is a combination of the host name and the agent type and uses
the following syntax:
cartridge_name_on_host_name
For example, the generic name for a LogFilter agent instance that monitors a
host MyHost.MyDomain.com, Foglight sets the agent name to:
Managing Agents 323
Installing and Managing Agent Instances on a Monitored Host
LogFilter_on_MyHost.MyDomain.com
The Create button in the Create Agent dialog box becomes enabled.
5 Click Create.
The Create Agent dialog box closes and the Create Agent Results dialog box
appears, showing the status of the operation.
After a few moments, in the Create Agent Results dialog box, in the Status
column of the Progress table, a green check mark appears, indicating a success of
the operation.
324 Foglight
Administration and Configuration Guide
After creating an agent instance, you need to activate that instance and start its data
collection. For more information, see “Activating or Deactivating Agents” on page 327.
Before creating an agent instance, you need to insure that the applicable agent type
already exists on the monitored host using the fglcmd’s agent:types command.
This command lists the available agent types per client ID.
In multi-host scenarios, you need to identify the Foglight Agent Manager running on the
monitored host for which you want to list the agent types.
Note In Foglight, the Foglight Agent Manager is used to manage agent instances and their
communication with the Foglight Management Server. Some monitoring environments use
the Foglight Client, which is an older version of the agent manager. While Foglight supports
both types of agent managers, some may display slightly different type of information. This
section includes command-line examples that illustrate a monitoring environment that uses
the Foglight Agent Manager. For information on those interfaces in environments that use
the Foglight Client, see “Foglight Client IDs” on page 818.
Foglight Agent Manager IDs identify agent management processes on remote machines.
For agents managed by the Foglight Agent Manager, Foglight Agent Manager IDs
identify instances of the Foglight Agent Manager. Since it is possible to have several
process managers on a monitored host, Foglight Agent Manager IDs are more complex
than host names. For example, a Foglight Agent Manager ID can look like this:
tor012991.prod.quest.corp#cf238d96-3a56-45d6-a33e-b88bb7d4ff55
Foglight Agent Manager IDs for running agent managers can be obtained by executing
the agent:packages command:
C:\Quest_Software\Foglight\bin>fglcmd -usr foglight -pwd foglight
-cmd agent:types -host tor012991
Client ID: tor012991.prod.quest.corp#cf238d96-3a56-45d6-a33e-
b88bb7d4ff55
Client Name: tor012991.prod.quest.corp
Agent Types:
NetMonitor
LogFilter
WebMonitor
ApacheSvr
SNMP
AppMonitor
Windows_System
------------------------------------
Foglight Agent Manager IDs are generally persistent. They do not change after
restarting the Foglight Management Server or Foglight Agent Manager instances.
Nonetheless, changing Foglight Agent Manager configuration may affect both Foglight
Agent Manager and Installer IDs. These IDs may change in future releases of Foglight.
326 Foglight
Administration and Configuration Guide
When you ensure that the agent type that you want to use to create a new agent instance
is available, use the agent:create command to create the agent instance.
Alternatively, you can create an agent instance using the Agent Status dashboard. For
instructions, see “Using the Agent Status dashboard to create agent instances” on
page 320.
Important The procedure below assumes that you have configured the fglcmd package on the
computer you are using to create agent instances. For complete instructions, see the
Command-Line Reference Guide.
Note If you are running the commands below on a UNIX platform, you can use a back slash ‘\’ to
indicate a new line when running long commands.
2 List the agent types that are available to the Foglight Agent Manager using the
following command syntax:
fglcmd -usr username -pwd password -cmd agent:types
-clientname myhost.mydomain
An output similar to the following appears, listing all agent types that are
available to the specified Foglight Agent Manager.
Client ID: tor012991.prod.quest.corp#cf238d96-3a56-45d6-
a33e-b88bb7d4ff55
Client Name: tor012991.prod.quest.corp
Agent Types:
NetMonitor
LogFilter
WebMonitor
ApacheSvr
SNMP
AppMonitor
Windows_System
------------------------------------
Managing Agents 327
Installing and Managing Agent Instances on a Monitored Host
3 Review the above output and record the type of the agent whose instance you
want to create.
4 Create an agent instance using the following command syntax:
fglcmd -usr username -pwd password -cmd
agent:create -name instance_name -type agent_type
-host host_name
If successful, this command does not generate any output.
Note For information on how to create agent instances in a monitoring environment that uses the
Foglight Client, see “Creating agent instances” on page 815.
Agent is inactive
Tip Some Foglight agents, such as the AIX and HP system agents that come included with the
OS Cartridge, require root-level privileges to run on Unix. This can be accomplished by
328 Foglight
Administration and Configuration Guide
making sure that the user account used to install the Foglight Agent Manager on the
monitored host does not appear in the sudo configuration file. However, if the Foglight Agent
Manager does not have root-level privileges, the agents that require those privileges fall back
to normal, non-root launch. Starting those agents without root privileges does not prevent
them from activating and collecting data. For more information about installing the Foglight
Agent Manager with root privileges, see the Installation and Configuration Guide. For
information about the OS Cartridge, refer to the cartridge documentation.
Note This procedure continues from “Accessing the Agent Status Dashboard” on page 293.
1 In the Agent Status dashboard, select the row containing an inactive agent
instance that you want to activate.
Tip To select multiple agent instances, press the CTRL or SHIFT key while selecting the
rows containing the instances that you want to activate.
After a few moments, in the Agent Operation dialog box, in the Status column
of the Progress table, a green check mark appears, indicating a success of the
operation.
Note It may take some time for the Activated ( ) and Collecting Data ( ) icons to appear even if
activation of the agent was successful.
The Activated icon appears when the Management Server has confirmed that the agent has
started and is running.
If the activation command was executed successfully but the agent fails after starting, the
Activated icon will not appear.
330 Foglight
Administration and Configuration Guide
Note This procedure continues from “Accessing the Agent Status Dashboard” on page 293.
1 In the Agent Status dashboard, select the row containing an active agent instance
that you want to deactivate.
Tip To select multiple agent instances, press the CTRL or SHIFT key while selecting the
rows containing the instances that you want to deactivate.
After a few moments, in the Agent Operation dialog box, in the Status column
of the Progress table, a green check mark appears, indicating a success of the
operation.
Managing Agents 331
Installing and Managing Agent Instances on a Monitored Host
If you no longer require the agent that you deactivate, you can remove it from the
monitored host. For more information, see “Deleting Agents” on page 337.
You can stop or start data collection for an active agent using the Agent Status
dashboard, as described below. For information on how to activate or deactivate an
agent, see “Activating or Deactivating Agents” on page 327.
Alternatively, use the agent:start or agent:stop commands to start or stop data
collection. These commands come with the fglcmd interface. For complete
information, see the Command-Line Reference Guide.
Caution Changes made to the data-collection status of an agent by following the instructions
below will not be persisted if the agent enters a blackout period. See “Assigning
Blackouts to Agent Instances” on page 357 for information about agent blackouts.
The Collecting Data icon ( ) indicates that the agent is collecting data while the Not
Collecting Data icon ( ) indicates the opposite. An empty column indicates that the
agent is inactive.
Figure 5
Agent is inactive
Note This procedure continues from “Accessing the Agent Status Dashboard” on page 293.
1 In the Agent Status dashboard, select the row containing an active agent instance
for which you want to start data collection.
Note The Activated icon ( ) indicates whether or not the agent is active.
Tip To select multiple agent instances, press the CTRL or SHIFT key while selecting the
rows containing the instances for which you want to start data collection.
After a few moments, in the Agent Operation dialog box, in the Status column
of the Progress table, a green check mark appears, indicating a success of the
operation.
334 Foglight
Administration and Configuration Guide
Note It may take some time for the Collecting Data icon ( ) to appear even if activation of the
agent was successful.
The Activated icon appears when the Management Server has confirmed that the agent has
started and is running.
If the activation command was executed successfully but the agent fails after starting, the
Activated icon will not appear.
Note This procedure continues from “Accessing the Agent Status Dashboard” on page 293.
Managing Agents 335
Installing and Managing Agent Instances on a Monitored Host
1 In the Agent Status dashboard, select the row containing an active agent instance
whose data collection you want to stop.
Note The Collecting Data icon ( ) indicates that the agent is collecting data.
Tip To select multiple agent instances, press the CTRL or SHIFT key while selecting the
rows containing the instances for which you want to stop data collection.
2 Click the Stop Data Collection button at the bottom.The Stopping Data
Collection dialog box appears, showing the status of the activation process.
After a few moments, in the Agent Operation dialog box, in the Status column
of the Progress table, a green check mark appears, indicating a success of the
operation.
336 Foglight
Administration and Configuration Guide
Caution Changes made to the data-collection status of an agent by following the instructions
below will not be persisted if:
• The server is restarted.
• The agent exits a blackout period. See “Assigning Blackouts to Agent Instances” on
page 357 for information about agent blackouts.
Managing Agents 337
Installing and Managing Agent Instances on a Monitored Host
Deleting Agents
When you delete an agent, that agent instance is removed from the monitored host. You
can delete an agent using the Delete button on Agent Status dashboard, as described
below. Alternatively, use the agent:delete command to delete an agent instance. The
command comes with the fglcmd interface. For complete information about this
command, see the Command-Line Reference Guide.
You can only delete those agent instances that you create after the installation. This
excludes agent adapters that also appear in the Agent Status dashboard. If one or more
of your agent instances use the Foglight Agent Manager for communication with the
Foglight Management Server, and you select the SPI Network adapter in the Agent
Status dashboard, the Delete button becomes disabled.
To delete an agent instance:
Note This procedure continues from “Accessing the Agent Status Dashboard” on page 293.
A message box appears, indicating that the agent instance is successfully deleted.
The listing in the Agent Status dashboard refreshes, no longer showing the newly-
deleted agent instance.
Note This procedure continues from “Accessing the Agent Status Dashboard” on page 293.
1 In the Agent Status dashboard, select the row containing the agent instance whose
log you want to retrieve.
2 Click Get log.
Your Web browser displays a dialog box that allows you to open or save the log
file.
340 Foglight
Administration and Configuration Guide
Note The appearance of the above dialog may be different, depending on the type and
version of your Web browser.
Important The procedure below assumes that you have configured the fglcmd package on the
computer you are using to retrieve agent logs. For complete instructions, see the
Command-Line Reference Guide.
One agent instance can generate multiple log files, one for each period of time the agent
is running. The command line offers the flexibility of selecting log files for an agent,
while the Agent Status dashboard allows you to retrieve only the most recent log file.
Managing Agents 341
Installing and Managing Agent Instances on a Monitored Host
This way of collecting log files is useful in situations where you do not have permission
or resources to access log files on the monitored host using a file browser.
Note If you pull Agent Logs into the <foglight_home>\logs directory, they will be packaged as part
of a support bundle.
2 List the agent log files using the following command syntax:
fglcmd -usr username -pwd password -cmd agent:logs
-host myhost.mydomain
An output similar to the following appears, listing all log files that exist on the
specified host.
Client ID: myhost.mydomain#cf238d96-3a56-45d6-a33e-b88bb7d
4ff55
Client Name: myhost.mydomain
Host Name: myhost.mydomain
50 log files found.
OSCartridge\5.5.0\logs\AIX_Console_My_AIX_Console_Agent
_2009-01-21_095227_001.log
OSCartridge\5.5.0\logs\AIX_MPStat_My_AIX_MPStat_Agent_
2009-01-21_094945_001.log
OSCartridge\5.5.0\logs\AIX_System_My_AIX_System_Agent_
2009-01-21_095149_001.log
OSCartridge\5.5.0\logs\ApacheSvr_ApacheSvr_
2009-01-16_102536_001.log
OSCartridge\5.5.0\logs\ApacheSvr_My_ApacheSvr_Agent_
2009-01-16_114450_001.log
…
3 Review the above output and record the log file that you want to retrieve.
4 Transfer that log file into a local directory using the following command syntax:
fglcmd -usr username -pwd password -cmd
agent:getlog -log path_and_name_of_log_file -f
path_and_name_of_destination_file
342 Foglight
Administration and Configuration Guide
Note For information on how to retrieve agent log files in a monitoring environment that uses the
Foglight Client, see “Retrieving agent logs” on page 817.
Note Some monitoring environments use the Foglight Client, which is an older version of the
agent manager. While Foglight supports both types of agent managers, some commands
and dashboards may display slightly different type of information. This chapter contains
samples of command-line output and screen captures that illustrate a monitoring
environment that uses the Foglight Agent Manager. For information on those interfaces in
environments that use the Foglight Client, see “Appendix: Foglight Client Reference” on
page 807.
For information about the types of adapters that your agents require in order to
communicate with the Foglight Management Server, see your cartridge documentation.
Managing Agents 343
Deploying Agent Instances to Multiple Monitored Hosts
For information on how to install and configure the Foglight Agent Manager, see the
Foglight Installation and Setup Guide.
For information about the types of adapters that your agents require in order to
communicate with the Foglight Management Server, see your cartridge documentation.
For information on how to install and configure the Foglight Agent Manager, see the
Foglight Installation and Setup Guide.
The Agent Hosts dashboard allows you to view information about hosts as well as
deploy agent packages and create an agent instance on multiple hosts at a time.
Tip Use the Agent Hosts dashboard to deploy agent packages and create agent instances to
multiple hosts. Unlike the Agent Hosts dashboard, that you can use to manage agent
instances on multiple hosts, the Extend Your Monitoring Reach dashboard, accessible from
the Welcome page, includes additional functionality that allows you to complete configuration
interviews and create interactive configuration plans that identify the required agents, and to
install them. Extend Your Monitoring Reach can be used as an alternative when adding agent
instances for host, database or JavaEE monitoring in small- and mid-size organizations. If
your business requirements change over time, the collection of active agent instances can be
modified using the Agent Hosts dashboard, or by returning to Extend Your Monitoring Reach.
For information about the Extend Your Monitoring Reach dashboard, see Chapter 2,
“Extending Your Monitoring Reach” on page 67.
Tip Use the Agent Hosts dashboard to deploy agent packages and create agent instances to
multiple hosts. Unlike the Agent Hosts dashboard, that you can use to manage agent
instances on multiple hosts, the Extend Your Monitoring Reach dashboard, accessible from
the Welcome page, includes additional functionality that allows you to complete configuration
344 Foglight
Administration and Configuration Guide
interviews and create interactive configuration plans that identify the required agents, and to
install them. Extend Your Monitoring Reach can be used as an alternative when adding agent
instances for host, database or JavaEE monitoring in small- and mid-size organizations. If
your business requirements change over time, the collection of active agent instances can be
modified using the Agent Hosts dashboard, or by returning to Extend Your Monitoring Reach.
For information about the Extend Your Monitoring Reach dashboard, see Chapter 2,
“Extending Your Monitoring Reach” on page 67.
3 To sort the list by the host name, or OS name, version or the architecture of the
Foglight Agent Manager installer, click the Hostname, Type, Version, OS
Name, OS Version, or OS Arch column headings, as required.
Managing Agents 345
Deploying Agent Instances to Multiple Monitored Hosts
4 To filter the list of hosts by the host name, OS name, or the package to which it
can be deployed, use one or more of the Hostname, OS Name, Installable
Packages, or Installable Upgrades boxes at the top of the Agent Hosts list.
For example, to list only the hosts whose OS name contains “Windows”, in the
Agent Name box, type Windows.
To clear the filters, click Clear Filters.
From here, you can proceed to any of the following procedures:
• “Deploying Agent Packages to Multiple Hosts” on page 345
• “Creating Agent Instances on Multiple Hosts” on page 348
Note Any agents that you install must be compatible with the host’s OS and architecture.
Some agents (for example, the Java® EE Agent) are installed using an agent installer
that can be downloaded and run from the Components for Download dashboard. See
“Downloading Agent Components” on page 265 for instructions.
Use the Agent Hosts dashboard to deploy an agent package to multiple hosts at the same
time. In some cases, agent deployment should be followed by editing the agent’s
properties. See “Editing Agent Properties by Agent Instance” on page 296. For
information on which properties to edit, refer to your cartridge documentation.
Alternatively, if you need to perform a series of agent-related operations on a single
host, the Agent Status dashboard. For more information, see “Deploying Agent
Packages to a Monitored Host” on page 312.
To deploy an agent package to multiple hosts:
Note This procedure continues from “Accessing the Agent Hosts Dashboard” on page 343.
346 Foglight
Administration and Configuration Guide
1 In the Agent Hosts dashboard, select the row containing the host to which you
want to deploy an agent package.
2 Click the Deploy Agent Package button at the bottom.
The Deploy Agent Package dialog box appears.
5 Ensure that the agent package the you want to deploy is selected in the Package
box.
Note You can only deploy those agent packages whose cartridges have already been
installed on the Foglight Management Server.
6 Click Deploy.
The Deploy Agent Package dialog box refreshes, showing the status of the
deployment operation.
After a few moments, in the Deploy Agent Package dialog box, in the Status
column of the Progress table, green check marks indicate a success of the
deployment operation.
348 Foglight
Administration and Configuration Guide
Note This procedure continues from “Accessing the Agent Hosts Dashboard” on page 343.
1 In the Agent Host dashboard, select the row containing one or more hosts on
which you want to create agent instances.
2 Click the Create Agent button at the bottom.
The Create Agent dialog box appears.
For example, to create a Windows_System agent instance, in the Agent Type list,
click Windows_System.
6 Specify the name of the agent instance that you are about to create.
• To assign a specific name to the agent instance, in the Instance Name box,
type that name. For example, MyAgent.
or
• To assign a generic name, select the Generate Name check box.
A generic name is a combination of the host name and the agent type and uses
the following syntax:
cartridge_name_on_host_name
For example, the generic name for a LogFilter agent instance that monitors a
host MyHost.MyDomain.com would be as follows:
LogFilter_on_MyHost.MyDomain.com
The Create button in the Create Agent dialog box becomes enabled.
7 Specify the name of the agent instance that you are about to create.
In the Instance Name box, type a unique name of the agent instance. For
example, MyAgent.
The Create button in the Create Agent dialog box becomes enabled.
8 Click Create.
The Create Agent dialog box closes and the Create Agent Results dialog box
appears, showing the status of the operation.
Managing Agents 351
Deploying Agent Instances to Multiple Monitored Hosts
After a few moments, in the Create Agent Results dialog box, in the Status
column of the Progress table, a green check mark appears, indicating a success of
the operation.
352 Foglight
Administration and Configuration Guide
For information on how to use the Agent Adapters dashboard, see the following
sections:
• “Accessing the Agent Adapters Dashboard” on page 354
• “Activating or Deactivating Agent Adapters” on page 356
Note For a sample screen capture of this dashboard in a monitoring environment that
uses the Foglight Client, see “Agent Adapters dashboard” on page 813.
Managing Agents 355
Viewing Agent Adapters
The list shows the agent adapters that exist in your monitoring environment. The
above screen shows three agent adapters: FglAM, SPI, and XML-HTTP. These
adapters are a part of the Foglight infrastructure and will appear in the Agent
Adapters dashboard when your configuration includes the Foglight Management
Server, Foglight Agent Manager, and one or more cartridges that use the Foglight
Agent Manager for communication with the server.
To sort the list of agent adapters by their ID, active state, name, health, cartridges
that use them for communication, or version number, click the id, Active ( ),
name, health, cartridge, or Version column headings as required.
3 To filter the list of agent adapters, use one or more of the following boxes at the
top of the Agent Adapters list: name, health, cartridge, or Version.
For example, to list only the Foglight Agent Manager adapters, in the Name box,
type FglAM.
The Agent Adapters list refreshes, showing the agent adapters whose name
matches the filter pattern.
Adapter is active
Adapter is inactive
Note This procedure continues from “Accessing the Agent Adapters Dashboard” on page 354.
Managing Agents 357
Assigning Blackouts to Agent Instances
1 In the Agent Adapters dashboard, select the row containing an inactive agent
adapter that you want to activate.
Tip To select multiple agent adapters, press the CTRL or SHIFT key while selecting the
rows containing the adapters that you want to activate.
Note This procedure continues from “Accessing the Agent Adapters Dashboard” on page 354.
1 In the Agent Adapters dashboard, select the row containing an active agent
adapter that you want to deactivate.
Tip To select multiple agent adapters, press the CTRL or SHIFT key while selecting the
rows containing the instances that you want to deactivate.
3 To sort the list by their ID, host name, instance name, agent type, or schedule
name, click the ID, Hostname, Agent Name, Type, or Schedule Name column
headings as required.
4 To filter the list of agents by the host name, instance name, agent type, or
schedule name, use the Hostname, Agent Name, Type, or Schedule Name
boxes at the top of the Agent Blackouts list.
For example, to list only the hosts whose agent type contains “Windows”, in the
Type box, type Windows.
The Agent Blackouts list refreshes, showing the agent instances whose name
matches the filter pattern.
Managing Agents 359
Assigning Blackouts to Agent Instances
The list reflects the entries in Manage Schedules dashboard. For more
information, see “Managing Schedules” on page 563.
• To remove a schedule, select —No Schedule— in the list.
or
• To assign a schedule, select any other entry in the list, as required. For
example, to black out the selected agent on the first day of each month, select
First day of month.
6 Click Assign Blackout.
The Blackout Schedule Results dialog box appears. A green check mark in the
Status column indicates that the blackout schedule is successfully assigned to the
selected agent instance.
This chapter introduces you to Foglight rules and registry and provides information on
how to create and manage these entities. It contains the following sections:
Note In order to complete each of the procedures in this chapter, your user account must belong
to a group with the Administration role. For more information about users, groups, and roles,
see “Managing Users and Security” on page 197.
3 To sort the list of variables by their name or type, click the Variable Name or
Type column headings as required.
4 Optional. Filter the list of variables.
• To show only the variables whose name matches a text pattern, type that
pattern into the Variable Name box at the top of the list.
The Manage Registry Variables dashboard refreshes, showing only the
variables whose name matches the text pattern.
• To show only the variables that are associated with specific topology types,
click By Topology at the top of the list and select the topology type for which
you want to filter from the list that appears.
The Manage Registry Variables dashboard refreshes, showing only the
variables that have one or more values scoped to the selected topology type.
• To show only the variables that have a global default value set, click By
Global Default and select Defined from the list that appears.
The Manage Registry Variables dashboard refreshes, showing only the
variables that have a global default value.
• To show only the variables that do not have a global default value set, click By
Global Default and select Undefined from the list that appears.
Working with Foglight Rules and Registry 367
Working with Foglight Registry Variables
The dwell shows the registry variable name, cartridge name, cartridge version,
data type, modification date, any comments (if existing), and global default.
From here, you can proceed to any of the following procedures:
• “Editing permissions of registry variables” on page 368
• “Copying registry variables” on page 372
• “Deleting registry variables” on page 374
• “Viewing and editing variable settings” on page 375
edit permissions to roles and users, as outlined below. The Edit Permissions for Registry
Variable area contains two tables that show the permissions for each Foglight user or
role.
Figure 1
Permission granted
Permission denied
Permissions not assigned
Note This procedure continues from “Accessing the Manage Registry Variables dashboard” on
page 365.
1 On the Manage Registry Variables dashboard, in the row containing the variable
whose permissions you want to edit, click the Edit Permissions for Registry
Variable button ( ).
The Edit Permissions for Registry Variable area appears in the display area.
370 Foglight
Administration and Configuration Guide
The Add Role Permission or Add User Permission dialog box appears.
Working with Foglight Rules and Registry 371
Working with Foglight Registry Variables
b In the dialog box that appears, use the Read, Write, and Control check boxes
to assign permissions as required, and click Save.
The dialog box closes and the selected entry refreshes, showing three check
marks in the Permission columns, one for each of the read, write, and control
permissions.
Permission granted
Permission denied
The Edit Role Permission or Edit User Permission dialog box appears.
372 Foglight
Administration and Configuration Guide
b To edit the permissions, ensure that the Edit option is selected and use the
Read, Write, and Control check boxes as required.
To delete the permissions, select the Delete option.
c Click Save.
The dialog box closes and the selected entry refreshes, showing the newly-
edited permissions.
Note This procedure continues from “Accessing the Manage Registry Variables dashboard” on
page 365.
1 In the Manage Registry Variables dashboard, in the row containing the variable
that you want to copy, click the Copy Registry Variable button ( ).
The Copy Registry Variable dialog box appears.
Working with Foglight Rules and Registry 373
Working with Foglight Registry Variables
The dialog box closes and the Edit Registry Variable pane appears in the display
area.
374 Foglight
Administration and Configuration Guide
Note When a registry variable is deleted, all references to that variable in rule conditions and
expressions become invalid. This may cause the rule to fail to evaluate. If this occurs, you
must manually modify the rule condition or expression.
Note This procedure continues from “Accessing the Manage Registry Variables dashboard” on
page 365.
Working with Foglight Rules and Registry 375
Working with Foglight Registry Variables
1 In the Manage Registry Variables dashboard, select the row containing the
variable that you want to delete.
2 Click the Delete Selected button at the bottom.
The Registry Variable Confirmation dialog box appears.
Note This procedure continues from “Accessing the Manage Registry Variables dashboard” on
page 365.
1 In the Manage Registry Variables dashboard, click the Variable Name column of
the row containing the variable whose definitions you want to view.
The Edit Registry Variable view appears in the display area.
376 Foglight
Administration and Configuration Guide
3 Specify the name, description, and data type for the variable using the following
boxes:
• Registry Variable Name: The name of the variable.
Note The registry variable name cannot be longer than two hundred and fifty (250)
characters and cannot be the same as the name of an existing registry variable.
In addition, the name cannot be changed once the registry variable has been
added. This is because registry variables are referred to by their names in rule
conditions and expressions and changing them would invalidate these
references. However, you can copy a registry variable and give the copy a
different name.
4 Click Add.
5 A confirmation message appears in the display area, informing you that the
variable has been created.
Working with Foglight Rules and Registry 381
Working with Foglight Registry Variables
Note This procedure continues from “Accessing the Manage Registry Variables dashboard” on
page 365 or “Creating Registry Variables” on page 377.
1 In the Manage Registry Variables dashboard, click the Variable Name column of
the row containing the variable whose definitions you want to view.
The Edit Registry Variable view appears in the display area.
382 Foglight
Administration and Configuration Guide
The Edit Registry Variable view shows the registry variable settings, such as the
registry variable name, cartridge name and version (if applicable), variable data
type, and the modification date. Additionally, it also displays the global value, or
any relative values that are either scoped to particular topology object instances,
or change according to performance calendars.
Tip If a registry variable comes with the Foglight Management Server or any installed
cartridge, the Cartridge Name and Cartridge Version values indicate the cartridge
Working with Foglight Rules and Registry 383
Working with Foglight Registry Variables
name and its version. Otherwise, if the registry variable is created using the Create
Registry Variable dashboard, this value is blank.
Caution The name and value type of a registry variable cannot be changed after the
variable creation. Registry variables are referred to by their names in rule
conditions and expressions and changing them would invalidate these
references. However, you can copy a registry variable and give that copy a
different name.
Specifying values
A registry variable can have a global value and multiple scoped values (that is, values
that are associated with specific topology types or objects). Each of these values has a
default setting. For example, if the variable’s type is Integer, the global default value
would be set to a specific integer. However, you can also configure the setting for each
value to vary over time by adding schedules and alternate values to the value’s
performance calendars. A performance calendar specifies an alternative value which is
only in effect during the span(s) of time set by a schedule. All of the schedules that have
been created are available for use with registry variables. See “Example: Assigning
Multiple Values to a Registry Variable” on page 399 for an example of how to use this
feature. For more information about schedules, see Chapter 8, “Using Schedules” on
page 561.
The values that you assign to a variable must be consistent with the data type that you
specify at variable creation time. For example, if you selected Integer as the data type,
type 10 when specifying the value, not ten.
To specify values for a variable:
Note This procedure continues from “Getting started with variable definitions” on page 381 or
“Viewing and editing variable settings” on page 375.
1 Specify a default value for the variable using the options in the Global Default
area.
There are two types of options you can specify:
• Static Value: This value does not change over time.
When you select this option, specify the value of the registry variable in the
Global Default area. The value you provide must be compatible with the
384 Foglight
Administration and Configuration Guide
variable’s data type that you set at variable creation. The appearance of the
Global Default area depends on the type of data you can use, as indicated in
the table below. For example, if the data type is Boolean, instead of typing
true or false, select the appropriate value from the list that appears.
For more information about different data types you can use, see “Creating
Registry Variables” on page 377
• Registry Variable Reference: This value references another registry variable.
When you select this option, the Global Default area refreshes, allowing you
to select from available registry variables whose data type matches the data
type of the registry variable that you are editing. For example, if the data type
is Long, clicking the box in the Global Default area shows a list containing
the registry variables of the Long type that exist in your configuration.
Working with Foglight Rules and Registry 385
Working with Foglight Registry Variables
Note The value that you specify in this field applies to all topology types and objects other
than those that you specify in the Registry Values table, as described in “Scoping
variables to topology types or object instances” on page 387. It is effective at all
times except at the times set in the schedules added to the Default Value
Performance Calendar, as described in “Using performance calendars” on
page 385.
1 Choose a schedule.
Click Schedule Name and select a schedule from the list that appears.
The list reflects the existing schedules. For information on how to add schedules
to Foglight, see Chapter 8, “Using Schedules” on page 561.
2 Specify the value for the newly-selected schedule.
Similar to the global default value, there are two options you can specify: Static
Value and Registry Variable Reference.
Use the Value box to specify the value with which you want to replace the default
value during the period defined by the schedule.
Note The value you specify here should match the data type of the variable. For example,
if the variable is a boolean, you can set it to true or false.
3 Click Add.
The schedule and alternate value appear in the Default Value Performance
Calendars table, as specified.
4 If required, add more schedules to the list and ensure that their order is valid.
Caution The Foglight Management Server evaluates schedule-based values in the order
that they are listed, starting with the first one. Changing their order affects the
output of actions that are associated with the value that is associated with their
schedule entries.
Working with Foglight Rules and Registry 387
Working with Foglight Registry Variables
Note This procedure continues from “Using performance calendars” on page 385.
2 Click Topology Type and select a type from the list that appears.
3 Optional. Narrow down your scope to a particular object
Click Topology Object and select an object from the list that appears.
4 Specify the default value that you want the variable to use when scoping on the
newly-specified topology type or object.
In the Default Value area, select the Static Value or Registry Variable Reference
option and use the Value box to specify the default value.
5 Click Add.
The Create Registry Value—Step 2 view appears in the display area.
6 Optional. If you want the default value to change over time, add one or more
schedules to the Default Value Performance Calendars table and specify the
value for each schedule.
To add a schedule to the performance calendar, complete the following steps.
a Choose a schedule.
Click Schedule Name and select a schedule from the list that appears.
The list reflects the existing schedules. For information on how to add
schedules to Foglight, see Chapter 8, “Using Schedules” on page 561.
b Specify the value for the newly-selected schedule.
Similar to the global default value, there are two options you can specify:
Static Value and Registry Variable Reference.
Working with Foglight Rules and Registry 389
Working with Foglight Registry Variables
Use the Value box to specify the value with which you want to replace the
default value during the period defined by the schedule.
c Click Add.
The schedule and alternate value appear in the Default Value Performance
Calendars table, as specified.
d Click Done.
In the Edit Registry Variable pane, the Registry Value table refreshes,
showing the newly-added registry value scoped to a topology type or object, as
specified.
390 Foglight
Administration and Configuration Guide
• Registry Value: The value to which the variable is set during a specified date
and time range. If there are multiple time ranges during which the registry
value changes, the table shows the registry value for each range.
4 Specify the name of the variable whose values you want to view.
For example, look at the SYSADMIN variable that is scoped to two topology object
instances and two different performance calendars.
Note By default, the SYSADMIN variable has no scoped values. They have been created
for the purpose of this exercise. For an example of how you can scope a registry
variable to multiple topology objects, see “Example: Assigning Multiple Values to a
Registry Variable” on page 399.
a In the View Registry Variable view, click the link that appears on the right of
Variable Name.
The Registry Variable list appears, showing the registry variables that exist in
your Foglight environment. This includes any registry variables that came
with the installation of the Foglight Management server, any installed
cartridges, or any variables you created using the Create Registry Variable
dashboard.
392 Foglight
Administration and Configuration Guide
Note The list does not include the registry variables that contain password values.
b In the Registry Variable list, scroll down until you find a registry variable,
and select that entry. For example, to select the SYSADMIN variable, select the
SYSADMIN entry in the list.
5 Select the topology type to which the selected registry variable is scoped.
a In the View Registry Variable view, click the link that appears on the right of
Topology Type Name.
The Topology Type list appears, showing all topology types that exist in your
Foglight environment.
Working with Foglight Rules and Registry 393
Working with Foglight Registry Variables
b In the Topology Type list, scroll down until you find Host and select that
entry.
6 Select the object instance of the selected topology type to which the selected
registry variable is scoped.
a In the View Registry Variable view, click the link that appears on the right of
Topology Object.
The Topology Object list appears, showing the object instances of the
selected topology type.
a In the View Registry Variable view, click the time range control in the upper-
right corner of the display area.
The Zonar appears with the Timeline tab open, indicating the time range for
which the registry values are displayed.
b Change the date and time range for which the registry values are displayed.
To change the time range for the current date, on the Timeline tab of the
Zonar, drag the edges of the selected time period.
To change the date and the time range, in the Zonar, open the Calendar tab
and select a desired range.
For complete information about the Zonar, see the Foglight User Guide.
Working with Foglight Rules and Registry 395
Working with Foglight Registry Variables
The Registry Value table refreshes, showing different registry values for
different date and time periods.
For complete information about the Zonar, see the Foglight User Guide.
8 Optional. Reduce the number of columns that appear in the Registry Value
table.
a In the Registry Value table, click the Show/Hide columns button.
Show/Hide columns
Since all of the three columns appear in the Registry Value table by default,
all of the check boxes that correspond to the columns appear selected.
396 Foglight
Administration and Configuration Guide
b To hide a column, in the Show columns dialog box, clear the corresponding
check box.
or
To show a column, clear the corresponding check box.
For example, to display only the time at which the value was set and the value,
ensure that the Period Begin Time and Registry Value check boxes are
selected, and clear the Period End Time check box.
c Click Apply.
The Registry Value table refreshes, showing only the selected columns.
Show/Hide columns
b In the Show Columns dialog box, under Actions, click one of the following
links:
Export as CSV, to export the table contents to a Comma Separated Values
(CSV) file.
Export as PDF, to export the table contents to a PDF file.
Export as Excel, to export the table contents to an Excel file.
Export as XML, to export the table contents to an XML file.
Clicking Export as PDF shows the PDF output in your Web browser.
Clicking Export as CSV, Export as Excel, or Export as XML shows a
dialog box, allowing you open the exported file, or to save it to disk.
398 Foglight
Administration and Configuration Guide
Note The appearance of the above dialog box may be different, depending on the type
and version of your Web browser.
Important If you previously show or hide one or more columns in the Registry Value
table, this layout is reflected in the exported file. For example, if you display
only the time at which the value was set and the registry value, only those
columns appear in the export file.
10 Change the object instance and the date and time range.
The Registry Value table refreshes, showing the values scoped to the selected
object instance and date and time range.
11 View the logic that determines a registry value that appears in the list.
Click a row containing a registry value.
Working with Foglight Rules and Registry 399
Working with Foglight Registry Variables
The Registry Lookup Path dialog box appears, showing the variable name,
scoped topology type and object (if applicable), and the time period during which
the selected value is valid.
Note If the schedule used in a performance calendar is deleted, the performance calendar will
automatically be deleted as well.
There is a simple rule that applies to the servlets in your application; an alarm fires if the
request response time for a servlet exceeds the threshold set in the rule condition. This
threshold is a registry variable called ResponseTimeTooLong; it is scoped to the
topology type J2EEServlet and its default scoped value is 8 seconds.
400 Foglight
Administration and Configuration Guide
However, you know that at certain times of day response times for servlet instances are
expected to exceed this threshold. At these times, the acceptable response time can be as
long as 15 seconds.
You can use registry variable performance calendars to account for this and avoid
having the rule fire as a result of false positives. You create a schedule called EndOfDay
that is set to the recur daily at the times when it is acceptable for response times for the
servlet instances to exceed eight seconds. You then navigate to the Manage Registry
Variables dashboard, and select the variable ResponseTimeTooLong. You leave the
variable’s scoped value for servlets at its default setting of 8 seconds but add the
schedule EndOfDay to the list of Performance Calendars for the variable, set the
replacement value to the alternative threshold of 15 seconds and then save your
changes.
HostA joe@xyzdomain.com
HostB larry@pdqdomain.com
To open the navigation panel, click the right-facing arrow on the left.
2 On the navigation panel, under Dashboards, choose Administration > Rules &
Notifications > Manage Registry Variables.
The Manage Registry Variables dashboard appears in the display area.
3 On the Manage Registry Variables dashboard, locate the row containing the
SYSADMIN variable.
Tip You can filter the list of variables using filters. At the top of the Manage Registry
Variables dashboard, in the Filter By Variable Name box, type SYSADMIN.
The Manage Registry Variables dashboard refreshes, showing only the SYSADMIN
variable.
402 Foglight
Administration and Configuration Guide
To add another email address, scoped to the other monitored host, repeat step a to
step f.
When you add the second topology-scoped value, the Registry Values table
shows two entries, one for each host.
Working with Foglight Rules and Registry 405
Working with Foglight Registry Variables
406 Foglight
Administration and Configuration Guide
• Registry Variable. A variable stored in the Foglight registry that can be used in
rule conditions, actions, and expressions. The value of a registry variable can be
configured to change over time. Variables can be scoped to specific topology
types or objects.
• Metric. A metric is a value measured over time. There are two types of metrics in
Foglight: raw and derived. Every metric is scoped to a topology type (and may be
scoped to one or more specific topology objects of that type).
• Raw Metric. A raw metric is simply collected from your monitored environment.
That is, it is not calculated from other metrics.
• Derived Metric. A derived metric is calculated from one or more (raw or derived)
metrics. Derived metrics can be created in the Foglight Administration Module.
• Topology Object Property. Data collected from your monitored environment that
describes a topology object.
You can create new rules, define existing or newly-created rules, and manage rules
using the dashboards that come with the Administration module. Foglight comes with a
set of core rules. Each cartridge has their own collection of rules. For information about
core Foglight rules, see “Rules Included with the Foglight Management Server” on
page 508. For details about cartridge-based rules, see your cartridge documentation.
For information about rule-related operations that you can perform in the
Administration module, see the following sections:
• “Managing Rules” on page 408
• “Creating Rules” on page 432
• “Defining Rules” on page 433
• “Defining Conditions, Alarms, and Actions” on page 442
• “Associating Rules with Schedules” on page 500
• “Defining Alarm and Action Behavior” on page 503
• “Defining Rule-Level Variables” on page 505
• “Rules Included with the Foglight Management Server” on page 508
• “Example: Creating a Multiple-Severity Rule Scoped to an EJB Instance” on
page 518
• “Example: Creating a Simple Data-Driven Rule Scoped to a Topology Type that
Triggers Email Actions” on page 520
408 Foglight
Administration and Configuration Guide
Managing Rules
The Manage Rules dashboard contains a table that lists all of the simple rules and
multiple-severity rules that are currently defined, the scope of each rule, and the
cartridge with which each rule is associated (if applicable).
This dashboard also includes controls for filtering the list of rules by cartridge; for
adding, copying, deleting, and editing rules; and for suspending rule alarms and actions.
For instructions on how to use the Manage Rules dashboard, see the following sections:
• “Accessing the Manage Rules dashboard” on page 408
• “Editing rule permissions” on page 411
• “Copying rules” on page 415
• “Deleting rules” on page 417
• “Disabling or enabling rules” on page 418
• “Suspending or resuming alarms” on page 420
• “Suspending or resuming actions” on page 422
• “Viewing rule schedules” on page 424
• “Viewing a rule summary” on page 425
• “Viewing and editing rule settings” on page 429
Note This procedure continues from “Logging in to Foglight” on page 22 or “Accessing the
Administration Dashboard” on page 57.
• To show only the rules whose name matches a particular text pattern, in the
Rule Name box at the top, type the text pattern.
The Manage Rules dashboard refreshes, showing only the rules whose name
matches the specified text pattern.
• To show only the rules whose scope name matches a particular text pattern, in
the Rule Scope box at the top, type the text pattern.
The Manage Rules dashboard refreshes, showing only the rules whose scope
matches the specified text pattern.
• To show only the rules that belong to a particular cartridge, in the Cartridge
Name box at the top, type the cartridge name.
The Manage Rules dashboard refreshes, showing only the rules that come with
the specified cartridge.
• To clear the filters, click Clear Filters.
The Manage Rules dashboard refreshes, showing the list of all rules.
The dwell shows the schedule name, any comments (if existing), next scheduled
time, and modification date.
From here, you can proceed to any of the following procedures:
• “Editing rule permissions” on page 411
• “Copying rules” on page 415
• “Deleting rules” on page 417
• “Disabling or enabling rules” on page 418
• “Suspending or resuming alarms” on page 420
• “Suspending or resuming actions” on page 422
• “Viewing rule schedules” on page 424
• “Viewing a rule summary” on page 425
• “Viewing and editing rule settings” on page 429
users, as outlined below. The Edit Permissions for Rules area contains two tables that
show the permissions for each Foglight user or role.
Figure 2
Permission granted
Permission denied
Permissions not assigned
Note This procedure continues from “Accessing the Manage Rules dashboard” on page 408.
1 In the Manage Rules dashboard, in the row containing the rule whose permissions
you want to edit, click the Edit Permissions for Rule button ( ).
The Edit Permissions for Rules area appears in the Manage Rules dashboard.
Working with Foglight Rules and Registry 413
Working with Rules
The Add Role Permission or Add User Permission dialog box appears.
414 Foglight
Administration and Configuration Guide
b In the dialog box that appears, use the Read, Write, and Control check boxes
to assign permissions as required, and click Save.
The dialog box closes and the selected entry refreshes, showing three check
marks in the Permission columns, one for each of the read, write, and control
permissions.
Permission granted
Permission denied
The Edit Role Permission or Edit User Permission dialog box appears.
Working with Foglight Rules and Registry 415
Working with Rules
b To edit the permissions, ensure that the Edit option is selected and use the
Read, Write, and Control check boxes as required.
c To delete the permissions, select the Delete option
d Click Save.
The dialog box closes and the selected entry refreshes, showing the newly-
edited permissions.
Copying rules
Use the Copy Rule button on the Manage Rules dashboard to copy a rule, as outlined
below.
To copy a rule:
Note This procedure continues from “Accessing the Manage Rules dashboard” on page 408.
1 In the Manage Rules dashboard, in the row containing the rule that you want to
copy, click the Copy Rule button ( ).
The Rule Confirmation dialog box appears.
416 Foglight
Administration and Configuration Guide
Simple rule
Multiple-severity rule
Note The appearance of the Edit Rule area depends on the severity levels of the newly-
copied rule as indicated in the above illustration. For more information about rule
severity levels, see “Adding severity-level variables” on page 444
Deleting rules
Use the Delete Selected button on the Manage Rules dashboard to delete a rule, as
outlined below.
418 Foglight
Administration and Configuration Guide
To delete a rule:
Note This procedure continues from “Accessing the Manage Rules dashboard” on page 408.
1 In the Manage Rules dashboard, select the row containing the rule that you want
to delete.
2 Click the Delete Selected button at the bottom.
The Delete Rule Confirmation dialog box appears.
Note This procedure continues from “Accessing the Manage Rules dashboard” on page 408.
Working with Foglight Rules and Registry 419
Working with Rules
1 In the Manage Rules dashboard, select the row containing the rule that you want
to disable.
Tip To select multiple rules, press the CTRL or SHIFT key while selecting the rows
containing the rules that you want to disable.
Note This procedure continues from “Viewing a rule summary” on page 425.
1 In the Manage Rules dashboard, select the row containing the disabled rule that
you want to enable.
Note A Rule is currently disabled icon ( ) appears in the row containing a rule that has
been disabled.
Tip To select multiple rules, press the CTRL or SHIFT key while selecting the rows
containing the rules that you want to enable.
Note Foglight stops both generating and clearing alarms for a rule during the period when its
alarms are suspended.
Note This procedure continues from “Accessing the Manage Rules dashboard” on page 408.
1 In the Manage Rules dashboard, select the row containing the rule whose alarms
you want to suspend.
2 Click the Suspend Alarms button at the bottom.
The Temporarily Suspend Rule Alarms dialog box appears.
Working with Foglight Rules and Registry 421
Working with Rules
3 Specify the time period for which you want to suspend alarms.
In the Temporarily Suspend Rule Alarms dialog box, click For and select the
time period as required, then click Go.
The Temporarily Suspend Rule Alarms dialog box closes and the Manage
Rules dashboard refreshes, showing a warning icon in the row containing the rule
with newly-suspended alarms.
Note The warning icon indicates different types of states a rule may be in. For example, it
appears when a rule is disabled, or when its alarms or actions are suspended.
Placing the mouse pointer over the icon shows more details about the rule state.
Note This procedure continues from “Accessing the Manage Rules dashboard” on page 408.
1 In the Manage Rules dashboard, select the row containing the rule whose alarms
you want to resume.
2 Click the Resume Alarms button at the bottom.
The Rule Confirmation dialog box appears.
422 Foglight
Administration and Configuration Guide
3 Click OK.
The Rule Confirmation dialog box closes and the Manage Rules dashboard
refreshes.
4 In the Manage Rules dashboard, observe the row containing the rule whose
alarms you resumed.
The absence of the warning icon indicates that the alarms for the rule are no
longer suspended.
If a warning icon appears in the row containing the rule with newly-resumed
alarms, place the mouse pointer over the icon. The tool tip that appears no longer
indicates that the rule’s alarms are suspended.
Note The warning icon indicates different types of states a rule may be in. For example, it
appears when a rule is disabled, or when its alarms or actions are suspended.
Placing the mouse pointer over the icon shows more details about the rule state.
Note This procedure continues from “Accessing the Manage Rules dashboard” on page 408.
1 In the Manage Rules dashboard, select the row containing the rule whose actions
you want to suspend.
2 Click the Suspend Actions button at the bottom.
The Temporarily Suspend Rule Actions dialog box appears.
3 Specify the time period for which you want to suspend actions.
In the Temporarily Suspend Rule Actions dialog box, click For and select the
time period as required, then click Go.
Working with Foglight Rules and Registry 423
Working with Rules
A message appears, indicating the actions will be suspended for the selected
amount of time. Click Save.
The Temporarily Suspend Rule Actions dialog box closes and the Manage
Rules dashboard refreshes, showing a warning icon in the row containing the rule
with newly-suspended actions.
Note The warning icon indicates different types of states a rule may be in. For example, it
appears when a rule is disabled, or when its alarms or actions are suspended.
Placing the mouse pointer over the icon shows more details about the rule state.
Note This procedure continues from “Accessing the Manage Rules dashboard” on page 408.
1 In the Manage Rules dashboard, select the row containing the rule whose actions
you want to resume.
2 Click the Resume Actions button at the bottom.
The Rule Confirmation dialog box appears.
3 Click OK.
424 Foglight
Administration and Configuration Guide
The Rule Confirmation dialog box closes and the Manage Rules dashboard
refreshes.
4 In the Manage Rules dashboard, observe the row containing the rule whose
actions you resumed.
The absence of the warning icon indicates that the actions for the rule are no
longer suspended. If a warning icon appears in the row containing the rule with
newly-resumed actions, place the mouse pointer over the icon. The tool tip that
appears no longer indicates that the rule’s actions are suspended.
Note The warning icon indicates different types of states a rule may be in. For example, it
appears when a rule is disabled, or when its alarms or actions are suspended.
Placing the mouse pointer over the icon shows more details about the rule state.
Note This procedure continues from “Accessing the Manage Rules dashboard” on page 408.
1 In the Manage Rules dashboard, click the Schedules icon ( ) in the row
containing the rule whose schedules you want to view.
The Edit Rule area appears in the Manage Rules dashboard with the Schedules
tab open.
Working with Foglight Rules and Registry 425
Working with Rules
• Conditional expressions, alarm messages, and actions for each severity level
Figure 3
Note This procedure continues from “Accessing the Manage Rules dashboard” on page 408.
1 In the Manage Rules dashboard, click the Rule Name column of the row
containing the rule that you want to enable or disable
The Edit Rule view appears in the display area.
Working with Foglight Rules and Registry 427
Working with Rules
Simple rule
Multiple-severity rule
Note The appearance of the Edit Rule view depends on the severity levels of the newly-
copied rule as indicated in the above illustration. For more information about rule
severity levels, see “Defining rule types” on page 435.
2 Open the Rule Summary pane by clicking the Roll Down button ( ) on the
Rule Summary bar.
The Rule Summary pane expands in the display area.
428 Foglight
Administration and Configuration Guide
Note The appearance of the Rule Summary pane depends on the rule type, its severity
levels, and other settings. In the above illustration, the rule whose settings appear in
the Rule Summary pane is active.
Note This procedure continues from “Accessing the Manage Rules dashboard” on page 408.
1 In the Manage Rules dashboard, click the Rule Name column of the row
containing the rule whose definitions you want to view.
The Edit Rule view appears in the display area.
430 Foglight
Administration and Configuration Guide
Simple rule
Multiple-severity rule
Note The appearance of the Edit Rule area depends on the severity levels of the newly-
copied rule as indicated in the above illustration. For more information about rule
severity levels, see “Defining rule types” on page 435.
2 Observe the rule settings on each tab: Rule Definition, Conditions & Actions
(simple rules only), Conditions, Alarms, & Actions (multiple-severity rules
only), Schedules, Behavior, and Rule Variables.
3 Edit the rule definitions, as required.
On the Manage Rules dashboard, open the Rule Definition tab.
Working with Foglight Rules and Registry 431
Working with Rules
The Rule Definition tab shows the basic rule settings, such as the rule name, rule
description, alarm description, cartridge name and version (if applicable), rule
type (simple or multiple-severity), rule triggering, and the rule scope.
Tip If a rule comes with the Foglight Management Server or any installed cartridge, the
Cartridge Name (Cartridge Version) value indicates the cartridge name and its
version. Otherwise, if a rule is created using the Create Rule dashboard, this value is
blank.
• To edit the rule name, rule description, or alarm description, on the Rule
Definition tab, type the desired values into the Rule Name, Description/
Comments, or Alarm Description/Help boxes, as required. For more
information, see “Getting started with rule definitions” on page 434.
432 Foglight
Administration and Configuration Guide
• To edit the rule triggers, on the Rule Definition tab, use the Rule Triggering
area. For more information, see “Triggering rules” on page 438.
• To edit the rule scope, on the Rule Definition tab, use the Rule Scope area.
For more information, see “Defining the rule scope” on page 441.
• To make any additional changes to the rule settings, such as to edit the rule
conditions, alarms (multiple-severity rules only), and actions, rule schedules,
rule behavior, or rule variables, use the Conditions & Actions (simple rules
only), Conditions, Alarms, & Actions (multiple-severity rules only),
Schedules, Behavior, or Rule Variables tabs, as required. For complete
information, see the following sections:
“Defining Conditions, Alarms, and Actions” on page 442
“Associating Rules with Schedules” on page 500
“Defining Alarm and Action Behavior” on page 503
“Defining Rule-Level Variables” on page 505
Creating Rules
Creating rules allows you to customize how Foglight notifies you of the status of your
monitored system and to specify what actions should be performed when the status
changes.
Foglight allows you to create rules using the Create Rule dashboard. You can access this
dashboard from the navigation panel, or through the Manage Rules dashboard.
To create a rule:
In the Manage Registry Variables dashboard that appears in the display area,
click the Add Rule button in the lower-left corner.
or
• On the navigation panel, under Dashboards, choose Administration > Rules
& Notifications > Create Rule.
The rule definitions appears in the display area with the Rule Definition tab
open.
Defining Rules
Rule definitions can consist of any if the following components:
• Registry Variables. A registry variable can be used in rule conditions,
expressions, and actions. Registry variables are stored in the Foglight registry. A
registry variable can have a global value that is available to all topology types and
objects. It can also have multiple additional values associated with specific
434 Foglight
Administration and Configuration Guide
Note This procedure continues from “Copying rules” on page 415, “Viewing and editing rule
settings” on page 429, or “Creating Rules” on page 432.
If its condition is met, the state of the rule is set to Fire and any actions that are
associated with this state are performed. If the condition is not met, the rule
remains in the Normal state. If the rule’s condition cannot be evaluated because
data is missing or unavailable, the state of the rule is set to Undefined and any
actions that are associated with this state are performed.
The condition for a simple rule is regularly evaluated against monitoring data.
Therefore, the state of the rule can change if the data changes. For example, if a
set of monitoring data matches a simple rule’s condition, the rule enters the Fire
state. If the next set does not match the condition, the rule exits the Fire state and
enters the Normal state. You can configure a simple rule to perform one or more
actions upon entering and/or exiting each state.
• Multiple-Severity rules. A multiple-severity rule is a more complex type of rule
that can have up to five severity levels:
• Undefined
• Fatal
• Critical
• Warning
• Normal
When you create a multiple-severity rule, you must specify a condition for at least
one severity level (Fatal, Critical, or Warning).
As with simple rules, the conditions for a multiple-severity rule are regularly
evaluated against monitoring data. All conditions in a rule are evaluated; the
severity state is set to the highest level for which the condition evaluates to true. If
none of the conditions are met, the severity state is set to Normal. If a condition
cannot be evaluated because data is missing or unavailable, the state is set to
Undefined.
An alarm is generated each time a multiple-severity rule enters a new state. In
addition, you can configure a multiple-severity rule to perform one or more
actions upon entering and/or exiting each state.
Generated alarms can be viewed in Foglight dashboards that exist outside of the
Administration module, such as the Alarms or Agents dashboards. In addition to
viewing alarm details, these dashboards allow you to drill down to alarm details,
and to clear and acknowledge alarms.
Working with Foglight Rules and Registry 437
Working with Rules
The alarm list can show multiple alarms that are generated by the same rule. This
is because rule conditions are evaluated repeatedly, after each data sampling
interval. If rule conditions are met in subsequent sampling intervals, Foglight
generates an alarm instance for each positive condition evaluation. These alarms
can be of the same or different severity, depending on the value of the collected
data. For example, a rule can produce multiple Warning alarms, or alarms whose
severity ranges from Warning through Critical to Fatal.
Each alarm can be acknowledged or cleared. Acknowledging an alarm indicates
that the Foglight operator is aware of the alarm. You can acknowledge a single
alarm instance (the Acknowledge button in the alarm drill-down dialog box), or
all consecutive alarms generated by the same rule (the Acknowledge Until
Normal button in the alarm drill-down dialog box).
Clearing an alarm indicates that the alarm is examined by the Foglight operator
and that it is safe to remove it from the list. Along with cleared alarms, any
acknowledged alarms can be removed from the list if required using the alarm
filter.
438 Foglight
Administration and Configuration Guide
For complete information about working with alarms, see the Foglight User
Guide.
To define the rule type:
Note This procedure continues from “Getting started with rule definitions” on page 434.
Triggering rules
The type of the trigger that you select determines when the rule’s conditions are
evaluated against the data that is collected from your monitored environment. You
configure a rule to have one of the following triggers:
Working with Foglight Rules and Registry 439
Working with Rules
Tip Unlike simple rules, that fire without raising any alarms, multiple-severity rules can generate
alarms when their conditions are met. These alarms appear in a number of different
dashboards that exist in Foglight outside of the Administration module. You can also create
your own dashboards that display alarms. In order for alarms to work correctly in dashboards,
they must be generated by multiple-severity, data-driven rules. Alarms generated by multiple-
severity, time- or event- driven rules do not have the same functionality in dashboards as
multiple-severity, data-driven rules. For complete information about the dashboards that exist
outside of the Administration module, see the Foglight User Guide; for details on how to add
custom dashboards to Foglight, see the Web Component Tutorial.
Note This procedure continues from “Defining rule types” on page 435.
1 In the Rule Definition tab, under Rule Triggering, select the Time Driven
option.
440 Foglight
Administration and Configuration Guide
The Rule Definition tab refreshes, showing a set of Recurrence Interval boxes
on the right.
2 Specify the recurrence interval for the trigger in the hh:mm:ss format.
3 To make time driven rules evaluate on each time interval, regardless of the
existence of data, select the Trigger Without Data check box.
Note For details on how to write conditions for time-driven rules, see “Defining conditions
for data-driven and time-driven rules” on page 451.
Note This procedure continues from “Defining rule types” on page 435.
• In the Rule Definition tab, under Rule Triggering, ensure that the Data Driven
option is selected.
Note For details on how to write conditions for data-driven rules, see “Defining conditions
for data-driven and time-driven rules” on page 451.
Note This procedure continues from “Defining rule types” on page 435.
1 In the Rule Definition tab, under Rule Triggering, select the Event Driven
option.
The Rule Definition tab refreshes, showing the Event Name box on the right.
2 Specify the event that you want to use as the rule trigger.
Working with Foglight Rules and Registry 441
Working with Rules
From here, you can proceed to “Defining the rule scope” on page 441.
Caution You may need to reconfigure the rule’s condition(s) if you change its scope: the metrics,
registry variables, and topology object properties specified in the existing condition(s)
may not be available for the new topology type or object(s).
• In the Rule Definition tab, use the Rule Scope area to scope the rule to one or
more topology objects.
For detail instructions, see “Setting the Scope for a Rule or Derived Metric” on
page 784.
From here, you can proceed to “Defining Conditions, Alarms, and Actions” on
page 442.
442 Foglight
Administration and Configuration Guide
Figure 4
Simple rule
Multiple-severity rule
If you plan to make use of this feature, you need to add those variables before writing
conditional expressions.
For instructions, see the following sections:
• “Adding severity-level variables” on page 444
• “Writing conditions” on page 449
• “Copying conditions in multiple-severity rules” on page 464
• “Defining actions” on page 466
444 Foglight
Administration and Configuration Guide
Severity-Level Variables
In the above example, the Text and Subject variables make use of the expression-type
variables, var1, var2, and var3. Furthermore, the Text and Subject variables can be
used in an alarm message in an email action that sends that information to a specified
recipient when the rule generates an alarm.
If you are defining a simple severity rule, you can add one set of severity-level
variables. Multiple-severity rules allow you to add one set of variables to each severity
level that you want to define.
Additionally, you can create rule-level variables and reference them in expressions
defined in different severity levels within the same rule. For more information, see
“Defining Rule-Level Variables” on page 505. For details on Foglight registry variables,
see “Working with Foglight Registry Variables” on page 364.
To add a severity-level variable:
Note This procedure continues from “Defining the rule scope” on page 441.
If you are defining a multiple-severity rule, the Conditions, Alarms & Actions
tab opens.
446 Foglight
Administration and Configuration Guide
Note For more information about rule severity levels, see “Adding severity-level variables”
on page 444.
2 Choose the severity level (multiple rules) or the state (simple rules) for which you
want to define the severity-level variables.
If you are defining a simple rule, click Fire.
If you are defining a multiple-severity rule, click one of the following bars:
• Fatal
• Critical
• Warning
A pane containing the severity-level condition definitions expands under the
severity bar with the Condition tab open.
Working with Foglight Rules and Registry 447
Working with Rules
Simple rule
Multiple-severity rule
4 Define the type of the severity variable by selecting one of the following Type
options on the right:
• Expression
• Message
5 Name the severity-level variable.
In the Name box, type the name of the variable.
Important. The following names are reserved and should not be used:
• foglight_severity_level
• foglight_severity_level_name
6 Specify the variable value.
Expressions can contain registry variable or functions while messages are text
strings that can make use of the existing severity-level variables.
For example:
Severity-Level Variables
To delete a severity-level variable from the list, select the row containing that
variable in the Severity Level Variables pane, and click Delete Selected.
From here, you can proceed to “Writing conditions” on page 449.
Writing conditions
A condition is the part of a rule that is evaluated against monitoring data. When it
evaluates to True, the rule is said to fire, causing any actions that are associated with the
rule or severity level to be performed.
When you create a simple rule, you specify a single condition for it. You can edit this
condition after you create the rule. When you create a multiple-severity rule, you must
specify a condition for one or more of its severity levels, Fatal, Critical, and Warning,
along with an alarm message that is associated with each condition.
• Conditional Expression. A conditional expression can be either true or false.
They can reference registry variables, Groovy functions, and metrics associated
with the one or more topology types or their topology objects to which the rule
applies.
Additionally, conditional expressions can reference properties of topology objects
that are related (within the hierarchy of the topology model) to one or more
topology objects to which the rule is scoped. For example, the condition for a
simple rule that is associated with a specific JVM can reference properties of the
server on which the JVM is running (such as the server name), or properties of the
cluster to which the server belongs.
450 Foglight
Administration and Configuration Guide
Furthermore, event-driven rules can retrieve data generated by report- and alarm-
related events.
Expressions can be simple—for example, an expression can consist only of a
metric name—but they can also be defined using very complex syntax. See
“Examples” on page 791 for examples of expressions.
Conditional expressions make use of the query language. See “Using the Query
Language in Rule Conditions or Derived Metric Expressions” on page 790 for
detailed information about the query language in Foglight.
• Alarm Message. Foglight generates an alarm message when the conditional
expression associated with a multiple-severity rule evaluates to True. An alarm
message is typically a text string that can include other severity-level variables,
displaying dynamically-supplied data about your monitored system.
Important Simple rules do not generate alarms. They fire when the condition for their Fire
state is met. On the other hand, multiple-severity rules generate alarms each time they
enter a severity state.
Expression scope
Expressions and messages can be set with one of two distinct scopes:
• Rule-scoped expressions and messages. They can be referenced by the actions set
for the Fire and Undefined states of a simple rule and for all severity levels
(Fatal, Critical, Warning, Normal, and Undefined) in a multiple-severity rule.
Note It is a best practice that rule-scoped expressions are used until there is a need for
more finely scoped expressions.
Note In addition to rule-level expressions and severity-level expressions, Foglight also includes
pre-defined system expressions. For example, there is a pre-defined expression that refers
to each severity level. System expressions are listed in the Foglight Administration Module.
Note This procedure continues from “Adding severity-level variables” on page 444.
1 In the Conditions and Actions tab (simple rules) or Conditions, Alarms &
Actions tab (multiple-severity rules), open the Conditions tab.
The Condition tab opens in the display area.
452 Foglight
Administration and Configuration Guide
Simple rule
Multiple-severity rule
Important The appearance of the Condition tab depends on the rule type. In addition to the
condition editor, multiple-severity rules also include an alarm editor that allows you to
compose an alarm message associated with each severity state (Warning, Critical,
and/or Fatal).
Unlike simple rules, that can have only one condition associated with their Fire state,
multiple-severity rules can have a conditional expression associated with each severity
(Warning, Critical, and/or Fatal) along with an alarm message associated with that
conditional expression.
This is because simple rules do not generate alarms. They fire when the condition for
their Fire state is met. On the other hand, multiple-severity rules generate alarms each
time they enter a severity state.
For complete information about the differences between simple rules and multiple-
severity rules, see “Defining rule types” on page 435.
In the Condition tab, use the Condition area to write the conditional expression.
You can type the condition directly into the Condition box, or use the operator
controls and the Condition Editor to add logical operators, registry variables,
metrics, or Groovy functions. For complete information about inserting operators
or using the Condition editor, see “Specifying Rule Conditions or Derived Metric
Expressions” on page 792.
Caution If you change the metrics, registry variables, or topology object properties that are
referenced in the condition, ensure that the new items are available for the
topology type or object(s) to which the rule is scoped.
Important To separate multiple lines in conditional expressions, use a semicolon followed
by a carriage return. In conditional expressions consisting of a single line, using a
semicolon to end the line is optional. For example:
Multi-line expressions
Example A
Correct
println @event.dump();
@event.get("report/name") == "MyReport";
Incorrect
println @event.dump()
@event.get("report/name") == "MyReport";
Note The first line is missing a semicolon which causes the expression
to result in an error.
Single-line expressions
Example B
Correct
println @event.dump();
Example C
Correct
454 Foglight
Administration and Configuration Guide
println @event.dump()
4 Multiple-severity rules. Define the alarm message associated with the newly-
defined condition.
In the Alarm box, type the alarm message.
5 Multiple-severity rules (Optional). To reference a rule-level variable or a
system variable in the alarm message, in the Alarm Message box, click the
location to which you want to add the variable, and then click the Alarm Message
Editor button ( ) above the Alarm Message box.
The Alarm Message Editor dialog box appears.
Working with Foglight Rules and Registry 455
Working with Rules
• To add a rule-level variable, in the Alarm Message Editor dialog box, on the
Rule Variables tab, select the rule-level variable and click Insert.
• To add a system variable, on the System Variables tab, select the system
variable and click Insert.
The newly-added variable appears in the Alarm Message box.
When you finish adding variables to the alarm message, close the Alarm
Message box by clicking Close.
6 Save the newly-defined rule condition by clicking the Save button above the
Condition tab.
From here, you can proceed to “Defining actions” on page 466.
events and use the following properties in rule conditions in order to trigger
event-driven rules:
• ReportGeneratedEvent
458 Foglight
Administration and Configuration Guide
Report generation creates system events. You can monitor these events and their
properties in order to trigger event-driven rules:
Note This procedure continues from “Adding severity-level variables” on page 444.
1 On the Conditions and Actions tab (simple rules) or Conditions, Alarms &
Actions tab (multiple-severity rules), open the Conditions tab.
The Condition tab opens in the display area.
460 Foglight
Administration and Configuration Guide
Simple rule
Multiple-severity rule
Important The appearance of the Condition tab depends on the rule type. In addition to the
condition editor, multiple-severity rules also include an alarm editor that allows you to
compose an alarm message associated with each severity state (Warning, Critical,
and/or Fatal).
Unlike simple rules, that can have only one condition associated with their Fire state,
multiple-severity rules can have a conditional expression associated with each severity
(Warning, Critical, and/or Fatal) along with an alarm message associated with that
conditional expression.
This is because simple rules do not generate alarms. They fire when the condition for
their Fire state is met. On the other hand, multiple-severity rules generate alarms each
time they enter a severity state.
For complete information about the differences between simple rules and multiple-
severity rules, see “Defining rule types” on page 435.
In the Condition tab, use the Condition area to write the conditional expression.
using the following syntax:
some_value.equals(@event.get("[report/]property");
Where
• report indicates that you want to use the ReportGeneratedEvent in the
conditional expression.
• property is the name of the event property that you want to use in the
comparison. For a complete list of event properties and the information they
contain, see “AlarmSystemEvent” on page 455 or “ReportGeneratedEvent” on
page 457.
• some_value contains the value that is to be compared with the specified
property value.
Caution The data type of the value you specify here must match the data type of the
property with which you compare this value.
For example, to write a condition that triggers an event-driven rule to fire when
Foglight generates a report whose name is System Resources, write the
following expression:
@event.get("report/name") == "System Resources";
Report attachments are not stored in ReportGeneratedEvent object properties. To
retrieve a report attachment in a rule condition, use the following syntax:
byte[] a_pdf_object =
server.get("ReportingService").getReportData(@event.get
("report/reportId"));
Where a_pdf_object is the name of the report file that you want to retrieve.
Important To separate multiple lines in conditional expressions, use a semicolon followed
by a carriage return. In conditional expressions consisting of a single line, using a
semicolon to end the line is optional. For example:
Multi-line expressions
Example A
Correct
462 Foglight
Administration and Configuration Guide
println @event.dump();
@event.get("report/name") == "MyReport";
Incorrect
println @event.dump()
@event.get("report/name”) == "MyReport";
Note The first line is missing a semicolon which causes the expression
to result in an error.
Single-line expressions
Example B
Correct
println @event.dump();
Example C
Correct
println @event.dump()
4 Multiple-severity rules. Define the alarm message associated with the newly-
defined condition.
In the Alarm box, type the alarm message.
Working with Foglight Rules and Registry 463
Working with Rules
• To add a rule-level variable, in the Alarm Message Editor dialog box, on the
Rule Variables tab, select the rule-level variable and click Insert.
The Rule Variables tab lists all of the rule-level variables, including
expressions and messages.
• To add a system variable, on the System Variables tab, select the system
variable and click Insert.
The newly-added variable appears in the Alarm Message box.
When you finish adding variables to the alarm message, close the Alarm
Message box by clicking Close.
6 Save the newly-defined rule condition by clicking the Save button above the
Condition tab.
From here, you can proceed to “Defining actions” on page 466.
464 Foglight
Administration and Configuration Guide
Note This procedure continues from “Adding severity-level variables” on page 444.
1 On the Conditions, Alarms & Actions tab, open the Conditions tab.
The Condition tab opens in the display area.
2 Choose the severity level from which you want to copy the conditional
expression.
Caution You can only copy the conditions from those severity levels that are already
defined. Attempting to copy a condition for a rule that has no conditions defined
results in an error.
Working with Foglight Rules and Registry 465
Working with Rules
Caution Attempting to copy a condition for a rule that has no conditions defined results
in error.
3 Optional. Edit the conditional expression and the alarm message, if required. For
instructions, see one of the following sections:
• “Defining conditions for data-driven and time-driven rules” on page 451
• “Defining conditions for event-driven rules” on page 455
4 Save your changes to the rule condition by clicking the Save button above the
Condition tab.
From here, you can proceed to “Defining actions” on page 466.
466 Foglight
Administration and Configuration Guide
Defining actions
An action is a particular operation that is performed when a rule enters or exits a state
(for example, when a rule condition is met).
Multiple actions can be associated with simple rules as well as with each severity level
in a multiple-severity rule. Actions can be added to a rule after it is created.
For examples on how to add actions to a rule severity level, see “Example: Configuring
Rule Action Parameters” on page 547 and “Example: Associating Command Actions
with Rules” on page 556.
Foglight actions
The actions available in Foglight are as follows:
• BSM Actions. They send alarm data to Foglight Service Discovery Dashboards.
• SNMP Trap Actions. They cause alarms to be forwarded as SNMP traps to a
management system that supports SNMP (such as Tivoli® NetView®, Micromuse
NetCool® or HP® Vantage Point) when the rule fires. Various parameters can be
set for sending the SNMP trap, including the community, the host and port for the
monitoring service. For more information about viewing the settings related to
SNMP trap actions and their configuration in Foglight, see “Configuring SNMP
trap actions” on page 477.
Caution SNMP trap actions do not work with data-driven rules. For more information
about different rule triggers, see “Triggering rules” on page 438.
Working with Foglight Rules and Registry 467
Working with Rules
Tip In some situations you may need to filter the reports before sending them to email recipients.
You can do that by editing the Fire condition of the rule Email Reports Sample as required.
For instructions on how to write rule conditions, see “Writing conditions” on page 449.
Tip When you create a scheduled report, the default name of the PDF file containing the
scheduled report is report.pdf. If required, you can configure Foglight to use the report title as
468 Foglight
Administration and Configuration Guide
the PDF file name. To do that, edit the Email Reports Sample rule by adding a severity-level
variable containing the following expression:
return @event.get("report/reportName"), and setting the email action’s
mail.attachement.file.name parameter to point to that variable.
For information on how to add severity-level variable to a rule, see “Adding severity-level
variables” on page 444. For details on configuring the rule action parameter, see “Editing
action parameters” on page 495.
Additionally, you may need to edit the default mail settings that control mail connection
and mail sockets by creating two new registry variables, mail.connection.timeout
and mail.socket.timeout, and assigning them the appropriate value in seconds. The
default values are 20 seconds for the connection and 10 seconds for the socket time-out.
Global mail settings can be viewed in the following dashboards of the Foglight browser
interface:
• Foglight Configuration dashboard, Mail (Global Settings) view.
For more information about this view, see Chapter 3, “Mail (Global Settings)” on
page 104.
• Email Configuration dashboard.
Tip This dashboard allows you to both view and edit mail settings.
For more information about this dashboard, see Chapter 3, “Configuring Email
Actions” on page 119.
To view mail settings in Foglight:
• View mail settings in the Foglight Configuration dashboard.
a On the navigation panel, under Dashboards, choose Administration > Setup
& Support > Foglight Configuration.
The Foglight Configuration dashboard appears in the display area, showing
the Foglight configuration items.
Working with Foglight Rules and Registry 469
Working with Rules
For more information about this dashboard, see Chapter 3, “Viewing Foglight
Configuration” on page 98.
b On the Foglight Configuration dashboard, scroll down until you locate the
Mail (Global Settings) view.
470 Foglight
Administration and Configuration Guide
The Mail (Global Settings) view contains email settings that are used by
Foglight when sending messages to specified recipients. These settings
include the connection time-out, default email sender, host name, port
number, recipient’s email address, the socket time-out, and email sender login
name. For complete information about the settings in the Mail (Global
Settings) view, see Chapter 3, “Mail (Global Settings)” on page 104.
These settings need to be configured after the installation. For details, proceed
to To configure email actions in Foglight:.
or
• View mail settings in the Email Configuration dashboard.
On the navigation panel, under Dashboards, choose Administration > Setup &
Support > Email Configuration.
The Email Configuration dashboard appears in the display area, showing the
current email settings.
Working with Foglight Rules and Registry 471
Working with Rules
The dashboard contains two views, Email Server and Email Alias Group, each
containing a group of configuration parameters. Each parameter contains a
registry value that Foglight uses to carry out email actions.
For more information about this dashboard, see Chapter 3, “Configuring Email
Actions” on page 119.
To configure email actions in Foglight:
Note This procedure continues from “Accessing the Manage Registry Variables dashboard” on
page 365.
Important The procedure below provides information on how to configure Foglight email actions by
editing the values of the appropriate registry variables. Alternatively, these settings can
be configured using the Email Configuration dashboard. For complete information about
editing email configuration parameters using the Email Configuration dashboard, see
Chapter 3, “Configuring Email Actions” on page 119.
In the Edit Registry Variable view, in the Global Default area, type the
global default value that you want to assign to the variable.
For example, to configure the mail.host variable, type the name of the default
email host that you want the Foglight Management Server to use for sending
emails.
b On the right of the Global Default area, click Save.
A message appears in the upper-left corner, indicating success.
The Manage Registry Variables dashboard refreshes, and the row containing
the newly-edited variable appears selected in the list.
For complete information on how to edit a registry variable, see “Editing Registry
Variables” on page 381.
3 Optional. Configure the mail connection and mail socket time-outs.
The default values are 20 seconds for the connection and 10 seconds for the
socket time-out. To use different values, create the following registry variable
values and assign them the appropriate integer value in seconds:
mail.socket.timeout and mail.connection.timeout.
To create a Foglight registry variable, complete the following steps:
a On the navigation panel, under Dashboards, choose Administration > Rules
& Notifications > Create Registry Variable.
The Create Registry Variable dashboard appears in the display area, showing the
Step 1: Create Registry Variable view.
Working with Foglight Rules and Registry 475
Working with Rules
b Specify the name and data type for the variable using the following boxes:
Registry Variable Name: The name of the variable:
mail.connection.timeout when specifying the connection time-out or
mail.socket.timeout for the socket time-out.
Registry Value Type: Click the box and select Integer from the list that
appears.
c Click Add.
The Create Registry Variable dashboard refreshes, showing the Step 2:
Registry Variable Added view.
476 Foglight
Administration and Configuration Guide
For complete information on how to edit a registry variable, see “Editing Registry
Variables” on page 381.
Important In some situations you need to create or receive email alerts that contain a URL to the
browser interface. To ensure the URL points to the computer on which the Foglight
Management Server is running, ensure that the CATALYST_URL registry variable
contains the correct computer name and port number.
Caution SNMP trap actions do not work with data-driven rules. For more information about
different rule triggers, see “Triggering rules” on page 438.
478 Foglight
Administration and Configuration Guide
Figure 5
Tip The Cartridge Inventory dashboard, shown above, lists the cartridges that exist in your
Foglight environment. For more information about this dashboard, see Chapter 5, “Installing
and Managing Cartridges” on page 251.
You can download the quest-foglight.mib file using the Components for
Download dashboard.
480 Foglight
Administration and Configuration Guide
Tip The Components for Download dashboard, shown above, lists any components that are
delivered with any of the installed cartridges. For more information about this dashboard, see
Chapter 5, “Downloading Agent Components” on page 265.
This type of configuration involves editing the SNMP Forward rule’s SNMP
community string and the IP address of the trap receiver, as described in “To configure
SNMP trap actions using the SNMP Forward rule:” on page 481. When configured, the
SNMP Forward rule sends traps that are formatted according to the settings specified in
the SNMP trap action MIB file, quest-foglight.mib. The rule contains an entering
SNMP trap action with a set of pre-defined parameters that are compatible with the MIB
file.
In addition to editing the SNMP community string and trap receiver IP address, it is
possible to define advanced SNMP settings, such as the Enterprise Object ID (OID) or
variable bindings using this rule. You can either edit, or copy and edit the SNMP
Forward rule to meet your needs. Another option is to define SNMP traps in new or
existing rules by adding an entering or exiting SNMP trap action to a rule, and edit the
action’s parameters, including the community string and trap receiver IP address, along
with any other applicable parameters such as the Enterprise OID or trap variables. This
process typically requires advanced knowledge of the SNMP protocol and is beyond the
scope of this guide. For more details, consult your SNMP documentation. For
information on how to add actions to rules, see “Defining actions” on page 466. To find
out more about the available SNMP trap action parameters, see “About action
parameters” on page 488.
Working with Foglight Rules and Registry 481
Working with Rules
Note This procedure continues from “Accessing the Manage Rules dashboard” on page 408.
Tip The Manage Rules dashboard, shown above, lists the rules that exist in your Foglight
environment. For more information about this dashboard, see “Managing Rules” on
page 408. For details about the SNMP Forward rule, see “SNMP Forward rule” on
page 518.
The SNMP Forward rule is a simple rule, which means that it only contains one
state—Fire. The settings for the rule’s Fire state appear by clicking the Fire bar in
the Conditions and Actions tab. For more information about simple rules, and
the differences between simple and multiple-severity rules, see “Defining
Conditions, Alarms, and Actions” on page 442.
3 View the settings of the SNMP Forward rule’s Fire state.
On the Conditions and Actions tab, click the Fire bar.
The Fire pane expands under the Fire bar with the Condition tab open.
The Action tab opens, showing an entering SNMP trap action in the Actions
table.
The Action Parameter Editor dialog box closes and the Action Parameters
table refreshes, showing the newly-edited parameter after you edit a parameter
value.
When you finished configuring both parameters to desired values,
CommunityString and TargetAddress, those values can be viewed in the
Action Parameters table.
You have successfully configured the SNMP trap actions using the core SNMP
Forward rule and enabled the forwarding of SNMP traps to your trap receiver.
Note This procedure continues from “Defining conditions for data-driven and time-driven rules”
on page 451.
1 In the Conditions and Actions tab (simple rules) or Conditions, Alarms &
Actions tab (multiple-severity rules), open the Action tab.
The Action tab appears in the display area.
2 Define the action type by selecting one of the following Action Type options on
the right:
• Entering
• Exiting
See “Foglight action types” on page 466 for more information.
3 Specify the action.
Click Action and select an action from the list that appears.
See “Foglight actions” on page 466 for more information.
4 Optional. Add information about the selected action.
In the Description box, type the action description.
5 Click Add.
The Action tab shows a list of parameters associated with the newly-selected
action.
488 Foglight
Administration and Configuration Guide
From here, you can edit the action parameters as required. For details, see “About action
parameters” on page 488.
Note To successfully configure an action, you must ensure that all of the actions’s mandatory
parameters are specified.
BSM Actions
Command Actions
Working with Foglight Rules and Registry 489
Working with Rules
Email Actions
Note When the condition of a simple rule is met, the rule enters the Fire state. By default,
simple rules do not generate alarms when their conditions are met. Some simple rules
that ship with Foglight, such as the Services or LogFilter rules that are included with the
OS Cartridge, create observation alarms that are not directly associated with the original
rule. This is accomplished by calling the checkObservationAlarms() function in the rule
condition. When the condition of a simple rule includes a call to the
checkObservationAlarms() function, and the rule includes an email action, in the
message body of the resulting email, the following text always precedes the value
specified by the mail.message parameter:
For more information about the checkObservationAlarms() function, see Chapter 11,
“Using Functions with Conditions and Expressions” on page 801. For complete details
about the Services or LogFilter rules, refer to the OS Cartridge documentation.
Script Actions
The following rules apply to the command syntax for Command and Remote Command
actions:
• The executable command must point to a path which can be understood and
executed by the native operating system (such as a a Windows batch file or a
binary executable file). For example:
Correct
Working with Foglight Rules and Registry 493
Working with Rules
Windows
C:\hello.bat
perl C:\hello.pl
\\my_domain\my_server\my_group\my_user_account\hello.bat
Incorrect
Unix
ssh -l user1 "ls"
Windows
P:\hello.bat (where P: is a mapped drive)
Only those commands that point to a specific batch file on a physical drive
produce a command output in the Command Prompt window (Windows) or the
terminal window (Unix). That is because command actions invoked by a script do
not read back from the stream nor print the command output to the console,
waiting for the command to finish. In the above examples, only C:\hello.bat
generates a command-line output.
Invoking command actions through ssh on Unix systems is supported. However,
keep in mind that most Unix servers prompt for a password when ssh is used,
which interrupts the command execution. Therefore, using ssh in command
actions is not recommended.
• The executable command should be separated from the arguments by one or more
space characters, and the arguments should similarly be separated by one or more
space characters.
• If the executable or an argument contains one or more space characters, it should
be quoted with double quotation marks (“). Command actions do not recognize
single quotation marks. Do not use a back slash (\) as an escape character for
single or double quotation marks as it has no effects in command actions. For
example:
Correct
arg1 arg2 arg3
"arg one" arg2
Incorrect
'arg three here'
"arg \"one"
• If the command or an argument is quoted and has to contain one or more double
quotes, the embedded double quotation mark must be escaped by using two
494 Foglight
Administration and Configuration Guide
adjacent quotes (““) or using a back slash and quote (\”), whichever is suitable to
the underlying OS.
• Triple quotes (“““) are recognized as one quotation mark. This is useful in dealing
with Windows batch files.
• Triple quotes are not allowed in a quoting context.
For more information on rule trigger types, see “Triggering rules” on page 438.
Note Foglight prevents you from creating a rule variable with the same name as a system
variable. However, the variable name can change if you change the trigger type. In this
instance, a warning icon will appear in the Rule Variables and Severity Level Variables
listings.
Note This procedure continues from “Adding actions to rules” on page 486.
496 Foglight
Administration and Configuration Guide
1 In the Action tab, in the Actions pane, click the Action Name column of the row
containing the action whose parameter you want to edit.
The action definitions appear in the display area.
Note The above screen capture shows a list of parameters for a command action. Each
action has a different set of parameters associated with it. For more information, see
the table listing preceding this procedure.
2 Observe the Type column of the row containing the parameter that you want to
edit.
Caution The Type column shows the parameter’s data type. When changing the
parameter value, ensure that the value you specify matches that data type.
Each action comes with its own set of action parameters. For more information,
see “About action parameters” on page 488.
3 In the Action Parameters pane, in the row containing the parameter that you
want to edit, click the Default link of that appears in the row’s Value column.
The Action Parameter Editor dialog box appears.
Working with Foglight Rules and Registry 497
Working with Rules
4 Specify the parameter value by completing one of the following steps in the
Action Parameter Editor dialog box.
Caution When specifying the parameter value, ensure that the value you specify matches
the parameter’s data type. For more information, see step 2.
In the Variable tab, in the Rule/System Variables table, select the row
containing the rule system variable to which you want to set the parameter.
The list of available variables depends on the rule trigger type.
For complete information about rule system variables, see “About rule system
variables” on page 494. For details on rule triggers, see “Triggering rules” on
page 438.
• Set the parameter to a custom value.
Open the User Defined tab and type a value for the action parameter.
5 Click Change.
The Action Parameter Editor dialog box closes and the Action Parameters
table refreshes, showing the newly-modified parameter value in the Value
column of the parameter’s row.
6 When you finish making changes to the action parameters, click Go to Action
List to return to the list of actions.
The Actions pane refreshes, showing the newly-edited action.
To delete an action from the list, select the row containing that action in the
Actions pane, and click Delete Selected.
From here, you can proceed to “Associating Rules with Schedules” on page 500.
variables, see “Adding severity-level variables” on page 444 and “Defining actions” on
page 466.
While you are in the edit rule mode, any unsaved changes to the severity-level variables
or actions that you want to copy will be carried over to the destination severity. For
example, if you edit an action for the Warning condition of a rule without saving it, and
then proceed to copy that action in the Critical pane, the unsaved edits of the Warning
action will be carried over to the Critical severity.
Copying severity-level actions and variables can be useful in situations when those
definitions are identical or, in some cases, are similar. Instead of writing and validating
them for each severity level you can copy existing ones and modify them as required.
To copy variables and actions from an existing severity level:
Note This procedure continues from “Defining the rule scope” on page 441.
1 On the Conditions, Alarms & Actions tab, open the Conditions tab.
The Condition tab opens in the display area.
2 Choose the severity level from which you want to copy the conditional
expression.
Caution You can only copy the conditions from those severity levels that are already
defined. Attempting to copy a condition for a rule that has no conditions defined
results in error.
severity, and the conditions for the Fatal and Warning levels have already been
defined, the list shows two options: Fatal and Warning, as illustrated below.
Caution Attempting to copy a condition for a rule that has no conditions defined results
in error.
rule, then it is automatically active at all times other than those specified by the blackout
schedules.
If you add both effective and blackout schedules to a rule, then it will be active only at
the times specified by the effective schedules minus the times specified by the blackout
schedules. This is because blackout schedules take precedence over effective schedules.
For example, suppose you add two schedules to a rule: an effective schedule that runs
Monday to Friday, 9 am to 5 pm, and a blackout schedule that runs every Tuesday from
10am to 11am. The rule will be active every Monday, Wednesday, Thursday and Friday
from 9 am to 5 pm but will only be active from 9am to 10am and from 11am to 5pm on
Tuesdays.
To associate a rule with schedules:
Note This procedure continues from “Defining conditions for data-driven and time-driven rules”
on page 451.
The Effective Schedules list on the right refreshes, showing the newly-added
schedules.
Note Adding the Always entry to the list of blackout schedules does not create a black
out for the rule. It has no effect on the rule’s blackout schedule.
The same set of schedules are listed as Available Schedules for use as effective
schedules and blackout schedules. Do not add the same schedule as both an
effective schedule and a blackout schedule. If you do so, the schedule will
only count as a blackout schedule (because blackout schedules take
precedence over effective schedules).
Working with Foglight Rules and Registry 503
Working with Rules
From here, you can proceed to “Defining Alarm and Action Behavior” on page 503.
Note This procedure continues from “Associating Rules with Schedules” on page 500.
Simple rule
Multiple-severity rule
2 Configure the desired options for the behavior of rule alarms and actions by
selecting any of the following check boxes:
• Fire action if x consecutive evaluations are true
504 Foglight
Administration and Configuration Guide
A B
1:00 Yes No No
A
1:15 Yes No No
1:20 Yes No No
1:50 Yes No No
B
2:00 Yes Yes Yes
In the above example, even though the first behavior condition is met at 1:00, the
second behavior condition dictates that the rule waits an hour from the first time it
is evaluated before it fires. The rule fires at 2:00, only after both behavior
conditions are met.
Severity-Level Variables
For more information about Foglight registry variables, see “Working with Foglight
Registry Variables” on page 364. For details on severity-level variables, see “Adding
severity-level variables” on page 444.
To define a rule-level variable:
Note This procedure continues from “Defining Alarm and Action Behavior” on page 503.
2 Define the type of the rule-level variable by selecting one of the following Type
options on the right:
• Expression
• Message
3 Name the severity-level variable.
In the Name box, type the name of the variable.
Important. The following names are reserved and should not be used:
• foglight_severity_level
• foglight_severity_level_name
Note You cannot give the same name to more than one expression or message in the
same scope. If you give the same name to two expressions or messages in different
scopes, only the severity-scoped one will appear in the Rule Variables table.
Severity-Level Variables
To delete a rule-level variable from the list, select the row containing that variable
in the Rule Variables pane, and click Delete Selected.
A rule condition is a type of expression that can be true or false. When it evaluates to
true, the rule is said to fire, causing any actions that are associated with the rule or
severity level to be performed. You can configure a rule to perform one or more actions
upon entering or exiting each state. When a multiple-severity rule fires, an alarm also
appears in Foglight.
For more information see “Working with Rules” on page 406.
The Foglight Management Server includes some built-in rules that monitor the health of
your application server environment. Rules in this section:
• Agent Health State rule
• BSM All Events rule
• Catalyst Data Service Discarding Data rule
• Catalyst Database Space Checking rule
• Catalyst Free Space Checking for Oracle Tablespaces rule
• Clear Old LogFilter Alarms rule
• DiagnosticAgentDiscovery rule
• Email Reports Sample rule
• Foglight Agent Type License Checker rule
• Foglight Garbage Collector rule
• Foglight Memory Usage Check rule
• Foglight Topology Size Limit Reached rule
• Idle Agents rule
• Remote Agent Manager State per Host rule
• ServiceLevelEvaluation – FMSServiceSLP rule
• SNMP Forward rule
Purpose
This rule monitors the health of all agents in the monitoring environment. It generates
an alarm if it finds an agent whose health is deteriorating (Warning) or is down
(Critical).
510 Foglight
Administration and Configuration Guide
Scope
Agent : agentID != "0"
Rule Definition
Conditions State
Purpose
This rule sends all alarms from Foglight to the Service Discovery and Dashboards
product.
The BSM All Events rule includes an entering BSM action which includes two
mandatory action parameters: Alarm system event and BSM URL. These parameters
must be set in order for the BSM rule to work properly. By default , Alarm system
event is set to the alarmEvent rule-level expression, while the BSM URL action
parameter points to the BSM URL Foglight registry variable. To ensure this rule works as
expected, you need to configure the BSM URL Foglight registry variable to the
destination address, followed by enabling this rule (it is disabled by default). For more
information about editing action parameters in rules, see “Editing action parameters” on
page 495; for instructions on how to edit Foglight registry variables, see “Editing
Registry Variables” on page 381.
For more information about the Service Discovery and Dashboards, see the product
documentation.
Scope
None
Purpose
This rule monitors the observations and generates an alarm if the Data Service starts
discarding any observations. This can happen when the Foglight Management Server is
Working with Foglight Rules and Registry 511
Working with Rules
overloaded, or when there is a difference, or the difference in the system time between
the monitored system and the Foglight Management Server. This alarm indicates the
server is overloaded and cannot keep up with the incoming data.
Scope
CatalystDataService
Rule Definition
Conditions State
Purpose
This rule monitors the size of the database, checking whether the database size is higher
than the predefined threshold, set by the DBSMon.MaxDatabaseSize registry variable.
By default, this value is set to 2 Gb. If required, you can increase this value. For
information on how to view and edit Foglight registry variables, see “Working with
Foglight Registry Variables” on page 364.
Scope
CatalystDatabase
Rule Definition
Conditions State
The size of the Foglight database exceeds 75% of the maximum Warning
database size.
The size of the Foglight database exceeds 90% of the maximum Critical
database size.
The size of the Foglight database exceeds 98% of the maximum Fatal
database size.
512 Foglight
Administration and Configuration Guide
Purpose
This rule checks the space that is currently available to the Oracle database against the
thresholds defined in the Foglight registry. It generates alarms when the Oracle table
space becomes too large. The thresholds for generating alarms are set by the following
variables:
• DBSMon.WarningFreeTablespaceSize
• DBSMon.CriticalFreeTablespaceSize
• DBSMon.FatalFreeTablespaceSize
Database administrators should provide values for these thresholds in order to get
notified when the database starts growing out of bounds. For information on how to
view and edit Foglight registry variables, see “Working with Foglight Registry
Variables” on page 364.
Scope
CatalystTablespace
Rule Definition
Conditions State
The size that is available to the Oracle database exceeds the Warning
threshold of set by the DBSMon.WarningFreeTablespaceSize
registry variable.
The size that is available to the Oracle database exceeds the Critical
threshold of set by the DBSMon.CriticalFreeTablespaceSize
registry variable.
The size that is available to the Oracle database exceeds the Fatal
threshold of set by the DBSMon.FatalFreeTablespaceSize
registry variable.
Working with Foglight Rules and Registry 513
Working with Rules
Purpose
This rule periodically clears old LogFilter alarms.
Scope
None
DiagnosticAgentDiscovery rule
Purpose
This periodically looks for new agent instances that are connecting to the Foglight
Management Server. It rebuilds the topology if it detects new agents.
Scope
CatalystServer
Purpose
This rule directs all scheduled reports to their email recipients. A scheduled report can
have one or more email recipients.
Scope
None
Purpose
Checks whether the CPU count of an agent type exceeds the licensed number of agents.
It generates a Warning alarm if it finds that the number of monitored host an agent is
currently monitoring is higher than the number allowed by your license.
Scope
AgentTypeLicense
514 Foglight
Administration and Configuration Guide
Rule Definition
Conditions State
The number of monitored hosts is higher than the number allowed by Warning
the license.
Purpose
This rule checks the amount of time the Foglight Management Server spends for
garbage collection and generates alarms if that time exceeds pre-defined thresholds,
defined by a set of registry variables for each severity state: Warning, Critical, and
Fatal.
Scope
(CatalystServer).jvm.garbageCollectors where name not like '%copy%'
Rule Definition
Conditions State
The amount of time spent on garbage collection exceeds the threshold Warning
set by the registry variable FMSMon.gcWarn. The default value of
that variable is 10.
The amount of time spent on garbage collection exceeds the threshold Critical
set by the registry variable FMSMon.gcCritical. The default value
of that variable is 30.
The amount of time spent on garbage collection exceeds the threshold Fatal
set by the registry variable FMSMon.gcFatal. The default value of
that variable is 90.
Working with Foglight Rules and Registry 515
Working with Rules
Purpose
This rule checks the memory that is available to the Foglight Management Server and
generates a Critical alarm if the server is in danger of running out of memory, defined as
95% memory utilization. If this alarm is generated and cleared occasionally, this does
not indicate any potential problems, however, if the alarm stays active without clearing,
or if it is generated and cleared frequently, this indicates that you need to increase the
memory allotment.
Scope
(CatalystServer).jvm
Rule Definition
Conditions State
Purpose
Checks if any attempts to create topology objects are failing because the topology size
limit has been reached. This number is defined by the foglight.limit.instances
registry variable whose global default value is set to 10,000. You can change this value
if required. For more information, see “Editing Registry Variables” on page 381.
Caution Increasing the default value of the foglight.limit.instances variable may cause
performance issues on the Foglight Management Server. If you need to increase this
value, contact Quest Support for further instructions.
The setting of this threshold protects against volatile, untuned topology models. This
can be often caused by JavaEE Request URL tuning. If this rule fires, in most situations
agent tuning is required to make the data less volatile.
Scope
CatalystTopologySizeConstraintService
516 Foglight
Administration and Configuration Guide
Rule Definition
Conditions State
The attempts to create topology objects are failing because the Warning
maximum number of topology objects exceeds the value set by
foglight.limit.instances.
Purpose
This rule periodically checks whether there are any idle agents. An agent is considered
idle if it is running but the Foglight Management Server does not register any data
associated with that agent for a pre-defined period of time, defined by a registry
variable for each severity state: Warning, Critical, and Fatal
Scope
Agent
Rule Definition
Conditions State
The agent is idle for the number of hours set by the registry variable Warning
IdleAgent.Warning. The default value of that variable is 1.0
hours.
The agent is idle for a period of time set by the registry variable Critical
IdleAgent.Critical. The default value of that variable is 24.0
hours.
The agent is idle for a period of time set by the registry variable Fatal
IdleAgent.Fatal. The default value of that variable is 168.0
hours.
Working with Foglight Rules and Registry 517
Working with Rules
Purpose
This rule checks whether at least one instance of the Foglight Agent Manager is running
on a monitored host.
Scope
Host : detail instanceof RemoteClient
Rule Definition
Conditions State
Purpose
Foglight monitors each service (either implicit or user-defined) for service level
compliance. The ServiceLevelEvaluation – FMSServiceSLP rule checks the availability
of each service and raises an alarm if the availability is lower than the a predefined
threshold during a period of one hour.
Scope
FSMServiceLevelPolicy
Rule Definition
Conditions State
Purpose
This is a template rule that can direct all incoming SNMP traps to an SNMP trap
receiver, once the rule’s SnmpTrapAction parameters, CommunityString and
TargetAddress are set to point to the desired SNMP trap receiver.
You can use this rule as a template when creating rules with SNMP trap actions. For
more information about viewing the settings related to SNMP trap actions and their
configuration in Foglight, see “Configuring SNMP trap actions” on page 477
Scope
None
Foglight Management Server, you leave the Trigger Type at its default setting, Data
Driven.
You click the Validate Scope button ( ) to ensure that the topology type is valid and
that you used the correct syntax in the Rule Scope box. The rule scope is successfully
validated, so you click Next to navigate to the Condition, Alarms & Actions tab.
Specifying conditions
After scoping the rule to EJB_Instance1 in MyApplication, you specify the
conditions for the rule on the Condition, Alarms & Actions tab.
520 Foglight
Administration and Configuration Guide
To start the process of setting the condition for the Fatal severity level, you click the
header for this level on the Condition, Alarms & Actions tab.
You had previously created a derived metric called transactionRollbackRate: you
derived this metric from the raw metric transactionsRolledBackTotalCount so
that it returns a rate (the total number of transactions that are rolled back per minute).
On the Condition sub-tab for the Fatal level, you click the Condition Editor button
( ) to launch the Condition Editor. You switch to the Metric/Property tab, select
transactionRollbackRate from the Choose Metric Value list, and click Select to insert
it into the Condition box. You then type >10 in this box after the metric name.
When you finish editing the information in the Condition box, the condition is specified
as follows:
#transactionRollbackRate#>10
You repeat this process for the Critical and Warning levels, specifying the conditions for
these levels as #transactionRollbackRate#>8 and
#transactionRollbackRate#>6, respectively.
You click Finish when you have specified the conditions for all three severity levels.
You review the settings for the rule on the Rule Added area and then click the Go to
Rule List button. The new rule is listed on the Manage Rules dashboard.
Administrator when the rule enters the Fire state. Foglight executes email actions only if
they are properly configured in the Email Configuration dashboard. Prior to creating the
rule, you need to review the settings on this dashboard and edit them, if required. For
the purpose of this exercise, you need to add your email address to the value of the
SYSADMIN registry variable which allows you to receive the emails resulting from the
email action each time the rule condition is met.
To create a simple data-driven rule that is scoped to a topology property, that triggers
email actions:
1 Start the browser interface and log into Foglight.
a Open a Web browser instance and navigate to the URL that uses the following
syntax:
http://localhost:8080/console
Where localhost is the name of the machine on which the Foglight
Management Server is running.
Tip The above URL uses the default HTTP port number, 8080. For more information
about default port assignments, see Chapter 3, “Default port assignments” on
page 107.
In the Foglight login page, in the User and Password boxes, type your
Foglight user name and password, respectively, followed by clicking Login.
Tip For complete information about getting started with Foglight, see Chapter 1,
“Getting Started with the Administration Module” on page 19.
c In the browser interface that appears, ensure that the navigation panel is open.
To open the navigation panel, click the right-facing arrow on the left.
2 Ensure that email actions are configured.
Foglight executes email actions only if they are previously configured in the
Email Configuration dashboard. Review its settings to ensure that email actions
occur as expected.
Open the Email Configuration dashboard.
a On the navigation panel, under Dashboards, choose Administration > Setup
& Support > Email Configuration.
The Email Configuration dashboard appears in the display area, showing the
current email settings.
Working with Foglight Rules and Registry 523
Working with Rules
For more information about accessing the Email Configuration dashboard and
its contents, see Chapter 3, “Accessing the Email Configuration Dashboard”
on page 120.
b Observe the settings on the Email Configuration dashboard.
At minimum, Foglight requires the name or IP address of the mail server, and
the email address from which emails are sent. Your mail server may require
additional information, such as the name and password for logging into the
mail server or the mail protocol (if the mail server does not use the default
SMTP protocol). For more information, contact your mail administrator.
Additionally, because the rule is meant to send emails to the Foglight System
Administrator, ensure that this value is set as well. For a complete list of
email-related parameters and their usage, see Chapter 3, “Configuring Email
Actions” on page 119.
524 Foglight
Administration and Configuration Guide
The above example shows an email configuration in which the mail server,
mail sender, and Foglight system administrator address are set.
c If required, edit the email settings to enable email actions to occur.
If you are unsure about the settings that are required by your mail server, such
as the login name and password, or the mail protocol, contact your mail
administrator.
Also, for the purpose of this example, add your email address to the list of
Foglight system administrators, defined by the System Administrator
Addresses parameter in the Email Alias Group view. This enables you to
quickly verify the occurrence of email actions as the rule conditions are met by
checking your email account.
Tip The System Administrator Addresses parameter is a direct link to the
SYSADMIN Foglight registry variable. Editing this parameter also updates the
value of the SYSADMIN registry variable. For more information about email action
parameters and their links to the Foglight registry, see Chapter 3, “Configuring
Email Actions” on page 119.
To edit an email parameter, in the row containing the email parameter, click ,
followed by typing a desired value and clicking Save in the dialog box that
appears.
For complete information about scoping on rules, see Chapter 11, “Setting the
Scope for a Rule or Derived Metric” on page 784.
5 Write the rule condition.
a On the Create Rule dashboard, open the Condition and Actions tab, followed
by clicking the Fire bar.
The Fire pane expands, allowing you to specify the rule condition.
528 Foglight
Administration and Configuration Guide
In the Fire pane, click . In the Condition Editor dialog box that appears,
open the Metric/Property tab, and in the Type of Scope area, select JVM.
In the Metrics area that appears, select threadCount, followed by clicking
Insert.
Working with Foglight Rules and Registry 529
Working with Rules
Tip The Metrics view lists the metrics that exist in the selected topology type.
For complete information about adding severity level variables to rule definitions,
see “Adding severity-level variables” on page 444.
7 Create an email action that sends an email each time the rule condition is met,
when the threadcount metric of any JVM object instance becomes greater than
one hundred.
a In the Fire pane, open the Action tab.
532 Foglight
Administration and Configuration Guide
In the Action Parameter Editor dialog box, on the Variable tab, in the
Registry Variables list, select the row containing the SYSADMIN entry, and
click Change.
534 Foglight
Administration and Configuration Guide
The Action Parameter Editor dialog box closes and the Action Parameters
table refreshes, showing the updated mail.recipient entry.
The Value column of the mail.recipient entry indicates that the email action
uses the email address set by the SYSADMIN registry variable to which the
email action sends emails when the rule condition is met.
Tip For the purpose of this example, in step 2, you edited the value of the SYSADMIN
registry variable to include your email address. When you save the changes to this
Working with Foglight Rules and Registry 535
Working with Rules
rule, this helps you to observe the results of the entering email action which sends
emails to the email addresses specified by the SYSADMIN registry variable, each
time the rule condition is met.
In the Action Parameter Editor dialog box that appears, on the Variable tab,
in the Rule/System Variables list, select the row containing the
ProblemSynopsis entry, and click Change.
536 Foglight
Administration and Configuration Guide
The Action Parameter Editor dialog box closes and the Action Parameters
table refreshes, showing the updated mail.message entry.
The Value column of the mail.message entry indicates that the email message
contains the text set by the ProblemSynopsis severity-level rule variable.
Tip In step 6, you created the ProblemSynopsis severity-level variable. This variable
contains the content of the email message: Thread count is too high:
Working with Foglight Rules and Registry 537
Working with Rules
For complete information about adding actions to rule definitions, see “Defining
actions” on page 466.
8 Save your changes to the newly-created rule.
a On the Action tab, click Go to Action List.
The Action tab refreshes, showing the newly-added email action in the
Actions table.
b In the Create Rule view, immediately above the rule definition tabs, click
Finish.
538 Foglight
Administration and Configuration Guide
c In the browser interface that appears, ensure that the navigation panel is open.
To open the navigation panel, click the right-facing arrow on the left.
2 Get started with the rule definitions.
a Open the Create Rule dashboard.
On the navigation panel, under Dashboards, choose Administration > Rules
& Notifications > Create Rule.
The Create Rule dashboard appears in the display area with the Rule
Definition tab open.
Working with Foglight Rules and Registry 541
Working with Rules
Use the appropriate conditional expression in each of the severity level, as follows:
Critical: #percentUserTime#>10
Fatal: #percentUserTime#>15
Note The information in this procedure assumes that you have a good understanding of the rule
editing workflow. For step-by-step instructions on how to add actions to a rule and edit their
parameters, see “Defining actions” on page 466.
1 Verify that the script is accessible by the rule. To do that, copy your script to the
<foglight_home>/scripts directory on the Foglight Management Server.
2 Open the rule for editing and navigate to the Action tab of the severity level for
which you want to define the actions.
3 Add an entering ScriptAction and edit its parameters.
a If your script has one or more arguments, use the Argument 1-10
parameters to specify the arguments’ value.
548 Foglight
Administration and Configuration Guide
b If you want the script to run against a particular topology object, use the
Script object id parameter to specify the object’s ID.
c Use the Script name parameter to specify the script name.
4 Return to the Action tab.
5 Add an entering Remote Command Action that is to be executed on a monitored
host and edit its parameters.
a Use the HostName parameter to specify the name of the monitored host
machine.
b Use the RemoteWorkingDir parameter to specify the absolute path on the
remote host in which you want the command to run.
c Use the COMMAND_LINE parameter to specify the command that you want to
run remotely along with any options or arguments if applicable.
6 Return to the Action tab and save your changes to the rule.
When the rule enters the severity state that includes newly-defined actions it
executes those actions as specified.
Figure 6
Host Model
Host A Host B
Processor 1 Processor 1
percentUserTime percentUserTime
Processor 2 Processor 2
percentUserTime percentUserTime
Processor 3
percentUserTime
In the User and Password boxes, type your Foglight user name and password,
respectively, followed by clicking Login.
Tip For complete information about getting started with Foglight, see Chapter 1,
“Getting Started with the Administration Module” on page 19.
b In the browser interface that appears, ensure that the navigation panel is open.
To open the navigation panel, click the right-facing arrow on the left.
c On the navigation panel, under Dashboards, choose Administration > Rules
& Notifications > Create Rule.
The Create Rule dashboard appears in the display area with the Rule
Definition tab open.
Working with Foglight Rules and Registry 551
Working with Rules
d In the Create Rule dashboard, in the Rule Definition tab, in the Rule Name
box, type the rule name. For example, Processor Load.
e Under Rule Type, select the Simple Rule option.
f Under Rule Triggering, select the Data Driven option.
2 Scope the rule to the Processor topology type.
a In the Rule Definition tab, in the Rule Scope pane, ensure that the No
Scoping Query check box is clear.
b Click Topology Type and select Core > Processor from the list that appears.
c Click the Append button ( ) to the right of the Topology Type box.
The box immediately below the Topology Type box, showing the newly-
selected Processor type.
d Validate the topology scope by clicking the Validate Rule Scope button ( ) to
the right of the Property box.
A confirmation message appears above the Topology Type box while the
name of the Processor type appears in the box at the bottom.
552 Foglight
Administration and Configuration Guide
3 Write a condition that triggers the rule each time the utilization of a Processor
type reaches 90% using the Processor’s percentUserTime metric.
a In the Create Rule dashboard, open the Conditions and Actions tab.
e On the Metric/Property tab, in the left pane, in the Scoping Topology area,
click Processor.
Tip The Scoping Topology area shows the rule scope, Processor, that you
defined in step 1.
f The pane on the right refreshes, showing the instances and metrics for the
selected Processor type.
Working with Foglight Rules and Registry 555
Working with Rules
Note The information in this procedure assumes that you have a good understanding of the rule
creation workflow. For step-by-step instructions on how to scope a rule to a topology type or
use the Condition Editor, see the above procedure, “To scope a rule to the Processor type:”
on page 549.
2 In the Edit Rule view, open the severity level to which you want to add a
command action.
3 In the severity level area, open the Severity Level Variables tab, and add
severity-level variables that contain the information that you want to print to an
output file. For example:
• var6: Retrieves the alarm message that is associated with the severity level in
which these variables are defined using the scope variable and its get()
function.
• var7: Retrieves the agent name using the scope variable and its get()
function.
4 Open the Action tab and add an entering command action.
5 Define the action parameters as follows:
• COMMAND_LINE: Specify the absolute path and name of the shell script that
you want the command action to call.
• ENVIRONMENT_VARIABLES: Type a list of the variables that you defined in
step 3, using the following syntax to specify a variable:
output_data=@variable
Tip Use the exclamation mark ‘!’ to separate variables.
For example:
P1=@var1!P2=@var2!P3=@var3!P4=@var4!P5=@var5!P6=@var6!
P7=@var7
For example, to print the output of the newly-defined variables (P1 through P7),
type the following line:
/bin/echo ${P1}:${P2}:${P3}:${P4}:${P5}:${P6}:${P7} >
/opt/quest/out.txt
Tip Alternatively, to issue the command directly without referencing it in a script as
instructed in step 7, use the COMMAND_ACTION’s value to specify the command.
When the rule meets the condition that includes the newly-defined command
action, it writes the information to the output file. Here is a sample of what that
output may look like:
jorcl:PUBLIC:19.0:root@localhost:
melscv-w2k3-fdb.melsales.dev.mel.au.qsft Oracle
Database utilization is at 80%
For complete information on how to add actions to rules, see “Defining actions” on
page 466.
560 Foglight
Administration and Configuration Guide
8
Using Schedules
This chapter introduces you to Foglight schedules and provides information on how to
create and manage them. It contains the following sections:
Note In order to complete each of the procedures in this chapter, your user account must belong
to a group with the Administration role. For more information about users, groups, and roles,
see “Managing Users and Security” on page 197.
About Schedules
A schedule is a calendar entry. A schedule consists of one or more schedule items. Each
schedule item is effectively a sub-schedule: it includes a start date (and can include an
end date), a time range during which it runs, a recurrence pattern (once, periodically,
daily, weekly, monthly, or yearly), and range of recurrence.
You use schedules to set effective periods and blackout periods for rules and agents. For
more information, see Chapter 7, “Associating Rules with Schedules” on page 500 and
Chapter 6, “Assigning Blackouts to Agent Instances” on page 357. Additionally, you
can create schedule-driven derived metrics and configure the values for registry
variables to change at certain times based on schedules. See Chapter 9, “Triggering
derived metrics” on page 637 and Chapter 7, “Using performance calendars” on
page 385 for more information.
If a schedule only includes one schedule item, then that item is the schedule. If a
schedule includes multiple schedule items, then they collectively form the schedule. For
example, if you wanted a schedule to run indefinitely from 10:00 am to 11:00 am daily
and on the first day of the month from 8:00 am to 6:00 pm, but also every Saturday from
11:00 am to 4:00 pm in May, add a schedule item for each of these time spans to the
schedule.
You can create new schedules and manage the existing ones using the dashboards that
come with the Administration module. For complete information, see the following
sections:
• “Managing Schedules” on page 563
• “Creating Schedules” on page 574
Using Schedules 563
Managing Schedules
Managing Schedules
The Manage Schedules dashboard allows you to manage existing schedules, assign
permissions to schedules, and other features. For complete information, see the
following sections:
• “Accessing the Manage Schedules Dashboard” on page 563
• “Editing Schedule Permissions” on page 565
• “Copying Schedules” on page 569
• “Deleting Schedules” on page 571
• “Viewing Schedule Definitions” on page 572
• “Viewing and Editing Schedules” on page 573
3 To sort the list of variables by their name or next scheduled time, click the
Schedule Name or Next Scheduled Time column headings as required.
4 View summary information about a schedule.
Move the mouse pointer over the Schedule Name column in the row containing
the schedule whose summary that you want to view.
A dwell appears, showing the schedule summary.
Using Schedules 565
Managing Schedules
The dwell shows the schedule name, brief description, next scheduled time, and
the modification date.
From here, you can proceed to any of the following procedures:
• “Editing Schedule Permissions” on page 565
• “Copying Schedules” on page 569
• “Deleting Schedules” on page 571
• “Viewing Schedule Definitions” on page 572
• “Viewing and Editing Schedules” on page 573
Figure 1
Permission granted
Permission denied
Permissions not assigned
Note This procedure continues from “Accessing the Manage Schedules Dashboard” on
page 563.
1 In the Manage Schedules dashboard, in the row containing the schedule whose
permissions you want to edit, click the Edit Permissions for Schedule button ( ).
The Edit Permissions for Schedule area appears in the Manage Schedules
dashboard.
Using Schedules 567
Managing Schedules
The Add Role Permission or Add User Permission dialog box appears.
568 Foglight
Administration and Configuration Guide
b In the dialog box that appears, use the Read, Write, and Control check boxes
to assign permissions as required, and click Save.
The dialog box closes and the selected entry refreshes, showing three check
marks in the Permission columns, one for each of the read, write, and control
permissions.
Permission granted
Permission denied
The Edit Role Permission or Edit User Permission dialog box appears.
Using Schedules 569
Managing Schedules
b To edit the permissions, ensure that the Edit option is selected and use the
Read, Write, and Control check boxes as required.
c To delete the permissions, select the Delete option.
d Click Save.
The dialog box closes and the selected entry refreshes, showing the newly-
edited permissions.
Copying Schedules
Use the Copy Schedule button on the Manage Schedules dashboard to copy a schedule,
as outlined below.
To copy a schedule:
Note This procedure continues from “Accessing the Manage Schedules Dashboard” on
page 563.
1 In the Manage Schedules dashboard, in the row containing the schedule that you
want to copy, click the Copy Schedule button ( ).
The Copy Schedule dialog box appears.
570 Foglight
Administration and Configuration Guide
The dialog box closes and the Edit Schedule view appears in the Manage
Schedules dashboard.
Deleting Schedules
Use the Delete Selected button on the Manage Schedules dashboard to delete a
schedule, as outlined below.
Note When a schedule is deleted, all references to that schedule are removed as well; any
performance calendars that are based on that schedule are removed and the deleted
schedule is removed from the list of effective and blackout schedules for rules.
To delete a schedule:
Note This procedure continues from “Accessing the Manage Schedules Dashboard” on
page 563.
1 In the Manage Schedules dashboard, select the row containing the schedule that
you want to delete.
2 Click the Delete Selected button at the bottom.
The Schedule Delete Confirmation dialog box appears.
Note This procedure continues from “Accessing the Manage Schedules Dashboard” on
page 563.
1 In the Manage Schedules dashboard, click the Schedule Name column of the row
containing the schedule whose definitions you want to view.
The Edit Schedule view appears in the Manage Schedules dashboard.
to edit it to also run every Saturday from 11:00 am to 4:00 pm in May, add a schedule
item for each of these time spans to the schedule.
To view and edit a schedule:
Note This procedure continues from “Accessing the Manage Schedules Dashboard” on
page 563.
1 In the Manage Schedules dashboard, click the schedule that you want to edit.
The Edit Schedule view appears in the Manage Schedules dashboard.
Creating Schedules
Foglight allows you to create schedules using the Create Schedule dashboard. You can
access this dashboard from the navigation panel, or through the Manage Schedules
dashboard. When you create a schedule, you can use it in rule, derived metric, and agent
definitions as required.
Using Schedules 575
Creating Schedules
Creating a schedule involves several steps. Once you get started with schedule creation,
you need to define the start date and recurrence pattern. For instructions, see the
following sections:
• “Accessing the Create Schedule Dashboard” on page 575
• “Getting Started with Schedule Definitions” on page 576
• “Adding or Removing Schedule Items” on page 577
• “Defining Schedule Items” on page 582
From here, you can proceed to “Getting Started with Schedule Definitions” on
page 576.
Note This procedure continues from “Accessing the Create Schedule Dashboard” on page 575.
From here, you can proceed to “Adding or Removing Schedule Items” on page 577.
When you create a schedule, you have to specify at least one schedule item and its
recurrence pattern. You can edit the schedule at a later time by adding or removing
schedule items as required.
To add a schedule item to a newly-created schedule that has no other schedule items:
Note This procedure continues from “Getting Started with Schedule Definitions” on page 576.
Note This procedure continues from “Defining Schedule Items” on page 582.
The Edit Schedule -> Add Schedule Item view appears, allowing you to define
another schedule item.
580 Foglight
Administration and Configuration Guide
Note This procedure continues from “Viewing and Editing Schedules” on page 573.
1 In the Edit Schedule view, click Add Schedule Item in the lower-right corner.
Using Schedules 581
Creating Schedules
Note This procedure continues from “Viewing and Editing Schedules” on page 573 or “Defining
Schedule Items” on page 582.
1 In the Edit Schedule view, select the row containing the schedule item that you
want to delete and click Delete Selected.
The Schedule Confirmation dialog box appears, asking you to confirm the
delete operation.
Once Starts at a specified date and “To define a schedule item that
time, for a specified duration, occurs once:” on page 583
and ends at a defined end date
and time
Periodical Starts at a specified time and “To define a schedule item that
date for a certain duration, occurs periodically:” on page 586
repeats at specified time periods,
with or without a defined end
date and time
Daily Starts at a specified time and “To define a schedule item that
date, runs for a whole day or a occurs periodically:” on page 586
fraction of a day, repeats at a
regular interval of days, with or
without a defined end date and
time
Weekly Starts at a specified time and “To define a schedule item that
date, runs for a whole day or a occurs weekly:” on page 594
fraction of a day, repeats at a
regular interval of weeks on one
or more days of the week, with
or without a defined end date and
time
Monthly Starts at a specified time and “To define a schedule item that
date, runs for a whole day or a occurs monthly:” on page 600
fraction of a day, repeats at a
regular interval of months on one
or more days of the week, with
or without a defined end date and
time
Using Schedules 583
Creating Schedules
Yearly Starts at a specified time and “To define a schedule item that
date, runs for a whole day or a occurs yearly:” on page 607
fraction of a day, repeats at a
regular interval of years on one
or more days of the week each
month, with or without a defined
end date and time
Note This procedure continues from “Adding or Removing Schedule Items” on page 577.
1 In the Recurrence Pattern area, ensure that the Once option is selected.
2 Specify the start date and time of the recurrence pattern using the controls that
appear above the Recurrence Pattern area.
a Use the Start Date boxes to specify the day, month and year of the start date.
Alternatively, click the Calendar button on the right and use the calendar
controls that appear to specify the start date.
Tip The Day box accepts the values between 1 and 31. Any positive values outside
that range are automatically adjusted to 31; negative values are not accepted.
584 Foglight
Administration and Configuration Guide
b Use the Start Time [hh:mm] boxes to specify the hour and minute of the start
time.
Tip The Hour box accepts the values between 0 and 23. Any positive values outside
that range are automatically adjusted to 23; negative values are not accepted.
The Minute box accepts the values between 0 and 59. Any positive values outside
that range are automatically adjusted to 59; negative values are not accepted.
3 Specify the date and time after which the schedule item ends using the controls in
the Range of Occurrence area.
Note In the Range of Occurrence area, the No End option appears disabled while the
End By Date option is enabled and selected. This is because a schedule item that
occurs once must have an end date.
a Use the End Date boxes to specify the day, month and year of the start date.
Tip The Day box accepts the values between 1 and 31. Any positive values outside
that range are automatically adjusted to 31; negative values are not accepted.
Alternatively, click the Calendar button on the right and use the calendar
controls that appear to specify the end date.
Using Schedules 585
Creating Schedules
b Use the End Time [hh:mm] boxes to specify the hour and minute of the end
time.
Tip The Hour box accepts the values between 0 and 24. Any positive values outside
that range are automatically adjusted to 24; negative values are not accepted.
The Minute box accepts the values between 0 and 59. Any positive values outside
that range are automatically adjusted to 59; negative values are not accepted.
Note This procedure continues from “Adding or Removing Schedule Items” on page 577.
2 Specify the start date and time, and the duration of the recurrence pattern using
the controls that appear above the Recurrence Pattern area.
a Use the Start Date boxes to specify the day, month and year of the start date.
Alternatively, click the Calendar button on the right and use the calendar
controls that appear to specify the start date.
Tip The Day box accepts the values between 1 and 31. Any positive values outside
that range are automatically adjusted to 31; negative values are not accepted.
Using Schedules 587
Creating Schedules
b Use the Start Time [hh:mm] boxes to specify the hour and minute of the start
time.
Tip The Hour box accepts the values between 0 and 23. Any positive values outside
that range are automatically adjusted to 23; negative values are not accepted.
The Minute box accepts the values between 0 and 59. Any positive values outside
that range are automatically adjusted to 59; negative values are not accepted.
c Use the Duration [hh:mm] boxes to specify the hour and minute of the start
time.
Tip The Hour box accepts any positive values.
The Minute box accepts the values between 0 and 59. Any positive values outside
that range are automatically adjusted to 59; negative values are not accepted.
The Minute box accepts the values between 0 and 59. Any positive values outside that
range are automatically adjusted to 59; negative values are not accepted.
4 Specify the date and time after which the schedule item ends using the controls in
the Range of Occurrence area.
588 Foglight
Administration and Configuration Guide
• To specify an end date, in the Range of Occurrence area, ensure that the End
By Date option is selected, and specify the end date and time using the End
Date and End Time [hh:mm] boxes as required.
Tip Use the Calendar button on the right and use the calendar controls that appear to
specify the start date.
Tip The Day box accepts the values between 1 and 31. Any positive values outside
that range are automatically adjusted to 31; negative values are not accepted.
The Hour box accepts the values between 0 and 24. Any positive values outside
that range are automatically adjusted to 23; negative values are not accepted.
The Minute box accepts the values between 0 and 59. Any positive values outside
that range are automatically adjusted to 59; negative values are not accepted.
• To have the schedule item recurring at the recurrence pattern specified in step
3 without an end date, in the Range of Occurrence area, select the No End
option.
The Range of Occurrence area refreshes, no longer showing the controls for
specifying the end date.
Using Schedules 589
Creating Schedules
Note This procedure continues from “Adding or Removing Schedule Items” on page 577.
• Specify the start time and end time of the schedule item.
• Use the Start Time [hh:mm] boxes to specify the hour and minute
of the start time.
Tip The Hour box accepts the values between 0 and 23. Any positive values
outside that range are automatically adjusted to 23; negative values are
not accepted.
The Minute box accepts the values between 0 and 59. Any positive values
outside that range are automatically adjusted to 59; negative values are
not accepted.
• Select the End Time [hh:mm] option and specify the hour and
minute of the end time.
Note The Duration [hh:mm] boxes appear disabled when you specify the
End Time [hh:mm] option.
The Minute box accepts the values between 0 and 59. Any positive values
outside that range are automatically adjusted to 59; negative values are
not accepted.
or
• Use the Start Time [hh:mm] boxes to specify the hour and minute
of the start time.
Tip The Hour box accepts the values between 0 and 23. Any positive values
outside that range are automatically adjusted to 23; negative values are
not accepted.
The Minute box accepts the values between 0 and 59. Any positive values
outside that range are automatically adjusted to 59; negative values are
not accepted.
• Select the Duration [hh:mm] option and specify the hour and
minute of the duration time.
Note The End Time [hh:mm] boxes appear disabled when you specify the
Duration [hh:mm] option.
Tip The Hour box accepts the values between 0 and 24. Any positive values
outside that range are automatically adjusted to 24; negative values are
not accepted.
The Minute box accepts the values between 0 and 59. Any positive values
outside that range are automatically adjusted to 59; negative values are
not accepted.
or
• If you want the schedule to occur for the entire day, select the Whole Day
check box.
The Start Time [hh:mm], End Time [hh:mm], and Duration [hh:mm]
boxes appear disabled.
Using Schedules 593
Creating Schedules
5 Specify the date and time after which the schedule item ends using the controls in
the Range of Occurrence area.
• To specify an end date, in the Range of Occurrence area, ensure that the End
By Date option is selected, and specify the end date and time using the End
Date and End Time [hh:mm] boxes as required.
Tip Use the Calendar button on the right and use the calendar controls that appear to
specify the start date.
Tip The Day box accepts the values between 1 and 31. Any positive values outside
that range are automatically adjusted to 31; negative values are not accepted.
The Hour box accepts the values between 0 and 24. Any positive values outside
that range are automatically adjusted to 23; negative values are not accepted.
The Minute box accepts the values between 0 and 59. Any positive values outside
that range are automatically adjusted to 59; negative values are not accepted.
594 Foglight
Administration and Configuration Guide
• To have the schedule item recurring at the recurrence pattern specified in step
4 without an end date, in the Range of Occurrence area, select the No End
option.
The Range of Occurrence area refreshes, no longer showing the controls for
specifying the end date.
Note This procedure continues from “Adding or Removing Schedule Items” on page 577.
Using Schedules 595
Creating Schedules
• If you want the schedule to occur for a part of the day, complete one of the
following steps.
• Specify the start time and end time of the schedule item.
• Use the Start Time [hh:mm] boxes to specify the hour and minute
of the start time.
Tip The Hour box accepts the values between 0 and 23. Any positive values
outside that range are automatically adjusted to 23; negative values are
not accepted.
The Minute box accepts the values between 0 and 59. Any positive values
outside that range are automatically adjusted to 59; negative values are
not accepted.
• Select the End Time [hh:mm] option and specify the hour and
minute of the end time.
Note The Duration [hh:mm] boxes appear disabled when you specify the
End Time [hh:mm] option.
The Minute box accepts the values between 0 and 59. Any positive values
outside that range are automatically adjusted to 59; negative values are
not accepted.
or
• Use the Start Time [hh:mm] boxes to specify the hour and minute
of the start time.
Tip The Hour box accepts the values between 0 and 23. Any positive values
outside that range are automatically adjusted to 23; negative values are
not accepted.
The Minute box accepts the values between 0 and 59. Any positive values
outside that range are automatically adjusted to 59; negative values are
not accepted.
• Select the Duration [hh:mm] option and specify the hour and
minute of the duration time.
Note The End Time [hh:mm] boxes appear disabled when you specify the
Duration [hh:mm] option.
Tip The Hour box accepts the values between 0 and 24. Any positive values
outside that range are automatically adjusted to 24; negative values are
not accepted.
The Minute box accepts the values between 0 and 59. Any positive values
outside that range are automatically adjusted to 59; negative values are
not accepted.
or
• If you want the schedule to occur for the entire day, select the Whole Day
check box.
The Start Time [hh:mm], End Time [hh:mm], and Duration [hh:mm]
boxes appear disabled.
598 Foglight
Administration and Configuration Guide
Select one or more check boxes that represent the days of the week on which the
schedule occurs.
For example, to have the schedule occurring on Mondays and Wednesdays for
four weeks in a row, in the Every box, type 4, and select the Monday and
Wednesday check boxes, as illustrated bellow.
5 Specify the date and time after which the schedule item ends using the controls in
the Range of Occurrence area.
Using Schedules 599
Creating Schedules
• To specify an end date, in the Range of Occurrence area, ensure that the End
By Date option is selected, and specify the end date and time using the End
Date and End Time [hh:mm] boxes as required.
Tip Use the Calendar button on the right and use the calendar controls that appear to
specify the start date.
Tip The Day box accepts the values between 1 and 31. Any positive values outside
that range are automatically adjusted to 31; negative values are not accepted.
The Hour box accepts the values between 0 and 24. Any positive values outside
that range are automatically adjusted to 23; negative values are not accepted.
The Minute box accepts the values between 0 and 59. Any positive values outside
that range are automatically adjusted to 59; negative values are not accepted.
• To have the schedule item recurring at the recurrence pattern specified in step
4 without an end date, in the Range of Occurrence area, select the No End
option.
The Range of Occurrence area refreshes, no longer showing the controls for
specifying the end date.
The Schedule Items table refreshes, showing the newly-added schedule item.
Note This procedure continues from “Adding or Removing Schedule Items” on page 577.
• If you want the schedule to occur for a part of the day, complete one of the
following steps.
• Specify the start time and end time of the schedule item.
• Use the Start Time [hh:mm] boxes to specify the hour and minute
of the start time.
Tip The Hour box accepts the values between 0 and 23. Any positive values
outside that range are automatically adjusted to 23; negative values are
not accepted.
The Minute box accepts the values between 0 and 59. Any positive values
outside that range are automatically adjusted to 59; negative values are
not accepted.
• Select the End Time [hh:mm] option and specify the hour and
minute of the end time.
Note The Duration [hh:mm] boxes appear disabled when you specify the
End Time [hh:mm] option.
The Minute box accepts the values between 0 and 59. Any positive values
outside that range are automatically adjusted to 59; negative values are
not accepted.
or
• Use the Start Time [hh:mm] boxes to specify the hour and minute
of the start time.
Tip The Hour box accepts the values between 0 and 23. Any positive values
outside that range are automatically adjusted to 23; negative values are
not accepted.
The Minute box accepts the values between 0 and 59. Any positive values
outside that range are automatically adjusted to 59; negative values are
not accepted.
• Select the Duration [hh:mm] option and specify the hour and
minute of the duration time.
Note The End Time [hh:mm] boxes appear disabled when you specify the
Duration [hh:mm] option.
Tip The Hour box accepts the values between 0 and 24. Any positive values
outside that range are automatically adjusted to 24; negative values are
not accepted.
The Minute box accepts the values between 0 and 59. Any positive values
outside that range are automatically adjusted to 59; negative values are
not accepted.
or
• If you want the schedule to occur for the entire day, select the Whole Day
check box.
The Start Time [hh:mm], End Time [hh:mm], and Duration [hh:mm]
boxes appear disabled.
604 Foglight
Administration and Configuration Guide
For example, to have the schedule occurring on the fifth day of every second
month, in the Day box, type 5, and in the every box, type 2, as illustrated
bellow.
• To have the schedule occurring on one or more days of the week, at a rate of
one or more months, in the Recurrence Pattern area, select the By Week
option.
The Recurrence Pattern area refreshes, showing a set of the controls that
allow you to specify the pattern.
Specify the week of the month, the day of the week and the rate at which it
occurs.
Tip The every box accepts any positive values.
For example, to have the schedule occurring on the second Tuesday of every
third month, click First and select Second from the list that appears. Then,
select the Tuesday check box, and in the every box, type 3, as illustrated
below.
Using Schedules 605
Creating Schedules
In the Recurrence Pattern area, use the Every box to specify the number of
weeks at which the schedule occurs.
Tip The Every box accepts any positive values.
5 Specify the date and time after which the schedule item ends using the controls in
the Range of Occurrence area.
• To specify an end date, in the Range of Occurrence area, ensure that the End
By Date option is selected, and specify the end date and time using the End
Date and End Time [hh:mm] boxes as required.
Tip Use the Calendar button on the right and use the calendar controls that appear to
specify the start date.
Tip The Day box accepts the values between 1 and 31. Any positive values outside
that range are automatically adjusted to 31; negative values are not accepted.
606 Foglight
Administration and Configuration Guide
The Hour box accepts the values between 0 and 24. Any positive values outside
that range are automatically adjusted to 23; negative values are not accepted.
The Minute box accepts the values between 0 and 59. Any positive values outside
that range are automatically adjusted to 59; negative values are not accepted.
• To have the schedule item recurring at the recurrence pattern specified in step
4 without an end date, in the Range of Occurrence area, select the No End
option.
The Range of Occurrence area refreshes, no longer showing the controls for
specifying the end date.
Note This procedure continues from “Adding or Removing Schedule Items” on page 577.
• If you want the schedule to occur for a part of the day, complete one of the
following steps.
• Specify the start time and end time of the schedule item.
• Use the Start Time [hh:mm] boxes to specify the hour and minute
of the start time.
Tip The Hour box accepts the values between 0 and 23. Any positive values
outside that range are automatically adjusted to 23; negative values are
not accepted.
The Minute box accepts the values between 0 and 59. Any positive values
outside that range are automatically adjusted to 59; negative values are
not accepted.
• Select the End Time [hh:mm] option and specify the hour and
minute of the end time.
Note The Duration [hh:mm] boxes appear disabled when you specify the
End Time [hh:mm] option.
The Minute box accepts the values between 0 and 59. Any positive values
outside that range are automatically adjusted to 59; negative values are
not accepted.
or
• Use the Start Time [hh:mm] boxes to specify the hour and minute
of the start time.
Tip The Hour box accepts the values between 0 and 23. Any positive values
outside that range are automatically adjusted to 23; negative values are
not accepted.
The Minute box accepts the values between 0 and 59. Any positive values
outside that range are automatically adjusted to 59; negative values are
not accepted.
• Select the Duration [hh:mm] option and specify the hour and
minute of the duration time.
Note The End Time [hh:mm] boxes appear disabled when you specify the
Duration [hh:mm] option.
Tip The Hour box accepts the values between 0 and 24. Any positive values
outside that range are automatically adjusted to 24; negative values are
not accepted.
The Minute box accepts the values between 0 and 59. Any positive values
outside that range are automatically adjusted to 59; negative values are
not accepted.
or
• If you want the schedule to occur for the entire day, select the Whole Day
check box.
The Start Time [hh:mm], End Time [hh:mm], and Duration [hh:mm]
boxes appear disabled.
Using Schedules 611
Creating Schedules
For example, to have the schedule occurring on the sixth day of every April
month, click the Month box and select April from the list that appears, and in
the Day box, type 6, as illustrated bellow.
Specify the week of the month, the day of the week and the month on which
the schedule occurs.
For example, to have the schedule occurring every third Thursday in
November, click First and select Third from the list that appears. Then, select
the Thursday check box, click the Month box on the right and select
November from the list that appears, as illustrated below.
612 Foglight
Administration and Configuration Guide
5 Specify the date and time after which the schedule item ends using the controls in
the Range of Occurrence area.
• To specify an end date, in the Range of Occurrence area, ensure that the End
By Date option is selected, and specify the end date and time using the End
Date and End Time [hh:mm] boxes as required.
Tip Use the Calendar button on the right and use the calendar controls that appear to
specify the start date.
Tip The Day box accepts the values between 1 and 31. Any positive values outside
that range are automatically adjusted to 31; negative values are not accepted.
The Hour box accepts the values between 0 and 24. Any positive values outside
that range are automatically adjusted to 23; negative values are not accepted.
Using Schedules 613
Creating Schedules
The Minute box accepts the values between 0 and 59. Any positive values outside
that range are automatically adjusted to 59; negative values are not accepted.
• To have the schedule item recurring at the recurrence pattern specified in step
4 without an end date, in the Range of Occurrence area, select the No End
option.
The Range of Occurrence area refreshes, no longer showing the controls for
specifying the end date.
This chapter introduces you to Foglight data management entities on how to create and
manage these entities. It contains the following sections:
Note In order to complete each of the procedures in this chapter, your user account must belong
to a group with the Administration role. For more information about users, groups, and roles,
see “Managing Users and Security” on page 197.
Important Topology types can only be removed by uninstalling the cartridge that contains the types
that you want to delete.
3 To add one or more topology types that are defined in an XML file accessible by
your local machine, complete one of the following steps in the Import From File
area of the Add Topology Type dashboard.
• Ensure that the File on Local Computer option is selected. Then click
Browse, and navigate to the topology file in the file browser that appears.
The file browser closes and the File on Local Computer option refreshes to
show the absolute path and name of the topology file.
or
• Select the File on Local Computer option, and in the box to the right, type the
absolute path and name of the topology file
Note Use the back slash character ‘\’ as a directory separator on Windows platforms;
on Unix platforms, use the forward slash ‘/’.
Windows example:
C:\Quest_Software\Foglight\topology.xml
Working with Data 619
Adding Topology Types
4 To add one or more topology types that are defined in an XML file accessible by
the machine on which the Foglight Management Server is running, complete the
following steps.
a Select the File Location on Server option.
b In the File Location on Server box, type the path and name of the topology
file. Use either an absolute path or a path relative to the installation directory
of the Foglight Management Server.
Note Use the back slash character ‘\’ as a directory separator.
For example, both of the following lines point to the same topology file:
C:\Quest_Software\Foglight\topology\topology.xml
topology\topology.xml
5 To define one or more topology types using the text editor in the Add Topology
Type dashboard, in the Import From Text area, type the topology definition that
you want to add between the <types> and </types> tags.
For example:
<!DOCTYPE types SYSTEM "../dtd/topology-types.dtd">
<types>
<type name="MyHost" extends="Host">
<property name="MyAlarmTotalCount" type="Integer"
is-containment="true" />
<property name="MyDomainName" type="String"
is-containment="true" />
</type>
<type name="MyAgent" extends="Agent">
<property name="AgentName" type="String"
is-containment="true" />
<property name="MyAnnotations" type="String"
is-containment="true" />
</type>
</types>
Validate the topology definition by clicking Validate.
The Alert message box appears, indicating that the topology definition is valid.
620 Foglight
Administration and Configuration Guide
Note The validation process is limited. Your XML may appear to be valid and still fail on import.
To open the navigation panel, click the right-facing arrow on the left.
2 On the navigation panel, under Dashboards, choose Administration > Data >
Manage Derived Metrics.
The Manage Derived Metrics dashboard appears in the display area.
3 To sort the list of derived metrics by their name or scope, click the Derived
Metric Name or Derived Metric Scope column headings as required.
4 Optional. Filter the list of derived metrics.
• To show only the derived metrics whose name matches a particular text
pattern, in the Derived Metric Name box at the top, type the text pattern.
The Manage Derived Metrics dashboard refreshes, showing only the derived
metrics whose name matches the specified text pattern.
• To show only the derived metrics whose scope matches a particular text
pattern, in the Derived Metric Scope box at the top, type the text pattern.
The Manage Derived Metrics dashboard refreshes, showing only the derived
metrics whose scope matches the specified text pattern.
• To show only the derived metrics that belong to a particular cartridges, in the
Cartridge Name box at the top, type the cartridge name.
Working with Data 623
Working with Derived Metrics
The Manage Derived Metrics dashboard refreshes, showing only the rules that
come with the specified cartridge.
• To clear the filters, click Clear Filters.
The Manage Derived Metrics dashboard refreshes, showing the list of all
variables.
The dwell shows the derived metric name, cartridge name and version, last
modified date, any comments (if existing), modification date, and derived metric
scope.
From here, you can proceed to any of the following procedures:
• “Editing permissions of derived metrics” on page 624
• “Copying derived metrics” on page 628
• “Deleting derived metrics” on page 630
• “Viewing and editing derived metrics” on page 630
Figure 1
Permission granted
Permission denied
Permissions not assigned
Note This procedure continues from “Accessing the Manage Derived Metrics dashboard” on
page 621.
1 In the Manage Derived Metrics dashboard, in the row containing the rule whose
permissions you want to edit, click the Edit Permissions for Derived Metric
button ( ).
The Edit Permissions for Derived Metric area appears in the Manage Derived
Metrics dashboard.
626 Foglight
Administration and Configuration Guide
The Add Role Permission or Add User Permission dialog box appears.
Working with Data 627
Working with Derived Metrics
b In the dialog box that appears, use the Read, Write, and Control check boxes
to assign permissions as required, and click Save.
The dialog box closes and the selected entry refreshes, showing three check
marks in the Permission columns, one for each of the read, write, and control
permissions.
Permission granted
Permission denied
The Edit Role Permission or Edit User Permission dialog box appears.
628 Foglight
Administration and Configuration Guide
b To edit the permissions, ensure that the Edit option is selected and use the
Read, Write, and Control check boxes as required.
c To delete the permissions, select the Delete option
d Click Save.
The dialog box closes and the selected entry refreshes, showing the newly-
edited permissions.
Note This procedure continues from “Accessing the Manage Derived Metrics dashboard” on
page 621.
1 In the Manage Derived Metrics dashboard, in the row containing the derived
metric that you want to copy, click the Copy Derived Metric button ( ).
The Copy Derivation dialog box appears.
Working with Data 629
Working with Derived Metrics
Note This procedure continues from “Accessing the Manage Derived Metrics dashboard” on
page 621.
1 In the Manage Derived Metrics dashboard, select the row containing the derived
metric that you want to delete.
2 Click the Delete Selected button at the bottom.
The Delete Derivation dialog box appears.
Note This procedure continues from “Accessing the Manage Derived Metrics dashboard” on
page 621.
1 In the Manage Derived Metrics dashboard, click the Derived Metric Name
column of the row containing the derived metrics whose definitions you want to
view.
The Edit Derived Metric view appears in the Manage Derived Metrics
dashboard.
The Edit Derived Metric view shows the derived metric settings, such as the
derived metric name, cartridge name and version (if applicable), modification
date, and the derived metric calculations.
Tip If a derived metric comes with the Foglight Management Server or any installed
cartridge, the Cartridge Name and Cartridge Version values indicate the cartridge
632 Foglight
Administration and Configuration Guide
name and its version. Otherwise, if a derived metric is created using the Create
Derived Metric dashboard, this value is blank.
From here, you can proceed to “Defining Derived Metrics” on page 633.
Note This procedure continues from “Creating Derived Metrics” on page 632.
Note This procedure continues from “Getting started with derived metric definitions” on page 633
or “Viewing and editing derived metrics” on page 630.
1 New derived metrics. In the Derived Metric Calculations area, click Add
Calculation.
The display area refreshes, showing the Derived Metric Scope and Expression
areas that allow you to define the scope for the derived metric.
Working with Data 635
Working with Derived Metrics
2 Use the Derived Metric Scope and Expression areas to specify the scope of the
derived metric.
Caution If you change the topology type or object(s) to which the derived metric is scoped,
you may need to reconfigure the derived metric expression: the metrics specified
in the existing expression may not be available for the new topology type or
object.
Likewise, if you change the metrics that are specified in the Expression field,
ensure that the new metrics are available for the topology type or object(s) to
which the derived metric is scoped.
For detail instructions, see “Setting the Scope for a Rule or Derived Metric” on
page 784.
636 Foglight
Administration and Configuration Guide
3 When you finish adding calculations to derived metrics, ensure that their order is
valid.
Caution The Foglight Management Server evaluates derived metric calculations in the
order that they are listed, starting with the first one. Changing their order affects
the output of actions that are associated with those calculations.
• thousand
• thousandth
• trillion
• trillionth
• year
For example, to set the unit of the derived metric to a number of days per month,
click the left Unit box, and select day from the list that appears, then click the
right Unit box and select month, as illustrated bellow.
Note This procedure continues from “Adding calculations to derived metrics” on page 634.
1 In the Expression area, under Trigger Type, select the Schedule Driven option.
The Expression area refreshes, showing a set of controls on the right.
2 Choose the schedule during which you want the derived metric to be triggered.
Click Schedule and select a schedule from the list that appears.
Note The list shows all schedules that exist in Foglight. For information on how to add or
remove schedules, see Chapter 8, “Using Schedules” on page 561.
3 Select the trigger timing option to specify the point in time in which Foglight
evaluates the derived metric in relation with the newly-specified schedule.
Click Trigger Timing and select one of the following options from the list that
appears:
Working with Data 639
Working with Derived Metrics
Note This procedure continues from “Adding calculations to derived metrics” on page 634.
1 In the Expression area, under Trigger Type, select the Time Driven option.
The Expression area refreshes, showing a set of controls on the right.
2 Specify the recurrence interval for the trigger in the hh:mm:ss format.
3 To enable the trigger without data, select the Enable Trigger without Data check
box.
4 Save your changes.
To assign a data-driven trigger:
Note This procedure continues from “Adding calculations to derived metrics” on page 634.
1 In the Expression area, under Trigger Type, select the Data Driven option.
2 Save your changes.
From here, you can proceed to “Setting the value type” on page 639.
Note This procedure continues from “Triggering derived metrics” on page 637.
1 In the area immediately below the Derived Metric Calculations list, click Value
Type and select Metric from the list that appears.
2 Select the units of measurement.
Use one or both of the Unit boxes on the left of Unit Type as required.
For example, percent or count / second.
Note You cannot change the value type of a derived metric unless you also change the
name of the derived metric.
You can change the unit of measurement for a derived metric, but only to a
compatible unit. For example, you could change the unit from megabyte to kilobyte,
but you could not change it from megabyte to percent without also changing the
name of the derived metric.
Note This procedure continues from “Triggering derived metrics” on page 637.
1 In the area immediately below the Derived Metric Calculations list, ensure that
both of the Unit boxes are blank.
2 Specify the observation that you want to use as the value type for the derived
metric.
Click Value Type on the right and select an observation from the list that appears.
3 Optional. Add comments about the value type.
Type your comments in the Comments box.
4 Save your changes.
Click Add (when creating a new derived metric) or Save (when editing an
existing metric).
creating rules simpler and more efficient by creating a derived metric scoped to the
same topology type and using it in these rules’ conditions. See “Examples” on page 800
for an example.
In addition, creating a derived metric could help you manage these rules. For example,
if the metric expression used in the rules’ conditions needed to be calculated differently,
you could simply edit the expression for the derived metric instead of editing multiple
conditions.
Managing Thresholds
The Manage Threshold dashboard allows you to create new thresholds and manage
existing thresholds. For complete information, see the following sections:
• “Accessing the Manage Thresholds dashboard” on page 643
• “Editing threshold permissions” on page 644
• “Deleting thresholds” on page 647
• “Viewing and editing thresholds” on page 648
Working with Data 643
Working with Thresholds
3 To sort the list of thresholds by the metric in which they are defined or the
topology type that is used to define the metric, click the Metric or Topology
Type column headings as required.
4 Optional. Filter the list of thresholds using the topology type as the filter.
In the Topology Type box at the top, type the name of the topology type.
The Manage Thresholds dashboard refreshes, showing only the thresholds that
are defined for the specified topology type.
To clear the filter, click Clear Filters.
The Manage Thresholds dashboard refreshes, showing the list of all thresholds.
644 Foglight
Administration and Configuration Guide
Note This procedure continues from “Accessing the Manage Thresholds dashboard” on
page 643.
1 In the Manage Thresholds dashboard, in the row containing the variable whose
permissions you want to edit, click the Edit Permissions for Threshold button
( ).
Working with Data 645
Working with Thresholds
The Edit Permissions for Threshold area appears in the Manage Thresholds
dashboard.
The Add Role Permission or Add User Permission dialog box appears.
646 Foglight
Administration and Configuration Guide
b In the dialog box that appears, use the Read, Write, and Control check boxes
to assign permissions as required, and click Save.
The dialog box closes and the selected entry refreshes, showing three check
marks in the Permission columns, one for each of the read, write, and control
permissions.
Permission granted
Permission denied
The Edit Role Permission or Edit User Permission dialog box appears.
Working with Data 647
Working with Thresholds
b To edit the permissions, ensure that the Edit option is selected and use the
Read, Write, and Control check boxes as required.
c To delete the permissions, select the Delete option
d Click Save.
The dialog box closes and the selected entry refreshes, showing the newly-
edited permissions.
Deleting thresholds
Use the Delete Selected button on the Manage Thresholds dashboard to delete a
threshold, as outlined below.
Note When a threshold is deleted, all references to that threshold in rule conditions or derived
metric expressions become invalid. This may cause a rule to fail to evaluate. If this occurs,
you must manually modify the rule condition or expression.
To delete a threshold:
Note This procedure continues from “Accessing the Manage Thresholds dashboard” on
page 643.
1 In the Manage Thresholds dashboard, select the row containing the threshold that
you want to delete.
2 Click the Delete Selected button at the bottom.
The Delete Threshold dialog box appears.
648 Foglight
Administration and Configuration Guide
Note This procedure continues from “Accessing the Manage Thresholds dashboard” on
page 643.
1 In the Manage Thresholds dashboard, click the Metric column of the row
containing the threshold whose definitions you want to view.
The Edit Threshold view appears in the Manage Thresholds dashboard.
Working with Data 649
Working with Thresholds
The Edit Threshold view shows the topology type and its metric property for
which the threshold is defined, the selected threshold level, modification date,
and threshold bounds. Each threshold level comes with a unique set of pre-
defined bound levels. For example, the threshold level for the agent state includes
the bound levels that correspond to different agent states, such as Stopped,
Started, Running, and others.
2 Observe the threshold definitions.
3 Edit the threshold as required.
• To change the topology type, metric property, or the threshold level, use the
Topology Type, Metric, or Threshold Levels boxes, as required.
Caution Because each threshold level comes with a unique set of pre-defined bound
levels, changing any of these values may invalidate the existing threshold
bounds.
• To edit the threshold bounds, use the Threshold Bounds area. For complete
instructions, see “Adding bounds to threshold levels” on page 653.
650 Foglight
Administration and Configuration Guide
Creating Thresholds
You can add new thresholds to Foglight using the Create Threshold dashboard. You can
access this dashboard from the navigation panel, or through the Manage Thresholds
dashboard.
To create a threshold:
Defining Thresholds
Defining thresholds involves several steps. Once you get started with threshold creation,
you need to select the topology type and the metrics using that type for which you want
to define thresholds. Furthermore, you need to specify threshold levels and bounds, and
finally, view the threshold summary.
For instructions, see the following sections:
• “Selecting metrics and threshold levels” on page 651
• “Adding bounds to threshold levels” on page 653
1 Choose the topology type of the metric whose thresholds you want to set.
In the Create Threshold dashboard, in the Step 1: Create Threshold—Select
Metric area, click Topology Type and select the topology type from the list that
appears.
2 Choose the metric whose thresholds you want to set.
Click Metric and select the metric from the list that appears.
3 Click Next.
The Step 2: Create Threshold—Select Threshold Level area appears in the
Create Threshold dashboard.
652 Foglight
Administration and Configuration Guide
From here, you can proceed to “Adding bounds to threshold levels” on page 653.
AgentHealthState OK
Running Unexpectedly
Broken
AgentState Unknown
Stopped
Starting
Stopping
Running
Collecting data
AlarmChangeType Fire
Clear
Acknowledge
UserDefined Data
AlarmSeverity Undefined
Normal
Fire
Warning
Critical
Fatal
Working with Data 655
Working with Thresholds
CatalystServiceState Stopped
Stopping
Starting
Started
Failed
Destroyed
Created
Unregistered
Registered
HostDiscoveryStatus Active
Inactive
IncidentChangeType Create
Close
Acknowledge
Modify
Delete
ThresholdSeverity Normal
Critical
Fatal
Warning
656 Foglight
Administration and Configuration Guide
UnitGroupAutoScalingType smalestValue
Locale
You can have one or more types of threshold bounds in a threshold level. There are three
different types of threshold bound types:
The Foglight Management Server evaluates threshold bounds in the order that they are
listed, starting with the first one. Changing their order affects the output of actions that
are associated with those threshold levels.
For example, if a threshold level includes several threshold bounds that reference
standard Foglight severity levels in the ascending order such as Normal, Warning,
Critical, and Fatal, and you change their order in the list to Normal, Critical, Warning,
and Fatal, the Warning, the bound that is associated with the Warning level evaluates to
True only after the evaluation of the Critical level.
Working with Data 657
Working with Thresholds
The ranges of threshold levels are created by going over threshold bounds in the order
form first to last (from top to bottom in the Threshold Bounds table) and assigning the
threshold level of the bound to the range immediately above the threshold bound. In
some cases, their ranges do not always follow a progression sequence. This can happen
in cases where threshold bounds values are calculated in run-time. For example, a set of
threshold bounds can include a mix of constant values and baseline values. As a result,
the effective threshold ranges may be different at different time points. It is possible to
have valid configurations when threshold ranges minimize to zero '0' or even overlap.
When this happens, the default behavior causes the higher threshold level to be applied.
To ensure that the appropriate threshold level is applied when their ranges overlap, you
can either accept the default behavior, or define a precedence to override the level with a
higher value. This can be done with the Override flag. When set for a threshold bound,
this flag ensures that the threshold level associated with a particular threshold bound is
applied to incoming data even though its value overlap with a higher threshold level.
The example of this behavior is described in the following table.
There are no
threshold level
overrides set for
any of the threshold
bounds.
658 Foglight
Administration and Configuration Guide
Note This procedure continues from “Selecting metrics and threshold levels” on page 651 or
“Viewing and editing thresholds” on page 648.
3 Click Metric and select a metric from the list that appears.
4 Optional. Specify the standard deviation from the value that the selected metric
contains.
In the Number of Standard Deviation box, type the standard deviation.
5 Optional. If you want Foglight to acknowledge that the threshold is reached
when the threshold level exceeds the value of the binding metric, ensure that the
Inclusive check box is cleared.
If you want Foglight to acknowledge that the threshold is reached when the
threshold level reaches the value of the binding metric, check the Inclusive check
box.
6 Optional. If your threshold levels are expected to change over time, and you want
the associated threshold level to take precedence over any levels with that have a
higher value, select the Override check box.
For more information about this functionality, see “Adding bounds to threshold
levels” on page 653.
7 Click the Add button on the right of the Bound Type options.
The newly-created metric threshold bound appears in the Threshold Bounds
table.
660 Foglight
Administration and Configuration Guide
Note This procedure continues from “Selecting metrics and threshold levels” on page 651 or
“Viewing and editing thresholds” on page 648.
3 Click Registry Variable Name and select a variable from the list that appears.
4 Optional. If you want Foglight to acknowledge that the threshold is reached
when the threshold level exceeds the value of the binding registry variable, ensure
that the Inclusive check box is cleared.
Working with Data 661
Working with Thresholds
If you want the Foglight to acknowledge that the threshold is reached when the
threshold level reaches the value of the binding registry variable, check the
Inclusive check box.
5 Optional. If your threshold levels are expected to change over time, and you want
the associated threshold level to take precedence over any levels with that have a
higher value, select the Override check box.
For more information about this behavior, see “Adding bounds to threshold
levels” on page 653.
6 Click the Add button on the right of the Bound Type options.
The newly-created registry variable threshold bound appears in the Threshold
Bounds table.
Note The Baseline Threshold Bound option is only available after installing a baseline cartridge
that contains the baseline definitions for the selected metric property. A baseline illustrates
the behavior of a metric over time, allowing for its categorization into repeating patterns,
such as weekly, monthly, and so on, that can be charted, as required. A baseline cartridge
contains the definitions of one or more baselines for a particular metric. Agent developers
can write baseline cartridges followed by installing them on the Foglight Management
Server. When you add or edit a threshold for a metric, if a cartridge that contains baseline
definitions for that metric, the Baseline Threshold Bound option becomes available,
allowing you to use one or more metric baseline definitions in the selected metric’s
threshold definitions.
Note This procedure continues from “Selecting metrics and threshold levels” on page 651 or
“Viewing and editing thresholds” on page 648.
3 Select the baseline and a bound value from that baseline to which you want to
bind the selected threshold level.
The installed baseline cartridge contains one or more baseline definitions for the
selected metric. Each baseline contains one or more values that can be used as
threshold bounds.
a Click Baseline Name and select a baseline from the list that appears.
b Click Baseline Bound and select a baseline value that you want to use as a
threshold.
4 Optional. If you want Foglight to acknowledge that the threshold is reached
when the threshold level exceeds the value of the binding baseline value, ensure
that the Inclusive check box is cleared.
If you want the Foglight to acknowledge that the threshold is reached when the
threshold level reaches the value of the binding baseline value, check the
Inclusive check box.
5 Optional. If your threshold levels are expected to change over time, and you want
the associated threshold level to take precedence over any levels with that have a
higher value, select the Override check box.
For more information about this behavior, see “Adding bounds to threshold
levels” on page 653.
Working with Data 663
Working with Thresholds
6 Click the Add button on the right of the Bound Type options.
The newly-created baseline threshold bound appears in the Threshold Bounds
table.
Note This procedure continues from “Selecting metrics and threshold levels” on page 651 or
“Viewing and editing thresholds” on page 648.
3 Specify the value to which you want to bind the threshold level.
664 Foglight
Administration and Configuration Guide
In the Value box, type that value. This can be a positive or a negative value,
depending on the metric range.
4 Optional. If you want Foglight to acknowledge that the threshold is reached
when the threshold level exceeds the value of the binding registry variable, ensure
that the Inclusive check box is cleared.
If you want the Foglight to acknowledge that the threshold is reached when the
threshold level reaches the value of the binding registry variable, check the
Inclusive check box.
5 Optional. If your threshold levels are expected to change over time, and you want
the associated threshold level to take precedence over any levels with that have a
higher value, select the Override check box.
For more information about this behavior, see “Adding bounds to threshold
levels” on page 653.
6 Click the Add button on the right of the Bound Type options.
The newly-created registry variable threshold bound appears in the Threshold
Bounds table.
1 Ensure that the order of the bounds in the threshold bounds is valid.
Caution The Foglight Management Server evaluates threshold bounds in the order that
they are listed, starting with the first one. Changing their order affects the output
of actions that are associated with that threshold level.
Working with Data 665
Working with Thresholds
or
• New thresholds. Click Add.
A list appears in the display area, showing the threshold bounds for the
selected threshold level.
666 Foglight
Administration and Configuration Guide
Important Any changes to the retention policies that you make in the Data Management dashboard
apply to the collected data to help you adjust the current database size. The retention
policies specified in the Manage Retention Policies dashboard continue to apply to any
incoming data.
You create new retention policies and manage the existing ones using the Manage
Retention Policies dashboard. For complete information, see the following sections:
• “About Retention Policy Mechanisms” on page 668
• “Accessing the Manage Retention Policies Dashboard” on page 675
• “Deleting Retention Policies” on page 680
• “Viewing the Hierarchy of Topology Types in the Database Schema” on page 685
• “Editing Retention Policies” on page 688
• “Creating Retention Policies” on page 693
668 Foglight
Administration and Configuration Guide
• The third sets the granularity of data that live indefinitely (until a purge) in
generation 3
• Have 2 retention policies (including a purge), where:
• The first retention policy sets the granularity of data stored for up to 14 days in
generation 1 and/or generation 2
• The second sets the granularity of data that live indefinitely (until a purge) in
generation 3
• Have 1 retention policy (including a purge), where
• The first retention policy sets the granularity of data that will live indefinitely
(until a purge) in generation 1, 2 or 3.
Database roll-ups
A nightly roll-up job aggregates data and writes that data to generations 2 and 3. The
roll-up is only done once a day, according to the time set in the Daily Database
Maintenance schedule. For more information about schedules in Foglight, see
Chapter 8, “Using Schedules”.
Policies can be set at an object level; however, retention policies also adhere to the
object inheritance capabilities. If a policy has not been explicitly assigned to an object,
it inherits a value from a higher level in the model. The top-level object is
TopologyObject.
The policy that is applied to TopologyObject, and therefore any object which does
not have explicitly assigned policies, is as follows:
Policy Translates to
Age 4 hours Data older than four hours is eligible for roll-up (they are
actually only rolled up once a day during the database roll-
Roll-up 1 hour up) to one-hour averages and persisted into Generation 2
(where they are stored for 14 days)
Age 5 days Data older than 5 days old is eligible for Roll-up (they are
actually only rolled up once per day during the database
Roll-up 4 hours roll-up) to four-hour averages and persisted into
Generation 3 indefinitely
The illustration below shows the interaction between the TopologyObject retention
policy and the default generation definitions.
Working with Data 671
Managing Retention Policies
Figure 3
Note Individual cartridges frequently have their own policies which must be examined on
individual object level to understand that retention policy behavior.
As indicated in the above diagram, any data whose retention policies include the purge
settings is stored in the Generation 3 aggregation, from which it is purged in accordance
with the purge settings. Purging from the last generation is done by recreating the tables
to filter out the observations that are to be purged, and it occurs once a month for each
configured purge setting. For example, if there are n policies that request a purge after
12 months and m policies that request a purge after 18 months, then at the start of the
month, Foglight performs a single purge on the 12-month tables and a single purge on
the 18-month tables. In case your business requirements dictate that any data older than
x months should be purged from the database, the most efficient implementation is to
edit the Generation 3 setting in <foglight_home>/config/storage-config.xml, whose
default length is set to one hundred years, to x months. For example, the following code
block illustrate a Generation 3 setting in storage-config.xml that dictates the purge of
any data that is older than six months:
<generation>
<timeslice-size length="1" unit="MONTH" />
<generation-size length="6" unit="MONTH" />
</generation>
672 Foglight
Administration and Configuration Guide
Level 2 > 15 minutes Any roll-up The age date for the Level 2 policy
and < 3 days greater than must be less than or equal to three
Level 1 days. Data is persisted at the roll-
up interval defined in the Level 2
policy for 14 days.
Level 3 > Level 2 Any roll-up The age date for the Level 3 policy
setting and < greater than must be less than or equal to 14
14 days Level 2 days. Data is persisted at this roll-
up interval indefinitely. A purge
policy defines a minimum length
of time that data must persist
before it is truncated.
Level 2 <= 14 days Any roll-up The age date for the Level 2 policy
greater than must be less than or equal to 14
Level 1 days. Data is persisted at this roll-
up interval indefinitely. A purge
policy defines a minimum length
of time that data must persist
before it is truncated.
Important Any changes to the retention policies that you make in the Data Management dashboard
apply to the collected data to help you adjust the current database size. The retention
policies specified in the Manage Retention Policies dashboard continue to apply to any
incoming data.
On the Manage Retention Policies dashboard, the Age column specifies the amount of
time allotted for data collection. The roll-up period defines the granularity of the
collection period. For example, if age is defined as one minute, and the roll-up period is
defined as five minutes, any data older than one minute is eligible to be aggregated into
the five-minute roll-up period.
Caution The first period in the retention policy specifies the aggregation that is performed before
the raw data is persisted. Therefore, the age determines how long raw samples remain
in memory before being persisted. In order to constrain the server’s memory usage, the
age specified for the first roll up period should not be too large. Settings larger than 30
minutes should be carefully considered.
Caution The roll-up period of the first retention policy period determines the amount of the initial
aggregation. If you do not want any aggregation to be performed, this can be set to 0 ms.
If not set to zero, this setting should not be too small, as it increases the amount of
processing performed by the server. A setting smaller than 30 seconds should be
carefully considered.
676 Foglight
Administration and Configuration Guide
For metrics, the aggregation retains the count, minimum, maximum, sum, average, and
standard deviation of the aggregated values. For other observation types, aggregation is
a sampling process that retains the latest value per time slice.
The default roll-up period is 15 minutes; therefore any raw data older than 15 minutes is
rolled up to the next period.
If a topology type references the default data storage cycle, its retention policies cannot
be modified or deleted. The default data storage cycle can be modified using the Data
Management dashboard. For more information about this dashboard, see the Foglight
User Guide. Any types descending from that type that inherit its retention policies can
have their retention policies modified or deleted. This also applies to the descendants
that have custom retention policies.
This prevents any accidental modifications of default observation life cycles through the
Manage Retention Policies dashboard. For example, the retention policies of the
TopologyObject super-type reference the default cycle, and as such, cannot be
modified. The TopologyMergeRule type is a descendent of TopologyObject which
inherits the retention policies of the ancestor type; those policies can be modified or
deleted using the Manage Retention Policies dashboard. Modifying the
TopologyMergeRule‘s retention policy, inherited from TopologyObject, creates a
custom policy. The TaskManager type, also a descendant of TopologyObject, has a
custom retention policy; this policy can be modified or deleted as required. The Manage
Retention Policies dashboard indicates whether a type directly references the default
storage cycle, inherits policies from another type, or has its own custom policies.
Working with Data 677
Managing Retention Policies
Figure 4
3 To sort the list of retention policies by the topology type to which they apply,
click the Topology Type—Property Name column heading as required.
4 Optional. Filter the retention policies by the subset of topology types for any
installed cartridges in your monitoring environment. Use this filter to search for,
isolate, and apply policies on the basis of each individual case.
Working with Data 679
Managing Retention Policies
In the Filter area, click By Cartridge and select the cartridge from the list that
appears.
The Manage Retention Policies dashboard refreshes, showing only those
topology types that exist in the specified cartridge.
Example. If you have the OS Cartridge installed and you want to look up the
retention policy for the Windows_System_Top_CPU_Table, use the agent
name, OS-Windows_System, as the filter.
The list of topology types refreshes, showing the tables that come with the
selected agent, including the Windows_System_Top_CPU_Table.
• “Viewing the Hierarchy of Topology Types in the Database Schema” on page 685
• “Editing Retention Policies” on page 688
• “Creating Retention Policies” on page 693
Important Deleting an inherited policy requires a conversion of that policy and all of its sibling policy
to custom policies before it can be deleted.
For example, the retention policies of the TopologyObject super-type reference the
default cycle, and as such, cannot be modified. The retention policy of any
TopologyObject descendents that inherit its default policy can be deleted after its
conversion to a custom policy. Any custom policies are enabled for deletion by default.
To delete a retention policy:
Note This procedure continues from “Accessing the Manage Retention Policies Dashboard” on
page 675.
1 Topology types with inherited retention policies only. Convert the inherited
retention policy to a custom policy.
Tip Placing the mouse cursor over the Age or Roll-up Period column indicates if the policy
is inherited from another topology type.
Working with Data 681
Managing Retention Policies
Any inherited default policies cannot be selected for deletion unless they are converted
to custom policies.
The Add Retention Policy dialog box closes and the Manage Retention
Policy refreshes, showing a set of check boxes on the right of each sampling
period, allowing you to select them for deletion.
682 Foglight
Administration and Configuration Guide
Tip Inherited policies cannot be selected. An inherited policy can be deleted after its
conversion to a custom policy. For more information, see step 1.
Figure 6
3 Ensure that the Schema Browser shows the core topology types.
On the navigation panel, under Schema Selector, verify if the Foglight entry is
selected.
4 Observe the list of topology types that appear in the Schema Browser dashboard.
5 Select a topology type in the upper pane of the Schema Browser and review its
details in the lower pane.
For example, to look at the details of the Alarm topology type, in the list
appearing in the upper pane, click the Alarm entry.
The lower pane shows the details of the Alarm topology type.
688 Foglight
Administration and Configuration Guide
To find out the ancestors of the selected topology type, at the top of the lower
pane, on the right of View by, click Ancestors.
The lower pane refreshes, showing the ancestors of the selected topology types.
When you find out the hierarchy of the topology type whose retention policies you want
to edit, you can proceed to “Editing Retention Policies” on page 688. For additional
complete information about the Schema Browser dashboard, see the Foglight User
Guide.
Any types descending from TopologyObject that inherited its retention policies can
have their retention policies modified. This also applies to the descendants that have
custom retention policies.
Important Modifying an inherited policy requires a conversion of that policy and all of its sibling
policy to custom policies before it can be modified.
For example, the retention policies of the TopologyObject super-type reference the
default cycle, and as such, cannot be modified. The retention policy of any
TopologyObject descendents that inherit its default policy can be modified after its
conversion to a custom policy. Any custom policies are enabled for edits by default.
To edit the default retention policy period:
Note This procedure continues from “Accessing the Manage Retention Policies Dashboard” on
page 675.
1 Topology types with inherited retention policies only. Convert the set of
inherited retention policy to custom policies.
Tip Placing the mouse cursor over the Age or Roll-up Period column indicates if the policy
is inherited from another topology type.
Inherited default policies cannot be selected unless they are converted to custom
policies.
The Add Retention Policy dialog box closes and the Manage Retention
Policy refreshes, showing a set of check boxes on the right of each sampling
period, allowing you to select them for deletion.
3 Review the retention policies for the type or property whose retention policies
you want to edit.
Tip Inherited policies cannot be selected for deletion. An inherited policy can be deleted
after its conversion to a custom policy. For more information, see step 1.
4 Expand the node representing that type or property to see its retention periods.
One or more policies appears under the selected node.
692 Foglight
Administration and Configuration Guide
The Edit Retention Policy Period dialog box closes and a message appears in
the upper-left, indicating the success of the edit operation.
Important Adding a new policy to a set of inherited policies for a type or property converts all of the
policies of that type or property to custom properties, including the existing inherited
policies and the newly-created policy.
For example, the retention policies of the TopologyObject super-type reference the
default cycle. You cannot add new retention policies to that topology type. The retention
policy of any TopologyObject descendents that inherit its default policy can be
694 Foglight
Administration and Configuration Guide
Note This procedure continues from “Accessing the Manage Retention Policies Dashboard” on
page 675.
1 On the Manage Retention Policies dashboard, click the topology type to which
you want to add a new retention policy.
The Add Retention Policy dialog box appears.
2 Topology types with one or more inherited retention policies only. Ensure that
the retention policy that you are about to create does not overwrite any inherited
policies by making sure that the Copy inherited retention policy check box is
selected in the Add Retention Policy dialog box.
Note This check box appears in the Add Retention Policy dialog box only if the selected
type includes any inherited retention policies.
Working with Data 695
Managing Retention Policies
Specify the data sampling and roll-up or purging parameters periods for the
newly-added retention period using the controls in the After and Roll-up to
columns.
To delete a retention period from the table, use the red Delete button ( ).
6 Click Save.
The Edit Retention Policy Period dialog box closes and a message appears in
the upper-left, indicating the success of the edit operation.
696 Foglight
Administration and Configuration Guide
Note If the roll-up period is less than one day, the roll-up period must be a multiple of the previous
roll-up period value.
Note You cannot define two identical data sampling periods for the same topology type or
property.
Working with Data 697
Enabling the Collection of Data with Older Timestamps
This chapter introduces you to the Tooling dashboards and provides information on how
to build script agents and use the query tool. It contains the following sections:
Note In order to complete each of the procedures in this chapter, your user account must belong
to a group with the Administration role. For more information about users, groups, and roles,
see “Managing Users and Security” on page 197.
For a sample of a Type 1 script in this manual, see “Example: Type 1 Script” on
page 719.
Additionally, sample Type 1 scripts are also available from the Foglight
Management Server installation directory:
Windows
<foglight_home>/scripts/agent/Type1_NT_Script.bat
Unix
<foglight_home>/scripts/agent/Type1_Unix_Script.bat
• Type 2 scripts. These scripts control their own collection frequency cycle. In Type
2 scripts, the Foglight collector executes the script and remains open. The script
controls the standby period instead of the agent properties. Type 2 scripts perform
data calculations before the data enters the database and measure changes
between collection periods.
For a sample of a Type 2 script in this manual, see “Example: Type 2 Script” on
page 720.
Additionally, a Windows version of the Type 2 script is also available from the
Foglight Management Server installation directory:
<foglight_home>/scripts/agent/Type2_NT_Script.bat
Building a script agent involves several steps. First, you need to write an agent script
using a particular syntax, upload it using the Build Script Agent dashboard. The upload
process automatically builds the agent package. Next, you deploy that agent package to
the Foglight Agent Manager, create one or more agent instances as required, and edit
agent properties if required. For complete instructions, see the following sections:
• “Looking at the Script Syntax” on page 701
• “Accessing the Build Script Agent Dashboard” on page 704
• “Uploading Agent Scripts and Building Agent Packages” on page 705
• “Deploying Script Agent Packages” on page 707
• “Creating and Activating Script Agent Instances” on page 710
• “Editing Script Agent Properties” on page 717
TABLE table_name
START_SAMPLE_PERIOD
field_name[.type[.{id|obs}]][:unit]=value
…
END_SAMPLE_PERIOD
…
END_TABLE
…
Note The ellipsis ‘…’ indicates that you can repeat the level.
A Canonical Data Transformation (CDT) dynamically converts the output data into the
appropriate format (such as topology types and observations) that exist in the collection
model. This mechanism dictates the syntax of the line of the code that specifies the field
data immediately following the START_SAMPLE_PERIOD command, as shown in the
above syntax block:
START_SAMPLE_PERIOD
field_name[.type[.{id|obs}]][:unit]=value
The following table describes the script elements, some of which appears in the above
block.
START_SAMPLE_PERIOD Starts the data collection for the specified table and
inserts field data using the line of code that
immediately follows this command.
TABLE table_name Opens the table with table_name specifying the
name of the table. If an identity field is declared,
append it to the table name.
When you finish writing the agent script, you can proceed to “Accessing the Build
Script Agent Dashboard” on page 704.
704 Foglight
Administration and Configuration Guide
From here, you can go to “Uploading Agent Scripts and Building Agent Packages” on
page 705.
Working with Foglight Tooling 705
Building Script Agents
Note This procedure continues from “Accessing the Build Script Agent Dashboard” on page 704.
3 Ensure that the version number of the script agent that you are about to upload is
correct.
To change the version number, use the Script Version boxes as required.
4 Upload the script and build the agent.
Click Submit.
The Confirm Script Upload dialog box appears, asking you to confirm the build
operation.
706 Foglight
Administration and Configuration Guide
The Confirm Script Upload dialog box shows that the agent you are about to
create includes two components: an agent component and a cartridge component.
That is because in Foglight each agent requires a cartridge component that
contains topology definitions and default agent properties while the agent
component acts as a data collector. When you create script-based agents, the
name and version number of the agent component are identical to the name and
version number of the cartridge component.
5 In the Build Script Agent dialog box, click Build.
Note Foglight checks the collection of the existing cartridge list and displays a warning
message if duplicate cartridges exist. If it finds a cartridge with the same name and
version, the Confirm button appears disabled and a warning message appears. If a
cartridge with the same name but different version exists, a warning message
appears but the Confirm button is enabled. In this case, Foglight disables the
existing cartridge during the installation of the new cartridge.
The Confirm Script Upload dialog box closes. A progress bar in the Build Script
Agent dashboard indicates that the upload operation is in progress. After a few
moments, the Build Script Agent dialog box appears, indicating the success of
the build operation.
6 In the Build Script Agent dialog box, click Continue to Agent Status.
Working with Foglight Tooling 707
Building Script Agents
The Agent Status area appears in the Build Script Agent dashboard.
From here, you can proceed to “Deploying Script Agent Packages” on page 707.
Note This procedure continues from “Uploading Agent Scripts and Building Agent Packages” on
page 705.
708 Foglight
Administration and Configuration Guide
1 On the Build Script Agent dashboard, in the lower-left corner of the Agent Status
area, click Deploy Agent Package.
The Agent Status area appears in the Build Script Agent dashboard.
The Deploy Agent Package dialog box appears.
2 Specify the monitored host to which you want to deploy the agent package.
Note In order to select the agent adapter, the adapter must be up and running on the
monitored host.
Tip To deploy an agent package to multiple hosts, navigate to the Agent Hosts dashboard
by clicking Agent Hosts in the Deploy Agent Package dialog box. For more
information, see Chapter 6, “Deploying Agent Packages to Multiple Hosts” on
page 345.
In the Deploy Agent Package dialog box, click Host and select the monitored
host to which you want to deploy the agent package.
3 Select the script agent package.+
Click Package and select the script agent package that you created in “Uploading
Agent Scripts and Building Agent Packages” on page 705 from the list that
appears.
Working with Foglight Tooling 709
Building Script Agents
After a few moments, in the Deploy Agent Package dialog box, in the Status
column of the Progress table, a green check mark appears, indicating a success of
the deployment operation.
710 Foglight
Administration and Configuration Guide
Note This procedure continues from “Deploying Script Agent Packages” on page 707.
Working with Foglight Tooling 711
Building Script Agents
1 In the Build Script Agent dashboard, in the Agent Status area, click the Create
Agent button in the lower-left corner.
The Create Agent dialog box appears.
Tip To create script agent instances on multiple hosts, navigate to the Agent Hosts
dashboard by clicking Agent Hosts in the Create Agent dialog box. For more
information, see Chapter 6, “Deploying Agent Packages to Multiple Hosts” on
page 345.
2 Specify the host that you want to monitor with the script-based agent instance that
you are about to create.
Note In order to select the host, the Foglight Agent Manager must be up and running on
the monitored host.
In the Create Agent dialog box, click Host and select the monitored host
computer.
The Agent Type box refreshes, showing a list of agent types that can be created
on the selected host. The script agent package that you deployed to the monitored
host in “Deploying Script Agent Packages” on page 707 appears in the list.
712 Foglight
Administration and Configuration Guide
The list reflects the cartridges that have been installed, enabled, and deployed to
the monitored host.
3 Select the script agent to use as a type for the agent instance you are about to
create.
Note You can only create instances of those agents whose types have already been
deployed to the monitored host.
In the Agent Type box, click script agent type whose package you deployed in
“Deploying Script Agent Packages” on page 707.
For example, MyScriptAgent/MyScriptAgent.
4 Specify the name of the agent instance that you are about to create.
• To assign a specific name to the agent instance, in the Instance Name box,
type that name. For example, MyAgent.
or
• To assign a generic name, select the Generate Name check box.
5 Click Create.
The Create Agent dialog box closes and the Create Agent Results dialog box
appears, showing the status of the operation.
Working with Foglight Tooling 713
Building Script Agents
After a few moments, in the Create Agent Results dialog box, in the Status
column of the Progress table, a green check mark appears, indicating a success of
the operation.
714 Foglight
Administration and Configuration Guide
After a few moments, in the Agent Operation dialog box, in the Status
column of the Progress table, a green check mark appears, indicating a
success of the operation.
716 Foglight
Administration and Configuration Guide
Note It may take some time for the Activated ( ) and Collecting Data ( ) icons to appear even if
activation of the agent was successful.
The Activated icon appears when the Management Server has confirmed that the agent has
started and is running.
If the activation command was executed successfully but the agent fails after starting, the
Activated icon will not appear.
Working with Foglight Tooling 717
Building Script Agents
Note This procedure continues from “Deploying Script Agent Packages” on page 707.
1 On the Build Script Agent dashboard, in the Agent Status area, select the row
containing the script agent whose properties you want to edit.
2 Click the Edit Properties button at the bottom.
The Build Script Agent dashboard refreshes, showing the properties of the
selected script agent instance.
718 Foglight
Administration and Configuration Guide
Note The type and range of script agent properties depends on the script that you used to
build the agent.
4 In the agent properties area, edit the script agent properties as required.
Working with Foglight Tooling 719
Building Script Agents
Tip Additionally, sample Type 1 scripts are also available from the Foglight Management Server
installation directory:
Windows
<foglight_home>/scripts/agent/Type1_NT_Script.bat
Unix
<foglight_home>/scripts/agent/Type1_Unix_Script.sh
@echo off
if not "%ECHO%"=="" echo %ECHO%
if not "%OS%"=="Windows_NT" goto EXIT
if "%sample_freq%"=="" set sample_freq=60
echo LOG Start collecting data for NT at %sample_freq% seconds
echo TABLE NT
echo START_SAMPLE_PERIOD
echo FooId.String.id = Bar
echo stringProp.String = This is a non-identity string property.
echo intProp.Integer = 30
echo countMetric = 40
echo timeMetric:second = 50
echo rateMetric:count/second = 50
echo fancyMetric:[4 kilobyte] = 50
echo intWithUnit.Integer:[minute] = 60
echo stringObs.StringObservation.obs = Hello World
echo END_SAMPLE_PERIOD
echo START_SAMPLE_PERIOD
echo FooId.String.id = Another Bar
echo stringProp.String = This is a non-identity string property.
echo intProp.Integer = 31
echo countMetric = 41
echo timeMetric:second = 51
echo rateMetric:count/second = 51
echo fancyMetric:[4 kilobyte] = 51
720 Foglight
Administration and Configuration Guide
echo intWithUnit.Integer:minute = 61
echo stringObs.StringObservation.obs = abc
echo END_SAMPLE_PERIOD
echo END_TABLE
Tip Additionally, a Windows version of the Type 2 script is also available from the Foglight
Management Server installation directory:
<foglight_home>/scripts/agent/Type2_NT_Script.bat
@echo off
if not "%ECHO%"=="" echo %ECHO%
if not "%OS%"=="Windows_NT" goto EXIT
if "%sample_freq%"=="" set sample_freq=60
echo LOG Start collecting data for NT at %sample_freq% seconds
:Loop
echo LOG New sample is available
echo TABLE NT
echo START_SAMPLE_PERIOD
echo FooId.String.id = Bar
echo stringProp.String = This is a non-identity string property.
echo intProp.Integer = 30
echo countMetric = 40
echo timeMetric:second = 50
echo rateMetric:count/second = 50
echo fancyMetric:[4 kilobyte] = 50
echo intWithUnit.Integer:[minute] = 60
echo stringObs.StringObservation.obs = Hello World
echo END_SAMPLE_PERIOD
echo START_SAMPLE_PERIOD
echo FooId.String.id = Another Bar
echo stringProp.String = This is a non-identity string property.
echo intProp.Integer = 31
echo countMetric = 41
echo timeMetric:second = 51
echo rateMetric:count/second = 51
echo fancyMetric:[4 kilobyte] = 51
echo intWithUnit.Integer:minute = 61
Working with Foglight Tooling 721
Retrieving Data with Queries and Scripts
• Instance names
• Object IDs
• Object type hierarchies
• Object properties, including:
• Unique ID
• Object ID
• ID
• Version
• Effective start date
To select topology objects:
Note This procedure continues from “Accessing the Script Editor Dashboard” on page 721.
The Object Type Hierarchy area displays the hierarchical relationship between
the selected topology type and its parent types. The parent types appear as
selectable items in the hierarchical listing. If you click on any of the parent types,
the Instances box refreshes, showing the entire set of instances for the parent
type.
4 Observe the object properties.
Use the scroll bar on the right to view the values contained in the object
properties.
From here, you can go to “Retrieving Data” on page 725.
Working with Foglight Tooling 725
Merging Host Objects
Retrieving Data
Once you retrieve information about one or more topology objects, you can run scripts
against a selected topology object and retrieve the data that it contains as required.
The Script Editor dashboard allows you to write and run scripts using the Foglight query
language and process scoping queries against one or more topology objects that exist in
your monitoring system.
The query language allows you to specify the scope for a rule or derived metric. A rule
or derived metric must be scoped to a topology type and can optionally be scoped to
specific instances (topology objects) of that type. The expression that sets the rule or
derived metric scope is called a scoping query. For more information about the query
language, see “Using the Query Language” on page 763.
To retrieve data:
Note This procedure continues from “Selecting Topology Objects” on page 722.
1 Using the Groovy language, write a script to retrieve information about the
selected object. For information about the Groovy language, see“Using the Query
Language” on page 763.
In the Script Editor dashboard, in the Script box, type your script.
2 Run your script.
Click Run.
The Result area refreshes, showing the data retrieved as a result of your script.
• Simple merging rules consist of a stand-alone rule. They are used to merge one or
more host objects, or to rename a host object in the model.
• Advanced merging rules consist of a group of individual rules that are executed in
a pre-defined order. They are used to merge one or more topology objects and are
as such more complex. For example, merging two agent instances involves a rule
for transforming the instance name and another one for merging the two
instances, as illustrated below.
Figure 1
Simple merging
rules
Advanced
merging rule
Merging rules are useful in situations when a host name changes and there is a need to
consolidate the data under a single host object. For example, the Foglight Agent
Manager component is installed on a host whose name is Toronto123. The host
reports into Foglight as Toronto123, which creates a new topology object,
Toronto123, of the Host type. A system administrator modifies the host's
configuration which causes Toronto123 to start reporting itself using its IP address,
10.1.234.56. When the Foglight Agent Manager collects information from the
newly-renamed host, a new Host object is created on the server, with the name
10.1.234.56. The Foglight administrator notices the problem and creates an alias for
the host 10.1.234.56, mapping it to its original name, Toronto123.
Important Changing host names is reflected in the data collection model and any dashboards
associated with it, but not in the Agent Hosts dashboard which shows the actual host
names.
Use the Manage Host Aliasing Rules dashboard to create host aliasing rules or to
manage the existing ones. For complete information, see the following sections:
• “Accessing the Manage Host Aliasing Rules dashboard” on page 727
• “Managing Host Aliasing Rules” on page 727
• “Creating Host Aliasing Rules” on page 735
Working with Foglight Tooling 727
Merging Host Objects
If any existing host aliasing rules already exist, they are listed on the Manage
Host Aliasing Rules dashboard. For each host aliasing rule, the list shows the
object type it applies to and its priority.
3 To sort the list by the rule name, object it applies to, or priority, click the Brief
Description, Apply to, or Priority column headings, as required.
4 To filter the list, use the Search box.
a To enable regular expressions in your search, move the mouse pointer over the
Search box, and select the Use Regular Expressions check box that appears.
b Specify the text string that you want to use as the search filter.
Working with Foglight Tooling 729
Merging Host Objects
In the Search box, type a text string that you want to use as a search filter,
such as a full or partial (regular expressions only) brief description, priority, or
the target object type, followed by clicking Search.
For example, to search for a rule whose priority is 2.0, in the Search box, type
2.0, and click Search.
The Manage Host Aliasing Rules dashboard refreshes, showing one or more
rules that match the filter pattern.
Figure 2
For more information about the differences between simple and advanced merging
rules, see “Merging Host Objects” on page 725.
Additionally, changing the priority of a rule can affect the order in which other rules are
executed, as illustrated in the following example:
Rule Priority before the change Change Priority after the change
Note In the above example, as the priority of rule B decreases to 4.0, the priority of rule C
increases from 4.0 (the value now assigned to rule B) to 3.0.
Use the Priority column on the Manage Host Aliasing Rules dashboard to change the
priority of a simple merging rule or a group of rules within an advanced merging rule, as
required.
To change the priority of a host aliasing rule:
Note This procedure continues from “Accessing the Manage Host Aliasing Rules dashboard” on
page 727.
732 Foglight
Administration and Configuration Guide
1 On the Manage Host Aliasing Rules dashboard, locate the row containing the
simple or advanced rule whose priority you want to edit.
Important You can only edit the priority of a simple merging rule or an advanced merging
rule consisting of individual rules. The priorities of individual rules with a group
(advanced merging rules) are assigned automatically on rule creation and as such
cannot be changed. A priority action icon appears on the right of an editable priority .
Clicking the Priority column of a rule that is a part of a group shows the following
message:
The dwell closes, and the list of rules in the Manage Host Aliasing dashboard
refreshes, showing the newly-updated rule priority.
For more information about the differences between simple and advanced merging
rules, see “Merging Host Objects” on page 725.
Use the Rename column on the Manage Host Aliasing Rules dashboard to rename a
host aliasing rule.
Figure 3
Note This procedure continues from “Accessing the Manage Host Aliasing Rules dashboard” on
page 727.
1 On the Manage Host Aliasing Rules dashboard, locate the row containing the host
aliasing rule that you want to rename.
2 In that row, click the Rename column .
The Change Rule Display Name Form dialog box appears.
Use the button on the Manage Host Aliasing Rules dashboard to remove a host
aliasing rule.
To delete a host aliasing rule:
Note This procedure continues from “Accessing the Manage Host Aliasing Rules dashboard” on
page 727.
1 On the Manage Host Aliasing Rules dashboard, locate the row containing the host
aliasing rule that you want to delete.
2 Mark the rule for deletion.
In that row, select the check box on the left of the rule name.
3 Remove the rule marked for deletion.
At the top of the rule list, click Delete.
The Confirm Delete dialog box appears.
Note Property matching filters can only reference a subset of the entire property set for a
topology type such as String or Boolean properties. To see a full set of properties that are
included in Host or other types of topology types, view the Schema Browser dashboard; for
more information about this dashboard, see the Foglight User Guide.
The merging process is in effect only while the merging rules exist and are active while
the data consolidation resulted from a merging rule is permanent. For example, creating
a rule that merges a source host with a target host results in the source host’s data being
consolidated with the target host’s data, which is not only reflected in the data collection
model, but also in any dashboards that display host-related data such as the Agents
dashboard. When the rule is deleted, the data collected from the source host before the
rule deletion still appears as collected by the target host, while the data collected after
the deletion is stored under each individual host. For more information on how to delete
rules, see “Deleting host aliasing rules” on page 734.
Important Creating new topology objects does not delete any existing objects from the data model.
Based on their complexity, there are two types of host aliasing rules:
• Rules for merging hosts
• Rules for renaming or changing other properties of host objects
The button on the Manage Host Aliasing Rules dashboard invokes the New
Merging Rule Introduction dialog box that shows three options, one for each rule type.
736 Foglight
Administration and Configuration Guide
Choosing each option starts a unique flow that takes you through the rule creation
process, step by step. The nature and complexity of the rule creation process depends on
the rule type. For example, if you choose to merge one host object with another, you
specify the names of the host object while the process of merging two or more topology
objects which results in a creation of a stand-alone rule. Merging two hosts based on a
property matching logic requires you to specify a more complex property matching
filter, and results in a creation of an advanced rule containing two or more individual
rules.
This section describes the process of getting started with the creation of host aliasing
rules by choosing the rule type, and points you to the sections that describe the creation
of each of the two rule types (rules for merging hosts, or renaming or changing other
properties of host objects) in more detail.
To get started with the creation of a host aliasing rule:
Note This procedure continues from “Accessing the Manage Host Aliasing Rules dashboard” on
page 727.
Working with Foglight Tooling 737
Merging Host Objects
2 Choose the type of the rule that you want to create by clicking one of the
following options in the New Merging Rule Introduction dialog box:
Merge two host Create a focused rule for “Merging host objects” on
objects a single host page 738
Note Choosing this option results in a creation of one or more objects without deleting
the existing objects whose properties are about to be changed.
When you make a selection, the New Merging Rule Introduction dialog box
closes and the Host Aliasing dialog box appears. The appearance of the Host
738 Foglight
Administration and Configuration Guide
Aliasing dialog box depends on the rule type selection. For additional
information, refer to the sections listed in the table above.
Note Property matching filters can only reference a subset of the entire property set for a
topology type such as String or Boolean properties. To see a full set of properties that are
included in Host or other types of topology types, view the Schema Browser dashboard; for
more information about this dashboard, see the Foglight User Guide.
Important The merging process is in effect only while the merging rules exist and are active while
the resulted data consolidation is permanent. For more information, see “Creating Host
Aliasing Rules” on page 735.
Selecting the Create a focused rule for a single host option in the New Merging Rule
Introduction dialog box invokes the Specify Target Host workflow for creating a host
merging rule.
Working with Foglight Tooling 739
Merging Host Objects
Figure 4
From there, you specify the target host and the source host, and finally review the
summary of the merge process, as described below.
To merge host objects:
Note This procedure continues from “Creating Host Aliasing Rules” on page 735.
Optional. To use a different property, in the Host Aliasing dialog box, click
Name: String. From the list that appears, click the row containing the desired
property.
740 Foglight
Administration and Configuration Guide
Important The list that appears shows only a subset of the entire property set for the
host object. This is because property matching filters can only reference
certain types of properties such as String or Boolean properties. To see a full
set of properties that exist in the Host type, view the Schema Browser
dashboard; for more information about this dashboard, see the Foglight User
Guide.
Tip To look for a particular property, use the search filter at the top of the list.
The property list closes and the newly-selected property name and its data type
appear in the Host Aliasing dialog box. For example, selecting the
domainName property shows Domain Name: String in the dialog box.
The same property you select here to specify the target host is used to match
the source host in step 2 on page 742.
b Specify the value of the selected property that you want to use as a search
filter.
In the Host Aliasing dialog box, in the box on the left of the Look up button,
type the value that you want to search for in the host objects that exist in the
data collection model. For example, to look for a host object whose name is
Working with Foglight Tooling 741
Merging Host Objects
Tip To look for a particular property value, use the search filter at the top of the list.
Close Host Finder dialog box. The Host Aliasing dialog box refreshes,
showing the selected property value.
The Specify Source Host page contains the information about the target host.
Tip To select a different target host, click Previous to return to the Specify Target
Host page.
2 Specify a source host object using the host object property you selected in step 1,
sub-step a.
a In the Host Aliasing dialog box, on the Specify Source Host page, in the box
on the left of the Look up button, type the value that you want to search for in
the host objects that exist in the data collection model. For example, to look
for a host object whose name is mysourcehost.mydomain.com, with the
name property selected (Name: String, see step 1, sub-step a), type
mysourcehost.mydomain.com into the box.
Optional. To choose from the values of the selected property in the existing
host objects, click Look up. In the Host Finder dialog box that appears, select
the row containing the desired value, followed by closing the dialog box.
Working with Foglight Tooling 743
Merging Host Objects
Tip To look for a particular property value, use the search filter at the top of the list.
Click Close to close the Host Finder dialog box. The Host Aliasing dialog
box refreshes, showing the selected property value.
The Summary page in the Host Aliasing dialog box contains information
about the source and target hosts. It also allows you to change the rule priority
and to instruct Foglight to stop processing any rules with a lower priority when
this rule executes (see the Stop processing lower priority rules when
successful check box, disabled by default). By default, this rule is placed at the
bottom of the priority queue. For example, if there are six existing host
aliasing rules, this rule is assigned the priority of 7 (see the Priority box). You
can also change the priority at a later time. For more information, see
“Changing the priorities of host aliasing rules” on page 730.
Optional. To change the rule priority or prevent the processing of the rules
with the lower priority, use the Priority box and Stop processing lower
priority rules when successful check box, as required.
Tip To select a different source host, click Previous to return to the Specify Source
Host page.
Note Property matching filters can only reference a subset of the entire property set for a
topology type such as String or Boolean properties. To see a full set of properties that are
included in Host or other types of topology types, view the Schema Browser dashboard; for
more information about this dashboard, see the Foglight User Guide.
Renaming host objects results in the creation of new host objects without deleting any
existing objects. When the rule is created, it instructs Foglight to consolidate any data
collected from the renamed hosts under the newly-created host objects.
Important The property changing process is in effect only while its rules exist and are active while
the resulted data consolidation is permanent. For more information, see “Creating Host
Aliasing Rules” on page 735.
Selecting the option Create a broad rule which works with many hosts in the New
Merging Rule Introduction dialog box invokes the Specify Matching Parameters
workflow for creating a rule that changes the names or other host properties. The Host
Aliasing dialog box includes several options that simplify the process of renaming host
properties, with each option having a unique flow.
746 Foglight
Administration and Configuration Guide
Figure 5
From there, you specify the current and target names, and review the summary of the
merge process, as described below.
Note This procedure continues from “Creating Host Aliasing Rules” on page 735.
1 In the Specify Matching Parameters page of the Host Aliasing dialog box,
select the option Remove characters from the end of a host name, followed by
clicking Next.
The Host Aliasing dialog box refreshes, showing the page Remove characters
from the end of a host name.
This page contains an example of how host names are truncated followed by a set
of controls that allow you to continue with the character removal.
Tip To use a different type of matching parameter, click Previous to return to the Specify
Matching Parameters page.
test_host_3.company_c.com No No
test_host_4.company_d.com No No
3 Specify the characters that you want to remove from the end.
In the Host Aliasing dialog box, in the Host Names start with box, type a literal
expression containing the characters that you want to remove from the host name.
For example:
my_host_2.company_b.com No No
The Host Aliasing dialog box refreshes, showing the Summary page.
Working with Foglight Tooling 749
Merging Host Objects
The Summary page in the Host Aliasing dialog box describes the character
renaming logic. It also allows you to change the rule priority and to instruct
Foglight to stop processing any rules with a lower priority when this rule executes
(see the Stop processing lower priority rules when successful check box,
disabled by default).
By default, this rule is placed at the bottom of the priority queue. For example, if
there are seven existing host aliasing rules, this rule is assigned the priority of 8
(see the Priority box). You can also change the priority at a later time. For more
information, see “Changing the priorities of host aliasing rules” on page 730.
To change the rule priority or prevent the processing of the rules with the lower
priority, use the Priority box and Stop processing lower priority rules when
successful check box, as required.
Caution Host aliasing rules include a system-level rule, adjustHostName, that
automatically restores host names if the entire domain name is removed. This
rule is hidden and as such does not appear in the browser interface. The rule
includes a default priority of one '1', while newly created rules have a default
priority of two '2' or lower, causing adjustHostName to override the removal
of domain names. For example, if you have a host called
example.mydomain.com, and want to remove the domain name,
.mydomain.com from that host name, adjustHostName reverts the
removal of the domain name. To successfully remove the entire domain name
from the host name, you must prevent adjustHostName from executing. This
750 Foglight
Administration and Configuration Guide
can be done by selecting the Stop processing lower priority rules when
successful option.
Tip To use a different replacement text or to select different hosts, click Previous to return
to the Remove Characters from the End of a Host Name page.
Note This procedure continues from “Creating Host Aliasing Rules” on page 735.
1 In the Specify Matching Parameters page of the Host Aliasing dialog box,
select the option Replace characters in a host name, followed by clicking Next.
The Host Aliasing dialog box refreshes, showing the page Replace characters
in a host name.
Working with Foglight Tooling 751
Merging Host Objects
This page contains an example of how host names are renamed followed by a set
of controls that allow you to continue with the character replacement.
Tip To use a different type of matching parameter, click Previous to return to the Specify
Matching Parameters page.
test_host_3.domain_c.com No No
test_host_4.domain_d.com No No
752 Foglight
Administration and Configuration Guide
Alternatively, to select all hosts, select the Any host check box.
3 Specify the replacement text.
In the Host Aliasing dialog box, in the Replace With box, type a literal
expression containing the characters that you want to use as the replacement text.
For example:
The Host Aliasing dialog box refreshes, showing the Summary page.
The Summary page in the Host Aliasing dialog box describes the character
renaming logic. It also allows you to change the rule priority and to instruct
Foglight to stop processing any rules with a lower priority when this rule executes
Working with Foglight Tooling 753
Merging Host Objects
(see the Stop processing lower priority rules when successful check box,
disabled by default). By default, this rule is placed at the bottom of the priority
queue. For example, if there are seven existing host aliasing rules, this rule is
assigned the priority of 8 (see the Priority box). You can also change the priority
at a later time. For more information, see “Changing the priorities of host aliasing
rules” on page 730.
Optional. To change the rule priority or prevent the processing of the rules with
the lower priority, use the Priority box and Stop processing lower priority rules
when successful check box, as required.
Tip To use a different replacement text or to select different hosts, click Previous to return
to the Specify Matching Parameters page.
Note This procedure continues from “Use a regular expression to rename hosts” on page 746.
1 In the Specify Matching Parameters page of the Host Aliasing dialog box,
select the option Use a regular expression to convert a host name, followed by
clicking Next.
The Host Aliasing dialog box refreshes, showing the page Use a regular
expression to convert a host name.
754 Foglight
Administration and Configuration Guide
This page contains an example of how host names are replaced with a regular
expression, followed by a set of controls that allow you to continue with the
character replacement.
Tip To use a different type of matching parameters, click Previous to return to the Specify
Matching Parameters page.
test_host_3.domain_c.com No No
test_host_4.domain_d.com No No
For complete information about the regular expressions syntax in Foglight, see
the Command-Line Reference Guide.
3 Specify the replacement text.
In the Host Aliasing dialog box, in the Replace Expression box, type a literal
expression that you want to use as the replacement text.
For example:
The Host Aliasing dialog box refreshes, showing the Summary page.
756 Foglight
Administration and Configuration Guide
The Summary page in the Host Aliasing dialog box describes the character
renaming logic. It also allows you to change the rule priority and to instruct
Foglight to stop processing any rules with a lower priority when this rule executes
(see the Stop processing lower priority rules when successful check box,
disabled by default). By default, this rule is placed at the bottom of the priority
queue. For example, if there are seven existing host aliasing rules, this rule is
assigned the priority of 8 (see the Priority box). You can also change the priority
at a later time. For more information, see “Changing the priorities of host aliasing
rules” on page 730.
Optional. To change the rule priority or prevent the processing of the rules with
the lower priority, use the Priority box and Stop processing lower priority rules
when successful check box, as required.
Tip To use a different replacement text or to select different hosts, click Previous to return
to the Use a Regular Expression to Convert a Host Name page.
Note This procedure continues from “Change other host properties” on page 746.
1 In the Specify Matching Parameters page of the Host Aliasing dialog box,
select the option Merge hosts by a property other than name, followed by
clicking Next.
The Host Aliasing dialog box refreshes, showing the page Merge hosts by a
property other than name.
Tip To use a different type of matching parameters, click Previous to return to the Specify
Matching Parameters page.
758 Foglight
Administration and Configuration Guide
Important The list that appears shows only a subset of the entire property set for the
host object. This is because property matching filters can only reference
certain types of properties such as String or Boolean properties. To see a full
set of properties that are exist in the Host type, view the Schema Browser
dashboard; for more information about this dashboard, see the Foglight User
Guide.
b Click the row containing the property that you want to change.
The list closes and the Host Aliasing dialog box refreshes, showing the newly-
selected property.
In the Host Aliasing dialog box, in the Regular Expression box, type a regular
expression that translates into the property value that you want to replace.
For example:
myhost_c.123.mydomain.com No No
myhost_d.123.mydomain.com No No
For complete information about the regular expressions syntax in Foglight, see
the Command-Line Reference Guide.
4 Specify the replacement text.
In the Host Aliasing dialog box, in the Replace Expression box, type a regular
expression that you want to use as the replacement text.
For example:
The Host Aliasing dialog box refreshes, showing the Summary page.
760 Foglight
Administration and Configuration Guide
The Summary page in the Host Aliasing dialog box describes the character
renaming logic. It also allows you to change the rule priority and to instruct
Foglight to stop processing any rules with a lower priority when this rule executes
(see the Stop processing lower priority rules when successful check box,
disabled by default). By default, this rule is placed at the bottom of the priority
queue. For example, if there are seven existing host aliasing rules, this rule is
assigned the priority of 8 (see the Priority box). You can also change the priority
at a later time. For more information, see “Changing the priorities of host aliasing
rules” on page 730.
Optional. To change the rule priority or prevent the processing of the rules with
the lower priority, use the Priority box and Stop processing lower priority rules
when successful check box, as required.
Tip To select a different source host, click Previous to return to the Specify Source Host
page.
A query language is used in Foglight to set the scope for rules and derived metrics, to
create rule conditions and expressions, to reference expressions in messages, and to
create derived metric expressions.
This appendix contains the following sections:
About the Query Language .......................................................................................................764
Using the Query Language to Set the Rule or Derived Metric Scope .......................................784
Using the Query Language in Rule Conditions or Derived Metric Expressions ........................790
Using the Query Language FAQ ...............................................................................................805
764 Foglight
Administration and Configuration Guide
Important This procedure assumes that you have access to a Foglight installation, which includes a
user account with the Operator role. For more information on how to get started with
Using the Query Language 765
About the Query Language
Foglight, see Chapter 1, “Getting Started with the Administration Module” on page 19. To
find out more about users and security in Foglight, see Chapter 4, “Managing Users and
Security” on page 197.
Note The contents of the Value column depend on the complexity of your monitoring
environment and your user permissions. The above screen capture illustrate a
collection of topology models that appear in a core installation of the Foglight
Management Server and the Foglight Cartridge for Operating Systems that is shown
to a user with the Operator role. To find out the type and range of cartridges that
exist in your environment, review a list of installed cartridges in the Cartridge
Inventory dashboard, as described in Chapter 5, “Accessing the Cartridge Inventory
Dashboard” on page 252. For more information about users and security in Foglight,
see the Chapter 4, “Managing Users and Security” on page 197.
In the upper-left corner of the Data dashboard is a table that allows you to browse
through one or more topology models that exist in your monitoring environment.
The table contains the following columns:
• Value: Contains object instances, or nodes, and shows relationships between
the nodes. Each root node represents a topology model. Expanding a node
shows one or more child nodes. An object instance can appear multiple times
766 Foglight
Administration and Configuration Guide
in the model, depending on its relationship with other nodes that exist in the
system.
• Data Type: Identifies the topology type of the object instance (node). The
collection of topology types that exist in your environment depend on the type
of the systems you monitor and the range of installed cartridges. For more
information about finding out which topology types exist in your monitoring
environment, see “Viewing Topology Types” on page 767.
3 View the structure of a topology model.
In the Data dashboard, in the Value column, expand one of the nodes, and
observe the list of nodes that appear underneath. For example, to look at the
monitored hosts that exist in your environment, click Hosts, and then expand a
host node that appears.
A set of object properties for the selected host appears below.
Using the Query Language 767
About the Query Language
For example, to view the contents of the host’s memory utilization metric, in the
Value column, click memory > utilization.
The collected memory utilization metrics appear in the Property Viewer on the
right.
For complete information about the Data dashboard, see the Foglight User Guide.
You have successfully viewed a sample of a topology model. From here, you can start
looking at the topology types that are associated with object instances in the model.
“Viewing Topology Types” on page 767.
Important This procedure assumes that you have access to a Foglight installation, which includes a
user account with the Operator role. For more information on how to get started with
Foglight, see Chapter 1, “Getting Started with the Administration Module” on page 19. To
find out more about users and security in Foglight, see Chapter 4, “Managing Users and
Security” on page 197.
The Schema Browser dashboard appears in the display area, and the Schema
Selector appears in the navigation panes
3 Ensure that the Schema Browser shows the core topology types.
On the navigation panel, under Schema Selector, verify if the Foglight entry is
selected.
4 Observe the list of topology types that appear in the Schema Browser dashboard.
Tip The entries in the list are alphabetically sorted.
5 Select a topology type in the upper pane of the Schema Browser and view its
details in the lower pane.
For example, to look at the details of the Host topology type, in the list appearing
in the upper pane, scroll down until you see the Host entry, then click Host.
In the Schema Browser dashboard, the lower pane shows the details of the Host
topology type.
770 Foglight
Administration and Configuration Guide
• To view the ancestor types of the selected topology type, in the View by menu
of the Details pane, click Ancestors.
The Details pane refreshes, showing the ancestors of the selected topology
type in hierarchical order, from the selected topology type at the top, to the
root type at the bottom.
• To view the descendant types of the selected topology type, in the View by
menu of the Details pane, click Descendants.
772 Foglight
Administration and Configuration Guide
The Details pane refreshes, showing a map of the descendants of the selected
topology type.
• To view the instances of the selected topology type, in the View by menu of
the Details pane, click Instances.
The Details pane refreshes, showing a list of all instances of the selected
topology type.
Using the Query Language 773
About the Query Language
For complete information about the Schema Browser, see the Foglight User
Guide.
You have successfully viewed the details of a topology type that exists in the Foglight
database schema. From here, you can navigate to the dashboards that you can use to
write simple queries.
Interface
The interface for the Query Service consists of four methods for setting up and making
queries.
774 Foglight
Administration and Configuration Guide
Method ‘Description
Hands-on examples
This section includes hands-on usage examples for writing queries, such as examples
for writing topology and metric queries. It also describes how to form queries based on
an abstract graph that represents the topology model.
Topology queries
Begin by looking at the queries that are strictly within the domain of the Topology
Service. A simple example would be querying for all topology objects of type
EJBInstance. To get this, type the following.
(EJBInstance)
You can filter the set of topology objects that you get back based on their properties. For
example, if you want all EBJInstances who have their property “name” set to
“inst1-1”, then you would express your query in the following manner.
(EJBInstance where name=’inst1-1’)
Additional property conditions can be added using a comma as a separator, as follows:
(EJBInstance where name=’inst1-1’, application =’app1-1-
uniqueId’)
Another add an extra condition is with an ‘and’ instead of the comma:
Using the Query Language 775
About the Query Language
Note Regular expression matching from within a set is not yet supported.
You can specify the negation of a condition. For example, if we wanted only those
EJBInstances whose name did not start with “inst” we would change the above query to
this:
!EJBInstance : name ! matches 'inst.*'
Equivalently, we can write any of the following.
!EJBInstance : !(name matches 'inst.*')
or
!EJBInstance : not (name matches 'inst.*')
or
!EJBInstance : NOT ! (name matches 'inst.*')
Note that if a “not” is put before a comparison, then the entire comparison must be
enclosed in parenthesis.
776 Foglight
Administration and Configuration Guide
Property conditions can express programmatic relationships. For example, if you want
all EJBInstances where the “name” property of the EBJInstance’s “application”
property is set to “app1-1”, write the following expression:
(EJBInstance where application.name = ’app1-1’)
When a query is made, it can be made within a scope. A scope is simply a handle to
some known topology object and is represented in the query by the keyword: $scope.
If you want to find all siblings of the current EBJInstance according to their ejb,
write the following expression:
(EJBInstance where ejb=$scope.ejb)
There is one more way to do filtering, and that is by checking whether a topology object
is a particular set of objects. For example, if you want to query for all EJBInstances
on the same server (server is the property we are interested in) that the current scoping
EJB is on, use the following expression:
(EJBInstance where server in $scope.instances.server)
Finally, a topology object query can be used as the base of a programmatic walk through
object properties. For example, if you want all the EJBInstances from all EJBs that
are named “ejb1”, you can first ask for the EJBs and then look at their instances. To do
this use the following expression:
(EJB where name=’ebj1’).instances
As you might expect, this query can have filtering conditions applied to it, too. If you
want to retrieve only those EJBInstances from above who additionally have their
names starting with “inst”, use the following expression:
(EJB where name=’ebj1’).instances where name like ’inst%’
Another way to write this query is as follows:
(EJBInstance where ebj.name=’ebj1’,name like’inst%’)
could be a fast query if the set of EJBInstance objects is small or a slow query if the
set of EJBInstance objects is large.
As a query writer your rule-of-thumb is to keep the set small. To do this you need to
understand the model that your topology is describing. For example, let’s say you want
those objects whose type contains the word, Catalyst. A common first attempt is to
make a query for all TopologyObject instances where their topologyTypeName
property contains Catalyst.
!TopologyObject : topologyTypeName matches ‘.*Catalyst.*’
Another way to achieve the same goal is with this next query.
$objectsbytype(/.*Catalyst.*/)
Which query do you choose? The first query scans the set of all topology objects of
every type, checking each object’s topologyTypeName property. In a typical system
there are hundreds of thousands of topology objects so the set is quite large. The second
query scans the set of topology types, matches them against the /.*Catalyst.*/
regular expression, and finally returns all topology objects from the matching types. The
scanned set here is typically only hundreds of types, so it is relatively small. You should
choose the second query.
Metric queries
There are two differences between topology queries and metric queries. One is that you
prefix your query with a metric name and optionally suffix your query with a time
period. The other is that there are fewer parentheses required because you’re using the
keyword from.
Foglight agents collect metrics from monitored hosts and send them to the Foglight
Management Server in batches. The length of an agent's collection period for a batch is
specified in the agent properties. A metric query that includes a time component
retrieves the batch of data that exists on the server at the time specified by that time
component, not the batch of data collected at the time specified by the query, as it may
be expected. For example, the query ruletteCount at 15:00 on 2007-09-26
retrieves the batch of data for the rulleteCount metric that exists on the server at
15:00. As seen in the example below, the start and end time of the collection period for
that batch indicate that the collection period started at 14:22 (startTime) and ended at
14:59 (endTime).
uniqueId f0484b82-186e-4d97-b2d0-6d0d2fb3db98
778 Foglight
Administration and Configuration Guide
samplePeriod 2250000
count 75
min 0
max 35
avg 22.86666667
sum 1715
sumSquares 56425
stdDev 15.1475704
For specific information about the collection rate property for an agent, see the User
Guide accompanying the cartridge that includes the agent definitions. For information
about viewing and editing agent properties, see Chapter 6, “Managing Agent Properties
by Type” on page 279 and “Installing and Managing Agent Instances on a Monitored
Host” on page 292.
For example, if you want to get the collect the invocationTime for all
EBJInstances over a period of 1.5 hours, write the following expression:
invocationTime from EJBInstance for 1.5 hours
You can also use a registry variable (here called myDuration associated with the
current scoping topology object to specify a time period.
invocationTime from EJBInstance for $registry(myDuration) hours
As mentioned above, you can still use the mechanisms associated with topology
queries. For example:
invocationTime from EJBInstance where ebj.name=’ebj1’,name
like’inst%’ for 1.5 hours
Also, if you have a scoping EJBInstance topology object you could query for its
invocationTime in the following way:
invocationTime from $scope for 1.5 hours
Using the Query Language 779
About the Query Language
Because this is a common idiomatic case for the Rule Engine, there is a short-hand for
from $scope in the above.
invocationTime for 1.5 hours
In this case, the language interprets that there is no sub-query for topology objects, so it
assumes that the invocationTime metric is attached to the current scoping topology
object. It implies a $scope clause in the query.
The time period is optional. If you just want a current invocationTime from the
current scoping topology object, write the following expression:
invocationTime
Time periods can be used for base lining. The idea is that instead of querying for recent
metrics based on the current time, you can get older metrics from either a certain date or
an offset of a number of days, weeks, months or years into the past.
The first way to do this is to append an ago clause.
invocationTime for 1.5 hours 1 week ago
This statement looks at the current time, chooses the same calendar instant from week
ago, and selects the 1.5 hour period immediately prior to that 1 week ago instant. For
example, if it is currently Monday morning at 9:00 AM, this statement goes back to last
week’s Monday morning and select the invocation time from 7:30 AM to 9:00 AM.
Note that leaving off the ago clause will produce the same period of time (except on
today) allowing for apples to apples comparisons with visually similar queries.
The second clause we can append is an “on” clause.
invocationTime for 1.5 hours on 2009-05-25
This works the same way as the previous example, except that instead of using a relative
offset, we specify an absolute date to select the data from. Again, if it is currently 9:00
am, this query selects the data collected from 7:30 am to 9:00 am from May 25, 2009.
These clauses give wall clock equivalent comparisons, that is, they compare 9:00 am
today to 9:00 am in the past. If you want to compare 9:00 am today to a different wall
clock time in the past you can use a spanning clause.
invocationTime spanning 1.5 hours starting at 13:00 on 2009-05-25
The above query selects data from 1:00 pm to 2:30 pm on May 25, 2009. If you want,
you can specify time ending at a certain point as well.
invocationTime spanning 1.5 hours ending at 14:30 on 2009-05-25
And finally, you can use the relative offset with a spanning clause.
780 Foglight
Administration and Configuration Guide
Graph Query
Explanation:
This query filters all topology objects of 'B'
type and retrieves their 'a' observations.
782 Foglight
Administration and Configuration Guide
Graph Query
Explanation:
The query filters all topology objects of
type 'C', retrieves their ‘b’ properties
followed by retrieving the ‘a’ observations
from that set of ‘b’ properties.
Explanation:
The query filters all topology objects of
type 'B' and then retrieves the ‘a’ objects
from that set of ‘b’ properties.
Explanation:
The query filters all topology objects of
type 'A'.
Explanation:
The query filters all topology objects of
type 'C', and forms a set 'S' of the results’ ‘b’
property objects. Then it filters all objects of
type 'A' by checking that their ‘b’ property is
in 'S'.
Using the Query Language 783
About the Query Language
Graph Query
(C where d = ‘d’).b.a
Explanation:
The query filters all topology objects of
type 'C' and uses the resulting set as the base
to find the desired ‘a’ properties.
784 Foglight
Administration and Configuration Guide
Note The Rule Scope and Derived Metric Scope fields are case-sensitive.
2 Click the Append button ( ) to the right of the Topology Type box.
The name of the newly-selected topology type appears in the box immediately
below the Topology Type box.
3 Complete one of the following steps.
Using the Query Language 785
Using the Query Language to Set the Rule or Derived Metric Scope
Note You must select a topology type before you can use the Property drop-down menu or
launch the Scoping Query Editor.
Note This procedure continues from “Inserting topology types” on page 784.
1 In the box immediately below the Topology Type and Property boxes that
already contains the topology type name, edit the logical expression that matches
the rule scope.
For example, if you want to write a query for the instances of the selected
topology type with a property that contains a a particular value, edit the logical
expression as follows:
TopologyType where property = "value"
Where TopologyType is the topology type you selected in “Inserting topology
types” on page 784.
For more information about the query language syntax, see “Specifying the
scoping query manually” on page 789.
2 Specify the property name you want to query.
a In the above expression, select property.
b Click Property and select the property name from the list that appears.
Note You can also use the controls in the Scoping Query Editor to build a scoping query that
uses the correct syntax and then insert it into the Rule Scope or Derived Metric Scope
field. See Restricting the scope to topology objects below for instructions.
Note This procedure continues from “Inserting topology types” on page 784.
Note This procedure continues from “Restricting the scope to topology objects” on page 786.
1 In the Scoping Query Editor dialog box, ensure that the Instances tab is open.
2 Select a topology object instance.
In the Topology Instances box, select the object instance.
3 In the display area, in the box immediately below the Topology Type and
Property boxes, place the cursor where you want to insert the new segment of the
scoping query.
If that box is empty, a complete scoping query (including the topology type you
selected) will be inserted into it.
4 In the Scoping Query Editor dialog box, click Insert Query.
The Scoping Query Editor dialog box closes and the scoping query (or scoping
query segment) appears in the box immediately below the Topology Type and
Property boxes.
5 Validate the scope by clicking the Validate Scope button ( ) on the right.
If the scope is valid, a confirmation message appears above the Topology Type
box while the name of the newly-edited expression appears at the bottom with the
topology type instance referenced with its uniqueID property.
Note This procedure continues from “Restricting the scope to topology objects” on page 786.
1 In the Scoping Query Editor dialog box, click the Filter tab.
The Filter tab opens in the Scoping Query Editor dialog box, allowing you to
create a logical expression containing up to three comparison expressions that are
connected with “AND” or “OR” logical operators.
The Scoping Query Editor dialog box closes and the scoping query (or scoping
query segment) appears in the box immediately below the Topology Type and
Property boxes.
6 Validate the scope by clicking the Validate Scope button ( ) on the right.
If the scope is valid, a confirmation message appears above the Topology Type
box while the name of the newly-edited expression appears at the bottom with the
topology type instance referenced with its uniqueID property.
Note In addition to the examples shown below, there are many different ways of specifying a
scoping query. These examples are simply provided as guidelines with regard to the query
language syntax.
Examples
• You can scope the rule or derived metric to a specific, named topology object by
using the syntax
<TopologyType> where name ="<Object>"
where TopologyType is the name of the topology type of which Object is an
instance and Object is the specific instance to which you want the rule or
derived metric to be scoped.
• You can scope the rule or derived metric to multiple similarly-named topology
objects of a certain type by using syntax similar to
<TopologyType> where name like "%<Object>"
where TopologyType is the name of the topology type of which the topology
objects with names like Object are instances. In the example shown above,
the % wildcard causes the rule or derived metric to be scoped to all topology
objects (of the specified type) with names that end with what you specify in place
of Object.
• You can cause the rule or derived metric to be scoped to all topology objects of a
specific type except for a single, named instance by using the syntax
<TopologyType> where name ! ="<Object>"
790 Foglight
Administration and Configuration Guide
Tip If you want to include an email address in a message, simply use the @ symbol twice. For
example:
Send email to administrator@@example.com
Note The expressions that you can reference in a message vary depending on the scope of the
message. See Chapter 7, “Adding severity-level variables” on page 444 for details.
You can also reference registry variables in expressions using the syntax
registry("registryVariableName").
Examples
• You are editing a simple rule that is scoped to the topology type JVM; the
condition for the rule is #threads_started#>10. You want to create a message
(to use as the text of the email that is sent when the rule fires) that includes the
value of the #threads_started# metric at the time when the rule fires.
Using the controls on the Severity Level Variables tab of the Fire tab, you create
an expression called threadsNum whose value is #threads_started#. You
then create a message called ProblemSynopsis. The value that you set for this
message is:
Threads started count is too high: @threadsNum
In this message, the at sign ‘@’ is used to reference the threadsNum expression.
When the message shown above is included in the email, @threadsNum will be
replaced by the number of threads that were started at the time when the rule
fired.
• There is a registry variable called CPUFatal whose value is 90 for the topology
object to which the rule you are editing is scoped. You want to reference this
variable in the alarm message for the rule’s Fatal severity level, so you create an
expression called CPU whose definition is registry("CPUFatal"). You then
reference this expression in the rule’s alarm message: CPU usage is at
@CPU%.
792 Foglight
Administration and Configuration Guide
Inserting operators
The available operators are listed along the top of the Condition and Expression boxes.
These operators are part of the query language.
To insert an operator into a rule condition or derived metric expression:
1 Place the cursor in the Condition or Expression box where you want to insert the
operator.
2 Click the button for that operator.
• Click the Condition Editor (rules) or Expression Editor (derived metrics) button
( ).
The Condition Editor (rules) or Expression Editor (derived metrics) dialog box
appears.
Using the Query Language 793
Using the Query Language in Rule Conditions or Derived Metric Expressions
Caution Although you can insert a registry variable into a derived metric expression, it is not
recommended that you do so.
Using a registry variable in a derived metric expression could lead to unpredictable and
confusing results since the resulting metric might change its definition at different points
in time.
The Registry Variable tab in the Condition Editor (rules) and Expression Editor
(derived metrics) dialog box lists the registry variables that are available based on the
794 Foglight
Administration and Configuration Guide
rule or derived metric scope. Each registry variable’s type and global default value also
appear in this table.
Note The list of registry variables displayed in this table is based on the list shown on the Manage
Registry Variables dashboard (Administration > Rules & Notifications > Manage Registry
Variables). This table is empty if no registry variables are available for the associated
topology type.
To insert a registry variable into the rule condition or derived metric expression:
Note This procedure continues from “Editing conditions and expressions” on page 792.
1 In the display area, place the cursor in the Condition box (rules) or Expression
box (derived metrics) where you want to insert the variable.
2 In the Condition Editor (rules) or Expression Editor (derived metrics) dialog
box, ensure that the Registry Variable tab is open.
3 In the Registry Variable tab, select a variable from the list, and click Insert.
The dialog box closes and the Condition (rules) or Expression (derived metrics)
box refreshes, showing the newly-added variable.
From here, you can proceed to “Validating conditions or expressions” on page 800.
Note This procedure continues from “Editing conditions and expressions” on page 792.
1 In the display area, place the cursor in the Condition box (rules) or Expression
box (derived metrics) where you want to insert the metric.
2 In the Condition Editor (rules) or Expression Editor (derived metrics) dialog
box, click the Metric/Property tab.
The Metric/Property tab shows lists three groups of topology types: Scoping
Topology, Child Topology, and Other Topology.
The Metric/Property tab refreshes, showing the instances and metrics for the
selected topology type.
or
• To select an instance, in the Instances pane, click the instance name.
The Metric/Property tab refreshes, showing the list of properties for the
selected instance.
Using the Query Language 797
Using the Query Language in Rule Conditions or Derived Metric Expressions
In the Properties pane, select the property that you want to add to the condition
(rules) or expression (derived metrics).
a Choose a property from the list.
5 Click the Insert button.
The dialog box closes and the Condition (rules) or Expression (derived metrics)
box refreshes, showing the newly-selected instance or metric.
From here, you can proceed to “Validating conditions or expressions” on page 800.
Note Foglight supports embedding named scripts into cartridges by editing their monitoring
policy. In that file, only those named scripts that are marked as functions appear in the list of
798 Foglight
Administration and Configuration Guide
functions. This excludes any custom queries that are added to the monitoring policy.
Custom queries cannot be used in rule conditions.
For a full list of functions and their descriptions, see “Using Functions with Conditions
and Expressions” on page 801.
To insert a Groovy function into a rule condition or derived metric expression:
Note This procedure continues from “Editing conditions and expressions” on page 792.
1 In the display area, place the cursor in the Condition box (rules) or Expression
box (derived metrics) where you want to insert the function.
2 In the Condition Editor (rules) or Expression Editor (derived metrics) dialog
box, click the Function tab.
The Function tab opens in the dialog box.
3 Choose the Groovy function that you want to add to your condition or expression.
Click Function Name and select a function from the list.
Using the Query Language 799
Using the Query Language in Rule Conditions or Derived Metric Expressions
The Function tab refreshes, allowing you to specify the arguments for the
selected function, and shows usage examples.
4 Specify the function arguments as required using one or more Arg boxes.
The first argument represents the object on which the function will be performed,
such as a metric (specified using the format #metric#) or a topology object
within the rule or derived metric scope (specified as scope). See “Using
Functions with Conditions and Expressions” on page 801 for more information.
Tip Hover the cursor over the question mark icon ( ) next to one of the argument fields to
make a tooltip appear. This tooltip states which type of parameter is expected for that
field.
Note This procedure continues from “Editing conditions and expressions” on page 792.
• You are creating a number of rules, each of which is scoped to a different EJB
instance. You know that you need to configure the conditions for many of these
Using the Query Language 801
Using the Query Language in Rule Conditions or Derived Metric Expressions
Note Foglight supports embedding named scripts into cartridges by editing their monitoring
policy. In that file, only those named scripts that are marked as functions appear in the list of
functions on the Function tab of the Condition Editor (rules) or Expression Editor (derived
metrics) dialog box. This excludes any custom queries that are added to the monitoring
policy. Custom queries cannot be used in rule conditions.
802 Foglight
Administration and Configuration Guide
• alarmCount: Returns the current number of alarms for each topology object
referenced by this function’s scope parameter.
• avg: Calculates an average (arithmetic mean) from metric values.
If you are calculating an average for multiple topology objects, Foglight will
calculate an average from the metric values for each object, then calculate a
second average from the averages for the objects.
• changeSummary: Returns the list of topology property changes for each
topology object referenced by this function’s scope parameter over the specified
time period (supplied in milliseconds).
• checkObservationAlarms: Returns a list of all log entry objects with a
particular severity.
• checkUserPermission: Check the permissions assigned to a user.
• compareStrings: Compares two text strings.
• count: calculates the number of observations. An observation can be either a
metric or a property of a topology object.
• createObservationAlarms: Returns a list of all log entry objects with a
particular severity.
• currentUserHasAdvancedOperationsRole: Returns True if the current
user has Advanced Operator role
• delta: calculates the difference between the maximum value of the two most
recent samples of a single metric. The delta function is used with metrics whose
unit of measurement is count.
• delta_rate: calculates the rate per second of the delta.
• descendents: returns the set of topology objects that are directly or indirectly
contained by each topology object referenced by this function’s scope parameter.
• f4registry: Returns the value of a given registry variable for the current
scoping object.
• findObservationEntries: Returns a list of log entry objects with a specified
set of properties.
• generateUUID: Returns a random Universal Unique Identifier (UUID).
• getAlarmSeverities: Retrieves a list of alarm severities for a given object.
• getAllMonitoredComponents: Returns all monitored components in the
definition of the scoping object.
Using the Query Language 803
Using the Query Language in Rule Conditions or Derived Metric Expressions
• You are creating a simple rule that applies to JDBC requests. You want this rule
to fire an alarm if the metric #requestResponseTime# returns values greater
than 750 milliseconds more than 10% of the time over the period of an hour.
In the Condition box for the rule’s Fire state, you specify a condition similar to
the following:
metric = #requestResponseTime for 1 hour#
histo = histogram(metric, [10, 50, 250, 500, 750])
if (histo[5]/count(metric)>0.1)
{return true;}
else
{return false;}
Note In the example shown above, the exclamation point ‘!’ implies that the argument passed to
the alarmCount function is a topology object property and not a metric.
While the new versions of Foglight use the Foglight Agent Manager to communicate
with Foglight agents, previous versions used the Foglight Client. The Administration
module and Foglight command-line interface support both technologies, however, some
dashboards in the browser interface as well as Foglight commands can provide slightly
different type of data in monitoring environments that still use the Foglight Client for
agent communication. This appendix shows examples of dashboards and command-line
output in an environment that uses the Foglight Client.
Note For information on how to start the Foglight Agent Manager, see “Logging in to Foglight” on
page 22.
Note This procedure continues from “Managing Support Bundles” on page 139.
1 Locate the client support bundle whose content you want to view.
Each client support bundle is contained in a ZIP file in the <foglight_home>/
support/<user_name> directory on the computer hosting the Foglight Client.
2 Extract the contents of the ZIP file containing the client support bundle to a local
directory.
3 Observe the file structure.
Appendix: Foglight Client Reference 809
Viewing the Content of a Foglight Client Support Bundle
Each client support bundle consists of the following files and directories:
config/
spid/
<VERSION>/
<CACHE>/
SPI/
SPI/
<AGENT_NAME>/
SPINetwork/
SPINetwork
<AGENT_NAME>/
logs/
<CARTRIDGE>/
<VERSION>/
Note For information about the content of Foglight Agent Manager support bundles, see “Viewing
the Content of a Foglight Agent Manager Support Bundle” on page 148.
Appendix: Foglight Client Reference 811
Browser Interface
Browser Interface
This section contains sample screen captures that appear in monitoring environments
that use the Foglight Client for agent communication with the Foglight Management
Server. It includes screen captures for the following dashboards:
• “Agent Properties dashboard” on page 811
• “Agent Status dashboard” on page 811
• “Agent Adapters dashboard” on page 813
Note For a sample screen capture of this dashboard in a monitoring environment that uses the
Foglight Agent Manager, see “Accessing the Agent Properties Dashboard” on page 280.
Figure 2
Note For a sample screen capture of this dashboard in a monitoring environment that uses the
Foglight Agent Manager, see “Accessing the Agent Status Dashboard” on page 293.
Appendix: Foglight Client Reference 813
Browser Interface
Note For a sample screen capture of this dashboard in a monitoring environment that uses the
Foglight Agent Manager, see “Accessing the Agent Adapters Dashboard” on page 354.
814 Foglight
Administration and Configuration Guide
Command-Line Interface
This section contains fglcmd examples and their command-line output that appears
when the agent instances in your monitoring environment use the Foglight Client for
communication with the Foglight Management Server. It includes the following
sections:
• “Deploying agent packages” on page 814
• “Creating agent instances” on page 815
• “Retrieving agent logs” on page 817
• “Foglight Client IDs” on page 818
• “Installer IDs” on page 819
For more information about fglcmd and the command-line output that is generated in
environments that use the Foglight Agent Manager for managing agent instances, see
the Command-Line Reference Guide.
Important The procedure below assumes that the have access to and have configured the fglcmd
package on the computer you are using to deploy agent packages. For complete
instructions, see the Command-Line Reference Guide.
Note If you are running the commands below on a UNIX platform, you can use a back slash ‘\’ to
indicate a new line when running long commands.
2 List the agent packages that are available to the Foglight Client using the
following command syntax:
fglcmd -usr user_name -pwd password -cmd agent:types
-clientname SPI://myhost.mydomain.corp:0
Appendix: Foglight Client Reference 815
Command-Line Interface
An output similar to the following appears, listing all Foglight Clients and the
agent types that are available to them.
Client ID: myhost.mydomain#SPI://
myhost.mydomain.corp:0
Installer ID: myhost.mydomain#SPI://
myhost.mydomain:0#SpiInstaller/admin
Agent Package ID: OSCartridge-Windows2003-5.5.0-
AgentPackage
Agent Package Cartridge Name: OSCartridge-
Windows2003
Agent Package Cartridge Version: 5.5.0
3 Review the above output and record the ID of the agent package that you want to
deploy.
4 Deploy the agent package using the following command syntax:
fglcmd -usr user_name -pwd password -cmd
agent:deploy -packageid
cartridge_name-cartridge_version-AgentPackage
-host myhost.mydomain.corp
An output similar to the following appears:
Successfully installed package cartridge_name-
cartridge_version-AgentPackage on
myhost.mydomain.corp#SPI://
myhost.mydomain.corp:0#SpiInstaller/admin
Note For information on how to deploy an agent package in a monitoring environment that uses
the Foglight Agent Manager, see “Using the command line to deploy agent packages” on
page 316.
Important The procedure below assumes that the have access to and have configured the fglcmd
package on the computer you are using to create agent instances. For complete
instructions, see the Command-Line Reference Guide.
Note If you are running the commands below on a UNIX platform, you can use a back slash ‘\’ to
indicate a new line when running long commands.
816 Foglight
Administration and Configuration Guide
2 List the agent types that are available to the Foglight Client using the following
command syntax:
fglcmd -usr username -pwd password -cmd agent:packages
-clientname myhost.mydomain.corp
An output similar to the following appears, listing all agent types that are
available to the specified Foglight Client.
Client ID: myhost.mydomain.corp#SPI://
myhost.mydomain.corp:0
Client Name: SPI://myhost.mydomain.corp:0
Agent Types:
NetMonitor
Windows_System
WebMonitor
AppMonitor
LogFilter
SNMP
ApacheSvr
TerminalServer
3 Review the above output and record the type of the agent whose instance you
want to create.
4 Create an agent instance using the following command syntax:
fglcmd -usr username -pwd password -cmd
agent:create -name instance_name -type agent_type
If successful, this command does not generate any output.
Note For information on how to create agent instances in a monitoring environment that uses the
Foglight Agent Manager, see “Using the command line to create agent instances” on
page 324.
Appendix: Foglight Client Reference 817
Command-Line Interface
Important The procedure below assumes that the have access to and have configured the fglcmd
package on the computer you are using to retrieve agent logs. For complete instructions,
see the Command-Line Reference Guide.
2 List the agent log files using the following command syntax:
fglcmd -usr username -pwd password -cmd agent:logs
-host myhost
An output similar to the following appears, listing all log files that exist on the
specified host.
Client ID: tor013008.prod.quest.corp#SPI://
tor013008.prod.quest.corp:0
Client Name: SPI://tor013008.prod.quest.corp:0
Host Name: tor013008.prod.quest.corp
50 log files found.
OSCartridge\5.2.0\logs\AIX_Console_My_AIX_Console_Agent
_2008-01-21_095227_001.log
OSCartridge\5.2.0\logs\AIX_MPStat_My_AIX_MPStat_Agent_
2008-01-21_094945_001.log
OSCartridge\5.2.0\logs\AIX_System_My_AIX_System_Agent_
2008-01-21_095149_001.log
OSCartridge\5.2.0\logs\ApacheSvr_ApacheSvr_
2008-01-16_102536_001.log
OSCartridge\5.2.0\logs\ApacheSvr_My_ApacheSvr_Agent_
2008-01-16_114450_001.log
3 Review the above output and record the log file that you want to retrieve.
4 Transfer that log file into a local directory using the following command syntax:
fglcmd -usr username -pwd password -cmd
agent:getlog -log path_and_name_of_log_file -f
path_and_name_of_destination_file
818 Foglight
Administration and Configuration Guide
Note For information on how to retrieve agent log files in a monitoring environment that uses the
Foglight Agent Manager, see “Using the command line to retrieve agent logs” on page 340.
Note For information on how to retrieve Foglight Agent Manager IDs, see “Using the command
line to deploy agent packages” on page 316.
Appendix: Foglight Client Reference 819
Command-Line Interface
Installer IDs
Installer IDs help deploy new agent packages to remote hosts. Installer IDs identify
agent managers that are capable of installing agent packages on a remote machine. It is
possible to have several such installers within one Foglight Agent Manager, so installer
IDs are more complex than Foglight Agent Manager IDs.
The Foglight Agent Manager installer ID uses the following syntax:
HostName#SPI://HostName:0#SpiInstaller/admin
In general, each remote installer is capable of handling an agent package of one type.
The type of agent package is specified in the respective cartridge manifest file, but is not
visible directly through the command line interface. However, agent package types
affect the results of the agent:packages command. Given a Foglight Agent Manager
ID as a parameter, the agent:packages command checks the installers that are
available on the Foglight Agent Manager and returns IDs for all agent packages that can
be handled by at least one installer on the Foglight Agent Manager.
C:\Quest_Software\Foglight\bin>fglcmd -usr foglight -pwd foglight
-cmd agent:packages -clientid
tor012991.prod.quest.corp#cf238d96-3a56-45d6-a33e-
b88bb7d4ff55
Note For information on how to retrieve installer IDs in an environment that uses the Foglight
Agent Manager, see “Using the command line to deploy agent packages” on page 316.
Index
318, 320, 321, 324, 326, 327, 328, 329, 330, deleting 337
331, 332, 334, 335, 336, 337, 338, 339, 340, installing on a single host 292
343, 345, 348, 352, 714, 811 instances
accessing 293 creating 710
activating agents 327 managing
Agent Operation dialog box 328, 329, 330, blackouts 357
331, 332, 333, 334, 335, 336, 714, 715, managing on a single host 292
716 managing on multiple hosts 342
cloning lists in secondary agent packages
properties 304 deploying 707
Create Agent dialog box 321, 323, 324, 711, uploading 705
712 properties
Create Agent Results dialog box 323, 712, accessing Agent Properties dashboard 280
713 editing 717
creating agent instances 320 managing 279
deactivating agents 327 starting data collection 331
Delete Agent dialog box 337 status
deleting agents 337 accessing Agent Hosts dashboard 343
Deploy Agent Package dialog box 313, 314, accessing Agent Status dashboard 293
315, 316, 708 stopping data collection 331
deploying agent packages 312, 313 uploading 705
Edit Tags dialog box 310, 311 Agents dashboards 68, 277, 278, 292, 293
editing agent properties 296 about 278
choosing edit scope 300 Agent Adapters 40, 353, 354, 355, 356, 357,
editing agent tags 310 813
editing lists in secondary agent accessing 354
properties 305 activating agent adapters 356
editing primary agent properties 302 deactivating agent adapters 356
removing cloned lists from secondary agent Agent Blackouts 40, 357, 358, 359, 361
properties 309 Blackout Schedule Results dialog box 361
retrieving agent logs 338, 339 Selected Agents dialog box 360
starting agents’ data collection 331 Agent Hosts 40, 59, 293, 312, 320, 342,
stopping agents’ data collection 331 343, 344, 345, 346, 348
Stopping Data Collection dialog box 335, 336 accessing 343
Agent Status node in navigation panel 30, 35, Create Agent dialog box 349, 350, 352
294, 352 Create Agent Results dialog box 350, 351
agent tags creating agent instances 348
editing 310 Deploy Agent Package dialog box 346, 347
agents deploying agent packages 345
activating 327 Agent Properties 40, 59, 279, 280, 281, 282,
deactivating 327 283, 284, 286, 287, 289, 290, 296
Index 825
Deploy Agent Package dialog box 708, 709, downloading agent components 268
710 downloading agent components remotely
deploying agent packages 707 using Components for Download view 272
editing agent properties 717 using URLs 274
uploading agent scripts 705 enabling 261
Build Script Agent dialog box 706 installing 251, 258
Build Script Agent node in navigation accessing Cartridge Inventory
panel 704 dashboard 252
Business Hours dialog box 572, 573 managing 251
accessing Cartridge Inventory
C dashboard 252
uninstalling 263
cartridge 15
Cartridges dashboards 68, 249, 251
Cartridge Confirmation dialog box 263, 264,
about 250
265
Cartridge Inventory 41, 47, 61, 251, 252,
Cartridge Inventory dashboard 41, 47, 61, 251,
253, 256, 257, 259, 260, 261, 262, 263,
252, 253, 256, 257, 259, 260, 261, 262, 263,
264, 265
264, 265
accessing 252
accessing 252
Cartridge Confirmation dialog box 263,
Cartridge Confirmation dialog box 263, 264,
264, 265
265
Cartridge Operation Result message
Cartridge Operation Result message
box 260, 261
box 260, 261
disabling cartridges 262
disabling cartridges 262
enabling cartridges 261
enabling cartridges 261
installing cartridges 258
installing cartridges 258
uninstalling cartridges 263
uninstalling cartridges 263
View Cartridge Details view 255, 256
View Cartridge Details view 255, 256
Components for Download 41, 265, 266,
Cartridge Inventory node in navigation
267, 268, 269, 312, 345
panel 253
accessing 266
Cartridge Operation Result message box 260,
downloading agent components 268
261
Cartridges node in navigation panel 12, 13, 32,
cartridges
251, 253, 267
agent components
Change Password dialog box 206, 207
downloading 265, 268
Check Registry Value dashboard 390
downloading agent packages remotely 269
Show columns dialog box 395, 396, 397
downloading remotely using Components for
View Registry Variable view 390, 391, 392,
Download view 272
393, 394
downloading remotely using URLs 274
Check Registry Value node in navigation
components 250
panel 390
disabling 262
client support bundles
Index 827
Create Derived Metric node in navigation defining rule conditions 451, 455
panel 632 defining rule conditions, alarms, and
Create Group dialog box 214 actions 442
Create Registry Value—Step 1 view 387, 402, defining rule scope 441
403 defining rule triggers 438
Create Registry Value—Step 2 view 388, 403 defining rule types 435
Create Registry Variable dashboard 44, 375, defining rule-level variables 505
376, 377, 383, 391, 474 defining rules 433
creating derived metrics 632 getting started with defining rules 434
creating registry variables 377 Scoping Query Editor dialog box 785, 786,
scoping registry variables to topology 387 787, 788, 789
specifying registry variable values 383 setting expression scope in rule
Step 1: Create Registry Variable view 474 conditions 450
Step 2: Registry Variable Added view 475, using trigger-specific variables in rule condi-
476 tion expressions 494
using performance calendars in registry writing rule conditions 449
variables 385 Create Rule node in navigation panel 433, 518,
Create Registry Variable node in navigation 525, 540, 550
panel 377, 474 Create Schedule dashboard 44, 574, 575, 576,
Create Role dialog box 223, 224 577, 578
Create Rule dashboard 44, 429, 431, 432, 433, accessing 575
518, 525, 526, 527, 538, 540, 541, 542, 546, adding schedule items 577
550, 551, 552 creating schedules 574
Action Parameter Editor dialog box 496, 497, deleting schedule items 577
498, 533, 534, 535, 536 Edit Schedule view 579
action types 466 Edit Schedule—Add Schedule Item view 579
actions 466 getting started with schedule definitions 576
adding actions to rules 486 Schedule Confirmation dialog box 581
adding severity-level variables to rules 444 Step 1: Create Schedule—Schedule Name
Alarm Message Editor dialog box 454, 455, and Description view 575
463 Step 2: Create Schedule—Details of Schedule
associating rules with schedules 500 view 577, 578
Condition Editor dialog box 528, 529, 543, Step 3: Create Schedule—Schedule Added
545, 552, 553, 792, 793, 794, 795, 797, view 578
798, 800, 801 Create Schedule node in navigation panel 575
copying rule actions 498 Create Threshold dashboard 44, 648, 650,
copying rule conditions 464 651, 652
copying severity-level variables 498 adding bounds to metric threshold levels 653
creating rules 432 creating thresholds 650
defining alarm and action behavior 503 defining thresholds 651
defining rule actions 466 selecting metrics and levels in thresholds 651
Index 829
Edit User Permission dialog box 414 Edit Groups dialog box 205, 206
Rule Confirmation dialog box 415, 416, Monitoring Setup
421, 422, 423, 424 Delete dialog box 86
Scoping Query Editor dialog box 785, 786, Schema Browser 685, 686, 687, 725, 735,
787, 788, 789 738, 740, 745, 758, 768, 769
Temporarily Suspend Rule Actions dialog Script Editor
box 422, 423 Script Editor dashboard 43, 721, 722,
Temporarily Suspend Rule Alarms dialog 723, 725
box 420, 421 Service Builder 30
Manage Schedules 42, 361, 563, 565, 566, Service Operations Console 28
569, 570, 571, 572, 574, 575 View Audit Information 42, 57, 150, 151,
Add Role Permission dialog box 567 152, 155, 156
Add User Permission dialog box 567 Show columns dialog box 152, 153
Business Hours dialog box 572, 573 View Your Enterprise Health page 27
Copy Schedule dialog box 569 Welcome page 19, 23, 24, 26, 27, 30, 122
Edit Role Permission dialog box 568 Data dashboard 765
Edit Schedule view 570, 572, 574, 580, Data dashboards 615, 620, 642
581 about 616
Edit User Permission dialog box 568 Add Topology Type 617, 618, 619
Schedule Delete Confirmation dialog adding topology types 617
box 571 Create Derived Metric 44, 630, 632, 634
Manage Support Bundles 42, 44, 140, 141, adding calculations to derived metrics 634
142, 144 defining derived metrics 633
Support Bundle Inventory view 143, 144 Expression Editor dialog box 792, 793,
Manage Thresholds 41, 643, 644, 645, 647, 794, 795, 797, 798, 801
648, 650, 666 getting started with defining derived
Add Role Permission dialog box 645 metrics 633
Add User Permission dialog box 645 Scoping Query Editor dialog box 785, 786,
Delete Threshold dialog box 647, 648 787, 788, 789
Edit Role Permission dialog box 646 setting derived metric value types 639
Edit Threshold view 648, 649 triggering derived metrics 637
Edit User Permission dialog box 646 Create Registry Variable
Manage Users 43, 49, 200, 201, 203, 204, creating derived metrics 632
205, 206, 207, 208, 209, 210, 215, 218, Create Threshold 44, 648, 650, 651, 652
226, 232 adding bounds to metric threshold
Change Password dialog box 206, 207 levels 653
Confirm Delete dialog box 209, 210 creating thresholds 650
Confirm Force Password-Change dialog defining thresholds 651
box 207 selecting metrics and levels in
Confirm Unlock dialog box 208 thresholds 651
Create User dialog box 203, 204 Derived Metrics
Index 833
Delete Threshold dialog box 647, 648 Blackout Schedule Results 361
deleting internal users 209 Build Script Agent 706
Deploy Agent Package dialog box 313, 314, Business Hours 572, 573
315, 316, 346, 347, 708, 709, 710 Cartridge Confirmation 263, 264, 265
Derived Metric Scope field Change Password 206, 207
editing 784 Condition Editor 528, 529, 543, 545, 552,
derived metrics 553, 792, 793, 794, 795, 797, 798, 800,
creating 632 801
defining 633 Confirm Delete 209, 210
adding calculations 634 Confirm Force Password-Change 207
getting started 633 Confirm Script Upload 705, 706
setting value types 639 Confirm Unlock 208
triggering 637 Copy Derivation 628, 629
example Copy Registry Variable 372, 373
optimizing performance 642 Copy Schedule 569
examples Create Agent 321, 323, 324, 349, 350, 352,
creating and managing multiple rules with the 711, 712
same scope 640 Create Agent Results 323, 350, 351, 712,
using a single derivation with multiple scop- 713
ing or multiple derivations 641 Create Dashboard 30
managing 621 Create Group 214
accessing Manage Derived Metrics Create Role 223, 224
dashboard 621 Create User 203, 204
copying derived metrics 628 Delete 86
deleting derived metrics 630 Delete Agent 337
editing derived metric definitions 630 Delete Derivation 630
editing permissions 624 Delete Rule Confirmation 418, 419, 420
viewing derived metric definitions 630 Delete Threshold 647, 648
dialog boxes Deploy Agent Package 313, 314, 315, 316,
Action Parameter Editor 496, 497, 498, 533, 346, 347, 708, 709, 710
534, 535, 536 Edit Groups 205, 206, 224, 225
Add Hosts from Host Model 76, 77 Edit Retention Policy Period 692, 693, 695
Add Retention Policy 681, 689, 690, 694, Edit Role Permission 371, 414, 568, 627,
695 646
Add Role Permission 370, 413, 567, 626, Edit Roles 216, 217
645 Edit Tags 310, 311
Add User Permission 370, 413, 567, 626, Edit User Permission 371, 414, 568, 627,
645 646
Agent Operation 328, 329, 330, 331, 332, Edit Users 215, 216
333, 334, 335, 336, 714, 715, 716 Expression Editor 792, 793, 794, 795, 797,
Alarm Message Editor 454, 455, 463 798, 801
Index 835
defining rule triggers 438 Add User Permission dialog box 567
defining rule types 435 Business Hours dialog box 572, 573
defining rule-level variables 505 Copy Schedule dialog box 569
defining rules 433 copying schedules 569
Delete Rule Confirmation dialog box 418, deleting schedules 571
419, 420 Edit Role Permission dialog box 568
deleting rules 417 Edit Schedule view 570, 572, 574, 580, 581
disabling rules 418 Edit User Permission dialog box 568
Edit Role Permission dialog box 414 editing schedule definitions 573
Edit Rule view 425, 426, 427, 428, 429, 557 editing schedule permissions 565
Edit User Permission dialog box 414 Schedule Delete Confirmation dialog box 571
editing rule definitions 429 viewing schedule definitions 572, 573
editing rule permissions 411 Manage Schedules node in navigation
enabling rules 418 panel 563, 575
getting started with defining rules 434 Manage Support Bundles dashboard 42, 44,
resuming rule actions 422 139, 140, 141, 142, 144
resuming rule alarms 420 accessing 140
Rule Confirmation dialog box 415, 416, 421, server support bundles
422, 423, 424 creating 141
Scoping Query Editor dialog box 785, 786, retrieving 144
787, 788, 789 viewing content 145
setting expression scope in rule Support Bundle Inventory view 143, 144
conditions 450 Manage Support Bundles node in navigation
suspending rule actions 422 panel 140
suspending rule alarms 420 Manage Thresholds 643
Temporarily Suspend Rule Actions dialog Manage Thresholds dashboard 41, 643, 644,
box 422, 423 645, 647, 648, 650, 666
Temporarily Suspend Rule Alarms dialog accessing 643
box 420, 421 Add Role Permission dialog box 645
using trigger-specific variables in rule condi- Add User Permission dialog box 645
tion expressions 494 adding bounds to metric threshold levels 653
viewing rule definitions 429 creating thresholds 650
viewing rule schedules 424 defining thresholds 651
viewing rule summary 425 Delete Threshold dialog box 647, 648
writing rule conditions 449 deleting thresholds 647
Manage Rules node in navigation panel 409, Edit Role Permission dialog box 646
432 Edit Threshold view 648, 649
Manage Schedules dashboard 42, 361, 563, Edit User Permission dialog box 646
565, 566, 569, 570, 571, 572, 574, 575 editing threshold definitions 648
accessing 563 editing threshold permissions 644
Add Role Permission dialog box 567 selecting metrics and levels in thresholds 651
844 Foglight
Administration and Configuration Guide
Step 1: Create Registry Variable view 474 writing rule conditions 449
Step 2: Registry Variable Added view 475, Manage Registry Variables 42, 365, 366,
476 367, 368, 369, 372, 374, 375, 377, 381,
using performance calendars in registry 400, 401, 402, 403, 404, 418, 433, 471,
variables 385 472, 473, 474, 477, 481, 794
Create Rule 44, 429, 431, 432, 433, 518, accessing 365
525, 526, 527, 538, 540, 541, 542, 546, Add Role Permission dialog box 370
550, 551, 552 Add User Permission dialog box 370
Action Parameter Editor dialog box 496, Copy Registry Variable dialog box 372, 373
497, 498, 533, 534, 535, 536 copying registry variables 372
action types 466 Create Registry Value—Step 1 view 387,
actions 466 402, 403
adding actions to rules 486 Create Registry Value—Step 2 view 388,
adding severity-level variables to rules 444 403
Alarm Message Editor dialog box 454, 455, creating registry variables 377
463 deleting registry variables 374
associating rules with schedules 500 Edit Registry Variable view 375, 376, 381,
Condition Editor dialog box 528, 529, 543, 382, 402, 472, 473, 476, 477
545, 552, 553, 792, 793, 794, 795, 797, Edit Role Permission dialog box 371
798, 800, 801 Edit User Permission dialog box 371
copying rule actions 498 editing registry variables 381
copying rule conditions 464 editing variable definitions 375
copying severity-level variables 498 editing variable permissions 368
creating rules 432 getting started with editing registry
defining alarm and action behavior 503 variables 381
defining rule actions 466 Registry Variable Confirmation dialog
defining rule conditions 451, 455 box 375
defining rule conditions, alarms, and scoping registry variables to topology 387
actions 442 specifying registry variable values 383
defining rule scope 441 using performance calendars in registry
defining rule triggers 438 variables 385
defining rule types 435 viewing variable definitions 375
defining rule-level variables 505 Manage Rules 42, 48, 61, 62, 408, 409, 410,
defining rules 433 411, 412, 415, 416, 417, 418, 419, 420,
getting started with defining rules 434 421, 422, 423, 424, 426, 428, 429, 430,
Scoping Query Editor dialog box 785, 786, 432, 481, 520, 800
787, 788, 789 accessing 408
setting expression scope in rule Action Parameter Editor dialog box 496,
conditions 450 497, 498, 533, 534, 535, 536
using trigger-specific variables in rule condi- action types 466
tion expressions 494 actions 466
848 Foglight
Administration and Configuration Guide
Add Role Permission dialog box 413 setting expression scope in rule
Add User Permission dialog box 413 conditions 450
adding actions to rules 486 suspending rule actions 422
adding severity-level variables to rules 444 suspending rule alarms 420
Alarm Message Editor dialog box 454, 455, Temporarily Suspend Rule Actions dialog
463 box 422, 423
associating rules with schedules 500 Temporarily Suspend Rule Alarms dialog
Condition Editor dialog box 528, 529, 543, box 420, 421
545, 552, 553, 792, 793, 794, 795, 797, using trigger-specific variables in rule condi-
798, 800, 801 tion expressions 494
copying rule actions 498 viewing rule definitions 429
copying rule conditions 464 viewing rule schedules 424
copying rules 415 viewing rule summary 425
copying severity-level variables 498 writing rule conditions 449
creating rules 432 managing registry variables 365
defining alarm and action behavior 503 managing rules 408
defining rule actions 466 merging hosts or other topology objects 727
defining rule conditions 451, 455 Rules & Notifications node in navigation
defining rule scope 441, 442 panel 12, 13, 33, 365, 377, 390, 401, 409,
defining rule triggers 438 432, 433, 474, 518, 525, 540, 550
defining rule types 435
defining rule-level variables 505 S
defining rules 433
Schedule Confirmation dialog box 581
Delete Rule Confirmation dialog box 418,
Schedule Delete Confirmation dialog box 571
419, 420
schedules
deleting rules 417
adding schedule items 577
disabling rules 418
creating 574
Edit Role Permission dialog box 414
deleting schedule items 577
Edit Rule view 425, 426, 427, 428, 429,
getting started with schedule definitions 576
557
managing 563
Edit User Permission dialog box 414
accessing Create Schedule dashboard 575
editing rule definitions 429
accessing Manage Schedules
editing rule permissions 411
dashboard 563
enabling rules 418
copying schedules 569
getting started with defining rules 434
deleting schedules 571
resuming rule actions 422
editing permissions 565
resuming rule alarms 420
editing schedule definitions 573
Rule Confirmation dialog box 415, 416,
viewing schedule definitions 572, 573
421, 422, 423, 424
Schedules dashboards 561
Scoping Query Editor dialog box 785, 786,
about 562
787, 788, 789
Index 849
Create Schedule 44, 574, 575, 576, 577, Schema Browser node in navigation panel 686,
578 768
accessing 575 Schema dashboards
adding schedule items 577 Schema Browser 685, 686, 687, 725, 735,
creating schedules 574 738, 740, 745, 758, 768, 769
deleting schedule items 577 Schema node in navigation panel 686, 768
Edit Schedule view 579 scope
Edit Schedule—Add Schedule Item about 20
view 579 scoping queries
getting started with schedule definitions 576 using the query language 784
Schedule Confirmation dialog box 581 Scoping Query Editor dialog box 785, 786,
Step 1: Create Schedule—Schedule Name 787, 788, 789
and Description view 575 script agents
Step 2: Create Schedule—Details of Sched- building 700
ule view 577, 578 accessing Build Script Agent
Step 3: Create Schedule—Schedule Added dashboard 704
view 578 building agent packages 705
Manage Schedules 42, 361, 563, 565, 566, examples
569, 570, 571, 572, 574, 575 type 1 script 719
accessing 563 type 2 script 720
Add Role Permission dialog box 567 instances
Add User Permission dialog box 567 creating 710
Business Hours dialog box 572, 573 packages
Copy Schedule dialog box 569 deploying 707
copying schedules 569 uploading 705
deleting schedules 571 properties
Edit Role Permission dialog box 568 editing 717
Edit Schedule view 570, 572, 574, 580, script syntax 701
581 uploading 705
Edit User Permission dialog box 568 uploading agent scripts 705
editing schedule definitions 573 Script Editor dashboard
editing schedule permissions 565 accessing 721
Schedule Delete Confirmation dialog retrieving data from topology objects 725
box 571 selecting topology objects 722
viewing schedule definitions 572, 573 Script Editor node in navigation panel 722
managing schedules 563 security
Schedules node in navigation panel 12, 13, 33, managing groups 210
563, 575 managing roles 219
Schema Browser dashboard 685, 686, 687, managing users 199
725, 735, 738, 740, 745, 758, 768, 769 Select Database Platforms view 78
850 Foglight
Administration and Configuration Guide
Select Hosts For Standard Host Monitoring Foglight Configuration 42, 50, 51, 62, 98, 99,
view 78 100, 101, 102, 103, 104, 106, 117, 118,
Select Java EE Application Server Type 468, 469, 470
view 80 accessing 117
Select Technology Types view 73, 74 Database view 101, 118
Selected Agents dialog box 360 Federation Configuration view 100
Selected Installer Details view 272 Federation view 98, 99
Server Licensing Error view 25 JVM view 102
server support bundles 139 Mail (Global Settings) view 104, 105, 468,
creating 141 469, 470
retrieving 144 OS view 103
viewing content 145 Ports view 106, 107
Server view 50, 51, 99 Server view 50, 51, 99
Servers dashboards WCF view 104
Data Management 667, 675, 676, 680, 688, Manage Licenses 52, 53, 64, 133, 134, 137,
693 138
Service Builder dashboard 30 accessing 133
Service Builder node in navigation panel 30 deleting licenses 138
Service Operations Console dashboard 28 installing licenses 134
Services dashboards License Confirmation dialog box 138, 139
Domains 28 viewing license capabilities 136
Service Builder 30 Manage Support Bundles 42, 44, 139, 140,
Service Operations Console 28 141, 142, 144
Services node in navigation panel 30 accessing 140
Setup & Support dashboards 95 creating server support bundles 141
about 96 retrieving server support bundles 144
Connection Status 42, 96 Support Bundle Inventory view 143, 144
Email Configuration 27, 28, 29, 119, 120, viewing server support bundle content 145
122, 123, 124, 126, 127, 128, 130, 468, View Audit Information 42, 57, 150, 151,
470, 471, 521, 522, 523 152, 155, 156
accessing 120 accessing 151
editing email configuration parameters 123 filtering audit logs 155
Email Alias Group view 471 Show columns dialog box 152, 153
Email Routing view 120, 121 viewing audit logs 156
Email Server Configuration view 120, 129, Setup & Support node in navigation panel 12,
130, 131 13, 27, 29, 33, 95, 96, 117, 122, 133, 140,
Email Server view 471 151, 468, 470, 522
Successful dialog box 131, 132 Show columns dialog box 152, 153, 395, 396,
Test Configuration dialog box 131, 132, 397
524 specifying a condition 792
testing email configuration 129 specifying topology type properties
Index 851
using the Scoping Query Editor 788 collecting data with older timestamps 697
Step 1: Create Registry Variable view 474 Tooling dashboards 699
Step 1: Create Schedule—Schedule Name and about 700
Description view 575 Build Script Agent 43, 701, 704, 705, 706,
Step 2: Registry Variable Added view 475, 476 707, 708, 710, 711, 717, 719
Step 3: Create Schedule—Schedule Added accessing 704
view 578 Build Script Agent dialog box 706
Stopping Data Collection dialog box 335 building agent packages 705
Successful dialog box 131, 132 Confirm Script Upload dialog box 705, 706
suite 14 Create Agent dialog box 711
support 17 creating agent instances 710
Support Bundle Inventory view 143, 144 Deploy Agent Package dialog box 708,
support bundles 709, 710
client support bundles 139 deploying agent packages 707
managing 139 editing agent properties 717
accessing Manage Support Bundles uploading agent scripts 705
dashboard 140 Manage Host Aliasing Rules 726, 727, 728,
server support bundles 139 729, 730, 731, 732, 733, 734, 735, 737,
745, 750, 753, 757, 761
T changing rule priorities 730
creating rules 735
technical support 17
deleting rules 734
Temporarily Suspend Rule Actions dialog
Host Aliasing dialog box 737, 739, 740,
box 422, 423
741, 742, 743, 744, 745, 746, 747, 748,
Temporarily Suspend Rule Alarms dialog
749, 750, 751, 752, 753, 754, 755, 756,
box 420, 421
757, 758, 759, 760
Test Configuration dialog box 131, 132, 524
New Merging Rule Introduction dialog
text conventions 16
box 735, 737, 738, 745
thresholds
renaming rules 732
adding bounds to metric threshold levels 653
Manage Host Aliasing Rules dashboard
creating 650
accessing 727
defining 651
Manage Host Finder Rules
managing 642
Host Finder dialog box 741, 742, 743
accessing Manage Thresholds
Script Editor 43, 721, 722, 723, 725
dashboard 643
accessing 721
deleting thresholds 647
retrieving data from topology objects 725
editing permissions 644
selecting topology objects 722
editing threshold definitions 648
Tooling node in navigation panel 12, 13, 34,
viewing threshold definitions 648
699, 704, 722, 727
selecting metrics and levels 651
topology
timestamps
changing names or other host properties 745
852 Foglight
Administration and Configuration Guide
changing priorities of host aliasing rules 730 Manage Groups 43, 204, 210, 211, 214,
creating host aliasing rules 735 215, 216, 217, 218, 219, 220, 224
deleting host aliasing rules 734 accessing 211
merging hosts 738 assigning roles to groups 216
merging hosts or other topology objects 725, Create Group dialog box 214
727 creating groups 214
accessing Manage Host Aliasing Rule deleting internal groups 218
dashboard 727 Edit Roles dialog box 216, 217
renaming host aliasing rules 732 Edit Users dialog box 215, 216
retrieving data 721, 725 editing users in groups 215
accessing Script Editor dashboard 721 Manage Roles 43, 216, 219, 220, 221, 223,
selecting objects 722 224, 225, 226
topology types accessing 221
adding 617 Create Role dialog box 223, 224
creating users 223
U deleting internal roles 225
Edit Groups dialog box 224, 225
Unlicensed Server View 25
editing role groups 224
upgrading Foglight 177
Manage Users 43, 49, 199, 200, 201, 203,
about 157
204, 205, 206, 207, 208, 209, 210, 215,
users
218, 226, 232
adding users to groups 204
207
changing passwords 206
accessing 200
creating 203
adding users to groups 204
editing users in groups 215
Change Password dialog box 206, 207
forcing password changes 207
changing user passwords 206
managing 199
Confirm Delete dialog box 209, 210
accessing Manage Users dashboard 200
Confirm Force Password-Change dialog
unlocking passwords 207
box 207
Users & Security dashboards 197
Confirm Unlock dialog box 208
about 198
Create User dialog box 203, 204
Configure Directory Services 45, 231, 232,
creating users 203
236, 239, 243, 244, 245
Edit Groups dialog box 205, 206
editing directory settings 234
Users & Security node in navigation panel 12,
Configure Directory Services dashboard
13, 34, 201, 210, 211, 221, 228, 232, 243
accessing 232
using functions
Configure Password Services 45
with conditions 801
Configure Password Settings 208, 227, 228,
with expressions 801
229, 230
using the query language
accessing 228
in conditions 790
editing password settings 229
in scoping queries 784
Index 853