Vous êtes sur la page 1sur 853

Foglight ®

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.

License Credits and Third Party Information


To view license credit information, click the License Credits link on the Welcome to Foglight online help page.

Administration and Configuration Guide


July 2009
Version 5.5.0
Table of Contents

Introduction to this Guide .................................................................................................................................11


About Foglight ................................................................................................................................................................ 12
About this Guide............................................................................................................................................................. 12
Foglight Documentation Suite ........................................................................................................................................ 14
Core Documentation Set ....................................................................................................................................... 15
Cartridge Documentation Sets .............................................................................................................................. 15
Feedback on the Documentation........................................................................................................................... 16
Text Conventions ........................................................................................................................................................... 16
About Quest Software, Inc. ............................................................................................................................................ 16
Contacting Quest Software.................................................................................................................................... 17
Contacting Quest Support ..................................................................................................................................... 17

Getting Started with the Administration Module.............................................................................................19


About Models and Scope in Foglight.............................................................................................................................. 20
Logging in to Foglight ..................................................................................................................................................... 22
Introducing the Browser Interface .................................................................................................................................. 26
Welcome Page ...................................................................................................................................................... 26
Using a Single Pane of Glass for Your Administration Needs........................................................................................ 37
About the Administration Dashboard..................................................................................................................... 38
Accessing the Administration Dashboard.............................................................................................................. 57

Extending Your Monitoring Reach ...................................................................................................................67


About Extending Your Monitoring Reach ....................................................................................................................... 68
Accessing the Extend Your Monitoring Reach Dashboard ............................................................................................ 70
Completing Configuration Interviews.............................................................................................................................. 72
Viewing Configuration Plans .......................................................................................................................................... 84
Completing Configuration Tasks .................................................................................................................................... 89
4 Foglight
Administration and Configuration Guide

Setting Up Foglight ........................................................................................................................................... 95


About Foglight Setup ...................................................................................................................................................... 96
Viewing Connection Status............................................................................................................................................. 96
Viewing Foglight Configuration ....................................................................................................................................... 98
Accessing the Foglight Configuration Dashboard................................................................................................ 117
Configuring Email Actions............................................................................................................................................. 119
Accessing the Email Configuration Dashboard.................................................................................................... 120
Editing Email Parameters .................................................................................................................................... 123
Testing Email Configuration................................................................................................................................. 129
Managing Licenses....................................................................................................................................................... 133
Accessing the Manage Licenses Dashboard....................................................................................................... 133
Installing Licenses................................................................................................................................................ 134
Viewing License Capabilities ............................................................................................................................... 136
Deleting Licenses................................................................................................................................................. 138
Managing Support Bundles .......................................................................................................................................... 139
Accessing the Manage Support Bundles Dashboard .......................................................................................... 140
Creating Server Support Bundles ........................................................................................................................ 141
Retrieving Server Support Bundles...................................................................................................................... 144
Viewing Audit Information ............................................................................................................................................. 150
Accessing the View Audit Information Dashboard ............................................................................................... 151
Filtering Audit Logs .............................................................................................................................................. 155
Viewing Log Entries ............................................................................................................................................. 156
Backing Up, Upgrading, and Restoring Foglight........................................................................................................... 157
Backing Up Foglight............................................................................................................................................. 157
Upgrading Foglight............................................................................................................................................... 177
Restoring Foglight................................................................................................................................................ 178
About Database Management in Foglight .................................................................................................................... 193
Monitoring the Size of the Database.................................................................................................................... 193
Managing Database Size Using Retention Policies............................................................................................. 193
Factoring In Database Serviceability Metrics for More Accurate Estimates......................................................... 194
Reclaiming Table Space ...................................................................................................................................... 195

Managing Users and Security ........................................................................................................................ 197


About Security in Foglight............................................................................................................................................. 198
Managing Users............................................................................................................................................................ 199
Table of Contents 5

Accessing the Manage Users Dashboard ............................................................................................................200


Creating Users .....................................................................................................................................................203
Adding Users to Groups .......................................................................................................................................204
Changing Passwords ...........................................................................................................................................206
Forcing Password Changes .................................................................................................................................207
Unlocking Passwords ...........................................................................................................................................207
Deleting Internal Users.........................................................................................................................................209
Managing Groups..........................................................................................................................................................210
Accessing the Manage Groups Dashboard..........................................................................................................211
Creating Groups ...................................................................................................................................................214
Editing Users in Groups .......................................................................................................................................215
Assigning Roles to a Group..................................................................................................................................216
Deleting Internal Groups ......................................................................................................................................218
Managing Roles ............................................................................................................................................................219
Accessing the Manage Roles Dashboard ............................................................................................................221
Creating Roles......................................................................................................................................................223
Editing Groups for a Role .....................................................................................................................................224
Deleting Internal Roles .........................................................................................................................................225
Configuring Password Settings .....................................................................................................................................227
Accessing the Configure Password Settings Dashboard .....................................................................................228
Editing Password Settings....................................................................................................................................229
Changing Database Credentials ..........................................................................................................................230
Configuring Directory Services......................................................................................................................................231
Accessing the Configure Directory Services Dashboard......................................................................................232
Example: Integrating Foglight LDAP Directory Services with Microsoft Windows Active Directory .....................238

Managing Cartridges .......................................................................................................................................249


About Foglight Cartridges .............................................................................................................................................250
About Cartridge Components...............................................................................................................................250
Installing and Managing Cartridges...............................................................................................................................251
Accessing the Cartridge Inventory Dashboard.....................................................................................................252
Installing Cartridges..............................................................................................................................................258
Enabling Cartridges..............................................................................................................................................261
Disabling Cartridges .............................................................................................................................................262
Uninstalling Cartridges .........................................................................................................................................263
6 Foglight
Administration and Configuration Guide

Downloading Agent Components ................................................................................................................................. 265


Using the Browser Interface to Download Agent Components............................................................................ 266
Downloading Agent Components Remotely ........................................................................................................ 269

Managing Agents ............................................................................................................................................ 277


About Foglight Agents .................................................................................................................................................. 278
Managing Agent Properties by Type ............................................................................................................................ 279
Accessing the Agent Properties Dashboard ........................................................................................................ 280
Editing Type-Specific Agent Properties ............................................................................................................... 283
Viewing the Properties of the FglAMAdaper Agent.............................................................................................. 290
Installing and Managing Agent Instances on a Monitored Host.................................................................................... 292
Accessing the Agent Status Dashboard .............................................................................................................. 293
Editing Agent Properties by Agent Instance ........................................................................................................ 296
Editing Agent Tags............................................................................................................................................... 310
Deploying Agent Packages to a Monitored Host ................................................................................................. 312
Activating or Deactivating Agents ........................................................................................................................ 327
Starting or Stopping Data Collection.................................................................................................................... 331
Deleting Agents.................................................................................................................................................... 337
Retrieving Agent Logs.......................................................................................................................................... 338
Deploying Agent Instances to Multiple Monitored Hosts .............................................................................................. 342
Accessing the Agent Hosts Dashboard ............................................................................................................... 343
Deploying Agent Packages to Multiple Hosts ...................................................................................................... 345
Creating Agent Instances on Multiple Hosts ........................................................................................................ 348
Viewing Agent Adapters ............................................................................................................................................... 353
Accessing the Agent Adapters Dashboard .......................................................................................................... 354
Activating or Deactivating Agent Adapters........................................................................................................... 356
Assigning Blackouts to Agent Instances....................................................................................................................... 357

Working with Foglight Rules and Registry ................................................................................................... 363


About Rules, Registry, and Topology in Foglight.......................................................................................................... 364
Working with Foglight Registry Variables ..................................................................................................................... 364
Managing Registry Variables ............................................................................................................................... 365
Creating Registry Variables ................................................................................................................................. 377
Editing Registry Variables.................................................................................................................................... 381
Viewing Registry Values ...................................................................................................................................... 390
Table of Contents 7

Example: Assigning Multiple Values to a Registry Variable .................................................................................399


Example: Using Performance Calendars .............................................................................................................399
Example: Assigning Host-Specific Email Addresses of Foglight System Administrators.....................................400
Working with Rules .......................................................................................................................................................406
Managing Rules ...................................................................................................................................................408
Creating Rules......................................................................................................................................................432
Defining Rules ......................................................................................................................................................433
Defining Conditions, Alarms, and Actions ............................................................................................................442
Associating Rules with Schedules........................................................................................................................500
Defining Alarm and Action Behavior.....................................................................................................................503
Defining Rule-Level Variables ..............................................................................................................................505
Rules Included with the Foglight Management Server.........................................................................................508
Example: Creating a Multiple-Severity Rule Scoped to an EJB Instance ............................................................518
Example: Creating a Simple Data-Driven Rule Scoped to a Topology Type that Triggers Email Actions ...........520
Example: Creating Multiple-Severity Rules with a Topology Scope.....................................................................539
Example: Configuring Rule Action Parameters ....................................................................................................547
Example: Creating Rules Scoped to Different Topology Types ...........................................................................548
Example: Associating Command Actions with Rules ...........................................................................................556

Using Schedules ..............................................................................................................................................561


About Schedules ...........................................................................................................................................................562
Managing Schedules.....................................................................................................................................................563
Accessing the Manage Schedules Dashboard.....................................................................................................563
Editing Schedule Permissions..............................................................................................................................565
Copying Schedules ..............................................................................................................................................569
Deleting Schedules ..............................................................................................................................................571
Viewing Schedule Definitions ...............................................................................................................................572
Viewing and Editing Schedules ............................................................................................................................573
Creating Schedules.......................................................................................................................................................574
Accessing the Create Schedule Dashboard.........................................................................................................575
Getting Started with Schedule Definitions ............................................................................................................576
Adding or Removing Schedule Items ...................................................................................................................577
Defining Schedule Items ......................................................................................................................................582

Working with Data............................................................................................................................................615


8 Foglight
Administration and Configuration Guide

About Data Management in Foglight ............................................................................................................................ 616


Adding Topology Types ................................................................................................................................................ 617
Working with Derived Metrics ....................................................................................................................................... 620
Managing Derived Metrics ................................................................................................................................... 621
Creating Derived Metrics ..................................................................................................................................... 632
Defining Derived Metrics...................................................................................................................................... 633
Example: Creating and Managing Multiple Rules with the Same Scope ............................................................. 640
Example: Using a Single Derivation with Multiple Scoping or Multiple Derivations ............................................. 641
Example: Optimizing Performance ...................................................................................................................... 642
Working with Thresholds .............................................................................................................................................. 642
Managing Thresholds .......................................................................................................................................... 642
Creating Thresholds............................................................................................................................................. 650
Defining Thresholds ............................................................................................................................................. 651
Managing Retention Policies ........................................................................................................................................ 666
About Retention Policy Mechanisms ................................................................................................................... 668
Deleting Retention Policies .................................................................................................................................. 680
Editing Retention Policies .................................................................................................................................... 688
Creating Retention Policies.................................................................................................................................. 693
Example: Addressing Data Storage Concerns .................................................................................................... 696
Enabling the Collection of Data with Older Timestamps............................................................................................... 697

Working with Foglight Tooling....................................................................................................................... 699


About Foglight Tooling.................................................................................................................................................. 700
Building Script Agents................................................................................................................................................... 700
Looking at the Script Syntax ................................................................................................................................ 701
Accessing the Build Script Agent Dashboard ...................................................................................................... 704
Uploading Agent Scripts and Building Agent Packages ...................................................................................... 705
Deploying Script Agent Packages........................................................................................................................ 707
Creating and Activating Script Agent Instances................................................................................................... 710
Editing Script Agent Properties ............................................................................................................................ 717
Example: Type 1 Script........................................................................................................................................ 719
Example: Type 2 Script........................................................................................................................................ 720
Retrieving Data with Queries and Scripts ..................................................................................................................... 721
Accessing the Script Editor Dashboard ............................................................................................................... 721
Selecting Topology Objects ................................................................................................................................. 722
Table of Contents 9

Retrieving Data.....................................................................................................................................................725
Merging Host Objects....................................................................................................................................................725
Managing Host Aliasing Rules .............................................................................................................................727
Creating Host Aliasing Rules................................................................................................................................735

Using the Query Language .............................................................................................................................763


About the Query Language ...........................................................................................................................................764
Viewing Topology Models ....................................................................................................................................764
Viewing Topology Types ......................................................................................................................................767
Query Language Reference .................................................................................................................................773
Using the Query Language to Set the Rule or Derived Metric Scope...........................................................................784
Setting the Scope for a Rule or Derived Metric ....................................................................................................784
Using the Query Language in Rule Conditions or Derived Metric Expressions ............................................................790
About the Query Language in Rule Expressions and Messages .........................................................................791
Specifying Rule Conditions or Derived Metric Expressions .................................................................................792
Using Functions with Conditions and Expressions...............................................................................................801
Using the Query Language FAQ...................................................................................................................................805

Appendix: Foglight Client Reference.............................................................................................................807


Starting the Foglight Client............................................................................................................................................808
Viewing the Content of a Foglight Client Support Bundle .............................................................................................808
Browser Interface ..........................................................................................................................................................811
Command-Line Interface...............................................................................................................................................814

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.

This chapter contains the following sections:


About Foglight .............................................................................................................................12
About this Guide..........................................................................................................................12
Foglight Documentation Suite .....................................................................................................14
Text Conventions .........................................................................................................................16
About Quest Software, Inc...........................................................................................................16
12 Foglight
Administration and Configuration Guide

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.

About this Guide


This Administration and Configuration Guide provides conceptual information about
Foglight administration components, configuration instructions, and instructions on
how to use the dashboards in the Administration module.
This guide is intended for Foglight System Administrators to administer and configure
Foglight.
The Administration and Configuration Guide is organized as follows:
Chapter 1, Getting Started with the Administration Module—Discusses core
Foglight concepts, introduces the Administration module (a getting started approach),
and lists common administration tasks. It also lists the nodes that appear in the
Administration module and describes the type of tasks you can perform using the
dashboards that appear under each node: Agents, Cartridges, Data, Rules &
Notifications, Schedules, Setup & Support, Tooling, and Users & Security. Read this
chapter to learn about Foglight models and scope, access the Foglight Administration
module, and find out what type of administration tasks you can perform in Foglight.
Chapter 2, Extending Your Monitoring Reach—Includes information about setting
up a monitoring environment quickly and easily, using the Extend Your Monitoring
Reach dashboard. Read this chapter to find out how to complete configuration
interviews, view configuration plans, and complete configuration tasks when
monitoring hosts, databases, or JavaEE applications.
Chapter 3, Setting Up Foglight—Includes information about Foglight licenses and
support bundles, audit logs, and configuration items, and how to use them. Read this
chapter to find out how to gather Foglight diagnostic data during run-time, view port
Introduction to this Guide 13
About this Guide

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

Appendix A, Foglight Client Reference—Contains examples of dashboards and


command-line output in environments that use the Foglight Client for agent
communication and management.

Foglight Documentation Suite


The Foglight documentation suite is made up of the core documentation set, plus the
documentation set for each Foglight cartridge that you deploy. Documentation is
provided in a combination of online help, PDF and HTML formats.
• Online Help: You can open the online help by selecting the Help tab from
Foglight’s action panel.

• 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.

Core Documentation Set


The core documentation set consists of the following documents:
• Release Notes (HTML)
• Middleware Release Notes (HTML)
• Getting Started Guide (PDF)
• What’s New Guide (PDF)
• System Requirements and Platform Support Guide (PDF)
• Upgrade Guides (PDF)
• Installation and Setup Guide set (all in PDF format)
• Administration and Configuration Guide (PDF and online help)
• Foglight User Guide (PDF and online help)
• Command-Line Reference Guide (PDF and online help)
• Transition Guide (PDF)
• Web Component Guide (PDF and online help)
• Web Component Tutorial (PDF and online help)
• Web Component Reference (online help)

Cartridge Documentation Sets


When you deploy a cartridge, the documentation set for it is installed. The online help
for the cartridge is integrated automatically with the core Foglight help. When you open
the help, the name of the cartridge is displayed in a top level entry within the table of
contents.
Most cartridges include additional PDF guides, which may be one or more of the
following: a Getting Started Guide, an Installation Guide, a User Guide, and a
Reference Guide. Cartridges also generally include their own Release Notes.
16 Foglight
Administration and Configuration Guide

Feedback on the Documentation


We are interested in receiving feedback from you about our documentation. For
example, did you notice any errors in the documentation? Were any features
undocumented? Do you have any suggestions on how we can improve the
documentation? All comments are welcome. Please submit your feedback to the
following email address:
am.docfeedback@quest.com
Please do not submit Technical Support requests to this email address.

Text Conventions
The following table summarizes how text styles are used in this guide:

Convention Description

Code Monospace text represents code, code objects, and command-


line input. This includes:
• Java language source code and examples of file contents
• Classes, objects, methods, properties, constants, and events
• HTML documents, tags, and attributes

Variables Monospace-plus-italic text represents variable code or


command-line objects that are replaced by an actual value or
parameter.

Interface Bold text is used for interface options that you select (such as
menu items) as well as keyboard commands.

Files, components, Italic text is used to highlight the following items:


and documents • Pathnames, file names, and programs
• The names of other documents referenced in this guide

About Quest Software, Inc.


Quest Software, Inc., a leading enterprise systems management vendor, delivers
innovative products that help organizations get more performance and productivity from
Introduction to this Guide 17
About Quest Software, Inc.

their applications, databases, Windows infrastructure and virtual environments.


Through a deep expertise in IT operations and a continued focus on what works best,
Quest helps more than 100,000 customers worldwide meet higher expectations for
enterprise IT. Quest provides customers with client management as well as server and
desktop virtualization solutions through its subsidiaries, ScriptLogic and Vizioncore.
Quest Software can be found in offices around the globe and at www.quest.com.

Contacting Quest Software

Email info@quest.com

Mail Quest Software, Inc.


World Headquarters
5 Polaris Way
Aliso Viejo, CA 92656
USA

Web site www.quest.com

Refer to our web site for regional and international office information.

Contacting Quest Support


Quest Support is available to customers who have a trial version of a Quest product or
who have purchased a commercial version and have a valid maintenance contract. Quest
Support provides around the clock coverage with SupportLink, our web self-service.
Visit SupportLink at: http://support.quest.com.
From SupportLink, you can do the following:
• Quickly find thousands of solutions (Knowledgebase articles/documents).
• Download patches and upgrades.
• Seek help from a Support engineer.
• Log and update your case, and check its status.
View the Global Support Guide for a detailed explanation of support programs, online
services, contact information, and policy and procedures. The guide is available at:
http://support.quest.com/pdfs/Global Support Guide.pdf.
18 Foglight
Administration and Configuration Guide
1
Getting Started with the
Administration Module

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.

This chapter contains the following sections:


About Models and Scope in Foglight...........................................................................................20
Logging in to Foglight ..................................................................................................................22
Introducing the Browser Interface................................................................................................26
Using a Single Pane of Glass for Your Administration Needs .....................................................37
20 Foglight
Administration and Configuration Guide

About Models and Scope in Foglight


A model is a principle for organizing monitoring data that Foglight gathers from host
systems. Foglight models have a tree-like structure that contains nodes. Each node in
the model can have properties, metrics, alarms and other nodes associated with it.
Foglight adds these entities to the nodes in the data model as it collects them.
Foglight can create different types of models. Collection models include raw data.
Virtual models are built on top of other models. There are two types of virtual models:
aggregate models, that do not require any additional configuration, and user models,
that require user-based configuration. Depending on your monitoring needs and the type
and range of Foglight cartridges that you use for gathering data, your system includes
one or more collection models. An example of a collection model is the Host Model
illustrated above that collects information about host machines.
The following diagram illustrates a simplified version of the Host Model that Foglight
builds in a typical business scenario.
Figure 1
Utilization Paging rate

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

Utilization Paging rate

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.

2 Obtain your Foglight user name and password.


To obtain full access to the Administration module, ensure that your user account
belongs to a group with the Administrator and Security roles. For more
information, see “Managing Users and Security” on page 197.
3 Ensure that your Web browser has the JavaScript functionality enabled.
Note Foglight displays dynamic data that is regularly updated. For this reason it is
recommended that you do not use your browser’s Back and Forward buttons, as this
may cause cached views to be displayed or result in an error message.

4 Start the browser interface.


Getting Started with the Administration Module 23
Logging in to Foglight

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.

The Foglight login page appears in the Web browser.

5 Provide the user name and password you obtained in step 2.


a In the Foglight login page, in the User box, type your Foglight user name.
b In the Password box, type your Foglight password.
c Click Login.
Depending on the availability of a valid Foglight license and your user
permissions, one of the following pages appears in the display area:
• If your Foglight Management Server has a valid license, the Welcome page
appears in the browser interface.
24 Foglight
Administration and Configuration Guide

Navigation panel Display area Action panel

The Foglight browser interface contains the following elements:

• 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

Users whose account includes the Administration role

Users whose account does not include the Administration role

If your user account includes the Administration role, in the Unlicensed


Server View, click Install License. In the Manage Licenses dashboard that
appears, install the license for the Foglight Management Server. For
instructions on how to add a license, see Chapter 3, “Installing Licenses” on
page 134.
If your user account does not include the Administration role, contact your
Foglight administrator, as indicated in the Server Licensing Error view.
From here, after a successful login, you can explore the Administration dashboards in
the browser interface. For more information, see “Introducing the Browser Interface” on
page 26.
26 Foglight
Administration and Configuration Guide

Introducing the Browser Interface


This section describes the main dashboards that you see in a default installation:
• “Welcome Page” on page 26
• “Administration Dashboards” on page 31

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

dashboard. Choosing this option is equivalent to clicking Administration >


Setup & Support > Email Configuration on the navigation panel. For more
information about this dashboard, see Chapter 3, “Configuring Email Actions” on
page 119.
• Report on Your Enterprise: View reports that are scheduled, run a report using a
report template, create a custom report, schedule a report to run at a specific time
frame, and manage reports. This link takes you to the Reports dashboard.
Choosing this option is equivalent to clicking Reports under Homes on the
navigation panel. For more information on reports, see the Foglight User Guide.
• Do More with Foglight: Define your own custom services, quickly build
dashboards, view agents status, and perform other administrative functions.
Clicking this link shows the Do More With Foglight page containing additional
links to the dashboards that show more details about each aspect of your system
health.

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

• Define Services: Build a service to organize the collected data into


meaningful business components. This link takes you to the Service Builder
dashboard. Choosing this option is equivalent to clicking Services > Service
Builder on the navigation panel. For more information about this dashboard,
see the Foglight User Guide.
• Contact Supportlink: Navigate to the Quest Support home page and look for
existing problem solutions, download patches and upgrades, seek help from a
Support engineer, log and update your case, and check its status.
• Build a Dashboard: Quickly create a dashboard using a dashboard editor, and
create your own view that illustrates your business environment and its
monitored data. Clicking this link shows the Create Dashboard dialog box.
Choosing this option is equivalent to clicking Create dashboard under Other
Actions in the action panel.
• View Agent Status: Observe the status of the agent instances, create new
agents, or manage the existing ones. This link takes you to the Agent Status
dashboard. Choosing this option is equivalent to clicking Administration >
Agents > Agent Status on the navigation panel. For more information about
this dashboard, see Chapter 6, “Installing and Managing Agent Instances on a
Monitored Host” on page 292.
• Explore Foglight Documentation: Learn more about Foglight by reading the
online help topics. This links shows the help content in a new tab or Web
browser instance (depending on the type and version of your Web browser).
Choosing this option is equivalent to opening the Help tab on the action panel
and clicking a help book under Help Contents.
• Tap Into the Foglight Community: Navigate to http://www.foglight.org to read
blogs about Foglight and actively participate in existing discussions.
The Welcome to Foglight page will remain your default home page unless you set a
different home page. For instructions on changing your home page to a dashboard of
your choice, or about the operator’s version of the Welcome page, see the Foglight User
Guide.
Getting Started with the Administration Module 31
Introducing the Browser Interface

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.

Node Tasks See

Administration View entry points to the This chapter, “Using a


Administration module and use it Single Pane of Glass for
as a portal to your administration Your Administration
tasks Needs” on page 37

Agents List and assign agent blackouts Chapter 6, “Managing


Agents” on page 277
Deploy agent packages to hosts

View and edit agent properties

Manage agents

Activate or deactivate agent


adapters

Cartridges Install, list, and manage cartridges Chapter 5, “Managing


Cartridges” on page 249
List and download agent installers
Getting Started with the Administration Module 33
Introducing the Browser Interface

Node Tasks See

Data Add topology types Chapter 9, “Working


with Data” on page 615
Add derived metrics

Add thresholds

List, edit or delete derived metrics

List, edit or delete retention


policies

List, add, edit, or delete thresholds

Rules & Notifications Add registry variables Chapter 7, “Working


with Foglight Rules and
Add rules Registry” on page 363

List, edit, or delete registry


variables

List, edit, or delete rules

Schedules Add schedules Chapter 8, “Using


Schedules” on page 561
List, edit, or delete schedules

Setup & Support Check connection status Chapter 3, “Setting Up


Foglight” on page 95
View port assignments

View, edit, or test email


configuration parameters

List, add, or delete licenses

List, add, or delete support bundles

View audit information


34 Foglight
Administration and Configuration Guide

Node Tasks See

Tooling Upload scripts for building agents Chapter 10, “Working


with Foglight Tooling”
Edit and run queries and scripts on page 699

Merge host objects

Users & Security List, add, edit, or delete users Chapter 4, “Managing
Users and Security” on
List, add, edit, or delete groups page 197

List, add, edit, or delete roles

View or edit password settings

View or edit directory services

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.

To access the Administration dashboards:

Note This procedure continues from “Logging in to Foglight” on page 22.

1 Ensure that the navigation panel is open.


To open the navigation panel, click the right-facing arrow on the left.
2 On the navigation panel, under Dashboards, expand the Administration
module.
A set of nodes appears under the Administration module.
Getting Started with the Administration Module 35
Introducing the Browser Interface

3 Expand a node that appears under the Administration module.


For example, to look at dashboards that let you manage agents and hosts, expand
the Agents node.

4 Select a dashboard and look at its contents in the display area.


For example, to look at the Agent Status dashboard that allows you to manage
Foglight agents, on the navigation panel, under Dashboards, choose
Administration > Agents > Agent Status.
The Agent Status dashboard appears in the display area.
36 Foglight
Administration and Configuration Guide

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

Using a Single Pane of Glass for Your Administration


Needs
The Administration dashboard can be used as a front-end for most of your
administration tasks. This dashboard contains links to most of the administration
dashboards and shows some configuration information that may be critical to your day-
to-day operation. If your Foglight role involves daily administration, this is probably the
best place to start as it gives you a quick insight into the system complexity and its
health, along with close-at-hand links to all of the Administration dashboards.
Figure 6

An alternative way to access any of the Administration dashboards is through the


Administration node on the navigation panel, as described in “Administration
Dashboards” on page 31.
38 Foglight
Administration and Configuration Guide

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

About the Administration Dashboard


The Administration dashboard contains links to the majority of administration
dashboards, logically grouped. It also provides some high-level information about the
health and state of your environment, including the number of active agents, cartridges,
rules, and users, a list of licensed capabilities that reflect the features defined in your
Foglight license, and a list of audit activities such as login entries or agent-related
operations.
Use this dashboard as a central point for common administration tasks. From here, you
can navigate to most of the dashboards that come with the Administration module.
Getting Started with the Administration Module 39
Using a Single Pane of Glass for Your Administration Needs

The Administration dashboard contains the following views:


• Navigation (see page 39)
• Current Statistics (see page 45)
• Currently Licensed Capabilities (see page 51)
• License Information (see page 52)
• Federation (see page 54)
• Audited Activities (see page 56)
The sections below describe the views that appear on the Administration dashboard in
more detail. For complete information about accessing the Administration dashboard
and using it to perform administration tasks, see “Accessing the Administration
Dashboard” on page 57.

About the Navigation view


The Navigation view contains links to Administration dashboards.
40 Foglight
Administration and Configuration Guide

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.

Entry Dashboard Use it to


or View

Explore

Agents

Adapters Agent Activate or deactivate agent adapters.


Adapters For more information, see “Viewing Agent
Adapters” on page 353.

Blackouts Agent List and assign agent blackouts.


Blackouts For more information, see “Assigning
Blackouts to Agent Instances” on page 357.

Hosts Agent Hosts Deploy agent packages to hosts.


For more information, see “Deploying
Agent Instances to Multiple Monitored
Hosts” on page 342.

Properties by Agent View and edit agent properties.


Type Properties For more information, see “Managing
Agent Properties by Type” on page 279.
Getting Started with the Administration Module 41
Using a Single Pane of Glass for Your Administration Needs

Entry Dashboard Use it to


or View

Status Agent Status Manage agents.


For more information, see “Deploying
Agent Instances to Multiple Monitored
Hosts” on page 342.

Cartridges

Inventory Cartridge Install, list, and manage cartridges.


Inventory For more information, see “Installing and
Managing Cartridges” on page 251.

Component Components List and download agent installers.


Download for Download For more information, see “Downloading
Agent Components” on page 265.

Data

Data Data View the Foglight topology.


Management Management

Derived Metrics Manage List, edit or delete derived metrics.


Derived For more information, see “Managing
Metrics Derived Metrics” on page 621.

Retention Manage List, edit or delete retention policies.


Policies Retention For more information, see “Editing
Policies Retention Policies” on page 688.

Thresholds Manage List, add, edit, or delete thresholds.


Thresholds For more information, see “Managing
Thresholds” on page 642.

Topology Types Add Topology Add topology types.


Type For more information, see “Adding
Topology Types” on page 617.

Rules and Notifications


42 Foglight
Administration and Configuration Guide

Entry Dashboard Use it to


or View

Registry Manage List, edit, or delete registry variables.


Variables Registry For more information, see “Managing
Variables Registry Variables” on page 365.

Rules Manage Rules List, edit, or delete rules.


For more information, see “Managing
Rules” on page 408.

Setup and Support

Audit View Audit View audit log entries.


Information Information For more information, see “Viewing Audit
Information” on page 150.

Connection Connection Check connection status.


Status Status For more information, see “Viewing
Connection Status” on page 96.

Foglight Foglight View Foglight configuration items.


Configuration Configuration For more information, see “Viewing
Foglight Configuration” on page 98.

Licenses Manage List, add, or delete licenses.


Licenses For more information, see “Managing
Licenses” on page 133.

Support Manage List, add, or delete support bundles.


Bundles Support For more information, see “Managing
Bundles Support Bundles” on page 139.

Schedules

Schedule Manage List, edit, or delete schedules.


Management Schedules For more information, see “Using
Schedules” on page 561.

Tooling and Diagnostics


Getting Started with the Administration Module 43
Using a Single Pane of Glass for Your Administration Needs

Entry Dashboard Use it to


or View

Server Log Log Analyzer Lists server log entries. For more
Overview information about this dashboard, see the
Foglight User Guide.

Server Performance Contains a series of tabs, each containing a


Performance Overview dashboard about the performance of a
Overview monitoring component. For more
information about this dashboard, see the
Foglight User Guide.

Script Agent Build Script Upload scripts for building agents.


Builder Agent For more information, see “Building Script
Agents” on page 700.

Script Editor Script Editor Allows you to query the Foglight database.
For more information, see “Retrieving Data
with Queries and Scripts” on page 721.

Users and Security

Groups Manage List, add, edit, or delete groups.


Groups For more information, see “Managing
Groups” on page 210.

Roles Manage Roles List, add, edit, or delete roles.


For more information, see “Managing
Roles” on page 219.

Users Manage Users List, add, edit, or delete users.


For more information, see “Managing
Users” on page 199.

Tasks

Create
44 Foglight
Administration and Configuration Guide

Entry Dashboard Use it to


or View

Topology Type Add Topology Add topology types.


Type For more information, see “Adding
Topology Types” on page 617.

Derived Metric Create Add derived metrics.


Derived Metric For more information, see “Creating
Derived Metrics” on page 632.

Threshold Create Add thresholds.


Threshold For more information, see “Creating
Thresholds” on page 650.

Registry Create Add registry variables.


Variable Registry For more information, see “Creating
Variable Registry Variables” on page 377.

Rule Create Rule Add rules.


For more information, see “Creating Rules”
on page 432.

Schedule Create Add schedules.


Schedule For more information, see “Creating
Schedules” on page 574.

Support Bundle Manage Create a server support bundle. When you


Support click Support Bundle, a message box
Bundles appears, indicating that a server support
bundle is created, as illustrated below.
For more information, see “Managing
Support Bundles” on page 139.

Configure
Getting Started with the Administration Module 45
Using a Single Pane of Glass for Your Administration Needs

Entry Dashboard Use it to


or View

Directory Configure View or edit directory services.


Services Directory For more information, see “Configuring
Services Directory Services” on page 231.

Password Configure View or edit password settings.


Settings Password For more information, see “Configuring
Services Password Settings” on page 227.

About the Current Statistics view


The Current Statistics view contains information about the installed cartridges, active
agents, rules, users, and the Foglight Management Server configuration.
Figure 8

This view displays the following information:


• Active Agents (see page 45)
• Installed Cartridges (see page 46)
• Rules (see page 48)
• Users (see page 49)
• Server Version (see page 50)
• Server OS (see page 50)

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

A Foglight agent is an application that monitors a specific part of your environment,


such as an operating system, application, or server. This number gives you a rough idea
on how much data is coming into the Foglight Management Server. If you have no
active agents, there is probably a connectivity issue between the agents and Foglight
Management Server. If that number is lower than you think it should be, clicking the
Active Agents entry drills down to the Agent Status dashboard.

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

A Foglight cartridge contains components that encapsulate a specific Foglight


functionality. Your monitoring environment includes a set of server-specific cartridges,
as well as additionally installed Foglight cartridges that are designed to monitor a
specific type of environment. This number includes both the cartridges that come with
the Foglight Management Server, and any other installed cartridges that exist in your
system. Clicking the Installed Cartridges entry drills down to the Cartridge Inventory
dashboard.
Figure 10

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.

About the Currently Licensed Capabilities view


The Currently Licensed Capabilities view lists available licenses and their status
(enabled or disabled). A Foglight license, typically distributed as in a foglight.license
file, contains the information about the capabilities that are licensed. Installing this file
on the Foglight Management Server enables all of the licensed capabilities. You can
52 Foglight
Administration and Configuration Guide

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

About the License Information view


The License Information view contains information about one or more installed
licenses. A Foglight license, typically distributed as in a foglight.license file, contains
the information about the capabilities that are licensed. Installing this file on the
Foglight Management Server enables all of the licensed capabilities. You can install a
Foglight license either using the command line, or the Manage Licenses dashboard.
Getting Started with the Administration Module 53
Using a Single Pane of Glass for Your Administration Needs

Figure 20

This view displays the following information:


• Installed Licenses (see page 54)
• Expired Licenses (see page 54)
• Licenses Expiring in 30 Days (see page 54)
Clicking any of the entries drills down to the Manage Licenses dashboard.
Figure 21

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

Licenses Expiring in 30 Days


The number on the right of Licenses in 30 Days in the License Information view is the
number of licenses that will expire in the next 30 days. 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 24

About the Federation view


The Federation view contains information about the server federation. Federation is a
Foglight feature that allows you to monitor large environments that are partitioned into
Getting Started with the Administration Module 55
Using a Single Pane of Glass for Your Administration Needs

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

This view displays the following information:


• Federation Mode (see page 56)
• Number of Children (see page 56)
Clicking any of the entries drills down to the Foglight Server Topology view which
appears in the display area.
Figure 26

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

About the Audited Activities view


The Audited Activities view lists the operations that are invoked on the Foglight
Management Server.
Figure 29

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.

Accessing the Administration Dashboard


The navigation panel contains links to the Administration dashboard. After logging into
the Foglight browser interface, this dashboard can be accessed by clicking
Administration, under Homes, or alternatively it can be found under Dashboards,
Administration > Administration.
58 Foglight
Administration and Configuration Guide

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:

Note This procedure continues from “Logging in to Foglight” on page 22.

1 Ensure that the navigation panel is open.


To open the navigation panel, click the right-facing arrow on the left.
2 On the navigation panel, under Dashboards, choose Administration >
Administration.
The Administration dashboard appears in the display area.
Getting Started with the Administration Module 59
Using a Single Pane of Glass for Your Administration Needs

3 In the Administration dashboard, observe the Navigation view.

The Navigation view contains links to Administration dashboards, grouped into


task-specific categories. For complete information about this view, see “About
the Navigation view” on page 39.
Drill down to another dashboard in the Administration module using a link in the
Navigation view. For example, to drill down to the Agent Hosts dashboard, under
Explore > Agents, click Properties by Type.
The Agent Properties dashboard appears in the display area.
60 Foglight
Administration and Configuration Guide

To return to the Administration dashboard, click Administration in the


breadcrumb trail.
4 In the Administration dashboard, observe the Current Statistics view.
The Current Statistics view shows the number of active agents, cartridges, rules,
and users in your monitoring environment, and shows the version of the Foglight
Management Server and its OS version.
• To find out more about the agents that are collecting data from monitored
hosts in your environment, in the Current Statistic view, click Active Agents.
The Agent Status dashboard appears in the display area.

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

To return to the Administration dashboard, click Administration in the


breadcrumb trail.
• To find out more about the cartridges that are installed on the Foglight
Management Server, in the Current Statistic view, click Installed
Cartridges.
The Cartridge Inventory dashboard appears in the display area.

For complete information about the Cartridge Inventory dashboard, see


Chapter 5, “Installing and Managing Cartridges” on page 251.
To return to the Administration dashboard, click Administration in the
breadcrumb trail.
• To find out more about the rules that exist in your environment, in the Current
Statistic view, click Rules.
The Manage Rules dashboard appears in the display area.
62 Foglight
Administration and Configuration Guide

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

To return to the Administration dashboard, click Administration in the


breadcrumb trail.
5 In the Administration dashboard, observe the Currently Licensed Capabilities
view.

The Currently Licensed Capabilities view lists license-related features,


indicating which features are included in your license. An icon appears to the
right of each capability, indicating if the capability is licensed.
6 In the Administration dashboard, observe the License Information view.
64 Foglight
Administration and Configuration Guide

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.

To return to the Administration dashboard, click Administration in the


breadcrumb trail.
7 In the Administration dashboard, observe the Federation view.
Getting Started with the Administration Module 65
Using a Single Pane of Glass for Your Administration Needs

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.

To return to the Administration dashboard, click Administration in the


breadcrumb trail.
8 In the Administration dashboard, observe the Audited Activities view.
66 Foglight
Administration and Configuration Guide

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.

This chapter contains the following sections:


About Extending Your Monitoring Reach.....................................................................................68
Accessing the Extend Your Monitoring Reach Dashboard..........................................................70
Completing Configuration Interviews...........................................................................................72
Viewing Configuration Plans........................................................................................................84
Completing Configuration Tasks..................................................................................................89
68 Foglight
Administration and Configuration Guide

About Extending Your Monitoring Reach


A monitoring setup includes defining hosts, databases, and/or applications whose
performance you intend to monitor. Configuring these entities involves installing and
configuring applicable cartridges and their agents. Extend Your Monitoring Reach,
allows you to quickly generate an interactive configuration plan that helps you to
efficiently configure your monitoring environment. With this dashboard you can
perform the following tasks:
• Complete configuration interviews to generate configuration plans
• View a configuration plans
• Complete configuration tasks in a configuration plan

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.

A configuration plan can be used to describe your entire monitoring environment, or


some of its components. For example, if you have a large monitoring environment and
Extending Your Monitoring Reach 69
About Extending Your Monitoring Reach

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

Accessing the Extend Your Monitoring Reach Dashboard


The Extend Your Monitoring Reach dashboard allows you to specify your business
requirements based on which you will compile a list of tasks that you need to complete
in order to set up your monitoring environment.
To access the Extend Your Monitoring Reach dashboard:

Note This procedure continues from “Logging in to Foglight” on page 22.

1 Ensure that the Welcome page appears in the display area.


To access the welcome page, on the navigation panel, click Main under Homes.
Tip To open the navigation panel, click the right-facing arrow on the left.

2 On the Welcome page, click Extend Your Monitoring Reach.


The Extend Your Monitoring Reach dashboard appears in the display area,
showing two options you can choose from: Start a new configuration interview
and View existing configuration plans.
Extending Your Monitoring Reach 71
Accessing the Extend Your Monitoring Reach Dashboard

• Clicking Start a new configuration interview creates a new configuration


plan. For more information, see “Completing Configuration Interviews” on
page 72.
• Clicking View existing configuration plans lists the existing plans and takes
you to a specific plan, as selected. For more information, see “Viewing
Configuration Plans” on page 84.
72 Foglight
Administration and Configuration Guide

Completing Configuration Interviews


Generating a configuration plan involves completing a configuration interview during
which you describe your monitoring needs. Here, you provide the information about
any hosts, JavaEE applications, or databases that you plan to monitor with Foglight.
Upon successful completion of these steps, the workflow generates an interactive list of
tasks that you need to complete to configure your monitoring entities.

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

To complete a configuration interview:

Note This procedure continues from “Accessing the Extend Your Monitoring Reach Dashboard”
on page 70.

1 On the Extend Your Monitoring Reach dashboard, click Start a new


configuration interview.
The Select Technology Types view appears in the display area.
74 Foglight
Administration and Configuration Guide

2 Specify the type of monitoring.


a In the Select Technology Types view, select any of the available options:

Option Monitors

Hosts Host computers’ CPU, memory and disk


consumption, and the network activity

Databases Database activity

JavaEE Systems JavaEE application servers, server groups, and


individual JavaEE applications

b Move to the next step in the wizard by clicking Next.


The List Hosts to Monitor view appears in the display area.
Extending Your Monitoring Reach 75
Completing Configuration Interviews

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:

Option Choose this option to specify hosts by:

Enter host names Typing the host names.


manually

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

Option Choose this option to specify hosts by:

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.

Discover Hosts Using the Cartridge for Discovery.


Note The Discover Hosts option requires an installed
and active Cartridge for Discovery. For more
information about this cartridge, see your Cartridge
for Discovery documentation.

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.

b In the List Hosts to Monitor view, click Next.


4 Provide information about the hosts that you want to monitor for those
technology types that you choose in step 2.
78 Foglight
Administration and Configuration Guide

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.

b Database monitoring only. In the Select Database Platforms view that


appears, choose one or more database types that you want to monitor by
selecting the appropriate check box: DB2, Oracle, SQL Server (for SQL
Server 2000), SQL Server 2005 (for SQL Server 2005 and 2008), or
Sybase.
Click Next.
Extending Your Monitoring Reach 79
Completing Configuration Interviews

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.

c JavaEE application monitoring only. In the Select Java EE Application


Server Type view that appears, specify the Java EE application server types,
followed by clicking Next.
Extending Your Monitoring Reach 81
Completing Configuration Interviews

In the refreshed display area, continue with the JavaEE configuration.


If you selected multiple JavaEE application servers, you are presented with a
series of deployment steps that you need to perform for each application
server. The type and range of the steps that you perform here depend on the
type of the selected application servers. Some steps are common for all
application servers, such as specifying the domain name for a group of hosts,
and the JVM or OS information for each host. Other steps are different for
each application server, as dictated by their platform requirements.
For example, when configuring JBoss or Oracle application servers, you
specify the hosts, while WebSphere domains may require the specification of
the Deployment Manager and Node Agents. Similarly, WebLogic domains can
have an Admin Server and Node Managers. For more information about the
82 Foglight
Administration and Configuration Guide

types of application server nodes in your environment, see your application


server documentation.
Tip Configuring JavaEE application servers with Foglight requires the Cartridge for
JavaEE. The configuration plan that you are about to generate includes the
instructions for installing this cartridge on the Foglight Management Server and its
configuration. For additional information, you can also refer to the Cartridge for
JavaEE 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.

The generated configuration plan appears in the display area.


Extending Your Monitoring Reach 83
Completing Configuration Interviews

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

Viewing Configuration Plans


A configuration plan contains a list of tasks that you need to perform to quickly get
started with monitoring your environment. The list is interactive and gives you an
option to perform most of the configuration tasks without leaving the Extend Your
Monitoring Reach dashboard. The tasks are grouped into steps. For example, tasks for
installing cartridges are grouped together while, tasks for setting up the database appear
in a step.
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,
A configuration plan can contain up to six deployment steps:

Deployment step Monitoring type

Host Database JavaEE

Set Up FglAM Yes Yes No

Install Cartridges Yes Yes Yes

Set Up Host Monitoring Yes No No

Set Up Database Monitoring No Yes No

Install the Instrumented Agent for Java EE No No Yes

Instrument Java EE Application Servers No No Yes

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

You can view a configuration plan immediately after completing a configuration


interview, or at a later time, as described below.
To view a configuration plan:

Note This procedure continues from “Accessing the Extend Your Monitoring Reach Dashboard”
on page 70.
86 Foglight
Administration and Configuration Guide

1 On the Extend Your Monitoring Reach dashboard, click View existing


configuration plans.
Tip The number of completed task lists appears in the parenthesis on the right.

2 The Configuration Plans view appears in the display area.

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

dialog box that appears, click the Delete button.

3 Open a configuration plan.


a Select the configuration whose task list you want to view.
In the Configuration Plans view, in the Name column, click the row
containing a completed configuration.
A dwell appears, allowing you to open the configuration plan.

b In the dwell, click View Configuration Plan.


The selected configuration plan appears in the display area.
88 Foglight
Administration and Configuration Guide

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

Completing Configuration Tasks


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 four steps: a step for installing Foglight Agent Manager on
monitored hosts, a step for installing the required cartridges on the Foglight
Management Server, and the steps for setting up host, database, and/or JavaEE
monitoring, as illustrated below.
Each configuration task includes a description that helps you understand the action you
are about to perform. In some cases, a task includes detailed instructions on how to
complete it, and, if applicable, a link to the target dashboard that you use to complete the
task. Some tasks in the configuration plan can include controls that help you complete
the task without leaving the configuration plan.
Task instructions include any applicable background information and hands-on
instructions. In the case of database or JavaEE monitoring, where you need to install the
applicable cartridges on the Foglight Management Server, you can refer to the
appropriate cartridge installation guides for additional information.
Upon a successful completion, you can mark the task as complete and move to the next
one to complete your configuration plan.
90 Foglight
Administration and Configuration Guide

Figure 4

To complete a configuration task:

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

3 Complete the task as instructed.


Read carefully the information provided with each task. The information you see
here has detailed information about each task and the required instructions. For
additional information on any of the specific tasks related to database or JavaEE
monitoring, see your cartridge documentation.
4 After a successful completion, click Mark As Complete.
The task refreshes, and a green check mark on the right indicates that the task
is complete.

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

manually mark deployment steps as complete or incomplete, as you configure your


Foglight environment.
94 Foglight
Administration and Configuration Guide
3
Setting Up Foglight

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.

This chapter contains the following sections:


About Foglight Setup ...................................................................................................................96
Viewing Connection Status..........................................................................................................96
Viewing Foglight Configuration....................................................................................................98
Configuring Email Actions ......................................................................................................... 119
Managing Licenses....................................................................................................................133
Managing Support Bundles .......................................................................................................139
Viewing Audit Information..........................................................................................................150
Backing Up, Upgrading, and Restoring Foglight .......................................................................157
About Database Management in Foglight .................................................................................193
96 Foglight
Administration and Configuration Guide

About Foglight Setup


The Administration module includes a number of features that allow you to gather data
about Foglight while it is running, such as audit logs and diagnostic data that can be sent
to Quest Support. Additionally, it includes a set of dashboards that you can use to view
Foglight connection status, port numbers, database properties, or manage licenses and
server support bundles.

Viewing Connection Status


The Connection Status dashboard lists the agent manager instances that are connected to
the Foglight Management Server, including any instances of Foglight Agent Manager or
Foglight Client.

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:

Note This procedure continues from “Logging in to Foglight” on page 22.

1 Ensure that the navigation panel is open.


To open the navigation panel, click the right-facing arrow on the left.
2 On the navigation panel, under Dashboards, choose Administration > Setup &
Support > Connection Status.
The Connection Status dashboard appears in the display area, showing a list of the
agent manager instances connected to the Foglight Management Server.
Setting Up Foglight 97
Viewing Connection Status
98 Foglight
Administration and Configuration Guide

Viewing Foglight Configuration


The Foglight Configuration dashboard provides information about Foglight
configuration items.
The configuration settings that appear in this dashboard reflect the settings that you
specify at or after the installation while others can be set at run-time. For example, the
database settings whose values appear in the Foglight Configuration dashboard are
typically set after the installation in the file <foglight_home>/config/foglight.config.
Any changes to the parameters in this file take effect only after a restart of the Foglight
Management Server. Other types of settings reflect the version, and in some cases, the
patch level of the components that come with Foglight, such as the Foglight
Management Server, WCF, JVM, or refer to the OS of the computer on which the
Foglight Management Server is installed, and its patch level. These settings cannot be
changed unless you choose to upgrade to a higher version of Foglight, if one is
available. There are also some settings that can be defined using Foglight registry
variables. For example, the values that reflect global mail settings, which Foglight uses
for sending emails, as required, are specified in the Foglight registry. Changes to these
settings do not require a system restart.
The Foglight Configuration dashboard contains the following views:
• Federation (see page 98)
• Server (see page 99)
• Federation Configuration (see page 100)
• Database (see page 101)
• JVM (see page 102)
• OS (see page 103)
• WCF (see page 104)
• Mail (Global Settings) (see page 104)
• Ports (see page 106)

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’.

For information on how to view the information on the Foglight Configuration


dashboard, see “Accessing the Foglight Configuration Dashboard” on page 117.
From the Federation view, you can drill down to the Foglight Server Topology view
by clicking Federation Mode or Number of Children to see additional details about
the federation status.
Figure 1

Server
The Server view displays the following settings:
100 Foglight
Administration and Configuration Guide

• Version. The version number of the Foglight Management Server whose


configuration items you are viewing.
• Build. The build version of the Foglight Management Server whose
configuration items you are viewing.
• Foglight Home. The installation directory of the Foglight Management Server on
the computer on which it is installed.
• JBoss Server Directory. The installation directory of the JBoss application
server that is running Foglight Management Server, on the computer on which the
Foglight Management Server is installed.
Figure 2

For information on how to view the information on the Foglight Configuration


dashboard, see “Accessing the Foglight Configuration Dashboard” on page 117.

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

For information on how to view the information on the Foglight Configuration


dashboard, see “Accessing the Foglight Configuration Dashboard” on page 117.

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

• User. The database user name. This setting is defined by the


foglight.database.user parameter.
• Location. Indicates if the database is embedded or external. This setting is
defined by the foglight.database.embedded parameter.
Figure 4

For information on how to view the information on the Foglight Configuration


dashboard, see “Accessing the Foglight Configuration Dashboard” on page 117.

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

<foglight_home>/logs/ManagementServer_<date>_<time>_001.log , as shown in the


code listing below that illustrates the default JVM settings.
VM Options:
-dsa
-da
-Djava.net.preferIPv4Stack=true
-Xrs
XX:+UseAltSigs
exit
-Dsun.java.command=org.jboss.Main
-Xms782m
-Xmx782m
-XX:MaxPermSize=195m
-Djava.endorsed.dirs=C:\Quest_Software\Foglight\lib\endorsed
-Djava.awt.headless=true
-Dsun.rmi.dgc.client.gcInterval=86400000
-Dsun.rmi.dgc.server.gcInterval=86400000
-XX:+ForceTimeHighResolution
-XX:+UseConcMarkSweepGC
-XX:+CMSClassUnloadingEnabled
-Dsun.lang.ClassLoader.allowArraySyntax=true
-Djava.security.manager
-Djava.security.policy=C:\Quest_Software\Foglight\config\
foglight.policy
For information on how to view the information on the Foglight Configuration
dashboard, see “Accessing the Foglight Configuration Dashboard” on page 117.

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

For information on how to view the information on the Foglight Configuration


dashboard, see “Accessing the Foglight Configuration Dashboard” on page 117.

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

For information on how to view the information on the Foglight Configuration


dashboard, see “Accessing the Foglight Configuration Dashboard” on page 117.

Mail (Global Settings)


This view contains email settings that are used by Foglight when sending messages to
specified recipients. For example, you can configure Foglight to generate and send
reports to a specified mail recipient, or email warning messages to Foglight
administrators when certain thresholds are reached. For information on how to
configure email actions in Foglight, see “Configuring Email Actions” on page 119.

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 example: http://MyHost.MyDomain.com:8080/


Setting Up Foglight 105
Viewing Foglight Configuration

For information on how to look up Foglight registry variables, see Chapter 7, “Managing
Registry Variables” on page 365.

The Mail (Global Settings) view displays the following settings:


• Connection Timeout. The default connection timeout for sending emails to
specified email recipients. This setting is defined by the global value of the
mail.connection.timeout Foglight registry variable.
Important The mail.connection.timeout variable does not come with Foglight. To configure
the global connection 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.

• 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

For information on how to view the information on the Foglight Configuration


dashboard, see “Accessing the Foglight Configuration Dashboard” on page 117.

Ports
This view lists ports used by Foglight.
Figure 9

For information on how to view the information on the Foglight Configuration


dashboard, see “Accessing the Foglight Configuration Dashboard” on page 117.
The Ports view displays the following ports:
Setting Up Foglight 107
Viewing Foglight Configuration

• 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.

Default port assignments


The following table shows the default port assignments for the ports listed in the Ports
view along with a few other ports that are used for communication with the database or
internal application ports. The port numbers can be specified at installation time, or after
the installation using the configuration parameters in the file <foglight_home>/config/
foglight.config. For more information, see the Installation and Setup Guide.
108 Foglight
Administration and Configuration Guide

Port Server/Client Communication

Firewall Impact?

Communication
Default Number

Listens On

Direction
Used By
Name

1098 JNDI RMI N/A


Port Note This port is not involved for server/client communication.

Description: Port for the Remote Method Invocation (RMI) naming service.

Configuration parameter: foglight.jndi.rmi.port

1099 JNDI JNP N/A


Port Note This port is not involved for server/client communication.

Description: Port for the bootstrap JNP service.

Configuration parameter: foglight.jndi.jnp.port


Setting Up Foglight 109
Viewing Foglight Configuration

Port Server/Client Communication

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.

Configuration parameter: foglight.ha.jndi.jnp.port


110 Foglight
Administration and Configuration Guide

Port Server/Client Communication

Firewall Impact?

Communication
Default Number

Listens On

Direction
Used By
Name

1101 HA JNDI Foglight Foglight No From HA


RMI Port Management Management Foglight
Server Server Management
Server Primary
to HA Foglight
Management
Server
Secondary and
the other way
around

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.

Configuration parameter: foglight.ha.jndi.rmi.port


Setting Up Foglight 111
Viewing Foglight Configuration

Port Server/Client Communication

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.

Configuration parameter: foglight.ha.jndi.udpgroup.port

3306 Database MySQL Foglight Yes From Foglight


Port Database Management Management
Server Server to
database back-
end

Description: User-defined port for connecting to the database.

Configuration parameter: foglight.database.port


112 Foglight
Administration and Configuration Guide

Port Server/Client Communication

Firewall Impact?

Communication
Default Number

Listens On

Direction
Used By
Name

3528 ORB Foglight Foglight Yes From Foglight


(IIOP) Port Management Client Client to
Server Foglight
Management
Server

Description: Corba ORB port used by the Foglight Client.

Configuration parameter: foglight.orb.port

3529 ORB Foglight Foglight Yes From Foglight


(IIOP) SSL Management Client Client to
Port Server Foglight
Management
Server

Description: Corba ORB SSL port used by the Foglight Client.

Configuration parameter: foglight.orb.ssl.port

4444 JRMP N/A


INVOKER Note This port is not involved in server/client communication.
Port

Description: Port for the RMI/JRMP invoker.

Configuration parameter: foglight.jrmp.invoker.port


Setting Up Foglight 113
Viewing Foglight Configuration

Port Server/Client Communication

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.

Configuration parameter: foglight.ha.pooled.invoker.port

4447 HA JRMP 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: 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.

Configuration parameter: foglight.ha.jrmp.invoker.port


114 Foglight
Administration and Configuration Guide

Port Server/Client Communication

Firewall Impact?

Communication
Default Number

Listens On

Direction
Used By
Name

8080 HTTP Port Foglight Browser Yes From the


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

Description: HTTP/1.1 connector used for HTTP connections.

Configuration parameter: foglight.http.port


Setting Up Foglight 115
Viewing Foglight Configuration

Port Server/Client Communication

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

Description: HTTP/1.1 connector used for HTTPS connections.

Configuration parameter: foglight.https.port


Note The Foglight Management Server uses the HTTP port for local access even if you are
accessing the browser interface through an HTTPS connection. If that is the case, both
ports are open: the HTTPS port for external requests coming from the browser interface
and the HTTP port for local requests. For example, the reporting service accesses the
Foglight Management Server through the HTTP port while external requests use
HTTPS.

8448 QP5 Foglight Foglight No Local to


Application Management Management Foglight
Port Server Server Management
Server

Description: Port for the SQL parser.

Configuration parameter: foglight.qp5app.port


116 Foglight
Administration and Configuration Guide

Port Server/Client Communication

Firewall Impact?

Communication
Default Number

Listens On

Direction
Used By
Name

41705 JavaEE Foglight JavaEE Agent Yes From JavaEE


Agent Management Agent to
Server Foglight
Management
Server

Description: Port used by the JavaEE Agent. For more information about the
JavaEE Agent, see your JavaEE cartridge documentation.

Configuration parameter: Unlike other configuration parameters that are described


in this table, whose values can be viewed and edited in the server configuration file,
<foglight_home>/config/foglight.config, this port can be set in the configuration file
that ships with the JavaEE Agent. For more information about this file, see your
JavaEE cartridge documentation.

45566 Cluster Foglight Foglight No From HA


Mcast Port Management Management Foglight
Server Server Management
Server Primary
to HA Foglight
Management
Server
Secondary and
the other way
around

Description: Cluster multi-cast port. It is used when Foglight is running in the HA


mode. For more information about the HA mode, see the Installation and Setup
Guide.

Configuration parameter: foglight.cluster.mcast_port


Setting Up Foglight 117
Viewing Foglight Configuration

Accessing the Foglight Configuration Dashboard


Use the Foglight Configuration dashboard when you need to find out the configuration
of your monitoring environment.
To access the Foglight Configuration dashboard:

Note This procedure continues from “Logging in to Foglight” on page 22.

1 Ensure that the navigation panel is open.


To open the navigation panel, click the right-facing arrow on the left.
2 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.
118 Foglight
Administration and Configuration Guide

3 In the Foglight Configuration dashboard, locate the view that contains


information about a set of configuration items, as required.
For example, to find out what is the name of the database host, scroll down to the
Database view, and inspect the Host setting.
For complete information about each view that appears in the Foglight
Configuration dashboard, see the following sections:
• “Federation” on page 98
• “Server” on page 99
• “Federation Configuration” on page 100
• “Database” on page 101
• “JVM” on page 102
Setting Up Foglight 119
Configuring Email Actions

• “OS” on page 103


• “WCF” on page 104
• “Mail (Global Settings)” on page 104
• “Ports” on page 106

Configuring Email Actions


Foglight uses email actions to send reports to email recipients or to email alarm-related
messages to Foglight administrators when certain thresholds are reached. This can
happen, for example, when a rule that has an email action is triggered, or for emailing
scheduled reports.
Email actions can be associated with rules using the rule editor. For more information
about adding actions with rules, see Chapter 7, “Defining actions” on page 466. You can
create scheduled reports in Foglight using the Report Manager dashboard. For more
information, see the Foglight User Guide.
The Foglight registry includes a set of variables that can be used to specify default email
settings. A proper configuration of these settings enables Foglight to send emails to
selected recipients using your email server and an existing email account. The Email
Configuration dashboard lists the email configuration parameters and their values, and
acts as an interface between the email settings and the Foglight registry: each email
configuration parameter points to its respective registry value. Editing an email
parameter results in updating the registry variable that parameter points to.

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.

The list of parameters on the Email Configuration dashboard indicates which


parameters are mandatory, thereby simplifying your workflow and minimizing the
configuration effort.
120 Foglight
Administration and Configuration Guide

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

Accessing the Email Configuration Dashboard


Use the Email Configuration dashboard to view, configure and test email configuration
parameters in Foglight. A proper configuration of these settings enables Foglight to
send emails to selected recipients when certain thresholds are reached.
The dashboard contains two views, Email Server Configuration and Email Routing,
each containing a group of configuration parameters. Each parameter contains a registry
value that Foglight uses to carry out email actions. The following table lists the
parameters as they appear on the Email Configuration dashboard and shows their
relationship with their corresponding registry variables.

Parameter Registry Variable Required? Description

Email Server Configuration view

Mail Server mail.host Yes Name or IP address of the mail


(Name or IP) server.

Email Sender mail.from Yes Email address of the user that


Address Foglight uses to send emails.

Username to mail.user No User name of the account that


Login to Server Foglight uses to send emails.

User Password mail.password No Password of the user account


that Foglight uses to send
emails
Note If your mail server requires user authentication, you need to supply the user name and
password. For more information, contact you mail server administrator.
Setting Up Foglight 121
Configuring Email Actions

Parameter Registry Variable Required? Description

Mail Server Port mail.port No Port number that Foglight uses


to communicate with the mail
server. The default value is 25.
If you intend to use a different
port number, you need to set
this parameter.

Mail Protocol mail.transport No Protocol used for sending


.protocol emails. The default protocol is
SMTP. If you intend to use a
different email protocol, you
need to set this parameter.

Enable Debug mail.debug No Indicates whether email-


Mode? related debugging are stored in
the log.

Enable mail.smtp.star No Indicates whether you want to


STARTTLS? ttls.enable enable the STARTTLS
protocol and use encryption
when sending emails from
Foglight.

Enable SSL? mail.use.ssl No Indicates whether you want to


enable the SSL protocol and
use encryption when sending
emails from Foglight.

Email Routing view

Tip Configure the email alias addresses listed below to receive alarm-related emails from
Foglight.

Database DBADMIN No Database administrator email


Notifications addresses.

JavaEE J2EEADMIN No JavaEE administrator email


Notifications addresses.
122 Foglight
Administration and Configuration Guide

Parameter Registry Variable Required? Description

Operating SYSADMIN No System administrator email


System addresses.
Notifications

Global mail.recipient No Default recipient email


Notifications addresses.

To access the Email Configuration dashboard:

Note This procedure continues from “Logging in to Foglight” on page 22.

1 Ensure that the navigation panel is open.


To open the navigation panel, click the right-facing arrow on the left.
2 On the navigation panel, under Dashboards, choose Administration > Setup &
Support > Email Configuration.
Tip Another way to access this dashboard is through the Administrator’s version of the
Welcome page. To do that, from the Welcome page, click Configure Email Settings.
For more information about this page, see Chapter 1, “Welcome Page” on page 26.

The Email Configuration dashboard appears in the display area, showing the
current email settings.
Setting Up Foglight 123
Configuring Email Actions

3 Observe the Email Configuration dashboard.


Tip If you have not previously configured any of the email settings either using this
dashboard or email-related registry variables, none of the values are set, with the
exception of Enable Debug Mode which is set to false, and Mail Protocol which is set
to smtp, as shown in the above example.

From here, you can proceed to edit the email parameters. For instructions, see “Editing
Email Parameters” on page 123.

Editing Email Parameters


Use the Edit button on the Email Configuration dashboard to edit email settings.
124 Foglight
Administration and Configuration Guide

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

Bread crumb trail

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

To edit an email parameter using the Email Configuration dashboard:

Note This procedure continues from “Accessing the Email Configuration Dashboard” on
page 120.

1 On the Email Configuration dashboard, locate the row containing the


configuration parameter that you want to edit.
Important Specifying the Mail Server (Name or IP) and Email Sender Address parameters
is mandatory for a successful email configuration.

2 In the Edit column, click .


A dwell appears, allowing you to specify the parameter value.

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.

Testing Email Configuration


After configuring all of the applicable email parameters, you can test your configuration
to ensure success of future email actions initiated by Foglight. Use the Test
Configuration button on the Email Server Configuration view to quickly test the newly-
set email parameters.
130 Foglight
Administration and Configuration Guide

Figure 12

Testing email configuration involves specifying a destination email address. Using an


email address that you can easily access, such as your own email address, allows you to
quickly confirm the arrival of the test email. The test email arrives to the specified
destination address immediately after initiating the email test action, with Test Email
from Foglight as the subject.

To test an email configuration:

Note This procedure continues from “Editing Email Parameters” on page 123.

1 Ensure that all of your email parameters are properly set.


In the Email Configuration dashboard, in the Email Server Configuration view,
observe the Value column of each individual parameter.
Tip The Mail Server (Name or IP) and Email Sender Address parameters are
mandatory for a successful email configuration. Your mail server setup may require
additional parameters to be set, such as the user name and password of the default
sender, amongst others. For more information about the email parameters, see
“Accessing the Email Configuration Dashboard” on page 120.

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

Make any additional changes to any configuration parameters, if applicable. For


instructions on how to edit a configuration parameter, see “Editing Email
Parameters” on page 123.
2 In the Email Server Configuration view, click Test Configuration.
The Test Configuration dialog box appears.

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

4 Check your email.


Your mailbox contains a new email message with the subject Test Email from
Foglight.
Observe the sender’s email address. This is the value specified by the Email
Sender Address parameter. For more information about configuring this and
other email parameters, see “Editing Email Parameters” on page 123.
5 Close the Successful and Test Configuration dialog boxes.
The email configuration is complete.
Setting Up Foglight 133
Managing Licenses

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.

Accessing the Manage Licenses Dashboard


The Manage Licenses dashboard allows you to view, install, and delete licenses for your
Foglight Management Server installation. This page consists of three areas: Install
Licenses, Licensed Capability Summary, and a listing of currently installed licenses.
To access the Manage License dashboard:

Note This procedure continues from “Logging in to Foglight” on page 22 or “Accessing the
Administration Dashboard” on page 57.

1 Ensure that the navigation panel is open.


To open the navigation panel, click the right-facing arrow on the left.
2 On the navigation panel, under Dashboards, choose Administration > Setup &
Support > Manage Licenses.
The Manage Licenses dashboard appears in the display area, showing the list of
installed licenses.
134 Foglight
Administration and Configuration Guide

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.

Viewing License Capabilities


The Licensed Capability Summary area provides an overview of the licensed
capabilities currently enabled on the Foglight Management Server. A Foglight license,
typically distributed as in a foglight.license file, contains the information about the
capabilities that are licensed. Installing this file on the Foglight Management Server
enables all of the licensed capabilities. For information on how to install a license, see
“Installing Licenses” on page 134.
Each capability has an icon that is associated with it:

Cartridge Installation

Configuration Management

Data Archiving Trending

High Availability

LDAP Integration

Performance Calendars

Request Trace Analysis

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.

Licensed cartridges License capabilities

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.

For information on how to install a cartridge, see Chapter 5, “Managing


Cartridges” on page 249.
• If a license includes a license for one or more agents, it shows agent icons
( ). When you point your mouse over that icon, a tooltip appears, showing
the agent name along with the number of licensed agents.

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.

Managing Support Bundles


Foglight allows you to gather diagnostic data from the Foglight Management Server or
the Foglight Agent Manager. and save it in a support bundle.
There are two types of support bundles that you can create in Foglight:
• Server support bundles. Contain a number of files, including a diagnostic
snapshot of the Foglight Management Server, log files, and a list of cartridges
installed on the Foglight Management Server computer. Foglight saves each
server support bundle as a .ZIP file in the <foglight_home>/support/
<user_name> directory on the machine hosting the Foglight Management
Server.
140 Foglight
Administration and Configuration Guide

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.

Accessing the Manage Support Bundles Dashboard


Using the Administration module, you can gather diagnostic data from the Foglight
Management Server and save it in a support bundle for analysis by Quest Support.
To access the Manage Support Bundles dashboard:

Note This procedure continues from “Logging in to Foglight” on page 22.

1 Ensure that the navigation panel is open.


To open the navigation panel, click the right-facing arrow on the left.
2 On the navigation panel, under Dashboards, choose Administration > Setup &
Support > Manage Support Bundles.
Setting Up Foglight 141
Managing Support Bundles

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

Creating Server Support Bundles


A server support bundle contains diagnostic data gathered from the Foglight
Management Server. Foglight saves this data in a .ZIP file. When you click Create
Bundle on the Manage Support Bundles dashboard, the Foglight Management Server
creates the .ZIP file in the <foglight_home>/support/<user_name> directory on the
computer hosting the Foglight Management Server.
142 Foglight
Administration and Configuration Guide

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.

1 Optional. Specify the description of the support bundle.


In the Manage Support Bundles dashboard, in the Create Support Bundle area,
type the description in the Description box.
For example: My support bundle.
2 Click Create Bundle.
A status bar appears above the Create Bundle button indicating that the bundle
creation is in progress.

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.

3 Save the generated ZIP file to disk.


The newly-generated support bundle appears in the Support Bundle Inventory
view.

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

Retrieving Server Support Bundles


Foglight stores support bundles in the <foglight_home>/support/<user_name>
directory on the computer hosting the Foglight Management Server. You can retrieve a
copy of an existing support bundle as a file download using the Support Bundle
Inventory view immediately after its creation or at a later time.
To retrieve a server support bundle:

Note This procedure continues from “Accessing the Manage Support Bundles Dashboard” on
page 140.

1 In the Manage Support Bundles dashboard, in the Support Bundle Inventory


view, locate the support bundle that you want to retrieve.
2 Click the Name column of the row containing the support bundle.
Your Web browser shows a dialog box that allows you to open or save the support
bundle.

Note The appearance of the above dialog may be different, depending on the type and
version of your Web browser.

3 Save the file to disk.


Setting Up Foglight 145
Managing Support Bundles

Viewing the Content of Server Support Bundles


Server support bundles contain diagnostic data gathered from the Foglight Management
Server.
To view the content of a server support bundle:

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

AuditingLog_*.xml A listing of recent auditable changes to the


FMS/registry/rules/cartridges/security/etc
It contains information about the before and
after states of a configuration object,
including rules, registry variables, agent
properties, schedules, derived metrics, or
thresholds, for changes that occur within the
applicable default time range.

DiagnosticSnapshot_*.txt A diagnostic snapshot consisting of service


status, agent status, thread dump, etc

DirectoryListing_*.txt A full file listing for all files under the FMS
home directory

Foglight_<version>_InstallLog.log FMS installation log

InstalledCartridges_*.xml A listing of all installed cartridges, and their


versions

MonitoringPolicies_*.xml An export of the Monitoring Policies


(persistent configuration) of the FMS

support_bundle_foglight_*.xml Brief description about this support bundle

config/

agent-weight.config Defines the “weight” of attached agents.


Used to help determine FMS load

foglight.config Config parameters for the FMS

log.config Config parameters for the FMS logging


capabilities

remote_monitor.config Various configuration options for running


the FMS as a service

remote_monitor.log.config Various log configuration options for the


FMS
Setting Up Foglight 147
Managing Support Bundles

restart_monitor.config FMS restart configuration parameters (as a


service)

server_restarter.log.config Logging parameters for the FMS

logs/

ManagementServer_*.log The three most recent FMS logs

server/

default/

conf/

jacorb.properties FMS JacORB configuration parameters

deploy/

nitro-dyn-ds.xml FMS data source definition

jbossweb-
tomcat55.sar/

context.xml JBoss application configuration file

server.xml JBoss application configuration file

Note The “*” indicates a date/time stamp of the format “YYYY-MM-DD_HH-MM-SS”“.


148 Foglight
Administration and Configuration Guide

Viewing the Content of a Foglight Agent Manager Support


Bundle
Foglight Agent Manager support bundles contain diagnostic data about the Foglight
Agent Manager. When you create a Foglight Agent Manager support bundle using the
support-bundle command, Foglight saves this data in a ZIP file in the
<foglight_agent_mgr_home>/state/default/support directory on the computer hosting
the Foglight Agent Manager. It uses the following syntax when naming the file:
supportbundle-fglam-host_name-yyyy-mm-ddThh-mm-ss.zip
For example: supportbundle-fglam-MyHost-2008-07-29T22-08-49.zip
For more information about this command, see the Command-Line Reference Guide.
To view the content of a Foglight Agent Manager support bundle:

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>AttributeDefs.xml Attributes for the


agent package
Setting Up Foglight 149
Managing Support Bundles

<agent_type>ConfigDefs.xml Property
configuration
definitions for the
agent package

<agent_type>LogDefs.xml Log definitions


for the agent
package

<agent_type>Manifest.xml Manifest for the


agent package

<agent_type>ProcedureDefs.xml Procedure
definitions for the
agent package

common/

jvminfo.txt Java VM
information

jvmthreaddump.txt Java thread dump


information

mbean-info.txt MBean
information

glueconfig/

fglam.config.xml Foglight Agent


Manager
configuration
information

log.config Log
configuration

process.config Process
configuration

tools.config Tools information


150 Foglight
Administration and Configuration Guide

vm.config VM
configuration

logs/

FglAM-<yyyy>-<mm>-<dd>T<hh>-<mm>-<ss>.log Successful
startup logs

failed-startup-<yyyy>-<mm>-<dd>T<hh>-<mm>-<ss>.log Failed startup


logs

<cartridge_name>/

<cartridge_version>/

<agent_type>/

<agent_name>_<yyyy>-<mm>-<dd>_<hhmmss>_001.log Agent log

system/

<os>-system-info.txt OS information

Viewing Audit Information


Foglight maintains security and change audit logs that you can view using the View
Audit Information dashboard. Audit logs allow you to review information about users
who have been authenticated upon logging in to the Administration Module, changes
made in the Administration Module with regard to user management, or changes made
to configuration items such as rules or registry variables.
The View Audit Information dashboard allows you to select the time period for which
you want to view audit logs. Each log includes information such as the date and time at
which the action is performed, name of the user who initiated the action, name of the
service that carried out the action, and the operation name.
For complete information, about viewing audit information, see the following sections:
• “Accessing the View Audit Information Dashboard” on page 151
• “Filtering Audit Logs” on page 155
Setting Up Foglight 151
Viewing Audit Information

• “Viewing Log Entries” on page 156

Accessing the View Audit Information Dashboard


Use the View Audit Information dashboard to select a time period for which you want to
view security and change audit logs and display logs. It allows you to review security
and change audit logs and to filter the list of logs to show information for a specific span
of time. Optionally, you can show or hide the columns that appear in the audit log table,
or print the table contents to a file as required.
To access the View Audit Information dashboard:

Note This procedure continues from “Logging in to Foglight” on page 22.

1 Ensure that the navigation panel is open.


To open the navigation panel, click the right-facing arrow on the left.
2 On the navigation panel, under Dashboards, choose Administration > Setup &
Support > View Audit Information.
The View Audit Information dashboard appears in the display area, showing the
Zonar and a list of audit logs underneath.

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

The Show columns dialog box appears.

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.

5 Optional. Print the list of audit logs to a file.


a In the audit log table, in the Operation Name (Name) column, click the
Show/Hide columns button.

Show/Hide columns

The Show columns dialog box appears.

b In the Show Columns dialog box, under Actions, click one of the following
links:
154 Foglight
Administration and Configuration Guide

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.

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.

From here, you can proceed to any of the following procedures:


• “Filtering Audit Logs” on page 155
• “Viewing Log Entries” on page 156
Setting Up Foglight 155
Viewing Audit Information

Filtering Audit Logs


When you first access the View Audit Information dashboard, it displays log entries
from within the past four hours. You can filter the list of log entries to show information
for a specific period of time.
To filter an audit log using a date and /or time range:

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.

Viewing Log Entries


The log entries that appear on the View Audit Information dashboard allow you to
review information such as the users who have been authenticated upon logging in to
the Foglight, changes made in the Administration module with regard to user
management (such as changes to settings for users, groups, and roles), or changes made
to configuration items (such as rules, schedules, or registry variables).
To view an audit log entry:

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, Upgrading, and Restoring Foglight


Backup and restore processes are important aspects of database administration. This
section provides suggested end-to-end backup, upgrade, and restore procedures for
Foglight installations. It includes the following sections:
• “Backing Up Foglight” on page 157
• “Upgrading Foglight” on page 177
• “Restoring Foglight” on page 178

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

Foglight Single Tier

Foglight Management Server on Windows with embedded MySQL

Option 1 • Stop the Foglight Management Server.


• Perform a full system backup, including the file system and
the Windows Registry.

Option 2 • Issue a mysqldump command to export the MySQL


database.

Alternatively, use the InnoDB HotBackup tool to back up


the embedded MySQL database.
Tip To restore the database after backing it up with the mysql
command, use MySQL. To restore the database after backing it
up with InnoDB HotBackup and applying the logs, shut down the
Foglight Management Server, copy the backup files to
<foglight_home>/mysql/data, and start the Foglight Management
Server

• Perform a full system backup, including the file system and


the Windows Registry, but excluding the MySQL data and
transaction logs.

Option 3 • Issue a mysqldump command to export the MySQL


database to a remote drive or a backup tape.
Tip This option does not require backing up the Foglight installation
directory. To restore Foglight after choosing this backup method,
you need to complete the following actions:
1. Install the Foglight Management Server and any cartridges
that existed in the previous installation.
2. Shut down Foglight.
3. Delete the MySQL data files.
4. Start MySQL and import the exported dump file.
5. Shut down MySQL.
6. Start Foglight.
Alternatively, instead of steps 3 through 6, use the InnoDB
HotBackup tool to back up the embedded MySQL database.

Foglight Management Server on Unix with embedded MySQL


Setting Up Foglight 159
Backing Up, Upgrading, and Restoring Foglight

Option 1 • Stop the Foglight Management Server.


• Create a TAR or a ZIP file containing the Foglight
installation directory and copy it to a remote drive or a
backup tape.
Tip The ZIP format is recommended. TAR files can result in
corrupted binary and MySQL data files.

Option 2 • Issue a mysqldump command to export the MySQL


database to a remote drive or a backup tape.
Alternatively, use the InnoDB HotBackup tool to back up
the embedded MySQL database.
• Create a TAR or a ZIP file containing the Foglight
installation directory, excluding the MySQL data files, and
copy it to a remote drive or a backup tape.
Tip The ZIP format is recommended. TAR files can result in
corrupted binary and MySQL data files.

Foglight Two Tier

Foglight Management Server on Windows with MS SQL Server on a remote computer

Option 1 • Use MS SQL tools to back up the database.


Tip To restore the database after choosing this backup method, use
MS SQL tools.

• Stop the Foglight Management Server.


• Use backup tools from your Windows environment to back
up the Foglight installation directory.

Foglight Management Server on Windows with MySQL on a remote computer

Option 1 • Issue a mysqldump command to export the MySQL


database.
Tip To restore the database after choosing this backup method, use
MySQL.

• Stop the Foglight Management Server.


• Use backup tools from your Windows environment to back
up the Foglight installation directory.

Foglight Management Server on Unix with MySQL on a remote computer


160 Foglight
Administration and Configuration Guide

Option 1 • Issue a mysqldump command to export the MySQL


database.
Tip To restore the database after choosing this backup method, use
MySQL.

• Stop the Foglight Management Server.


• Create a TAR or a ZIP file containing the Foglight
installation directory and copy it to a remote drive or a
backup tape.
Tip The ZIP format is recommended. TAR files can result in
corrupted binary and MySQL data files.

Foglight Management Server on Windows with Oracle on a remote computer

Option 1 • Use Oracle tools to back up the database.


Tip To restore the database after choosing this backup method, use
Oracle tools.

• Stop the Foglight Management Server.


• Use backup tools from your Windows environment to back
up the Foglight installation directory.

Foglight Management Server on Unix with Oracle on a remote computer

Option 1 • Use Oracle tools to back up the database.


Tip To restore the database after choosing this backup method, use
Oracle tools.

• Stop the Foglight Management Server.


• Create a TAR or a ZIP file containing the Foglight
installation directory and copy it to a remote drive or a
backup tape.
Tip The ZIP format is recommended. TAR files can result in
corrupted binary and MySQL data files.

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.


a Press Ctrl + Alt + Delete on your keyboard, then click Task Manager.
The Windows Task Manager opens.
b Select the Processes tab to inspect the list of processes running on your
system.
If the fms.exe process is not running, the Foglight Management Server is
stopped.
3 Back up the entire Foglight installation directory. For detailed 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 uses an Oracle database, refer to “To back up an Oracle
database used by the Foglight Management Server:” on page 168 for
instructions.
• If your system uses a MySQL database, refer to “To back up a MySQL
database using MySQL commands:” on page 170 for instructions.
• If your system uses a MS SQL database, refer to “To back up an MS SQL
database used by the Foglight Management Server:” on page 163 for
instructions.
The Foglight backup on a Windows system is now complete.
To back up Foglight on a Unix system
1 Shut down the Foglight Management Server. In a Unix terminal window (e.g.,
xterm) go to the <installation_dir>/bin directory, then type the following
command:
./fms -q
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.

3 Optionally, compress the archive file. Use the following syntax:


gzip <tarfile>
A .tar.gz file is created in the current directory.
The backup of the Foglight installation directory on a Unix system is now
complete.
To back up the Foglight installation directory on a Windows system:
1 Navigate to the directory one level above the Foglight installation directory.
2 Create a ZIP file that includes all of the files in the Foglight installation directory.
The process for creating the ZIP file depends on the application that is installed
on the computer on which you want to perform the backup process. For example,
if that computer uses the Compressed (zipped) Folder Windows application to
create ZIP files, in Windows Explorer, right-click the Foglight installation
Setting Up Foglight 163
Backing Up, Upgrading, and Restoring Foglight

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.

3 Connect to the MS SQL database server.


a In the Connect to Server dialog box, use the following settings:
Server type: Ensure that Database Engine is selected.
164 Foglight
Administration and Configuration Guide

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.

b In the Connect to Server dialog box, click Connect.


Upon a successful connection to the MS SQL Server, the Connect to Server
dialog box closes, and the Object Explorer pane in the Microsoft SQL
Server Management Studio window refreshes, showing the objects related to
the database server to which you connected.
Setting Up Foglight 165
Backing Up, Upgrading, and Restoring Foglight

4 Locate the Foglight database.


In the Microsoft SQL Server Management Studio window, in the Object
Explorer pane, expand the Databases node.
Below the Databases node, a set of sub-nodes appear, including a node for
system databases, database snapshots, the foglight database node, along with any
other databases that exist in your environment, if applicable.
166 Foglight
Administration and Configuration Guide

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.

5 Issue the backup command.


a In the Object Explorer pane, right-click the foglight node and from the
cascading menus that appear, choose Tasks > Backup.
The Backup Up Database—foglight dialog box appears, showing a set of
general, default settings for backing up the Foglight database.
Setting Up Foglight 167
Backing Up, Upgrading, and Restoring Foglight

b Review the backup settings in the Backup Up Database—foglight dialog


box, and if required, make additional modifications.
For example, to change the location of the backup file, under Destinations,
click Add, and select a desired location.
Tip The Backup Up Database—foglight 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
168 Foglight
Administration and Configuration Guide

pane in the upper-left.

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 In the Backup Up Database—foglight dialog box, click OK.


The MS SQL backup command creates a backup file of the Foglight database.
After a few moments, the Microsoft SQL Server Management Studio
message box appears, indicating that the backup of the MS SQL database is
complete.

6 In the Microsoft SQL Server Management Studio message box, click OK to


close it.
The Microsoft SQL Server Management Studio message box and Backup Up
Database—foglight dialog box close.
To back up an Oracle database used by the Foglight Management Server:
1 Log in to the Oracle server machine.
2 Ensure that PATH and LD_LIBRARY_PATH & ORACLE_HOME are all set correctly.
On Windows systems:
Setting Up Foglight 169
Backing Up, Upgrading, and Restoring Foglight

a Open a Windows Explorer window, and right-click on My Computer.


b Select Properties.
The System Properties window is displayed.

c Click the Advanced tab and click Environment Variables.


The Environment Variables window is displayed.
170 Foglight
Administration and Configuration Guide

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

• the data that is to be backed up: my.cnf


• the backup location: backup.cnf
Open a text editor and create the two configuration files using the following
syntax.
my.cnf
datadir="foglight_home/mysql/data"
innodb_data_home_dir="foglight_home/mysql/data"
innodb_data_file_path=ibdata1:10M:autoextend
innodb_log_group_home_dir="foglight_home/mysql/data"
set-variable=innodb_log_files_in_group=2
set-variable=innodb_log_file_size=64
backup.cnf
datadir="path_to_backup_data"
innodb_data_home_dir="path_to_backup_data"
innodb_data_file_path=ibdata1:10M:autoextend
innodb_log_group_home_dir="path_to_backup_data"
set-variable=innodb_log_files_in_group=2
set-variable=innodb_log_file_size=64
Where:
• foglight_home contains the path to the Foglight installation directory.
• path_to_backup_data contains the path to the directory that is to contain the
backup files, as defined in step 1.
For example, C:\Quest_Software\Foglight\backup\data (Windows).
Important Use the back slash character ‘\’ as a directory separator on Windows platforms;
on Unix platforms, use the forward slash ‘/’.

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

InnoDB Hot Backup version 3.0.0; Copyright 2002-2005


Innobase Oy
License A11983 is granted to Quest Software, Inc.

This program is legally licensed to Quest Software


to be used in connection with a product of
Quest Software only.

Type ibbackup --license for detailed license terms,


--help for help

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.

This program is legally licensed to Quest Software


to be used in connection with a product of
Quest Software only.

Type ibbackup --license for detailed license terms,


--help for help

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

ibbackup: Compressed 210 MB of data files to 36 MB


(compression 82%).
080922 15:29:54 ibbackup: Full backup completed!
5 View the contents of the backup directory by issuing the following command:
C:\Quest_Software\Foglight\mysql\bin>dir
C:\Quest_Software\Foglight\backup\data
Volume in drive C is System
Volume Serial Number is BCD1-A216

Directory of C:\Quest_Software\Foglight\backup\data

10/24/2008 10:55 AM <DIR> .


10/24/2008 10:55 AM <DIR> ..
10/24/2008 10:55 AM 5,632 ibbackup_logfile
10/24/2008 10:55 AM 02:16 PM 77,594,624 ibdata1
2 File(s) 77,600,256 bytes
2 Dir(s) 49,386,782,720 bytes free
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 and the
dir command to list files. On Unix platforms, use the forward slash to separate
directories and the list -l command.

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.

This program is legally licensed to Quest Software


to be used in connection with a product of
Quest Software only.

Type ibbackup --license for detailed license terms, --help


for help

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

081024 10:56:21 ibbackup: ibbackup_logfile's creation


parameters:
176 Foglight
Administration and Configuration Guide

ibbackup: start lsn 0 43520, end lsn 0 43655,


ibbackup: start checkpoint 0 43655
InnoDB: Doing recovery: scanned up to log sequence number 0
43655
InnoDB: Starting an apply batch of log records to the
database...
InnoDB: Progress in percents: 0 1 2 3 4 5 6 7 8 9 10 11 12
13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50
51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69
70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88
89 90 91 92 93 94 95 96 97 98 99
Setting log file size to 0 134217728
InnoDB: Progress in MB: 100
Setting log file size to 0 134217728
InnoDB: Progress in MB: 100
ibbackup: We were able to parse ibbackup_logfile up to
ibbackup: lsn 0 43655
ibbackup: The first data file is
'C:\Quest_Software\Foglight\backup\data\ibdata1'
ibbackup: and the new created log files are at
'C:\Quest_Software\Foglight\backup\data\'

081024 10:56:35 ibbackup: Full backup prepared for


recovery successfully!
7 View and observe the contents of the backup directory by issuing the following
command:
Note The example bellow illustrates the process of backing up a MySQL database on
Windows, which uses the back slash character as a directory separator and the dir
command to list files. On Unix platforms, use the forward slash to separate
directories and the list -l command.
C:\Quest_Software\Foglight\mysql\bin>dir
C:\Quest_Software\Foglight\backup\data
Volume in drive C is System
Volume Serial Number is BCD1-A216

Directory of C:\Quest_Software\Foglight\backup\data

10/24/2008 10:56 AM <DIR> .


10/24/2008 10:56 AM <DIR> ..
10/24/2008 10:55 AM 5,632 ibbackup_logfile
10/24/2008 10:55 AM 10,485,760 ibdata1
10/24/2008 10:56 AM 64 ib_logfile0
Setting Up Foglight 177
Backing Up, Upgrading, and Restoring Foglight

10/24/2008 10:56 AM 64 ib_logfile1


4 File(s) 278,922,240 bytes
2 Dir(s) 48,747,614,208 bytes free
In addition to the files ibbackup_logfile and ibdata1 that were created at backup
time (see step 5), the backup directory now includes two additional log files,
ib_logfile0 and ib_logfile1, which means that the logs have been applied
successfully.
Your embedded MySQL database is successfully backed up. For instructions on
how to restore the database MySQL database using these files, see “To restore an
embedded MySQL database previously backed up using the InnoDB tools:” on
page 192. For complete information about the InnoDB Hot Backup tool, visit the
following URL: http://www.innodb.com/hot-backup/

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.

To restore a previous Foglight installation:


1 Restore the database used by the old Foglight Management Server, from the
database export file:
• If your system contains an Oracle database, see “To restore an Oracle database
from the database export file:” on page 191 for instructions.
• If your system contains a MySQL database, see “To restore a MySQL
database from the database export file:” on page 190 for instructions.
2 Restore the old Foglight installation directory. For instructions, see “To restore
the previous Foglight installation directory:” on page 192.
3 Ensure that the Foglight Management Server starts up successfully on the
restored installation:
cd <installation_dir>/bin
./fms
The previous Foglight installation is now restored.
To restore an MS SQL database from the database export file:
1 Log in to the MS SQL Server machine.
2 Start the Microsoft SQL Server Management Studio.
Setting Up Foglight 179
Backing Up, Upgrading, and Restoring Foglight

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.

3 Connect to the MS SQL database server.


a In the Connect to Server dialog box, use the following settings:
Server type: Ensure that Database Engine is selected.
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.
180 Foglight
Administration and Configuration Guide

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.

b In the Connect to Server dialog box, click Connect.


Upon a successful connection to the MS SQL Server, the Connect to Server
dialog box closes, and the Object Explorer pane in the Microsoft SQL
Server Management Studio window refreshes, showing the objects related to
the database server to which you connected.

4 Locate the Foglight database.


In the Microsoft SQL Server Management Studio window, in the Object
Explorer pane, expand the Databases node.
Below the Databases node, a set of sub-nodes appear, including a node for
system databases, database snapshots, the foglight database node, along with any
other databases that exist in your environment, if applicable.
Setting Up Foglight 181
Backing Up, Upgrading, and Restoring Foglight

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.

5 Delete the existing Foglight database.


a In the Object Explorer pane, right-click the foglight node and from the menu
that appears, choose Delete.
The Delete Object dialog box appears, showing a set of default settings for
deleting the Foglight database.
182 Foglight
Administration and Configuration 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

6 Issue the restore command.


a In the Object Explorer pane, right-click the Databases node and from the
menu that appears, choose Restore Database.
The Restore Database dialog box appears, showing a set of general, default
settings for restoring a database.
184 Foglight
Administration and Configuration Guide

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

Click OK to close the Specify Backup dialog box.


The Restore Database dialog box refreshes, indicating that a backup file is
selected.
188 Foglight
Administration and Configuration Guide

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

7 In the Microsoft SQL Server Management Studio message box, click OK to


close it.
The Microsoft SQL Server Management Studio message box and Backup Up
Database—foglight dialog box close. Additionally, in the Microsoft SQL
Server Management Studio window, in the Object Explorer pane, the foglight
node appears under Databases.

To restore a MySQL database from the database export file:


1 Log into the MySQL server machine.
2 Delete the database you are going to restore, so that all the tables in the database
are deleted (i.e., drop the database).
Setting Up Foglight 191
Backing Up, Upgrading, and Restoring Foglight

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).

The MySQL database is now restored.


To restore an Oracle database from the database export file:
1 Log in to the Oracle database server machine.
2 If necessary, delete the schema you are going to restore, so that all the tables in
the database are deleted (in other words, drop the schema). Choose one of the
following options:
• Locate the oracle_drop_db.sql script in the scripts/sql directory of your
Foglight Management Server installation, and then run that script using the
following syntax:
sqlplus <dbadmin_usr>/<dbadmin_pwd>@<ORACLE_SID>
SQL> @ <foglight_home>/scripts/sql/oracle_drop_db.sql
Note The files oracle_drop_dp.sql and oracle_drop_db.sql are included with Foglight
when you use an Oracle database, The files are located in the
<foglight_home>/scripts/sql directory.

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).

The Oracle database is now restored.


To restore the previous Foglight installation directory:
1 cd to the directory where you want to install Foglight.
2 If the backup of the old installation is not compressed, continue with step 3. If the
backup is a ZIP file, first unzip it:
gunzip <path_to_zipfile>/<old_installation_zipfile>.tar.gz
3 If the backup of the old installation is an archive (.tar file), extract it. Use the
following syntax:
tar xvf <old_installation_tarfile>.tar
The old Foglight installation directory is now restored.
To restore an embedded MySQL database previously backed up using the InnoDB tools:
1 Stop the Foglight Management Server.
2 Copy the backup data that was created with the InnoDB tool, including the data
files and the log files, to the directory <foglight_home>/mysql/data. The backup
data and log files use the following naming convention:
• ibdata<1-n>. The name of the first data file is ibdata1, of the second ibdata2,
and so on. The number of data files depends on the size of the backed up
database.
• ib_logfile<0-n>. The name of the first log file is ib_logfile0, of the second
ib_logfile1, and so on. The number of log files depends on the size of the
backed up database and the size of the log file specified in the backup
configuration file, backup.cnf.
For complete information about the process of backing up an embedded MySQL
database using InnoDB, see “To back up an embedded MySQL database using the
InnoDB Hot Backup tool:” on page 171
3 Start the Foglight Management Server.
Setting Up Foglight 193
About Database Management in Foglight

Your database files are now successfully restored to their original location.

About Database Management in Foglight


This section contains information on how to monitor, estimate, and manage the size of
your database.

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.

Monitoring the Size of the Database


Foglight server comes with a rule, Catalyst Database Space Checking, which
monitors the size of the database and triggers alarms at different severity levels. The
following registry variables define the thresholds used by the rule:
• DBSMon.MaxDatabaseSize (the intended maximum size of the database, in
bytes)
• DBSMon.FatalDatabaseUsagePct
• DBSMon.CriticalDatabaseUsagePct
• DBSMon.WarningDatabaseUsagePct
You can optionally attach actions to the rule, such as sending out emails to a database
administrator.
For more information about the Catalyst Database Space Checking rule, see
“Catalyst Database Space Checking rule” on page 511.

Managing Database Size Using Retention Policies


Each topology type can be assigned a retention policy, which determines either the
granularity at which the metric history data is rolled up or whether the data should be
194 Foglight
Administration and Configuration Guide

purged after reaching a certain age. For more information about retention policies, see
“Managing Retention Policies” on page 666.

Factoring In Database Serviceability Metrics for More Accurate


Estimates
In typical environments, metric history occupies most of the storage space in the
Foglight database. However, some Foglight cartridges employ non-metric-based
observations that are persisted in different ways than metric-based observations.
The following observation types are persisted in the obs_string_* tables:
• StringObservation
• StringListObservation
• TopologyObjectObservation
Complex observations are persisted in the obs_binary_* tables.
To achieve a more accurate size estimation, you can factor in the space taken by both
binary and string observation tables.
For example, the Windows_System cartridge has five complex observations. If all of
them are persisted in five-minute granularity for two weeks, some database space is
needed in addition to metric history.
You can check the typical record size of a table by looking at the database serviceability
metrics in the browser interface. Select the Configuration > Data node in the
navigation panel, and in the display area, expand the Foglight > All Data >
FSMDatabases > <foglight_management_server_machine> > Tables node. You will
see a list of sub-nodes that represent the tables used by Foglight.
Select and expand one of the obs_binary_* nodes and you will find several metric
nodes. You can calculate the typical record size using the following formula:
(dataLength + indexLength) / numberRows
Assuming that the average record size is 1.1KB, you can get a good idea of how much
space the complex observations will take using the following formula:
(1.1KB) * (# of complex observations) * (3600 / (granularity in
seconds)) * 24 * (# of days) * (# of hosts)
This gives us the number of MB needed (approximately an additional 220MB) to
monitor ten hosts for two weeks.
Setting Up Foglight 195
About Database Management in Foglight

Reclaiming Table Space


MySQL with innodb engine does not shrink the table space file, even after you
truncate the tables.
To decrease the size of your table space:
1 Stop the Foglight Management Server:
<foglight_home>/bin/fms -q
2 Start up MySQL server:
<foglight_home>/bin/runDb.bat
3 Use mysqldump to dump all your InnoDB tables:
cd <foglight_home>/mysql/bin
mysqldump -P<dbport> -u<dbuser> -p<dbpwd> -e -q -B <dbname>
-r mysqldata.sql
Note Substitute dbport, dbuser, dbpwd, and dbname with the correct port number, user
name, password, and database name.

4 Stop MySQL server:


<foglight_home>/bin/shutdownDb.bat
5 Remove all the existing tablespace files:
cd <foglight_home>/mysql/data del ib_log*
del ib_log*
del ibdata*
6 Start up MySQL server:
<foglight_home>/bin/runDb.bat
7 Import the dump files:
cd <foglight_home>/mysql/bin
mysqldump -P<dbport> -u<dbuser> -p<dbpwd> <mysqldata.sql
Note Substitute dbport, dbuser, and dbpwd the correct port number, user name,
password, and database name.

8 Stop MySQL server.


<foglight_home>/bin/shutdownDb.bat
9 Start up Foglight Management Server.
<foglight_home>/bin/fms
Note For Oracle and Microsoft SQL Server, please ask your database administrator for
help.
196 Foglight
Administration and Configuration Guide
4
Managing Users and Security

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.

This chapter contains the following sections:


About Security in Foglight..........................................................................................................198
Managing Users ........................................................................................................................199
Managing Groups ......................................................................................................................210
Managing Roles.........................................................................................................................219
Configuring Password Settings .................................................................................................227
Configuring Directory Services ..................................................................................................231
198 Foglight
Administration and Configuration Guide

About Security in Foglight


In Foglight, user management consists of three related entities:
• Users. A user has a user name and a password and can belong to one or more
groups. Logging in to Foglight as a specific user authorizes you to perform a
certain set of actions (based on the roles that have been assigned to the group(s) to
which the user belongs). Foglight can store user passwords on the Foglight
Management Server, or in an external directory
For more information, see “Managing Users” on page 199, “Configuring
Password Settings” on page 227, and “Configuring Directory Services” on
page 231.
• Groups. A group can contain one or more users. Roles are assigned to users
through groups. You can assign roles and add users to groups.
For more information, see “Managing Groups” on page 210.
• Roles. The default roles included with Foglight dictate what actions users can
perform with regard to one or more Foglight features or components. Foglight
System Administrators can also create custom roles. Roles are assigned to groups.
Users in a group have the roles that are assigned to that group.
For more information, see “Managing Roles” on page 219.
The following diagram illustrates the interrelationship of users, groups, and roles.
Managing Users and Security 199
Managing Users

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

Accessing the Manage Users Dashboard


The Manage Users dashboard contains a table that lists all of the users that have been
created in the Administration Module or imported from an LDAP-compatible directory
service supported by Foglight, the groups to which these users belong, and the roles that
are available to them. This dashboard also includes controls for managing user settings,
creating new users, deleting non-default users, filtering the list of users, forcing a
password change for new users, and unlocking a user who has been locked out after a
pre-defined number of bad login attempts.

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.

To access the Manage Users dashboard:

Note This procedure continues from “Logging in to Foglight” on page 22.

1 Ensure that the navigation panel is open.


To open the navigation panel, click the right-facing arrow on the left.
Managing Users and Security 201
Managing Users

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

To clear the filters, click Clear Filters.


The Manage Users list refreshes, showing the list of all users.

From here, you can proceed to any of the following procedures:


• “Creating Users” on page 203
• “Adding Users to Groups” on page 204
• “Changing Passwords” on page 206
Managing Users and Security 203
Managing Users

• “Forcing Password Changes” on page 207


• “Unlocking Passwords” on page 207
• “Deleting Internal Users” on page 209

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.

For example: test123.


204 Foglight
Administration and Configuration Guide

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.

Adding Users to Groups


Use the Edit Groups button on the Manage Users dashboard to add a user to one or more
groups, as outlined in the procedure below.
Alternatively, you can use the Manage Groups dashboard to assign users or roles to one
or more groups. For information, see “Editing Users in Groups” on page 215 and
“Assigning Roles to a Group” on page 216.
Alternatively, you can assign groups to users using the security:assigngroup
command that comes with the fglcmd interface. For more information, see the
Command-Line Reference Guide.
Managing Users and Security 205
Managing Users

To add a user to groups:

Note This procedure continues from “Creating Users” on page 203.

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:

Note This procedure continues from “Creating Users” on page 203.

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.

3 Specify the new password.


a In the Change Password dialog box, type the new password into each of the
the Password and Confirm Password boxes.
Note The Password box is encrypted.

For example: test456.


As you type the password into the Password and Confirm Password boxes,
asterisk ‘*’ characters appear.
Managing Users and Security 207
Managing Users

b Click OK.
4 The Change Password dialog box closes and Foglight updates the user password
in the database.

Forcing Password Changes


When you create a user account for a user that has no access to the Manage Users
dashboard, use the Force Password-Change button to ensure that the user changes their
password the first time they attempt to log into Foglight.
To force a password change for a user:

Note This procedure continues from “Creating Users” on page 203.

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.

3 Click OK to confirm the forced password change.


The Confirm Force Password-Change dialog box closes.
The next time the user attempts to log in they will be prompted to change their
password.

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.

d In the Confirm Unlock dialog box, click OK.


The dialog box closes and the Manage Users dashboard refreshes, showing the
user name in the Name column.
Managing Users and Security 209
Managing Users

Deleting Internal Users


Use the Delete button on the Manage Users dashboard to delete user accounts from
Foglight.
You can only delete those users that you add to Foglight after the installation. Their type
appears as Internal on the Manage Users dashboard. You cannot delete the user accounts
that are included with Foglight. Their type appears as Built In. If a Built In or Internal
User is the current user, their type appears as Current User.
Figure 2

User accounts that you create

User accounts that come with Foglight

Current Foglight user

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

3 In the Confirm Delete dialog box, click OK.


The dialog box closes and the Manage Users dashboard refreshes.
4 Observe the Manage Users dashboard.
The user account that you deleted no longer appears in the list.

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.

• External. The groups that are mapped from an LDAP-compatible directory


service supported by Foglight as part of the process of mapping external users.
Managing Users and Security 211
Managing Groups

For more information about configuring Foglight to use an external directory


service, see “Configuring Directory Services” on page 231.
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 Groups dashboard
allows you to create and manage groups, add users to groups, and assign roles to groups.
For more information on how to use the Manage Groups dashboard, see the following
sections:
• “Accessing the Manage Groups Dashboard” on page 211
• “Creating Groups” on page 214
• “Editing Users in Groups” on page 215
• “Assigning Roles to a Group” on page 216
• “Deleting Internal Groups” on page 218

Accessing the Manage Groups Dashboard


The Manage Groups dashboard contains a table that lists all of the groups that have been
created in the Administration Module or imported from an LDAP-compatible directory
service supported by Foglight, the users that belong to these groups, and the roles that
have been assigned to each group.
This page also contains controls for managing group settings, creating new groups, and
deleting non-default groups.
To access the Manage Groups dashboard:

Note This procedure continues from “Logging in to Foglight” on page 22.

1 Ensure that the navigation panel is open.


To open the navigation panel, click the right-facing arrow on the left.
2 On the navigation panel, under Dashboards, choose Administration > Users &
Security > Manage Groups.
The Manage Groups dashboard appears in the display area, showing a list of all
existing groups:
212 Foglight
Administration and Configuration Guide

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

To clear the filters, click Clear Filters.


The Manage Groups list refreshes, showing the list of all groups.

From here, you can proceed to any of the following procedures:


• “Creating Groups” on page 214
• “Editing Users in Groups” on page 215
• “Assigning Roles to a Group” on page 216
214 Foglight
Administration and Configuration Guide

• “Deleting Internal Groups” on page 218

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.

2 Specify the name of the group that you want to create.


a In the Create Group dialog box, in the Name box, type the user name.
For example: test.
b Click Create.
The Create Group dialog box closes and the Manage Groups dashboard
refreshes to show the newly-created group.

When you create groups, their type appears as Internal on the listing.
Managing Users and Security 215
Managing Groups

Editing Users in Groups


Use the Edit Users button on the Manage Groups dashboard to quickly edit users in one
or more groups.
Alternatively, if you need to edit groups for a single user account, use the Manage Users
dashboard. For information, see “Adding Users to Groups” on page 204.
Another way to assign or remove users from groups is to use the
security:assigngroup command that comes with the fglcmd interface. For more
information, see the Command-Line Reference Guide.
To add users to a group:

Note This procedure continues from “Creating Groups” on page 214.

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.

Assigning Roles to a Group


Use the Edit Roles button on the Manage Groups dashboard to quickly edit one or more
roles for a group.
Alternatively, if you need to edit multiple groups for a single role, use the Manage Roles
dashboard. For information, see “Editing Groups for a Role” on page 224.
Another way to assign or remove roles from groups is to use the
security:assignrole command that comes with the fglcmd interface. For more
information, see the Command-Line Reference Guide.
To assign roles to a group:

Note This procedure continues from “Creating Groups” on page 214.

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

Deleting Internal Groups


Use the Delete button on the Manage Groups dashboard to delete user accounts from
Foglight.
You can only delete those groups 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 3

Groups that you create

Groups that come with Foglight

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.

3 In the message box, click OK.


Managing Users and Security 219
Managing Roles

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.

Foglight comes with the following Built-In roles:


• Administrator. This role enables a user to access the Administration Module,
the Web Console (web.xml), hidden Administration URLs, and the JMX-
Console. An Administrator can manipulate agents, rules, derived metrics,
registry variables, cartridges, types, and scripts. The only limitation for
Administrators is that they cannot access or edit the Users and Security
dashboard.
• Advanced Operator. This role builds on the Operator role by adding the ability
to access build-oriented dashboards such as the Service Builder, Application
Builder, and the Report Builder, where users can add, manage, and manipulate
scheduled reports.
• Cartridge Developer. This role extends the Dashboard Designer role by
allowing the user to modify core dashboards and system modules.
• Console User. This role enables a user to access the Web Console (web.xml)
only. It is the base level locked-down read-only role. Users assigned this role
will not have access to core dashboards.
• Dashboard Designer. This role builds on the Dashboard User role by adding
the ability to access all dashboard tools such as Definitions, Data Sources, and
220 Foglight
Administration and Configuration Guide

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

Accessing the Manage Roles Dashboard


The Manage Roles dashboard contains a table that lists roles, their type, and the groups
that are assigned to each role. It also allows you to create and manage roles, and to
assign roles to groups.
To access the Manage Roles dashboard:

Note This procedure continues from “Logging in to Foglight” on page 22.

1 Ensure that the navigation panel is open.


To open the navigation panel, click the right-facing arrow on the left.
2 On the navigation panel, under Dashboards, choose Administration > Users &
Security > Manage Roles.
The Manage Roles dashboard appears in the display area, showing a list of all
existing 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.

To clear the filters, click Clear Filters.


The Manage Roles list refreshes, showing the list of all groups.
Managing Users and Security 223
Managing Roles

From here, you can proceed to any of the following procedures:


• “Creating Roles” on page 223
• “Editing Groups for a Role” on page 224
• “Deleting Internal Roles” on page 225

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

2 Specify the name of the role that you want to create.


a In the Create Role dialog box, in the Name box, type the user name.
For example: test.
b Click Create.
The Create Role dialog box closes and the Manage Roles dashboard refreshes
to show the newly-created role.

When you create roles, their type appears as Internal on the listing.

Editing Groups for a Role


Use the Edit Groups button on the Manage Roles dashboard to quickly edit one or more
groups for a role.
Alternatively, if you need to edit multiple roles for a single group, use the Manage
Groups dashboard. For information, see “Assigning Roles to a Group” on page 216.
To edit groups for a role:

Note This procedure continues from “Creating Roles” on page 223.

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.

Deleting Internal Roles


Use the Delete button on the Manage Roles dashboard to delete roles from Foglight.
226 Foglight
Administration and Configuration Guide

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

Roles that you create

Roles that come with Foglight

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.

3 In the message box, click OK.


The message box closes.
4 Observe the Manage Roles dashboard.
The role that you deleted no longer appears in the list.
Managing Users and Security 227
Configuring Password Settings

Configuring Password Settings


Foglight automatically times out after 60 minutes of inactivity.
The following are the default restrictions that apply to passwords for administrators and
for other types of internal users. For more information about the types of users in
Foglight, see “Managing Users” on page 199.
• An internal user’s password expires after ninety (90) days.
• An administrator’s password expires after forty-five (45) days. The one exception
is the password for the default user foglight, which does not expire.
• A user is locked out of the system after they enter an incorrect password for five
(5) consecutive login attempts.
• A user who fails five consecutive login attempts is locked out of the system for
fifteen (15) minutes.
• Foglight reminds a user fifteen (15) days before their password expires.
• The password must:
• Be at least seven (7) characters long.
• Contain both alphabetic and numeric characters.
• The password cannot:
• Be the same as the user name.
• Be a dictionary word.
• Be just the repetition of a single character.
• Be longer than 255 characters.
Note The recommended length of a password is sixteen (16) characters or fewer.

• Be the same as any of the user’s last twelve (12) passwords.


Use the Configure Password Settings dashboard to view and edit these settings as
required. For instructions, see the following sections:
• “Accessing the Configure Password Settings Dashboard” on page 228
• “Editing Password Settings” on page 229
• “Changing Database Credentials” on page 230
You can configure many of these settings on the Configure Password Settings
dashboard. For instructions, see “Editing Password Settings” on page 229.
228 Foglight
Administration and Configuration Guide

Accessing the Configure Password Settings Dashboard


The Configure Password Settings dashboard contains settings for password policies that
apply to administrators and internal users are set. The default settings for these policies
are described in “Configuring Password Settings” on page 227.
To view password settings:

Note This procedure continues from “Logging in to Foglight” on page 22.

1 Ensure that the navigation panel is open.


To open the navigation panel, click the right-facing arrow on the left.
2 On the navigation panel, under Dashboards, choose Administration > Users &
Security > Configure Password Settings.
The Configure Password Settings dashboard appears in the display area, showing
a list of password settings:

From here, you can proceed to any of the following procedures:


• “Editing Password Settings” on page 229
Managing Users and Security 229
Configuring Password Settings

Editing Password Settings


Use the Configure Password Settings dashboard to edit any policies that you want to
change.
To edit password settings:

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.

2 Edit the following settings as desired:


• Days before user password expires
• Days before administrator password expires
• Bad logins before user account is locked out
• Seconds after which lockout expires (0 for no expiration)
230 Foglight
Administration and Configuration Guide

• Minimum password length


• Number of old passwords that will be remembered
• Number of days before password expiry to warn user
• User cache expiry in minutes (login is fast until cache expires)
3 Edit the password complexity levels.
You can set the complexity level that must be used in the passwords of internal
users and the users with the Security role. Foglight uses the following levels:
• 1: Passwords are not checked for complexity.
• 2: Passwords must contain both alphabetic and numeric characters.
• 3: Passwords must contain at least one upper case letter, lower case letter, and
numeric character, as well as at least one character that is not alphanumeric.
Type a security level into the User password complexity level and
Administrator password complexity level boxes as required.
By default, the complexity level for internal users’ passwords is 2. The default
complexity level for the users with the Security role is set to 3.
Note Administrators’ passwords cannot be set to complexity level 1.

To restore the default values, click Restore Defaults.


4 Click Save.
The Configure Password Settings dashboard refreshes and a message appears in
the upper-left, indicating that your changes have been saved.

Changing Database Credentials


If you are using an external database, you may experience a situation where the database
password for the Foglight database account has changed (for example, in case password
policies change). You can reconfigure Foglight to start up with a new password by
changing the configuration file (foglight.config) and restarting the process.
foglight.database.password = "[updated password here]";
To avoid compromising the password, users must insert an updated encrypted password.
Managing Users and Security 231
Configuring Directory Services

To change the Foglight database password:


1 Delete the current Foglight database key from Foglight’s key store:
> bin\keyman delappkey dbpwd.[foglight db username]
2 Create a new key store entry for the updated password:
> bin\keyman addappkey dbpwd.[foglight db username]
[updated password] "FoglighT db UseR PassworD"
KeyToken: 1234567890123456789012345678901234567890
3 Edit the foglight.config file and update the following line with the generated
token
foglight.database.password =
"1234567890123456789012345678901234567890";
For more information about changing database credentials using the command line, see
the Command-Line Reference Guide.

Configuring Directory Services


Foglight supports the following Lightweight Directory Access Protocol (LDAP version
3) compatible directory services:
• Active Directory
• Sun Java Systems Directory Server,
• OpenLDAP
• Novell eDirectory
The Configure Directory Services dashboard allows you to access user login
information that is stored in an external directory. Once you set up the Configure
Directory Services dashboard, your Foglight users can sign in to Foglight using the
credentials from the external directory.
When you configure the LDAP directory service, Foglight creates a user account each
time an LDAP user successfully logs into Foglight for the first time. Any password
changes in the LDAP directory service are transparent to Foglight. After a user's
password change in the directory service, that user can log into Foglight with the new
password while any attempts to use the old password will fail. If a user account is
removed from the directory service, any login requests with those credentials result in a
failure. Similarly, if the LDAP authentication service is down, Foglight cannot
authenticate any of the users whose accounts are defined in the LDAP directory service.
232 Foglight
Administration and Configuration Guide

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

Accessing the Configure Directory Services Dashboard


Use the Configure Directory Services dashboard to view and edit the settings that
enable external users to log on to Foglight using the credentials they previously set up in
an external directory.
To access the Configure Directory Services dashboard:

Note This procedure continues from “Logging in to Foglight” on page 22.

1 Ensure that the navigation panel is open.


To open the navigation panel, click the right-facing arrow on the left.
2 On the navigation panel, under Dashboards, choose Administration > Users &
Security > Configure Directory Services.
The Configure Directory Services dashboard appears in the display area, showing
a list of directory settings:
Managing Users and Security 233
Configuring Directory Services

From here, you can proceed to “Editing Directory Settings” on page 234.
234 Foglight
Administration and Configuration Guide

Editing Directory Settings


Default settings for these LDAP directory servers are different. The table below shows
examples of these settings for different types of LDAP directory servers. Use the
following settings as guidelines; they should be substituted with the most appropriate
values. Refer to the documentation for your specific LDAP server for more information
about settings and values.

Examples

Setting Active Directory Sun Java Systems Novell eDirectory


Directory Server/
OpenLDAP

Nearest LDAP ldap://ldapserver.example.com:389/


server

Secondary ldap://backupldapserver.example.com:389/
LDAP server
URL

Distinguished The distinguished The distinguished name CN=foglight_a


name of the name (DN) of the (DN) of the service dmin,
service service account for account for further user O=services
account further user searching searching, or a special
account,
__anonymous__

Password User defined

LDAP query CN= uid= CN=


prefix

LDAP query ,OU=Employees,DC=example,DC=com ,O=novell


suffix

The scope(s) OU=Groups,DC=example,DC=com O=novell


to search for
groups
Managing Users and Security 235
Configuring Directory Services

Setting Active Directory Sun Java Systems Novell eDirectory


Directory Server/
OpenLDAP

The second OU=Dynamic Groups,DC=example,DC=com N/A


group
namespace

The third N/A


group
namespace

The LDAP OU=People,DC=example,DC=com o=novell


context for
user
searching

Role attribute name cn istweb


ID

Is Role false
attribute a DN

User alias sAMAccountName uid uniqueId


attribute ID

User attribute member uniqueMember member


ID to search
for groups

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

Setting Active Directory Sun Java Systems Novell eDirectory


Directory Server/
OpenLDAP

Parent group memberOf


attribute ID

Group member uniqueMember member


attribute for
nested group
searching

Maximum 15
level of group
nesting

LDAP search 10000


timeout
(milliseconds)

Mode of direct indirect direct


group
searching

Account is false
anonymous

To edit directory settings:

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

4 Edit the settings as required.


To restore the default values, click Restore Defaults.
5 Click Save.
The Configure Directory Settings dashboard refreshes and a message appears in
the upper-left corner, indicating that your changes have been saved.
238 Foglight
Administration and Configuration Guide

Example: Integrating Foglight LDAP Directory Services with


Microsoft Windows Active Directory
The purpose of this section is to assist in configuring Foglight 5 LDAP integration with
Windows Active Directory.
The idea behind LDAP integration within Foglight is to allow user and group
membership to be verified outside from internal Foglight users and groups. Many
companies wish to use a single username and password across their applications and
this functionality allows Foglight to check user and group membership against an
external LDAP source (in this case Active Directory) when logging in. This feature does
not use Single sign-on (SSO) access. SSO uses a logon ticket (usually Kerberos) from
Windows and passes it to Foglight through your web browser, logging you in
automatically, without prompting for the user name and password.
This example consists of the following sections:
• “Getting started” on page 238
• “Gathering LDAP information from the external directory” on page 239
• “Configuring Foglight LDAP settings” on page 243
• “Testing the configuration” on page 247

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.

Gathering LDAP information from the external directory


Connect your LDAP browser to the Active Directory Domain Controller from which
you plan to pull the user and group information. A virtual computer is used in this
example. It uses the following settings:
• Domain Controller: DC1
• Active Directory (AD) domain: 2K3.DOM
• Fully qualified domain name (FQDN): DC1.2K3.DOM

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

To obtain LDAP information:


1 Start the Softerra LDAP browser.
2 Record the LDAP connection string to the Domain Controller.
Tip This text string appears in the browser’s title bar.
Managing Users and Security 241
Configuring Directory Services

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

• CN of the Builtin folder (containing default groups), as recorded in step 4:


CN=Builtin,DC=2k3,DC=dom
• CN of the Users folder (containing other users and groups in AD), also recorded
in step 4:
CN=Users,DC=2k3,DC=dom

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.

Configuring Foglight LDAP settings


When you finish gathering information about the external directory, you can configure
Foglight to use Active Directory when authenticating external users. Upon a successful
configuration, you will be able to log into the Foglight browser interface using your
Active Directory user credentials.
To configure directory services:

Note This procedure continues from “Logging in to Foglight” on page 22.

1 Ensure that the navigation panel is open.


To open the navigation panel, click the right-facing arrow on the left.
2 On the navigation panel, under Dashboards, choose Administration > Users &
Security > Configure Directory Services.
The Configure Directory Services dashboard appears in the display area, showing
a list of directory settings:
244 Foglight
Administration and Configuration Guide

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

Parameter Value Default?

Nearest LDAP server ldap://dc1.2k3.dom:389/ No

Secondary LDAP Server URL Clear entry or enter second No


Domain Controller

Distinguished name of the service CN=administrator,CN=Users No


account ,DC=2k3,DC=dom

Password Type the password No

Confirm Password Re-type the password No

LDAP query prefix CN= Yes

LDAP query suffix ,CN=Users,DC=2k3,DC=dom No

The scope(s) to search for groups CN=Users,DC=2k3,DC=dom No

The second group namespace CN=Builtin,DC=2k3,DC=dom No

The third group namespace Leave blank unless you need Yes
want to specify another OU

The LDAP context for user CN=Users,DC=2k3,DC=dom No


searching

Role attribute ID name Yes

Is Role attribute a DN false Yes

User alias attribute ID sAMAccountName Yes

User attribute ID to search for member Yes


groups

Match on User DN true Yes


Managing Users and Security 247
Configuring Directory Services

Parameter Value Default?

JAAS LoginModule com.quest.nitro.service.s Yes


ecurity.auth.spi.NitroExt
endedLdapLoginModule

Parent group attribute ID memberOf Yes

Group attribute for nested group member Yes


searching

Maximum level of group nesting 15 Yes

LDAP search timeout 10000 Yes


(milliseconds)

Mode of group searching direct Yes

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.

Testing the configuration


After configuring Foglight with Active Directory, you can attempt to log in as a user
whose account exists in Active Directory. The first time you attempt to log in, that user
account does not belong to any Foglight groups and has no Foglight roles associated
with that account. After typing your Active Directory user name and password, the
following error message appears, indicating that you have no permissions to access any
dashboards in the browser interface.
248 Foglight
Administration and Configuration Guide

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.

About Foglight Cartridges..........................................................................................................250


Installing and Managing Cartridges ...........................................................................................251
Downloading Agent Components ..............................................................................................265
250 Foglight
Administration and Configuration Guide

About Foglight Cartridges


A Foglight cartridge contains components that encapsulate a specific Foglight
functionality. A Foglight Management Server installation includes a collection of
cartridges, such as the Monitoring Policy, Service Model, and other types of cartridges.
These server-specific cartridges are installed with the Foglight Management Server, and
are enabled on its startup. Along with the server-specific cartridges, your configuration
can include other cartridges that are packaged and installed separately, on top of the
Foglight Management Server cartridges and are designed to monitor specific types of
environments, such as the OS, JavaEE, database, or other types of monitored systems.
While the Foglight Management Server cartridges typically contain a set of rules,
registry variables, tables, retention policies, and other Foglight entities, installed
cartridges can also include agent installers, communication capabilities, as well as
modifications to the way that data is transformed or handled.
The following concepts and terms relate to cartridge management in Foglight:
• Cartridge. A unit that is distributed separately from the Foglight Management
Server. Cartridges contain components that extend the functionality of Foglight,
such as agents, rules, and views.
• Cartridge installation. The act of installing a cartridge on the machine hosting the
Foglight Management Server. Cartridge installation makes the Management
Server aware of the cartridge.
Note Installing a cartridge does not make it available for use by Foglight, but simply
prepares it to be enabled.

• Enabled cartridge. A cartridge whose components are part of the Management


Server and available for use by Foglight.
• Cartridge component. A cartridge contains one or more components, such as
dashboards and agent installers. See “About Cartridge Components” on page 250
for more information.

About Cartridge Components


A cartridge may include one or more components. Examples of cartridge components
are described below.
• Agent installers/packages. A cartridge may include one or more Foglight Agent
installers. An agent monitors a specific part of your environment, such as an
operating system, application, or server.
Managing Cartridges 251
Installing and Managing Cartridges

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.

Installing and Managing Cartridges


Use the Administration module to install cartridges on the Foglight Management
Server, enable and manage cartridges, and download agent installers.
Cartridges allow you to monitor additional operating systems, processes, databases,
applications, and servers in your environment. You manage them using the dashboards
that are accessible from the navigation panel, under Administration > Cartridges, or
using the fglcmd command-line interface. This section describes the dashboards for
managing cartridges. For information about fglcmd, see the Command-Line Reference
Guide.

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

Adding a cartridge to the Foglight Management Server is a two-step process. First,


the .car file that contains the cartridge must be installed on the Foglight Management
Server. Installing a cartridge causes the server to be aware of it.
You can only install those cartridges that are listed in your Foglight license. For
information on how to find out whether your license includes a particular cartridge, see
Chapter 3, “Viewing License Capabilities” on page 136.
Next, the cartridge must be enabled. Enabling a cartridge causes its components to be
available for use by Foglight. Using the Foglight Administration Module, you can cause
a cartridge to be automatically enabled upon installation or to be enabled after
installation.
When a cartridge has been installed and enabled, all of the components included in the
cartridge are part of the Management Server.
Use the Cartridge Inventory dashboard to view information about installed cartridges,
and to install, enable, disable, and remove cartridges. For more information on how to
use the Cartridge Inventory dashboard, refer to the following sections:
• “Accessing the Cartridge Inventory Dashboard” on page 252
• “Installing Cartridges” on page 258
• “Enabling Cartridges” on page 261
• “Disabling Cartridges” on page 262
• “Uninstalling Cartridges” on page 263

Accessing the Cartridge Inventory Dashboard


The Cartridge Inventory dashboard contains controls for installing, enabling, disabling,
and uninstalling cartridges, as well as for viewing information about the installed
cartridges.

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.

To access the Cartridge Inventory dashboard:

Note This procedure continues from “Logging in to Foglight” on page 22 or “Accessing the
Administration Dashboard” on page 57.

1 Ensure that the navigation panel is open.


To open the navigation panel, click the right-facing arrow on the left.
2 On the navigation panel, under Dashboards, choose Administration >
Cartridges > Cartridge Inventory.
The Cartridge Inventory dashboard appears in the display area, showing a list of
all existing cartridges.
254 Foglight
Administration and Configuration Guide

3 View the summary information about a cartridge.


• Move the mouse pointer over the Cartridge Name column in the row
containing the cartridge about which you want to view information.
A dwell appears, showing the cartridge information.
Managing Cartridges 255
Installing and Managing Cartridges

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

To return to the Cartridge Inventory dashboard, in the View Cartridge Details


view, click Go to Cartridge Inventory.
4 To sort the list of cartridges, click any of the Status, Cartridge Name, or Version
column headings as required.
5 To filter the list of cartridges, use one or more of the following boxes above the
cartridge table:
• Name: Type the cartridge name for which you want to filter.
• Version: Type the cartridge version for which you want to filter.
• Core Type: Click and select one of the following options as required: Core
Cartridges, Installed Cartridges, or All Cartridges.
For example, to list the core cartridges that are related to the cartridges core
cartridges, in the Name box, type Windows.
The Cartridge Inventory dashboard refreshes, showing the list of cartridges
whose name matches the filter pattern.
Managing Cartridges 257
Installing and Managing Cartridges

To clear the filters, click Clear Filters.


The Cartridge Inventory dashboard refreshes, showing the list of all cartridges.
258 Foglight
Administration and Configuration Guide

From here, you can proceed to any of the following procedures:


• “Installing Cartridges” on page 258
• “Enabling Cartridges” on page 261
• “Disabling Cartridges” on page 262
• “Uninstalling Cartridges” on page 263

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.

If the installation succeeds, the Cartridge Operation Result message box


appears.

Close the Cartridge Operation Result message box by clicking OK.


4 Important. In the list of installed cartridges, in the upper-right corner, click
.
The list refreshes, showing the newly-installed cartridge.
Note 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.

5 Observe the list of installed cartridges.


The Status column contain icons that indicate if a cartridge is enabled ,
enabled pending dependency , partially enabled , or disabled .
If you chose not to enable the cartridge immediately after the installation in step
2, you can do that at a later time. For instructions, see “Enabling Cartridges” on
page 261.
Managing Cartridges 261
Installing and Managing Cartridges

From here, you can proceed to “Enabling Cartridges” on page 261.

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:

Note This procedure continues from “Installing Cartridges” on page 258.

1 In the Cartridge Inventory dashboard, select one or more disabled cartridges in


the table that you want to enable.
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 enable.

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.

Close the Cartridge Operation Result message box by clicking OK.


262 Foglight
Administration and Configuration Guide

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:

Note This procedure continues from “Disabling Cartridges” on page 262.

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

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 list of cartridges.


The cartridges that you removed no longer appear in the list.

Downloading Agent Components


There are three types of agent components that you can download using this dashboard:
• Executable agent installers. Some cartridges, such as the Foglight® Cartridge for
Java® EE or the Foglight Agent Manager cartridge, include one or more
executable agent installers. The agent installers that are available for download
are listed on the Components for Download dashboard. You can use the controls
on this page to download agent installers from the Foglight Management Server
to a remote machine.
Caution Read and follow any documentation provided with the agent installers.

• Cartridge-related files. Some cartridges include files that offer additional


functionality to your monitoring configuration. For example, the
SNMPTrapAction cartridge that is included in the Foglight Management Server
installation, comes with a MIB file that contains the settings for entering SNMP
trap actions. For more information, see Chapter 7, “Configuring SNMP trap
actions” on page 477.
You can download agent components using any of the following ways.
266 Foglight
Administration and Configuration Guide

Browser To download agent For more information, see:


Interface components, use:
Access
Available?

Yes Components for dashboard “Using the Browser Interface to


Download Download Agent Components” on
page 266

No Components for view “Using the Components for


Download Download view to download agent
components” on page 270
Note You can use the Components for Download view to download agent
components and other types of files that come with cartridges, such as
Foglight Agent Manager installers or other file types.

A direct URL to the agent “Using a URL to download agent


component components” on page 274

Using the Browser Interface to Download Agent Components


If you have access to the browser interface, use the Components for Download
dashboard to view information about available agent components and to download
them. For more information on how to use the Components for Download dashboard,
refer to the following sections:
• “Accessing the Components for Download dashboard” on page 266
• “Downloading agent components using the browser interface” on page 268

Accessing the Components for Download dashboard


To access the Components for Download dashboard:

Note This procedure continues from “Logging in to Foglight” on page 22.

1 Ensure that the navigation panel is open.


To open the navigation panel, click the right-facing arrow on the left.
Managing Cartridges 267
Downloading Agent Components

2 On the navigation panel, under Dashboards, choose Administration >


Cartridges > Components for Download.
The Components for Download dashboard appears in the display area, 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.
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.

Downloading agent components using the browser interface


Use the Name column on the Components for Download dashboard to download agent
components, as outlined below.
Managing Cartridges 269
Downloading Agent Components

To download an agent component:

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.

2 Save the file to a desired location on your disk.

Downloading Agent Components Remotely


There are two ways to download agent components without having to access the
Foglight browser interface:
• Using the Components for Download view. The Components for Download view
lists all of the agent components that come with the Foglight Management Server
or any of the installed cartridges. This includes executable agent installers or her
types of files. For more information, see “Using the Components for Download
view to download agent components” on page 270.
• Using a direct URL to the agent component. This method allows you to download
agent installers without accessing the Components for Download view. This way
of downloading agent components can be useful in situations when you use
270 Foglight
Administration and Configuration Guide

command-line utilities to retrieve files from URLs. For more information, see
“Using a URL to download agent components” on page 274.

Using the Components for Download view to download agent components


If you do not have access to the browser interface, use the Components for Download
view to download agent components. For more information, refer to the following
sections:
• “Accessing the Components form Download view” on page 270
• “Downloading agent components remotely using the Components for Download
view” on page 272

Accessing the Components form Download view


The Components for Download view lists the agent components that come with the
Foglight Management Server or any of the installed cartridges, and are available for
download. Use this view to see which agent components are available for download,
obtain more information about each component, and to download them.
To access the Components for Download view:
1 Open a Web browser instance and navigate to a URL that using the following
syntax:
http://<host>:<port>/console/installer/client-installers.action
or
http://<host>:<port>/client-installers
or
http://<host>:<port>/console/installer/listinstaller.action
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”.
For example:
http://HostA:8080/console/installer/client-installers.action
Managing Cartridges 271
Downloading Agent Components

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.

3 Save the file to disk.

Using a URL to download agent components


Using a URL to download an agent component ID allows you to download cartridge
files accompany server and cartridge installations, without accessing the Components
for Download view.
To use a URL to download an agent component:
1 Save the file to a desired location either using a Web browser or a command-line
utility, that downloads files from a URL to a local disk, such as wget.
Important The wget utility 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/.

• Downloading an agent component using a Web browser. Open a Web


browser instance and navigate to a URL that uses the following syntax:
http://<host>:<port>/console/installer/download-
installer.action?downloadId=<file_name>
or
http://<host>:<port>/installer-download?downloadId=<file_name>
or
http://<host>:<port>/console/installer/
listInstaller!downloadFile.action?downloadId=<file_name>
Managing Cartridges 275
Downloading Agent Components

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.

Save the file to a desired location on your disk.


• Downloading a file using a command-line utility. Open a Command Prompt
window (Windows) or a terminal window (Unix or Linux). If the command-
line utility is not in your system path, navigate to the directory that contains
this utility.
Issue the command using the following syntax:
276 Foglight
Administration and Configuration Guide

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.

This chapter contains the following sections:


About Foglight Agents ...............................................................................................................278
Managing Agent Properties by Type .........................................................................................279
Installing and Managing Agent Instances on a Monitored Host ................................................292
Deploying Agent Instances to Multiple Monitored Hosts ...........................................................342
Viewing Agent Adapters ............................................................................................................353
Assigning Blackouts to Agent Instances....................................................................................357
278 Foglight
Administration and Configuration Guide

About Foglight Agents


A Foglight agent monitors a specific part of your environment, such as an operating
system, application, or server.
There are two categories of agents: agents that run remotely (on a monitored host) and
touchless agents, which monitor remote systems from within the Foglight Management
Server. You manage them using the dashboards that are accessible from the navigation
panel, under Administration > Agents, or using the fglcmd command-line interface.
This section describes the dashboards for managing agents. For information about
fglcmd, see the Command-Line Reference Guide.

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.

Managing Agent Properties by Type


When an agent connects to the Foglight Management Server, it is provided with sets of
properties that it uses to configure its correct running state. Foglight stores agent
properties in the Foglight Management Server. Any passwords that are defined in agent
properties, and stored in the database, are encrypted. This feature is useful in situations
when a database password is defined in agent properties, you have different types of
databases and their administrators in your environment, such as the Foglight database
and a production database. Having a database password encrypted prevents those
database administrators that do not interface with Foglight from accessing the Foglight
database.
Default versions of these properties are installed with the cartridge in which the agents
are included. You can edit the default properties, create sets of properties that apply only
to a specific agent instance, and create edited clones of property sets that are used by a
subset of the agents of a certain type.
There are two types of agent properties:
• Primary. They are included in the agent component and their settings can be
specific to the agent type or the agent instance. Each agent comes with a set type-
specific properties. You can edit them for a particular agent instance, leave them
unchanged, or apply their settings to all agent instances of the same type. If you
do not change agent properties for an instance, Foglight uses the default
properties that come with that agent type.
• Secondary. They are in list form. The value of each secondary property can be set
to one or more lists. You will recognize a list-based property by the Edit, Clone,
and Delete buttons that appear next to it.
280 Foglight
Administration and Configuration Guide

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.

Accessing the Agent Properties Dashboard


Use the Agent Properties dashboard to view and edit type-specific agent properties, both
primary and secondary.
For information on how to edit instance-specific properties, see “Editing Agent
Properties by Agent Instance” on page 296.
Managing Agents 281
Managing Agent Properties by Type

To access the Agent Properties dashboard:

Note This procedure continues from “Logging in to Foglight” on page 22.

1 Ensure that the navigation panel is open.


To open the navigation panel, click the right-facing arrow on the left.
2 On the navigation panel, under Dashboards, choose Administration > Agents >
Agent Properties.
The Agent Properties dashboard appears in the display area.

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.

The Agent Properties dashboard contains two views:


• The Namespace > Type view contains a list of Foglight adapters that allow
the agent to communicate with the Foglight Management Server and a list of
agents per adapter type. The majority of Foglight agents use the Foglight
282 Foglight
Administration and Configuration Guide

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.

4 Observe the agent properties.


A list-based property has the Edit and Clone buttons to its right.
Managing Agents 283
Managing Agent Properties by Type

List property

A primary property appears as a box or an option.

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

Editing Type-Specific Agent Properties


The Properties view of the Agent Properties dashboard contains simple (primary)
properties and list-based properties.
284 Foglight
Administration and Configuration Guide

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

Editing primary type-specific properties


Use the Properties view of the Agent Properties dashboard to edit primary type-specific
properties, as outlined below.
To edit a primary type-specific 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 primary
property that you want to edit.
Note Use caution when modifying type-specific agent properties, as these settings can
apply to multiple agents.

A primary property appears as a box or an option.


Managing Agents 285
Managing Agent Properties by Type

Primary
properties

2 Edit the property as required.


Note All text boxes on the Agent Properties dashboard have a limit of 64 characters.

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.

3 Click the Save button.


The Properties view refreshes.

Cloning lists in secondary properties


Each secondary property can have one or more lists to which it can be set. Cloning a list
allows you to create multiple instances of the same list and assign them to different
agent instances as required. This type of configuration can create instance-specific lists,
overriding the default behavior of lists in which they are shared amongst agent
instances.
286 Foglight
Administration and Configuration Guide

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.

3 In the dialog box, type the name of the cloned list.


4 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
Properties view to indicate the change.

5 Save your changes.


In the Properties view, in the lower-right corner, click the Save button.
The Properties view refreshes.
Managing Agents 287
Managing Agent Properties by Type

Editing lists in secondary properties


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.
Use this type of approach when you want to use different lists at different times, or to
assign different versions of the same list to agent instances of the same agent type.
Use the Edit button in the Properties view to edit the lists that are assigned to secondary
agent properties, as outlined below.

Caution Changes made to lists can affect multiple agents.

To edit a list for a secondary property:

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.

A dialog box appears, showing the contents of the selected list.


288 Foglight
Administration and Configuration Guide

Note The appearance of the list depends on its complexity and contents.

3 Make your changes by completing any of the following steps.


• To edit an entry in the list, in the dialog box, double-click the cell containing
the entry that you want to change, and type a desired value.
Note All text values have a limit of 64 characters.

A red marker appears, indicating a change.

• 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

Populate the newly-added row, as required.


• To delete a row from the list, in the dialog box, select that row and click Delete
Selected Row(s).
Tip To select multiple entries, press the CTRL key while clicking rows.

The list refreshes, no longer showing the newly-deleted rows.


4 Save your changes.
Click Save Changes and close the dialog box.

Removing cloned lists from secondary properties


Use the Remove button on the Agent pane to delete lists that are assigned to secondary
agent properties, as outlined below.
You can only remove cloned lists. Any lists that are included with Foglight cannot be
deleted.
To delete 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 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.

A message box appears, asking you to confirm the delete operation.

3 Click Yes in the message box.


4 Save your changes.
In the Properties view, in the lower-right corner, click Save.

Viewing the Properties of the FglAMAdaper Agent


The FglAMAdapter agent comes with the installation of the Foglight Agent Manager. It
includes a set of default agent properties that can be viewed in the Agent Properties
dashboard as required. These settings control how often the Foglight Agent Manager
instructs downstream hosts and agents to connect and poll for messages. The more hosts
that are connected, the less often they are instructed to poll. Changing these settings is
only recommended when instructed to do so by Quest Support. Most instances of the
FglAMAdapter agent do not need to change these settings.
To view the properties of the FglAMAdapter agent:

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

The Properties view refreshes, showing the properties of the FglAMAdapter


agent.

2 In the Properties pane, view the FglAMAdapter properties. These properties


control the FglAMAdapter polling rates.
• Minimum Polling Interval: The minimum polling interval, in seconds.
• Maximum Number of Polls (per minute): The maximum number of polls
per minute. Client polling intervals are adjusted to adhere to this.
• Polling Max Delay Factor: The multiplier for the maximum delay, based on
the computed minimum delay.
• Polling Min Timeout: The minimum length of time in seconds before
FglAMAdapter checks to see if a host is considered disconnected.
• Core Thread Pool Size: The size of the core thread pool.
• Maximum Thread Pool Size: The maximum size of the adapter thread pool.
292 Foglight
Administration and Configuration Guide

Installing and Managing Agent Instances on a Monitored


Host
Foglight uses agent adapters on monitored hosts to communicate with agents that
collect information from those hosts. The majority of Foglight agents use the Foglight
Agent Manager. There are some agents that use other types of agent adapters, such as
the Java EE Agent.
In order to deploy an agent package to a monitored host, the applicable agent adapter
must be up and running on the host computer. Before you get started with the Agent
Status dashboard, ensure that the applicable agent adapter is running on the monitored
host.
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 the agent manager
component separately on each host computer.

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

Accessing the Agent Status Dashboard


Use the Agent Status dashboard to deploy agent packages, activate and deactivate
Foglight Agents, start and stop data collection for one or more agent instances, and view
information about agents.

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.

To access the Agent Status dashboard:

Note This procedure continues from “Logging in to Foglight” on page 22 or “Accessing the
Administration Dashboard” on page 57.

1 Ensure that the navigation panel is open.


To open the navigation panel, click the right-facing arrow on the left.
2 On the navigation panel, under Dashboards, choose Administration > Agents >
Agent Status.
The Agent Status dashboard appears in the display area.

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.

To clear the filters, click Clear Filters.


The Agent Status dashboard refreshes, showing the list of all agents.

From here, you can proceed to any of the following procedures:


• “Editing Agent Properties by Agent Instance” on page 296
296 Foglight
Administration and Configuration Guide

• “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

Editing Agent Properties by Agent Instance


If an agent instance is using the default properties for that agent type, you have two
options:
• Edit the properties for a single agent instance. This is useful in situations when
your monitoring environment includes multiple instances of the same agent type,
each monitoring a different monitored host with a specific set of monitoring
requirements. For example, if you use the Windows_System agent to monitor a
number of Windows hosts, and the data sampling frequency for Host A needs to
be higher than that of Host B, you need to set the sample frequency lists
accordingly for each instance of the Windows_System agent instance.
• Edit the properties for all agent instances of the same type. This feature is useful
when you need to globally override of one or more agent parameters for all
instances of that agent type. For example, if you use the Windows_System agent
to monitor a number of Windows hosts, and the requirements for their data
sampling frequency are the same for each host, but different than their default
values, you can set the data sampling properties of all agent instances by doing a
global update of the sample frequency property for the Windows_System agent
type.
For complete information about the Windows_System agent, see the Managing
Operating Systems User Guide.
Unlike the Agent Properties dashboard that only allows you to edit type-specific
properties, the Agent Status dashboard allows you to choose the scope of the edit
operation. For more information on editing type-specific properties using the Agent
Properties dashboard, see “Editing Type-Specific Agent Properties” on page 283. For
more information on agent properties in Foglight, see “Managing Agent Properties by
Type” on page 279.
Managing Agents 297
Installing and Managing Agent Instances on a Monitored Host

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.

Note All text boxes have a limit of 64 characters.

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

Deleting custom agent properties


In some situations, your agent instances can have their agent properties set to custom
values and you want to revert them to their global defaults quickly, without having to go
through each property and setting it to its default value. The Agent Status dashboard
includes the Property State column which allows you to quickly identify the agent
instances that have custom properties assigned to them.
298 Foglight
Administration and Configuration Guide

Figure 3

Agent instance uses global properties


Agent instance uses custom properties

To delete custom agent properties:


1 On the Agent Status dashboard, select the rows containing one or more agent
instances whose properties are set to custom values.
The Property State column indicates if an agent instance includes custom
properties.

Agent instance uses global properties


Agent instance uses custom properties

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.

2 Click the Edit Properties button at the bottom.


The Agent Status dashboard refreshes, showing the properties of the selected
agent instance.
Managing Agents 299
Installing and Managing Agent Instances on a Monitored Host

Selected Agents area


Property Scope area
Agent Properties area

3 Revert the agent properties to their default values.


In the Property Scope area, click Delete custom set of properties for this agent.
For more information, see “Choosing the edit scope” on page 300.
4 To return to the Agent Status dashboard, in the lower-right corner, click Back To
Agent Status.
The Agent Status dashboard refreshes, showing the Uses Global Properties icon
in the agent’s row.
300 Foglight
Administration and Configuration Guide

From here, you can proceed to any of the following procedures:

Choosing the edit scope


Use the Agent Status dashboard to select one or more agent instances whose properties
you want to edit. Before proceeding with the edit operation, you need to decide whether
to edit the properties for the selected instance, or to include all instances of the selected
agent’s type.
You can edit the properties of multiple agents of the same type, using the properties of
an agent instance or the default type properties as the template.
To chose 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.

2 Click the Edit Properties button at the bottom.


The Agent Status dashboard refreshes, showing the properties of the selected
agent instance.

Single agent selection Multiple agent selection

Agent Properties area


Property Scope area
Selected Agents area
Managing Agents 301
Installing and Managing Agent Instances on a Monitored Host

The Agent Status dashboard contains the following areas:


• Selected Agents. Lists one or more of the selected agents. If multiple agent
instances are selected, it also lists the default agent type.
• Property Scope. Shows options for specifying the property scope (type-
specific or instance-specific) and corresponding messages. This area appears
only if you select a single agent instance.
• Agent Properties. Shows agent properties. When you select a single agent
instance, this area appears disabled. It becomes enabled when you specify the
edit scope in the Property Scope area. When you select multiple agent
instances, it shows a check box to the left of each property which allows you
to enable or disable the property for editing.
3 Single agent selections only. Choose the edit scope by clicking one of the
following options in the Property Scope area:
Note If the selected agent instance has one or more custom properties that you want to
override with their global defaults, click Delete custom set of properties for this
agent, followed by selecting one of the options below, as described in “Deleting
custom agent properties” on page 297.

• Modify the private properties for this agent


The Property Scope area refreshes, showing the following message which
reflects your selection.

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

Editing primary properties


Each agent comes with a set type-specific properties. They can be specific to the agent
type or the agent instance. Unlike secondary properties, that can contain a list of values,
each primary property can be set to a single value.
To edit a primary property:

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.

A primary property appears as a box or an option.

Primary
properties

2 Edit the property as required.


Note All text boxes in the Agent Properties area have a limit of 64 characters.

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.

Agent instance uses global properties


Agent instance uses custom properties

Cloning lists in secondary properties


Secondary properties are in list form. The value of each secondary property can be set to
one or more lists. You will recognize a list-based property by the Edit and Clone buttons
that appear next to it.
Cloning a list allows you to create multiple instances of the same list and assign them to
different agent instances as required. This type of configuration allows you to create
instance-specific lists, overriding the default behavior of lists in which they are shared
amongst agent instances.
When you clone a list, its selection of rows and fields remains unchanged. You can alter
it if required at a later time. For more information, see “Editing lists in secondary
properties” on page 287.
Use the Clone button in the Agent Properties area to clone lists that are assigned to
secondary agent properties, as outlined below.
To clone a secondary property:

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.

Agent instance uses global properties


Agent instance uses custom properties

Editing lists in secondary properties


Secondary properties are in list form. The value of each secondary property can be set to
one or more lists. You will recognize a list-based property by the Edit and Clone buttons
that appear next to it.
306 Foglight
Administration and Configuration Guide

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.

Caution Changes made to lists can affect multiple agents.

To edit a list for a secondary property:

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.

A dialog box appears, showing the list entries.


Managing Agents 307
Installing and Managing Agent Instances on a Monitored Host

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.

3 Make your changes by completing any of the following steps.


• To edit an entry in the list, in the dialog box, double-click the cell containing
the entry that you want to change, and type a desired value.
Note All text values have a limit of 64 characters.

A red marker appears, indicating a change.

• 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

Populate the newly-added row, as required.


• To delete a row from the list, in the dialog box, select that row and click Delete
Selected Row(s).
Tip To select multiple entries, press the CTRL key while clicking rows.

The list refreshes, no longer showing the newly-deleted rows.


4 Save your changes.
Click Save Changes and close the dialog box.
5 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.

Agent instance uses global properties


Agent instance uses custom properties
Managing Agents 309
Installing and Managing Agent Instances on a Monitored Host

Removing cloned lists from secondary properties


Secondary properties are in list form. The value of each secondary property can be set to
one or more lists. You will recognize a list-based property by the Edit and Clone buttons
that appear next to it.
Use the Remove button on the Agent pane to delete lists that are assigned to secondary
agent properties, as outlined below.
You can only remove cloned lists. Any lists that are included with Foglight cannot be
deleted.
To remove a cloned list:

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.

A message box appears, asking you to confirm the delete operation.

3 Click Yes in the message box.


The message box closes and the list is removed from the collection of lists that are
available for selection for the secondary property.
310 Foglight
Administration and Configuration Guide

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

Agent instance uses global properties


Agent instance uses custom properties

Editing Agent Tags


Agent tagging allows you to form logical groupings of agents for sorting and selection.
With tags, you can edit properties for a group of agents. For information on how to use
tags to select a group of agents in order to edit their properties, see “Choosing the edit
scope” on page 300.
Agent instances can have multiple tags. You can modify the tags for each individual
agent instance.
To edit agent tags:

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.

2 Click the Edit Tags button at the bottom.


The Edit Tags dialog box appears, containing a list of the selected agent instances
and any tags associated with them.
Managing Agents 311
Installing and Managing Agent Instances on a Monitored Host

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

Deploying Agent Packages to a Monitored Host


Foglight cartridges use agents to collect information from monitored hosts. Agents
communicate with the Foglight Management Server using agent adapters, such as the
Foglight Agent Manager. When you install a cartridge on the Foglight Management
Server, the cartridge installation process makes its agent packages available for
deployment. You can only deploy those agent packages whose cartridges have already
been installed on the Foglight Management Server and on which the applicable agent
adapter is up and running.

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.

Using the Agent Status dashboard to deploy agent packages


Before you deploy agent packages to a monitored host, you must first install the relevant
cartridges and ensure that the appropriate agent adapter is up and running on host
computer.
Use the Deploy Agent Package button on the Agent Status dashboard to initiate the
deployment of an agent package, as outlined below.
Alternatively, if an agent communicates with the Foglight Management Server through
the Foglight Agent Manager, you can deploy its package using the command line. For
instructions, see “Using the command line to create agent instances” on page 324.
To deploy an agent package using the Agent Status dashboard:

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.

3 Optional. Show agent packages that can be deployed on any platform.


Select the Show Packages for All Platforms check box.
When you click the Package box, the list that appears shows all agents packages
from all installed cartridges, regardless of the platform.
Managing Agents 315
Installing and Managing Agent Instances on a Monitored Host

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

6 Click OK to close the Deploy Agent Package dialog box.


Once you have successfully deployed an agent package, you can proceed to create the of
those agents included in the newly-deployed agent package. For instructions, see
“Creating Agent Instances on a Monitored Host” on page 320.

Using the command line to deploy agent packages


Before you deploy agent packages to a monitored host, you must first have installed the
relevant cartridges and ensure that the appropriate agent adapter is up and running on
host computer.
Use the fglcmd interface to deploy agent packages on the command line, as outlined
below. For complete information about fglcmd and other Foglight commands, see the
Command-Line Reference Guide.
Before deploying an agent package, you need to ensure that the applicable package is
available to the Foglight Agent Manager IDs using the fglcmd’s agent:packages
command. This command lists the available agent packages per installer ID. 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
Managing Agents 317
Installing and Managing Agent Instances on a Monitored Host

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

Client ID: tor012991.prod.quest.corp#cf238d96-3a56-45d6-a33e-


b88bb7d4ff55
Installer ID: tor012991.prod.quest.corp#cf238d96-3a56-45d6-a33e-
b88bb7d4ff55#FglAM:tor012991.prod.quest.corp/cf238d96-3a56-
45d6-a33e-b88bb7d4ff55/installer
Agent Package ID: OSCartridge-WindowsXP-5.5.0-OSCartridge-
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.*/
Agent Package OS Architecture: ia32,x86_64
------------------------------------

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.

To deploy an agent package using the command line:

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.

1 Open a Command Prompt window (Windows) or a terminal window (Unix or


Linux) and navigate to the directory on your computer that contains the
uncompressed fglcmd package. For example, <foglight_home>/bin.
Note For complete information on how to get started with fglcmd, see the Command-Line
Reference Guide.

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

Agent Package OS Architecture: ia32,x86_64


------------------------------------
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 agent_package_ID
-host myhost.mydomain.corp
An output similar to the following appears:
Successfully installed package agent_package_ID on
myhost.mydomain#cf238d96-3a56-45d6-a33e-b88bb7d4ff55
#FglAM:tor012991.prod.quest.corp/cf238d96-3a56-45d6-
a33e-b88bb7d4ff55/installer

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

Creating Agent Instances on a Monitored Host


You can create an agent instance once the package containing that agent type has been
deployed to the monitored host. For information on how to deploy an agent package, see
“Deploying Agent Packages to a Monitored Host” on page 312 and “Deploying Agent
Packages to Multiple Hosts” on page 345.
It is necessary to create first and subsequent instances of agents. For each agent type
available to a Foglight Agent Manager, an arbitrary number of agent instances can be
created.
Before you deploy and create agents on a monitored host, you must first have installed
the relevant cartridges and ensure that the appropriate agent adapter is up and running
on the host computer.
There are two ways to create an agent instance:
• Using the Agent Status dashboard. For instructions, see “Using the Agent Status
dashboard to create agent instances” on page 320.
• If an agent communicates with the Foglight Management Server through the
Foglight Agent Manager, you can create its instance using the command line. For
instructions, see “Using the command line to create agent instances” on page 324.
The Agent Status dashboard allows you to create one agent instance at a time. If you
need to perform a mass instance creation on multiple hosts, you can use the Agent Hosts
dashboard. For more information, see “Creating Agent Instances on Multiple Hosts” on
page 348

Using the Agent Status dashboard to create agent instances


Before you create an agent instance on a monitored host, you must first have installed
the relevant cartridges, deployed the agent package, and ensured that the appropriate
agent adapter is up and running on the host computer.
Use the Create Agent button on the Agent Status dashboard to initiate the deployment of
an agent package, as outlined below.
Alternatively, if an agent communicates with the Foglight Management Server through
the Foglight Agent Manager, you can create its instance using the command line. For
instructions, see “Using the command line to create agent instances” on page 324.
To create an agent instance using the Agent Status dashboard:

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

6 Click OK to close the Create Agent dialog box.


The Agent Status dashboard refreshes, showing the newly-created agent instance.

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.

Using the command line to create agent instances


Before you create an agent instance on a monitored host, you must first have installed
the relevant cartridges, deployed the agent package, and ensured that the appropriate
agent adapter is up and running on the host computer.
Use the fglcmd interface to create an agent instance on the command line, as outlined
below. For complete information about fglcmd and other Foglight commands, see the
Command-Line Reference Guide.
Managing Agents 325
Installing and Managing Agent Instances on a Monitored Host

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.

To create an agent instance using the command line:

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.

1 Open a Command Prompt window (Windows) or a terminal window (Unix or


Linux) and navigate to the directory on your computer that contains the
uncompressed fglcmd package. For example, <foglight_home>/bin.
Note For complete information on how to get started with fglcmd, see the Command-Line
Reference Guide.

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.

Activating or Deactivating Agents


Activating an agent instance starts the agent process on the machine on which the agent
is installed. Deactivating an agent stops the agent process.
You can activate and deactivate agents using the interface on the Agent Status
dashboard, as described below. The Activated icon ( ) indicates if the agent is active or
not. If the icon appears in the row containing the agent instance, the agent is active. If it
does not appear, the agent is inactive.
Figure 4
Agent is active

Agent is inactive

Alternatively, use the agent:activate or agent:deactivate commands to activate


or deactivate agents. These commands come with the fglcmd interface. For complete
information, see the Command-Line Reference Guide.
Activating an agent also starts the data collection for that agent. You can deactivate only
those agents that are not collecting data. For more information on how to start or stop
data collection for an agent, see “Starting or Stopping Data Collection” on page 331.
If an agent instance fails to activate, you can use the agent’s log file to determine the
cause of the problem. For more information, see “Retrieving Agent Logs” on page 338.

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.

To activate an 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 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.

2 Click the Activate button.


The Agent Operation dialog box appears, showing the status of the activation
process.
Managing Agents 329
Installing and Managing Agent Instances on a Monitored Host

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.

3 In the Agent Operation dialog box, click OK.


The Agent Operation dialog box closes and the Agent Status dashboard
refreshes, showing the Activated ( ) and Collecting Data ( ) icons in the agent
row, indicating a success.

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

To deactivate an 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 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.

2 Click the Deactivate button at the bottom.


The Agent Operation 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.
Managing Agents 331
Installing and Managing Agent Instances on a Monitored Host

3 In the Agent Operation dialog box, click OK.


The Agent Operation dialog box closes and the Agent Status dashboard
refreshes, no longer showing the Activated ( ) and Collecting Data ( ) icons in
the agent row.

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.

Starting or Stopping Data Collection


When you cause an agent to start data collection, the agent begins to monitor the
applicable part of your environment and send data about it to the Foglight Management
Server. When you stop data collection for an agent, the agent no longer collects
information from the monitored host.
332 Foglight
Administration and Configuration Guide

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 collecting data

Agent is not collecting data

Agent is inactive

To start data collection for an 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 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.

2 Click the Start Data Collection button at the bottom.


The Agent Operation dialog box appears, showing the status of the activation
process.
Managing Agents 333
Installing and Managing Agent Instances on a Monitored Host

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

3 In the Agent Operation dialog box, click OK.


The Agent Operation dialog box closes and the Agent Status dashboard
refreshes, showing the Collecting Data icon ( ) in the agent row.

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.

To stop data collection for an agent instance:

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

3 In the Agent Operation dialog box, click OK.


The Agent Operation dialog box closes and the Agent Status dashboard
refreshes, showing the Not Collecting Data icon ( ) in the agent row.

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.

1 Select and delete an agent instance.


a In the Agent Status dashboard, select the row containing the agent instance
that you want to delete.
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.

b Click the Delete button at the bottom.


or
To delete a single multiple agent instances, in the Agent Status dashboard, in the
row containing an agent instance that you want to delete, click the Delete Agent
button ( ).
The Delete Agent dialog box appears, asking you to confirm the delete operation.

2 In the Delete Agent dialog box, click OK.


The dialog box closes.
338 Foglight
Administration and Configuration Guide

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.

Retrieving Agent Logs


Agent log files contain entries that describe the operations an agent process performs
while it is running on the monitored host. If an agent instance fails to activate, you can
use an agent log file to determine the cause of the problem.
Foglight stores agent logs in the following file:
foglight_client_home/<cartridge_name>/
<cartridge_version>/logs/
<agent_type>_<agent_name>_<date>_<time>_<file_ID>.log
Where:
• foglight_client_home is the installation directory of the Foglight Agent
Manager.
• cartridge_name is the name of the cartridge. For example, OSCartridge.
• cartridge_version is the cartridge version. For example, 5.5.0.
• agent_type is the agent type. For example, AppMonitor.
• agent_instance_name is the name of the agent instance.
• date and time are the date and time the agent was started.
• file_ID identifies the log file.
For example: AppMonitor_MyAgent_2007-10-11_101440_001.log
There are two ways to retrieve agent logs:
• Using the Agent Status dashboard. For instructions, see “Using the Agent Status
dashboard to retrieve an agent log” on page 339.
Managing Agents 339
Installing and Managing Agent Instances on a Monitored Host

• If an agent communicates with the Foglight Management Server through the


Foglight Agent Manager, you can retrieve its logs using the command line. For
instructions, see “Using the command line to retrieve agent logs” on page 340.
One agent instance can generate multiple log files, one for each period of time the agent
is running. The Agent Status dashboard allows you to retrieve only the latest log file,
while the command line offers the flexibility of selecting log files for an agent.

Using the Agent Status dashboard to retrieve an agent log


Use the Get log button on the Agent Status dashboard to retrieve the most recent log file
for an agent, as outlined below.
Alternatively, if an agent communicates with the Foglight Management Server through
the Foglight Agent Manager, you can use the command line to choose from existing
logs and retrieve them as required. For instructions, see “Using the command line to
retrieve agent logs” on page 340.
To retrieve an agent log using the Agent Status dashboard:

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.

3 Open or save the log file as required.


Note If you pull agent logs into the <foglight_home>/logs directory, they will be packaged
as part of the server support bundle. For more information about server support
bundles, see Chapter 3, “Managing Support Bundles” on page 139.

Using the command line to retrieve agent logs


Use the fglcmd interface to choose from existing agent logs and retrieve them as
required, as outlined below. For complete information about fglcmd and other Foglight
commands, see the Command-Line Reference Guide.
Alternatively, you can retrieve the most recent agent log using the Agent Status
dashboard. For instructions, see “Using the Agent Status dashboard to retrieve an agent
log” on page 339.

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.

To retrieve an agent log using the command line:


1 Open a Command Prompt window (Windows) or a terminal window (Unix or
Linux) and navigate to the directory on your computer that contains the
uncompressed fglcmd package. For example, <foglight_home>/bin.
Note For complete information on how to get started with fglcmd, 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.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

If successful, this command does not generate any output.


Note If you pull agent logs into the <foglight_home>\logs directory, they will be packaged
as part of the server support bundle. For more information about server support
bundles, see Chapter 3, “Managing Support Bundles” on page 139.

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.

Deploying Agent Instances to Multiple Monitored Hosts


Foglight uses agent adapters on monitored hosts to communicate with agents that
collect information from those hosts. The majority of Foglight agents use the Foglight
Agent Manager. There are some agents that use other types of agent adapters, such as
the Java EE Agent.
In order to deploy an agent package to multiple hosts, the applicable agent adapter must
be up and running on each of the hosts to which you want to deploy the agent package.
Before you get started with the deploying agent packages, ensure that the applicable
agent adapter is running on each monitored host.
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 the agent manager
component separately on each host computer.

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.

Additionally, if you need to perform a series of agent-related operations on a single host,


use the Agent Status dashboard. For more information, see “Installing and Managing
Agent Instances on a Monitored Host” on page 292.
For information on how to use the Agent Hosts dashboard, see the following sections:
• “Accessing the Agent Hosts Dashboard” on page 343
• “Deploying Agent Packages to Multiple Hosts” on page 345
• “Creating Agent Instances on Multiple Hosts” on page 348

Accessing the Agent Hosts Dashboard


Use the Agent Status dashboard to deploy agent packages, activate and deactivate
Foglight Agents, start and stop data collection for one or more agent instances, and view
information about agents.

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.

To access the Agent Hosts dashboard:

Note This procedure continues from “Logging in to Foglight” on page 22.

1 Ensure that the navigation panel is open.


To open the navigation panel, click the right-facing arrow on the left.
2 On the navigation panel, under Dashboards, choose Administration > Agents >
Agent Hosts.
The Agent Hosts dashboard appears in the display area.

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

Deploying Agent Packages to Multiple Hosts


Foglight cartridges use agents to collect information from monitored hosts. Agents
communicate with the Foglight Management Server using agent adapters, such as the
Foglight Agent Manager. When you install a cartridge on the Foglight Management
Server, the cartridge installation process makes its agent packages available for
deployment. You can only deploy those agent packages whose cartridges have already
been installed on the Foglight Management Server and on which the applicable agent
adapter is up and running.

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.

3 Observe the Host setting.


It lists the monitored or more hosts that you selected in step 1.
4 Optional. Show agent packages that can be deployed on any platform.
Select the Show Packages for All Platforms check box.
When you click the Package box, the list that appears shows all agents packages
from all installed cartridges, regardless of the platform.
Managing Agents 347
Deploying Agent Instances to Multiple Monitored Hosts

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

Creating Agent Instances on Multiple Hosts


You can create an agent instance once the package containing that agent type has been
deployed to the monitored host. For information on how to deploy an agent package, see
“Deploying Agent Packages to a Monitored Host” on page 312 and “Deploying Agent
Packages to Multiple Hosts” on page 345.
It is necessary to create first and subsequent instances of agents. For each agent type
available to a Foglight Agent Manager, an arbitrary number of agent instances can be
created.
Before you deploy and create agents on a monitored host, you must first have installed
the relevant cartridges and ensure that the appropriate agent adapter is up and running
on host computer.
You can create an instance of the same agent on multiple hosts using the Agent Hosts
dashboard.
Alternatively, if you need to perform a series of different agent-related operations
against a single host, you can use the Agent Status dashboard. For more information, see
“Creating Agent Instances on a Monitored Host” on page 320.
Managing Agents 349
Deploying Agent Instances to Multiple Monitored Hosts

To create agent instances on multiple hosts:

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.

3 Observe the Host setting.


It lists the monitored or more hosts that you selected in step 1.
4 In the Create Agent dialog box, observe the Host setting.
It lists one or more hosts that you selected in step 1.
350 Foglight
Administration and Configuration Guide

5 Specify the type of the agent that you want to create.


Note You can only create instances of those agents whose agent packages have already
been deployed.

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

9 Click OK to close the Create Agent Results dialog box.


10 Observe the listing in the Agent Status dashboard.
On the navigation panel, under Dashboards, choose Administration > Agents >
Agent Status.
The Agent Status dashboard appears in the display area, showing the
newly-created agent instances in the list.
Managing Agents 353
Viewing Agent Adapters

Viewing Agent Adapters


Foglight uses agent adapters to communicate with agents that collect information from
monitored hosts. The majority of Foglight agents use the Foglight Agent Manager.
There are some agents that use other types of agent adapters, such as the Java EE Agent.
In order to deploy an agent package to a monitored host, the applicable agent adapter
must be running on the host computer.
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 Adapters dashboard allows you to view information about agent adapters
and to activate or deactivate them as necessary.
354 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

Accessing the Agent Adapters Dashboard


Use the Agent Adapters dashboard to view information about the existing agent
adapters that your Foglight agents use to communicate with the Foglight Management
Server, and to activate or deactivate them as required.
To access the Agent Adapters dashboard:

Note This procedure continues from “Logging in to Foglight” on page 22.

1 Ensure that the navigation panel is open.


To open the navigation panel, click the right-facing arrow on the left.
2 On the navigation panel, under Dashboards, choose Administration > Agents >
Agent Adapters.
The Agent Adapters dashboard appears in the display area.

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.

To clear the filters, click Clear Filters.


The Agent Adapters dashboard refreshes, showing the list of all agents.
356 Foglight
Administration and Configuration Guide

From here, you can proceed to “Activating or Deactivating Agent Adapters” on


page 356.

Activating or Deactivating Agent Adapters


Activating an agent adapter starts the agent adapter process on the monitored host while
deactivating an agent adapter stops that process.
You can activate and deactivate agent adapters using the interface on the Agent
Adapters dashboard, as described below. The Activated icon ( ) indicates if an adapter
is active or not. If the icon appears in the row containing the agent instance, the agent is
active. If it does not appear, the agent is inactive.
Figure 6

Adapter is active

Adapter is inactive

To activate an agent adapter:

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.

2 Click the Activate button at the bottom.


The Agent Adapters dashboard refreshes, showing the Activated icon ( ) in the
Active State ( ) column of the adapter’s row.
Note If the activation command was executed successfully but the agent fails after
starting, the Activated icon does not appear.

To deactivate an agent adapter:

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.

2 Click the Deactivate button at the bottom.


The Agent Adapters dashboard refreshes, no longer showing the Activated icon
( ) in the Active State ( ) column of the adapter’s row.

Assigning Blackouts to Agent Instances


A schedule defines a period of time during which an action occurs. Blackout schedules
prevent agents from collecting data. You can use an existing schedule or create another
one if required. For more information about schedules, see Chapter 8, “Using
Schedules” on page 561.
An agent blackout is a scheduled event during which the agent does not collect data for
set intervals. For example, you might want to set the times when regularly scheduled
maintenance is performed on a server as the blackout period for the agents that run on
that server.
Use the Agent Blackouts dashboard to manage agent blackouts.
358 Foglight
Administration and Configuration Guide

To manage agent blackouts:

Note This procedure continues from “Logging in to Foglight” on page 22.

1 Ensure that the navigation panel is open.


To open the navigation panel, click the right-facing arrow on the left.
2 On the navigation panel, under Dashboards, choose Administration > Agents >
Agent Blackouts.
The Agent Blackouts dashboard appears in the display area, listing all agent
instances.

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

To clear the filters, click Clear Filters.


The Agent Blackouts dashboard refreshes, showing the list of all agents.

To clear the filters, click Clear Filters.


5 Assign or remove a blackout schedule for an agent.
a Select the row containing that agent.
b Click the Assign Blackout button at the bottom.
360 Foglight
Administration and Configuration Guide

The Selected Agents dialog box appears.

c Choose a blackout schedule for the selected agent.


Click Choose a Schedule.
A list of all available schedules appears.
Managing Agents 361
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.

7 Close the Blackout Schedule Results dialog box by clicking OK.


The Blackout Schedule Results dialog box closes and the Agent Blackouts
dashboard refreshes, showing the schedule assigned to the agent instance in the
Schedule Name column.
362 Foglight
Administration and Configuration Guide
7
Working with Foglight Rules and
Registry

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.

This chapter contains the following sections:


About Rules, Registry, and Topology in Foglight .......................................................................364
Working with Foglight Registry Variables ..................................................................................364
Working with Rules....................................................................................................................406
364 Foglight
Administration and Configuration Guide

About Rules, Registry, and Topology in Foglight


Foglight collects data about your system and dynamically builds topology models at
run-time. A topology model organizes the data in a way that represents the logical and
physical relationship between items in your monitored environment and provides the
context for the collected metrics. Each topology model includes one or more topology
types, and each type has an associated set of metrics. Topology objects are instances of a
topology type. For example, a Host model may contain Processor, Host, and Memory
topology types; a specific CPU would be an instance of the Processor topology type. For
more information on data and topology models, see Chapter 9, “Working with Data” on
page 615.
A registry variable can have a global value that is available to all topology types and
objects as well as multiple values that are associated with specific topology types or
objects. If required, these values can be configured to change at certain times. For more
information, see “Working with Foglight Registry Variables” on page 364.
A rule is associated with a topology type and can be configured to run against specific
topology objects. Rule definitions can include registry variables, raw metrics, derived
metrics, and topology object properties. At run-time, Foglight creates topology objects
and initiates rules to run against these objects, using registry variables, metrics, and
object properties as thresholds for alarm generation, as specified in rule definitions. For
more information, see “Working with Rules” on page 406.

Working with Foglight Registry Variables


Foglight registry variables can be used in rule conditions, expressions, and actions.
They 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 topology types or objects, or calendar dates. In addition, these
values can be configured to change at certain times.
You create new registry variables, assign values to registry variables, and manage
registry variables using the dashboards that come with the Administration module.
Because registry variables can have multiple values that are tied to the topology or
dates, you can see verify their values and see how they are affected by these parameters.
For complete information, see the following sections:
• “Managing Registry Variables” on page 365
• “Creating Registry Variables” on page 377
Working with Foglight Rules and Registry 365
Working with Foglight Registry Variables

• “Editing Registry Variables” on page 381


• “Viewing Registry Values” on page 390
• “Example: Assigning Multiple Values to a Registry Variable” on page 399
• “Example: Using Performance Calendars” on page 399
• “Example: Assigning Host-Specific Email Addresses of Foglight System
Administrators” on page 400

Managing Registry Variables


The Manage Registry Variables dashboard allows you to create new registry variables,
assign values to registry variables, and manage registry variables. For complete
information, see the following sections:
• “Working with Foglight Registry Variables” on page 364
• “Accessing the Manage Registry Variables dashboard” on page 365
• “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

Accessing the Manage Registry Variables dashboard


The Manage Registry Variables dashboard includes a list of the registry variables that
exist in your monitoring environment and includes an interface for adding and deleting
registry variables.
To access the Manage Registry Variables dashboard:

Note This procedure continues from “Logging in to Foglight” on page 22.

1 Ensure that the navigation panel is open.


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.
366 Foglight
Administration and Configuration Guide

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 Manage Registry Variables dashboard refreshes, showing only the


variables that do not have a global default value.
• To show only the variables that come with a specific cartridge, in the By
Cartridge box, type the cartridge name.
The Manage Registry Variables dashboard refreshes, showing only the
variables that come with the cartridge whose name matches the expression.
• To clear the filters, click Clear Filters.
The Manage Registry Variables dashboard refreshes, showing the list of all
variables.

5 View summary information about a registry variable.


Move the mouse pointer over the Variable Name column in the row containing
the registry variable whose summary you want to view.
A dwell appears, showing the summary about the registry variable.
368 Foglight
Administration and Configuration Guide

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

Editing permissions of registry variables


Foglight allows you to control access to registry variables. For each variable you can
grant or deny read, write, or control access to roles or users. For more information about
security concepts in Foglight, see Chapter 4, “Managing Users and Security” on
page 197.
Foglight employs the following behavior when it comes to permissions for registry
variables:
• If no one has a permission to the registry variable, everyone has a permission.
• If one has a permission to the registry variable, others with undefined permission
do not have any permission.
• Final permission is based on a combination of the role, user, and registry variable
defined on the server side.
Use the Edit Permissions button ( ) on the Manage Registry Variables dashboard to
navigate to the Edit Permissions for Registry Variable area, that allows you to add or
Working with Foglight Rules and Registry 369
Working with Foglight Registry Variables

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

To add permissions for a registry variable:

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

2 To add permissions to a variable, complete the following steps.


a Click the role or user to which you want to assign permissions.
Tip The Not Assigned icons in the Permissions columns indicate that the role has no
permissions assigned to it.

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

3 To edit or delete permissions for a variable, complete the following steps.


a Click the role or user whose permissions you want to edit.
Tip Three check marks in the Permissions columns indicate that the role already has
permissions assigned to it.

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.

Copying registry variables


Use the Copy Registry Variable button on the Manage Registry Variables dashboard to
copy a registry variable, as outlined below.
To copy a registry variable:

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

2 In the Copy Registry Variable dialog box, click OK.


The Copy Registry Variable dialog box closes and another dialog box appears,
asking you to specify the name of the destination variable.

3 Type the name of the variable and click OK.


Note You must use a unique name.

The dialog box closes and the Edit Registry Variable pane appears in the display
area.
374 Foglight
Administration and Configuration Guide

4 If required, edit the newly-copied variable.


For more information, see “Editing Registry Variables” on page 381.

Deleting registry variables


Use the Delete Selected button on the Manage Registry Variables dashboard to delete a
registry variable, as outlined below.

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.

To delete a registry variable:

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.

3 In the Registry Variable Confirmation dialog box, click OK.


The Registry Variable Confirmation dialog box closes.
4 Observe the Manage Registry Variables dashboard.
The newly-deleted variable no longer shows in the list.

Viewing and editing variable settings


The Manage Registry Variables dashboard shows all of the registry variables that exist
in your monitoring environment. This includes the variables that come with the Foglight
Management Server, any installed cartridges, and also any variables that you create
using the Create Registry Variable dashboard. From here, you can drill down to view the
settings for a registry variable, and edit them, as required.
To view or edit variable settings:

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

2 Observe the variable definitions.


3 Edit the variable if required.
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
name and its version. Otherwise, if the registry variable is created using the Create
Registry Variable dashboard, this value is blank.

For complete instructions, see “Specifying values” on page 383.


Working with Foglight Rules and Registry 377
Working with Foglight Registry Variables

Creating Registry Variables


Foglight allows you to create registry variables using the Create Registry Variable
dashboard. You can access this dashboard from the navigation panel, or through the
Manage Registry Variables dashboard.
To create a registry variable:

Note This procedure continues from “Logging in to Foglight” on page 22.

1 Ensure that the navigation panel is open.


To open the navigation panel, click the right-facing arrow on the left.
2 Open the Create Registry Variable dashboard by completing one of the following
steps:
• On the navigation panel, under Dashboards, choose Administration > Rules
& Notifications > Manage Registry Variables.
In the Manage Registry Variables dashboard that appears in the display area,
click the Add Variable button in the lower-left corner.
or
• On the navigation panel, under Dashboards, choose Administration > Rules
& Notifications > Create Registry Variable.
The Create Registry Variable dashboard appears in the display area.
378 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.

• Description/Comments: Any comments about the variable or its usage.


• Registry Value Type: The data type of the variable. There are 6 possible data
types to which a variable can be set, as listed below.
Note The registry variable type cannot be changed once the registry variable has been
added.

Registry Value Description Example


Type

Boolean A boolean value: true or false. true


Working with Foglight Rules and Registry 379
Working with Foglight Registry Variables

Registry Value Description Example


Type

String A text string. This


message was
generated
by
Foglight.

Integer An integer value between -23 1 and 6825


23 1 -1. For example, valid values
include 235 and -10000.

Double A decimal value. For example, valid 95.0


values include 34.1234, 35e3
(meaning 35,000.0) or 1.2E-2
(meaning 0.012).

Timestamp Contains a date and time. For 2008-08-10


example, valid values include 06/ 23:15:16.0
12/06, 2006-06-21 15:30:21.0,
June 7, 2006 3:08:21 PM.
Invalid date or time formats cannot be
saved to the database and any
attempts to save them result in an
error. If the time is not provided, or
the values are invalid, Foglight treats
the time as midnight.
Prior to saving the value of a
Timestamp variable, Foglight
converts it to the following format:
yyyy-mm-dd hh:mm:ss.ds
Once the value is converted, Foglight
stores it in the database.
380 Foglight
Administration and Configuration Guide

Registry Value Description Example


Type

PasswordValue A password value. Prior to storing the demo123


value of the PasswordValue data type
in the registry, Foglight encrypts it
and saves the encrypted value in the
database. This is useful in cases
where you need to secure password
values when passing it to command
or remote command actions.
For example, you create a registry
variable of the PasswordValue type,
MyPassword, and set its value to
demo123. Foglight encrypts the
registry value, then stores it
encrypted in the database (for
example, 43-119-184-240-170-
150-124-218-30-112-216-76-
197-233-188-206). In a function
call registry("MyPassword"),
Foglight retrieves the registry value
from the database in its encrypted
form, which secures the password
value.

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

6 To verify if the variable appears in the Manage Registry Variables dashboard,


click Go to Registry Variable List.
To edit the newly-created variable, click Edit Registry Variable. For information
on how to edit registry variables, see “Editing Registry Variables” on page 381.

Editing Registry Variables


You can edit a newly-created or an existing variable and assign it a global default value,
associate values with specific topology types or objects, or configure performance
calendars for each value.
For instructions, see the following sections:
• “Getting started with variable definitions” on page 381
• “Specifying values” on page 383
• “Using performance calendars” on page 385
• “Scoping variables to topology types or object instances” on page 387

Getting started with variable definitions


Once you create a variable, you can proceed to add comments to it and edit its settings
as required.
You cannot edit the name of a registry variable after it has been created. This is because
registry variables are referred to by name in rule conditions and expressions; changing
their names would invalidate these references. Additionally, you cannot edit the value
type of a registry variable after the variable is created.
To get started with editing variable definitions:

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.

2 Optional. Add or edit the existing comments in the Description/Comments box


and then click Save on the right.
From here, you can proceed to “Specifying values” on page 383.

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.

Data Type Global Default Area To specify the value

Boolean Click the box and


select true or false
from the list that
appears.

String Type the value in


the box, making
Long sure that the value
is compatible with
Integer
the data type. For
example, if the
Double
variable is of a
Timestamp String type, type a
text string.

Password Type the password


Value into each box.

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.

2 Click Save to save the global default value.


From here, you can proceed to “Using performance calendars” on page 385.

Using performance calendars


If you want the default value to change over time, add one or more schedules to the
performance calendar and specify the value for each schedule. See “Example: Using
Performance Calendars” on page 399 for an example of how to use this feature.
The Foglight Management Server evaluates the schedules in the performance calendar
in the order they are listed, starting with the first one. Changing their order affects the
behavior of the actions that are associated with the variable whose value is set by the
schedule-based entries in the performance calendar.
For example, if there are two schedule entries in the performance calendar that overlap
in time but have two different values, the first entry listed takes precedence, causing one
or more actions that are associated with that variable to make use of that entry for the
duration of the schedule.
386 Foglight
Administration and Configuration Guide

To add schedules to a performance calendar:

Note This procedure continues from “Specifying values” on page 383.

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

To move a threshold bound up or down, in the Default Value Performance


Calendar table, in the Schedule Name column, use the Move up the selected
performance calendar ( ) or Move down the selected performance calendar ( )
buttons as required.
From here, you can proceed to “Scoping variables to topology types or object instances”
on page 387.

Scoping variables to topology types or object instances


The way you define registry variables can help you to reduce the number of rules that
need to be created and managed by allowing you to create a single rule that can be
applied to several topology types or objects.
If you want to scope the registry variable to topology types or objects, and add schedule-
specific values to it, add one or more values to the Registry Values table.
To scope the registry value to a topology type or object:

Note This procedure continues from “Using performance calendars” on page 385.

1 Click Add Registry Value at the bottom.


The Create Registry Value—Step 1 view appears in the display area.
388 Foglight
Administration and Configuration Guide

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

Viewing Registry Values


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 topology
types or objects, or calendar dates. To find out what is the value of a registry variable for
a particular topology type or object, and, if applicable, during a specific time period, use
the Check Registry Value dashboard.
To view the values of a registry variable:
1 Ensure that the navigation panel is open.
To open the navigation panel, click the right-facing arrow on the left.
2 On the navigation panel, under Dashboards, choose Administration > Rules &
Notifications > Check Registry Value.
The Check Registry Value dashboard appears in the display area, showing the
View Registry Variable view.

3 The dashboard shows the following information:


• Variable Name: The name of the registry variable whose value you want to
view.
• Topology Type Name: The topology type with which the registry value is
associated.
• Topology Object: The object instance of the specified topology type with
which the registry value is associated.
Working with Foglight Rules and Registry 391
Working with Foglight Registry Variables

• 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.

b In the Topology Object list, select an object instance.


7 Specify the date and time range for which you want to see the registry values.
394 Foglight
Administration and Configuration Guide

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

The Show columns dialog box appears.

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.

9 Optional. Print the list of audit logs to a file.


a In the Registry Value table, click the Show/Hide columns button.

Show/Hide columns

The Show columns dialog box appears.


Working with Foglight Rules and Registry 397
Working with Foglight Registry Variables

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.

Example: Assigning Multiple Values to a Registry Variable


You have several groups of servers in your monitored environment. You want an email
to be sent to the system administrator if one of the servers becomes unavailable, but a
different administrator is responsible for each group. Instead of creating a different rule
with a different email action for each group, you create a registry variable called
Administrator and then assign it a different value (the email address of the appropriate
administrator) for each group of servers. You then create a single simple rule that fires if
any of the servers become unavailable and which uses the Administrator variable in the
rule’s email action.

Example: Using Performance Calendars


Creating a performance calendar for a variable’s values allows you to cause rules to
behave differently at different times.

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.

Example: Assigning Host-Specific Email Addresses of Foglight


System Administrators
The Foglight Management Server includes the global registry variable SYSADMIN that
allows you to set the email address of the Foglight System Administrator. Larger
monitoring environments have different system administrators that manage different
parts of Foglight. For example, you can have a different system administrator looking
after each monitored host. Monitored hosts in the Foglight data model exist as object
instances of the topology type Host. Foglight registry variables can have topology-
scoped variables associated with particular topology types and/or their object instances.
This feature allows you to assign host-specific email addresses of different Foglight
administrators using the SYSADMIN registry variable. In this example, there are two
monitored hosts and each host has a designated system administrator, as listed below.

Host Administrator’s email

HostA joe@xyzdomain.com

HostB larry@pdqdomain.com

To assign host-specific email addresses:

Note This procedure continues from “Logging in to Foglight” on page 22.

1 Ensure that the navigation panel is open.


Working with Foglight Rules and Registry 401
Working with Foglight Registry Variables

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

4 Open the SYSADMIN variable for editing.


Click the Variable Name column of the row containing SYSADMIN entry.
The Manage Registry Variables dashboard refreshes, showing the Edit Registry
Variable view.

5 Assign an email address to each monitored host by adding two host-specific


values to the SYSADMIN variable.
To add a topology-scoped value to the registry variable, complete the following
steps.
a At the bottom of the Edit Registry Variable view, click Add Registry Value.
The Manage Registry Variables dashboard refreshes, showing the Create
Registry Value—Step 1 view.
Working with Foglight Rules and Registry 403
Working with Foglight Registry Variables

b Set the scope of the SYSADMIN variable to the Host type.


In the Create Registry Value—Step 1 view, on the right of Topology Type,
click Select Type.
In the list that appears, under Core, select Host.
c Narrow down the scope of the value by setting the value scope to a particular
instance of the Host type.
On the right of Topology Object, click All Objects
In the list that appears, select a monitored host.
d Specify the email address of the system administrator that is responsible for
that host.
In the Default Value area, ensure that the Static Value option is selected.
In the box at the bottom of the Default Value area, type the administrator’s
email address.
e At the bottom of the Create Registry Value—Step 1 view, click Add.
The Manage Registry Variables dashboard refreshes, showing the Create
Registry Value—Step 2 view.
404 Foglight
Administration and Configuration Guide

f In the bottom-right, click Done.


The Manage Registry Variables dashboard refreshes, showing the newly-
added value in the Registry Values table.

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

Working with Rules


Foglight allows you to create flexible rules that can be applied to complex, interrelated
data from multiple sources within your distributed system. You can associate several
different actions with a rule, configure a rule so that it does not fire repeatedly, and
associate a rule with schedules that define when it should and should not be evaluated.
The following list introduces you to the concepts and terms related to rules.
• Rule. A rule is a piece of business logic that links a condition with a result. The
result may be linked to actions. There are two types of rules in Foglight: simple
rules and multiple-severity rules. A rule includes a scope, conditions, expressions,
messages, and actions.
• Rule Scope. The scope of a rule defines the set of topology objects against which
it will run. The scope object is the object on which alarms will appear in the
Foglight interface.
• Simple Rule. A simple rule runs user-defined actions when the condition for that
rule is met. Simple rules do not create alarms and unlike multiple-severity rules
(see below), they don't have severity levels. A simple rule is logic that is triggered
by data. See “Defining rule types” on page 435 for more information.
• Multiple-Severity Rule. A multiple-severity rule is a more complex type of rule
that can include up to five levels of severity. These levels are described in more
detail in “Defining rule types” on page 435. This type of rule always creates an
alarm when the condition associated with one of its severity levels is met.
• Severity State. A severity state is the highest severity condition of a multiple-
severity rule that evaluated to true.
• Fire Prevention. A group of settings that prevent actions and alarms from firing
repeatedly for a rule.
• Effective Period. A scheduled period during which a rule is active.
• Blackout Period. A scheduled period during which a rule is inactive.
• Monitoring Data. Data that has been collected from your monitored environment
by the agents and transformed into a standard format for use by the Foglight
Management Server. Monitoring data includes both metrics and topology object
properties.
• Function. Rule conditions and expressions are matched against monitoring data.
Functions cause calculations to be performed on the data specified in conditions
and expressions, allowing the data to be modified before it is matched.
Working with Foglight Rules and Registry 407
Working with Rules

• 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

• “Example: Creating Multiple-Severity Rules with a Topology Scope” on


page 539
• “Example: Configuring Rule Action Parameters” on page 547
• “Example: Creating Rules Scoped to Different Topology Types” on page 548
• “Example: Associating Command Actions with Rules” on page 556

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

Accessing the Manage Rules dashboard


The Manage Rules dashboard includes a list of the rules that exist in your monitoring
environment and allows you to add or delete rules and perform other rule management
operations.
Working with Foglight Rules and Registry 409
Working with Rules

To access the Manage Rules dashboard:

Note This procedure continues from “Logging in to Foglight” on page 22 or “Accessing the
Administration Dashboard” on page 57.

1 Ensure that the navigation panel is open.


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 Rules.
The Manage Rules dashboard appears in the display area.

3 Viewing the Manage Rules dashboard immediately after installing new


cartridges. In the upper-right corner, click .
The list of rules refreshes, showing any rules that come with newly-installed
cartridges.
4 To sort the list of variables by their name, scope or the name of the cartridge name
to which they belong, click the Rule Name, Rule Scope, or Cartridge Name
column headings as required.
5 Optional. Filter the list of rules.
410 Foglight
Administration and Configuration Guide

• 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.

6 View summary information about a rule.


Move the mouse pointer over the Rule Name column in the row containing the
rule whose summary want to view.
Working with Foglight Rules and Registry 411
Working with Rules

A dwell appears, showing the rule summary.

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

Editing rule permissions


Foglight allows you to control access to rules. For each rule you can grant or deny read,
write, or control access to roles or users. For more information about security concepts
in Foglight, see Chapter 4, “Managing Users and Security” on page 197.
Foglight employs the following behavior when it comes to rule permissions:
• If no one has a permission to the rule, everyone has a permission.
• If one has a permission to the rule, others with undefined permission do not have
any permission.
• Final permission is based on a combination of the role, user, and rule defined on
the server side.
Use the Edit Permissions button ( ) on the Manage Rules dashboard to navigate to the
Edit Permissions for Rule area, that allows you to add or edit permissions to roles and
412 Foglight
Administration and Configuration Guide

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

To add permissions for 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 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

2 To add permissions to a rule, complete the following steps.


a Click the role or user to which you want to assign permissions.
Tip The Not Assigned icons in the Permissions columns indicate that the role has no
permissions assigned to it.

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

3 To edit or delete permissions for a rule, complete the following steps.


a Click the role or user whose permissions you want to edit.
Tip Three check marks in the Permissions columns indicate that the role already has
permissions assigned to it.

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

2 In the Rule Confirmation dialog box, click OK.


The Rule Confirmation dialog box closes and the Edit Rule area appears in the
Manage Rules dashboard, allowing you to edit the newly-copied rule.
Working with Foglight Rules and Registry 417
Working with Rules

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

3 If required, edit the newly-copied rule.


For more information, see “Defining Rules” on page 433.

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.

3 In the Delete Rule Confirmation dialog box, click OK.


The Delete Rule Confirmation dialog box closes.
4 Observe the Manage Registry Variables dashboard.
The newly-deleted rule no longer shows in the list.

Disabling or enabling rules


In some cases you may need to enable or disable a rule. For example, if a rule monitors
a host that needs to taken offline for system maintenance, you can disable that rule
temporarily to avoid triggering its actions while the monitored host is unavailable. Use
the Manage Rules dashboard to drill down to the rule that you want to disable or enable,
and then use the Disable Rules or Enable Rules buttons on the Manage Rules dashboard
to change the rule state.
To disable a rule:

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.

2 Click the Disable Rules button at the bottom.


The Delete Rule Confirmation dialog box appears.

3 In Delete Rule Confirmation dialog box, click OK.


The Delete Rule Confirmation dialog box closes and the Manage Rules
dashboard refreshes, showing a Rule is currently disabled icon ( ) in the row
containing the newly-disabled rule.
4 Place the mouse pointer over the Rule is currently disabled icon ( ) icon.
A tool tip appears, indicating that the rule is disabled.
To enable a rule:

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.

2 Click the Enable Rules button at the bottom.


The Delete Rule Confirmation dialog box appears.
420 Foglight
Administration and Configuration Guide

3 In Delete Rule Confirmation dialog box, click OK.


The Delete Rule Confirmation dialog box closes and the Manage Rules
dashboard refreshes, no longer showing the Rule is currently disabled icon ( ) in
the row containing the newly-enabled rule.

Suspending or resuming alarms


You can configure a rule to stop generating alarms for a specified length of time
(beginning immediately). It can be useful to suspend alarms in many situations, such as
when one or more servers are being brought offline for system maintenance.

Note Foglight stops both generating and clearing alarms for a rule during the period when its
alarms are suspended.

To suspend alarms for 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 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.

4 Place the mouse pointer over the warning icon.


A tool tip appears, indicating that alarms are currently suspended for the rule.
To resume alarms for 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 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.

Suspending or resuming actions


You can configure a rule to stop performing actions for a specified length of time
(beginning immediately). It can be useful to suspend alarms in many situations, such as
when one or more servers are being brought offline for system maintenance.
To suspend actions for 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 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.

4 Place the mouse pointer over the warning icon.


A tool tip appears, indicating that actions are currently suspended for the rule.
To resume actions for 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 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.

Viewing rule schedules


A rule can be associated with one or more schedules during which it is active (effective
schedules) or inactive (blackout schedules). Use the Schedule button on the Manage
Rules dashboard to view the schedules that are assigned to a rule or edit schedule
assignments as required.
To view a rule’s schedules:

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

2 If required, edit the rule schedules.


For more information, see “Associating Rules with Schedules” on page 500.

Viewing a rule summary


The Edit Rule view includes a summary pane that allows you to quickly review a rule’s
settings and drill down to the appropriate tab if required. The Rule Summary pane
includes the following information:
• The rule name
• The name of the cartridge the rule belongs to, if applicable
• The rule type
• The type of the rule trigger
• The rule scope, if applicable
• Whether or not the rule alarms are active
• Whether or not the rule actions are active
• Whether or not the rule is active
• The rule's alarm and action behavior
• The rule's alarm description
426 Foglight
Administration and Configuration Guide

• Conditional expressions, alarm messages, and actions for each severity level
Figure 3

To view a rule summary:

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.

3 Observe the rule summary.


The Rule Summary pane includes links to other areas in the Edit Rule view and
Manage Rules dashboard that allow you to quickly edit the rule settings if
required.
4 Move the mouse pointer over the Rule Summary pane.
Hovering over a control that allows drill-down actions shows a tooltip that
describes the nature of the drill-down action.
For example, move the mouse pointer over Rule Triggering in the Rule
Summary pane.
A tooltip appears.

5 Optional. Edit the rule settings.


For example, to edit the rule’s alarm and action behavior, in the Rule Summary
pane, click Alarm & Action Behaviors.
Working with Foglight Rules and Registry 429
Working with Rules

The Behavior tab opens in the Edit Rule view.

Viewing and editing rule settings


The Manage Rules dashboard shows all of the rules that exist in your monitoring
environment. This includes the rules that come with the Foglight Management Server,
any installed cartridges, and also any rules that you create using the Create Rule
dashboard. From here, you can drill down to view the settings for a rule, and edit them,
as required.
To view or edit rule settings:

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:

Note This procedure continues from “Logging in to Foglight” on page 22.

1 Ensure that the navigation panel is open.


To open the navigation panel, click the right-facing arrow on the left.
2 Open the Create Rule dashboard by completing one of the following steps:
• On the navigation panel, under Dashboards, choose Administration > Rules
& Notifications > Manage Rules.
Working with Foglight Rules and Registry 433
Working with Rules

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.

From here, you can proceed to “Defining Rules” on page 433.

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

topology types or objects. In addition, these values can be configured to change at


certain times.
• Metrics. A metric is a specified value that is measured over time. In Foglight,
each metric is associated with a topology type or with a specific topology object.
There are two types of metrics in Foglight:
• Raw Metrics. Raw metrics are collected by the agents directly from your
monitored environment and sent to the Foglight Management Server.
• Derived Metrics. Derived metrics are calculated from one or more (raw or
derived) metrics. They are scoped to a topology type and can optionally be
scoped to specific objects of that type. Many derived metrics will
automatically be included with Foglight and its cartridges, and additional
derived metrics can be created from the Foglight Administration Module.
Note Derived metrics are listed on the Manage Derived Metrics dashboard in the
Administration module (Data > Manage Derived Metrics). However, no distinction
is made between raw metrics and derived metrics in other locations in Foglight or
in the Foglight Administration module.

• Topology Object Properties. Topology object properties describe a topology


object. These properties are collected by Foglight from your monitored
environment, generally from the configuration data for the object.
Both simple rules and multiple-severity rules include a scope, conditions, expressions,
messages, and actions. Once you create a rule, you can assign values to it, associate
values with specific topology types or objects, or configure performance calendars for
each value.
For an example of how to define a simple rule, see “Example: Creating a Simple Data-
Driven Rule Scoped to a Topology Type that Triggers Email Actions” on page 520.
For instructions, see the following sections:
• “Getting started with rule definitions” on page 434
• “Defining rule types” on page 435
• “Triggering rules” on page 438
• “Defining the rule scope” on page 441

Getting started with rule definitions


Once you create a rule, you can add comments to it and edit its settings as required.
Working with Foglight Rules and Registry 435
Working with Rules

To get started with rule definitions:

Note This procedure continues from “Copying rules” on page 415, “Viewing and editing rule
settings” on page 429, or “Creating Rules” on page 432.

1 Provide a descriptive name for the rule.


In the Rule Definition tab, in the Rule Name box, type the rule name.
Important. The following rule names are reserved and should not be used:
• foglight_rule_name
• foglight_rule_comments
• foglight_rule_domain_query
• foglight_rule_id
• foglight_monitored_host_name
• foglight_monitoring_agent_name
• foglight_rule_alarm_link
• foglight_scoping_id
Note The foglight_monitored_host_name and
foglight_monitoring_agent_name variables are only available for rules
with scoping queries.

2 Optional. Describe the rule.


In the Description/Comments box, type the rule description.
3 Optional. Add information about the nature of the alert message.
In the Alarm/Description box, type the information about the alert that is
generated by the rule.
From here, you can proceed to “Defining rule types” on page 435.

Defining rule types


There are two types of rules in Foglight. Each rule type of is associated with a topology
type and can be scoped to one or more specific topology objects. Those types are:
• Simple rules. A simple rule has a single condition, and can be in one of three
states:
• Fire
• Undefined
• Normal
436 Foglight
Administration and Configuration Guide

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.

• Select the rule type.


In the Rule Definition tab, select one of the following Rule Type options:
• Simple Rule
• Multiple-Severity Rule
From here, you can proceed to “Triggering rules” on page 438.

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

• Data-Driven Trigger. If a rule has a data-driven trigger, one or more if its


conditions will be evaluated every time that new data associated with one or more
topology types or objects to which the rule applies is sent to the Foglight
Management Server. This option is selected as the default trigger.
• Time-Driven Trigger. A time-driven trigger causes one or more of a rule’s
conditions to be evaluated once per pre-defined interval. By default time-driven
rules are only evaluated if data for the evaluation of the condition is available.
For details on how to write conditions for data-driven and event-driven rules, see
“Defining conditions for data-driven and time-driven rules” on page 451.
• Event- Driven Trigger. An event-driven trigger causes one or more of a rule’s
conditions to be evaluated as a response to a certain event. There are two types of
events that can act as rule triggers:
• AlarmSystemEvent. Multiple-severity rules generate system events when a
rule severity level is reached. Alarm-based system events allow you to monitor
alarm-related system events. This type of events can be useful, for example,
when forwarding alarms to an external system or when sending notifications.
• ReportGeneratedEvent. Report generation creates events. You can monitor
those events as required and use them to trigger report-related events.
For details on how to write conditions for event-driven rules, see “Defining
conditions for event-driven rules” on page 455.

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.

To assign a time-driven trigger:

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.

To assign a data -driven trigger:

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.

To assign an event-driven trigger:

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

Click Event Name and select one of the following events:


• AlarmSystemEvent
• ReportGeneratedEvent
Note For details on how to write conditions for event-driven rules, see “Defining conditions
for event-driven rules” on page 455.

From here, you can proceed to “Defining the rule scope” on page 441.

Defining the rule scope


The scope of a rule defines the set of topology objects against which it runs. A rule must
be scoped to a topology type and can optionally be scoped to specific topology objects
of that type. If a rule is not scoped to specific objects, it applies to all instances of that
type. The scope object is the object on which alarms will appear in the Foglight
interface. The rule scope is specified using the query language.
A rule can apply to a topology type or to one or more objects of that type. You can
change the scope of a rule (the topology type or specific topology object(s) to which it
applies) after its creation.
For detail information on how to scope a rule or derived metric to one or more topology
objects, see “Using the Query Language” on page 763.

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).

To get started with specifying a rule scope:

Note This procedure continues from “Triggering rules” on page 438.

• 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

Defining Conditions, Alarms, and Actions


Simple rules have a single condition only, and can be in one of three states: Fire,
Undefined, or Normal. If the 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. The condition for
a simple rule is regularly evaluated against monitoring data. Therefore, the state of the
rule can change if the data changes.
Multiple-severity rules can have up to five severity levels: Undefined, Fatal, Critical,
Warning, or Normal. When you create a multiple-severity rule, you must specify a
condition for one or more of the following severity levels Fatal, Critical, or Warning.
When you edit multiple-severity rules, you write a condition for each specified severity
level.
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.
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.
For complete information about simple and multiple-severity rules, see “Defining rule
types” on page 435.
Working with Foglight Rules and Registry 443
Working with Rules

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

• “Copying severity-level variables and actions in multiple-severity rules” on


page 498

Adding severity-level variables


Each severity-level can have its own set of variables that you can use in alarm messages.
Unlike registry variable that are global in nature, severity-level variables are only
accessible to the severity level in which you define them. There are two types of
severity-level variables:
• Expressions. An expression is used to retrieve data. It can contain a registry
variable or a function.
• Messages. A message is typically a text string that can include other severity-
level variables, displaying dynamically-supplied data about your monitored
system.
For example:

Severity-Level Variables

Name Value Type

var1 scope.get("agent/host/name") Expression

var2 #CPU_Utilization# Expression

var3 #Run_Queue_Length# Expression

Text @var1: CPU Utilization Message

Subject CPU Utilization is at @var2% and the Message


number of process in the run queue is
@var3. A CPU Bottleneck is being detected
on @var1. Check the top processes (using
the Top_CPU_Table) to determine which
processes are the greatest contributors to
CPU Loads, or follow the Foglight online
help to find out if the system is CPU
constrained. Please use the following URL
to obtain alarm details.
@foglight_rule_alarm_link
Working with Foglight Rules and Registry 445
Working with Rules

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.

1 Open the Conditions, Alarms, and Actions tab (multiple-severity rules) or


Conditions and Actions tab (simple rules).
If you are defining a simple rule, the Conditions & Actions tab opens.

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

3 Open the Severity Level Variables tab.


The Severity Level Variables tab appears in the severity-level definition pane.
448 Foglight
Administration and Configuration Guide

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

Name Value Type

var1 scope.get("agent/host/name") Expression

Text @var1: CPU Utilization Message


Working with Foglight Rules and Registry 449
Working with Rules

In the Expression/Message box, type the value of the variable.


7 Click Add.
The Severity Level Variables pane refreshes, showing the newly-added variable.

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.

For information on how to write conditions, see the following sections:


• “Expression scope” on page 450
• “Copying conditions in multiple-severity rules” on page 464
• “Defining conditions for data-driven and time-driven rules” on page 451
• “Defining conditions for event-driven rules” on page 455

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.

• Severity-scoped expressions and messages. They can only be referenced by the


actions set for the specific rule level at which the message is defined. For
Working with Foglight Rules and Registry 451
Working with Rules

example, if an expression is defined for the Fatal level of a multiple-severity rule,


it can only be referenced by the actions that are set for that severity level.

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.

Defining conditions for data-driven and time-driven rules


When you write conditions for data-driven or time-driven rules, you can make use of
variables, topology object metrics, and Groovy functions.
To define a condition for a data-driven or time-driven rule:

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.

2 Write the conditional expression.


Working with Foglight Rules and Registry 453
Working with Rules

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()

Note Using a semicolon to end the line in a single-line expression is optional,


therefore both expressions are valid.

3 Multiple-severity rules. Activate the condition by selecting the Activate check


box.
You must activate the condition for a severity level in a multiple-severity rule
before you can save it. If the Activate check box is cleared when you click Save,
the condition that you specified will be discarded, as will any expressions or
actions that you set in the sub-tabs of the tab for that severity level.
Caution Do not clear the Activate check box if you want to temporarily disable a rule. To
temporarily deactivate the alarms and actions for an entire rule, follow the
instructions in “Suspending or resuming alarms” on page 420. You can also
configure the behavior of the alarms and actions for the rule. See “Defining Alarm
and Action Behavior” on page 503 for more information.

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.

Defining conditions for event-driven rules


When you write conditions for event-driven rules, in addition to variables, topology
object metrics, and Groovy functions, you can use events and their properties to trigger
rule actions.
Event-driven rules allow you to monitor the events generated every time a pre-defined
event occurs. There are two types of events that can act as rule triggers:
• AlarmSystemEvent
Multiple-severity rules generate system events when a rule severity level is
reached. Alarm-based system events allow you to monitor alarm-related system
456 Foglight
Administration and Configuration Guide

events and use the following properties in rule conditions in order to trigger
event-driven rules:

Property Data Type Description

alarmID String Contains the ID of the alarm


that generates the event.

alarmLink String Contains the URL to the


alarm.

clearedTime Date Specifies the time at which


the alarm is cleared.

change AlarmChangeType Specifies the alarm change


type: Fire, Clear, or
Acknowledge.

createdTime Date Specifies the time at which


the alarm is created.

isAcknowledged Boolean Determines if the event is


acknowledged. It can be set
to True or False.

isCleared Boolean Determines if the event is


cleared. It can be set to
True or False.

message String Contains the alarm


message.

ruleComments String Contains any comments


associated with the rule that
generates the alarm.

ruleID String Contains the ID of the rule


that generates the alarm.
Working with Foglight Rules and Registry 457
Working with Rules

Property Data Type Description

ruleName String Contains the name of the


rule that generates the
alarm.

severityLevel Integer Contains a number that


identifies the severity level:
• 0: Undefined
• 1: Normal
• 2: Warning
• 3: Critical
• 4: Fatal

severityName String Contains one of the


following values that
identify the severity level:
Undefined, Normal,
Warning, Critical, or
Fatal.

sourceID String Contains the ID of the


source data object that
generates the event.

sourceName String Contains the name of the


source data object that
generates the event.

userDefinedData DataObject Contains a data object that


includes any additional
information about the
alarm. This data can be used
when creating event-related
dashboards. For more
information about creating
dashboards, see the
Foglight User Guide.

• 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:

Property Data Type Description

createdTime Date Specifies the time at which the event is


created.

report Report Contains an object of the Report type.


For complete information about creating and
scheduling reports in Foglight, see the
Foglight User Guide.

In addition to the ReportGeneratedEvent object properties you can reference


the Report object properties when writing rule conditions for a rule triggered by
a report generation event. The following table lists the Report object properties,
their data types, and descriptions.

Property Data Type Description

dateRun Date The date on which the report is run.

emailRecipients String The email recipients to which the


report is to be sent.

errorMessage String An error message associated with the


report.

isEnabled Boolean Specifies whether the report


generation is enabled.

name String The report name.

numResultsRetained Integer The number of records in that are


retained in the report.

reportId String The report ID.


Working with Foglight Rules and Registry 459
Working with Rules

Property Data Type Description

scheduleId String The ID of the schedule that is


associated with the report.

scheduleName String The name of the schedule that is


associated with the report.

size Integer The report size in bytes.

templateId String The ID of the template used to create


the report.

templateName String The name of the template used to


create the report.

user String The name of the Foglight user who


created the report.

To define a condition for an event-driven rule:

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.

2 Write the conditional expression.


Working with Foglight Rules and Registry 461
Working with Rules

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()

Note Using a semicolon to end the line in a single-line expression is optional,


therefore both expressions are valid.

3 Multiple-severity rules. Activate the condition by selecting the Activate check


box.
You must activate the condition for a severity level in a multiple-severity rule
before you can save it. If the Activate check box is cleared when you click Save,
the condition that you specified will be discarded, as will any expressions or
actions that you set in the sub-tabs of the tab for that severity level.
Caution Do not clear the Activate check box if you want to temporarily disable a multiple-
severity rule. To temporarily deactivate the alarms and actions for an entire rule,
follow the instructions in “Suspending or resuming alarms” on page 420. You can
also configure the behavior of the alarms and actions for the rule. See “Defining
Alarm and Action Behavior” on page 503 for more information.

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

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.

• 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

Copying conditions in multiple-severity rules


In some cases you may need to copy the conditions from an existing severity level of the
same rule. A condition is comprised of a conditional expression and an alarm message,
both of which are copied when required. For more information about conditional
expressions and alarm messages, see “Writing conditions” on page 449.
Copying a condition can be useful in situations when the conditional expressions of
different severities are similar, so instead of writing and validating them for each
severity level you can copy an existing expression and modify it as required.
While you are in the edit rule mode, any unsaved changes to the conditional expressions
or alarm messages that you want to copy will be carried over to the destination
condition. For example, if you edit a conditional expression for the Warning condition
of a rule without saving it, and then proceed to copy that condition in the Critical pane,
the unsaved edits of the Warning condition will be carried over to the Critical condition.
To copy a condition from an existing severity level:

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

a Click the Copy condition/alarm button above the Condition tab.


A list appears, showing those severity levels for which the conditions have
been defined. For example, if you are defining a condition for the Critical
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.

b Select the severity level whose condition you want to copy.


The Condition tab refreshes, showing the newly copied conditional expression
and alarm message in the Condition and Alarm Message boxes.

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 action types


There are two types of actions in Foglight:
• Entering. It causes the action to be performed when a simple rule or a severity
level in a multiple-severity rule enters the state in which the condition for that rule
or severity level is met.
It is a best practice that Entering actions be used by default.
• Exiting. It causes the action to be performed when a simple rule or a severity level
in a multiple-severity rule exits the state in which the condition for that rule or
severity level is met.
Use of the Exiting action should be restricted to cases where an action specific to
the state is needed. For example, if an Entering action starts a script, then the
Exiting action may stop the script.

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

• Email Actions. They cause email messages to be sent to a specified recipient


when the rule fires. For more information about viewing the settings related to
email actions and configuring email actions in Foglight, see “Viewing and
configuring email settings” on page 467.
• Command Actions. They cause an external action to be executed on the machine
hosting the Foglight Management Server. For example, a command action may
run the executable that starts a service. Various parameters can be set for this
action. The mandatory parameter is COMMAND_LINE which is the executable
command and one or more arguments. Optionally, you can also set OS
environment variables (separated by an exclamation mark).
• Remote Command Actions. They cause an external action to be executed on a
remote platform. Various parameters can be set for this action including a
mandatory parameter is COMMAND_LINE.
• Script Actions. They cause an arbitrary script to be run when the rule fires. This is
to be used for any integration not available through built-in actions. Various
parameters can be set for this action, such as script name (mandatory), scoping
topology ID, scripting object ID, and arguments associated with the script. The
ten arguments (0-9) must be mapped directly to the script, and it is the
responsibility of the rule creator to assure the parameters match the script in
number and type. There is currently no validation facility for script actions.
For a list of parameters that are supported in each action type, refer to “About action
parameters” on page 488.
Viewing and configuring email settings
Foglight uses email actions to send reports to email recipients or email alarm-related
messages to Foglight administrators when certain thresholds are reached. When you add
a scheduled report and specify its email recipients using the Report Manager dashboard,
Foglight uses the default mail parameters, set by the Foglight registry with the mail.
prefix, to send the report to the specified recipients at a rate set in the associated
schedule. For complete information about creating reports and the Report Manager
dashboard, see the Foglight User Guide.

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.

1 On the Manage Registry Variables dashboard, locate the following variables:


mail.from, mail.host, mail.password, mail.port, mail.receipient,
mail.transport.protocol, and mail.user.
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 mail.
The Manage Registry Variables dashboard refreshes, showing only the registry
variables that start with the mail prefix.
472 Foglight
Administration and Configuration Guide

2 Set the global default values of the following mail. variables:


• mail.from: The default email address used by the Foglight Management
Server from which emails are sent.
• mail.host: The default email host used by the Foglight Management Server
from which emails are sent.
• mail.password: The default password for logging into the email server.
• mail.port: The default port number of the email server used by the Foglight
Management Server from which emails are sent.
• mail.receipient: The default email address used by the Foglight Management
Server to which emails are sent.
• mail.transport.protocol: The default mail transport protocol (for example,
SMTP, POP3, IMAP4, or others).
• mail.user: The default user name that the Foglight Management Server uses
for logging into the email server.
To set the global value of a registry variable, complete the following steps:
a On the Manage Registry Variables dashboard, click the Variable Name
column of the registry variable whose global default value you want to edit.
For example, to edit the value of the mail.host variable, click mail.host.
The Edit Registry Variable view appears in the Manage Registry Variables
dashboard, showing the settings of the mail.host variable.
Working with Foglight Rules and Registry 473
Working with Rules

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.

c Return to the list of registry variables in the Manage Registry Variables


dashboard by clicking the Go to Registry Variable List button at the bottom.
474 Foglight
Administration and Configuration Guide

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

d Edit the newly-created registry variable.


In the Step 2: Registry Variable Added view, click Edit Registry Variable.
The Create Registry Variable dashboard refreshes, showing the Edit Registry
Variable view.
Working with Foglight Rules and Registry 477
Working with Rules

e Specify the length of the time-out.


In the Edit Registry Variable view, in the Global Default area, ensure that
the Static Value option is selected and type the number of seconds in the box.
f Save your changes.
On the right of the Global Default area, click Save.
A message appears in the upper-left corner, indicating success.

g Return to the list of registry variables in the Manage Registry Variables


dashboard by clicking the Go to Registry Variable List button at the bottom.
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.

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 example: http://MyHost.MyDomain.com:8080/

Configuring SNMP trap actions

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

In Foglight, Simple Network Management Protocol (SNMP) trap actions can be


configured to forward alarms to an SNMP trap receiver. Trap definitions are specified in
a Management Information Base (MIB) file. MIB files contain data structures that
define the types of events that are being monitored and controlled.
Configuring SNMP trap actions assumes that you plan on sending SNMP traps from
your monitoring environment to an external SNMP trap receiver. The process of
forwarding SNMP traps is triggered by rules. This means that a rule that has an SNMP
trap action assigned to it can cause Foglight to send an SNMP trap to a trap receiver
when the rule’s condition is met.
There are several ways that you can use to configure SNMP trap actions. The simplest
and probably most convenient way is to edit the SNMP Forward rule that is included
with a core installation of Foglight.
This rule relies on the definitions of the MIB file, quest-foglight.mib. Both the
SNMP Forward rule and the quest-foglight.mib file are delivered with the
SNMPTrapAction cartridge, deployed at the Foglight Management Server startup.
Working with Foglight Rules and Registry 479
Working with Rules

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

To configure SNMP trap actions using the SNMP Forward rule:

Note This procedure continues from “Accessing the Manage Rules dashboard” on page 408.

1 On the Manage Rules dashboard, locate the SNMP Forward rule.


Tip You can filter the list of rules using filters. At the top of the Manage Rules dashboard, in
the Filter By Rule Name box, type SNMP Forward.
The Manage Rules dashboard refreshes, showing the SNMP Forward rule in the list.

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.

2 Start editing the SNMP Forward rule.


On the Manage Rules dashboard, in the Rule Name column, click SNMP
Forward.
The Manage Rules dashboard refreshes, showing the Edit Rule view with the
Conditions and Actions tab open.
482 Foglight
Administration and Configuration Guide

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.

4 View the action settings of the SNMP Forward rule.


In the Fire pane, open the Action tab.
Working with Foglight Rules and Registry 483
Working with Rules

The Action tab opens, showing an entering SNMP trap action in the Actions
table.

5 View the SNMP trap action parameters.


In the Action tab, in the Actions table, click the SnmpTrapAction entry.
The Action tab refreshes, showing a list of the SNMP trap action parameters in
the Action Parameters table.

6 Edit the CommunityString and TargetAddress parameters of the SNMP trap


action.
484 Foglight
Administration and Configuration Guide

• Set the CommunityString parameter to contain your SNMP community


string of the trap receiver. This test string acts as a password used to
authenticate messages. For more information, refer to your SNMP
documentation.
• Set the TargetAddress parameter to the IP address of the trap receiving
computer.
7 To edit the value of each of the above action parameters, complete the following
steps.
a In the Action Parameters table, click the Value column of the parameter that
you want to edit.
For example, to edit the CommunityString or TargetAddress parameters,
in the row containing those entries, click its Value column (initially set to
Default and localhost, respectively).

The Action Parameter Editor dialog box appears.


Working with Foglight Rules and Registry 485
Working with Rules

The Action Parameter Editor allows you to reference registry or rule-level


variables (Variable tab) or to specify a literal string (User Defined tab). The
target address of the SNMP receiver and the SNMP community string are not
referenced in any system or rule-level variables and do not change over time
and are therefore specified as literal text string in the User Defined tab of the
Action Parameter Editor dialog box.
b Open the User Defined tab and type the SNMP community string
(CommunityString parameter) or the SNMP trap receiver IP address
(TargetAddress parameter), followed by clicking Change in the dialog box.
486 Foglight
Administration and Configuration Guide

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.

8 Save the changes to the SNMP Forward rule.


In the Edit Rule view, in the lower-left corner of the Condition and Actions tab,
click Save All.
The Condition and Actions pane refreshes, showing a success message in the
upper-left corner.

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.

Adding actions to rules


An action is a particular operation that is performed when a rule enters and/or exits a
state (for example, when a rule condition is met). You can associate multiple actions can
be with simple rules as well as with each severity level in a multiple-severity rule. You
can add actions to a rule after it is created.
Working with Foglight Rules and Registry 487
Working with Rules

To add an action to a rule:

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.

About action parameters


Each rule action has a set of parameters associated with it. Some action parameters are
mandatory while others are optional. When you add an action to a rule, you must
configure the action’s mandatory parameters in order for it to be executed when the rule
reaches the severity level for which the action is defined.
When specifying an action parameter you can make use of Foglight registry variables,
rule-level variables, or specify a custom value. The data type of the specified value must
match the action parameter’s data type.

Note To successfully configure an action, you must ensure that all of the actions’s mandatory
parameters are specified.

The following table lists rule actions and their parameters.

Parameter Required? Description

BSM Actions

Alarm system event Yes Alarm system event generated


by Foglight.

BSM URL Yes URL of the BSM system to


which to post the data.

Event Attributes No Optional event attributes to


pass to BSM.

Managed Control Attributes No Optional component attributes


to pass to BSM.

Technology Level Agreement No Optional Technology Level


Attributes Agreement attributes to pass to
BSM.

Command Actions
Working with Foglight Rules and Registry 489
Working with Rules

Parameter Required? Description

COMMAND_LINE Yes The command that you want to


run on the command line along
with its options and arguments
if applicable.
Note If the command is not
accessible from the
<foglight_home> directory,
you need to specify its path.

ENVIRONMENT_VARIABLES No A list of environment variables


separated by exclamation
marks ‘!’.

Email Actions

mail.attachement No Email attachment.

mail.attachement.file.name Yes The file name of the email


attachment.

mail.attachement.mime.type Yes The attachment’s MIME type.

mail.bcc No Blind CC list. Uses a comma as


a separator.

mail.cc No Mail CC list. Uses a comma as


a separator.

mail.content.type Yes Can be set to text/plain or


text/html.

mail.message No Message body.


490 Foglight
Administration and Configuration Guide

Parameter Required? Description

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:

The following alarms have been raised. Please use the


provided URLs to obtain alarm details.

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.

mail.recipient Yes Recipient's email address. It


overrides the value set by the
global mail.recipient
registry variable. For more
information about this variable,
see “Viewing and configuring
email settings” on page 467.

mail.subject No Mail subject line

Remote Command Actions

COMMAND_LINE Yes The command that you want to


run remotely along with its
options and arguments if
applicable.

ENVIRONMENT_VARIABLES No A list of environment variables


separated by exclamation
marks ‘!’.

HostName Yes The name of the host computer


on which the command is to be
executed.
Working with Foglight Rules and Registry 491
Working with Rules

Parameter Required? Description

MatchAll No A flag indicating whether to


run the command on all hosts
that match the selection
criteria. The false default runs
the command on the first
matching host only.

PlatformInfo No The target platform


specification.

RemoteInstallationId No Target installation ID. This


information is useful if there
are multiple remote agents that
support remote command
execution.

RemoteWorkingDir No Working directory on the


remote machine.

UseRegExp No Indicates whether the values


specified by the HostName,
PlatformInfo, and
RemoteInstallationId
parameters are regular
expressions.

Script Actions

Argument 1-10 No Parameters to pass to the script.

Scoping object id No The ID of the scoping object.

Script name Yes The name of the script.


Caution The rule runs the script
from the
<foglight_home>/scripts
directory. If you place
your script elsewhere in
the file system, include
the script path.
492 Foglight
Administration and Configuration Guide

Parameter Required? Description

SNMP Trap Actions

CommunityString Yes SNMP community string.

EnterpriseOID Yes The enterprise object ID


defined in the MIB file.

HostName No The name of the host computer


that is being monitored.

Severity No If the SNMP trap action is


event-driven, this parameter
can be set to the severity level
that causes the event to be
generated.

TargetAddress Yes The target address of the trap


receiver.

TargetPort Yes The target port of the trap


receiver.

VarBindnOID No The object ID of the trap


variable defined in the MIB
file, where n can be a value
between 00 and 19.

VarBindnValue No The value of the trap variable


defined in the MIB file, where
n can be a value between 00
and 19.

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.

About rule system variables


There are trigger-specific rule variables that can be used in conditional expressions of
rules with certain trigger types. Each variable contains the information relative to the
rule in which it is used. For example, if you create Rule A and use the rule-level variable
foglight_rule_name as a parameter in an action that you add to Rule A, that
parameter uses the actual rule name, Rule A.
Rules in Foglight can be triggered by data, time, or events. Different trigger types, such
as time, data, and event triggers, have different rule-level variables available to them.
For example, in an event-driven rule you can reference the properties of the system
alarm event that triggers the rule directly.
The following table lists all of the rule-level variables and indicates their availability in
different trigger types.

Variable Description Trigger Type

Event Data Time

event System event Yes No No

event_foglight_rule_alarm_link Link for the alarm Yes No No


causing the event

event_foglight_rule_comments The comments for Yes No No


the rule causing the
event

event_foglight_rule_id The ID of the rule Yes No No


causing the event

event_foglight_rule_name The name of the rule Yes No No


causing the event
Working with Foglight Rules and Registry 495
Working with Rules

Variable Description Trigger Type

Event Data Time

event_foglight_severity_level The severity level Yes No No


(0-4) causing the
event

event_foglight_severity_level_name Name of the severity Yes No No


level causing the
event

event_scope Event scope Yes No No

foglight_rule_alarm_link Link for the alarm Yes Yes Yes

foglight_rule_comments Comments for the Yes Yes Yes


rule

foglight_rule_domain_query Rule domain query Yes Yes Yes

foglight_rule_id Rule ID Yes Yes Yes

foglight_rule_name Rule name Yes Yes Yes

foglight_scoping_id ID of the topology Yes Yes Yes


object

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.

Editing action parameters


To edit an action parameter:

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.

• Set the parameter to a Foglight registry variable.


In the Variable tab, in the Registry Variables table, select the row containing
the Foglight registry variable to which you want to set the parameter.
• Set the parameter to a rule system variable.
498 Foglight
Administration and Configuration Guide

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.

Copying severity-level variables and actions in multiple-severity rules


In some cases you may need to copy the severity-level variables and actions from an
existing severity level of the same rule. Each severity level can have its own actions and
severity-level variables. For more information about severity-level actions and
Working with Foglight Rules and Registry 499
Working with Rules

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.

a Click the Copy variables/actions button above the Condition tab.


A list appears, showing those severity levels for which the conditions have
been defined. For example, if you are defining a condition for the Critical
500 Foglight
Administration and Configuration Guide

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.

b Select the severity level whose condition you want to copy.


The Condition tab refreshes.
3 Verify the settings of the newly-copied severity-level variables and actions in the
Severity Level Variables and Action tabs.
4 Optional. Edit the newly-copied severity-level variables and actions, if required.
For instructions, see one of the following sections:
• “Adding severity-level variables” on page 444
• “Defining actions” on page 466
5 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.

Associating Rules with Schedules


Once you have defined one or more conditions for a rule, you can associate the rule with
a schedule either as an effective period or as a blackout period.
An effective period is a schedule during which you want a rule to be evaluated. For
example, you might want to set your company’s hours of operation as the effective
period for a rule.
You can also set blackout periods for a rule. A blackout is a schedule during which
evaluation of the rule is suspended for set intervals. For example, you might want to set
the times when regularly scheduled maintenance is performed on a server as the
blackout period for a rule.
If a rule has no schedules associated with it, then it is always active. If you only add
effective schedules to a rule, then it is automatically inactive at all times other than those
specified by the effective schedules. Conversely, if you only add blackout schedules to a
Working with Foglight Rules and Registry 501
Working with Rules

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.

1 Open the Schedules tab.


The Schedules tab opens in the display area.

2 Assign effective schedules.


a In the list that appears in the upper-left corner, select one or more schedules
that you want to assign as effective schedules.
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.
b Click Add on the right of the list.
502 Foglight
Administration and Configuration Guide

The Effective Schedules list on the right refreshes, showing the newly-added
schedules.

3 Assign blackout schedules.


a In the list that appears in the lower-left corner, select one or more schedules
that you want to assign as blackout schedules.
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.

b Click Add on the right of the list.


The Blackout 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.

Defining Alarm and Action Behavior


Foglight allows you to configure a rule so that its actions and alarms (multiple-severity
rules only) do not fire repeatedly. Defining the behavior of rule alarms and actions can
help you avoid being overwhelmed with alerts when a rule condition is met many times
within a short period.
To define alarm and action behavior:

Note This procedure continues from “Associating Rules with Schedules” on page 500.

1 Open the Behavior tab.


The Behavior tab opens in the display area.

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

Sometimes, observations are high-strung, causing a single match in the


evaluation to lead to more actions than desired. With this option it is possible
to enforce a certain number of positive evaluations before a rule finally fires.
Setting this option to x causes the rule’s actions (simple and multiple-severity
rules) and alarms (multiple-severity rules only) to execute when the number of
evaluations defined by x are true.
Example: A rule that checks the current CPU utilization is evaluated every 5
minutes. To avoid having short spikes leading to a firing rule, you can
configure a damper mechanism to prevent actions and alarms from occurring
until a certain number of matches is reached, such as, for example, three
consecutive evaluations. That means that three times in 15 minutes (because
the rule is evaluated every five minutes) the evaluation has to resolve to true
before the rule fires.
• Fire actions if x out of y evaluations are true
Similar to the above setting, this option allows to enforce a pattern of the
evaluation behavior. When the frequency of positive evaluations matters less
than their reoccurrence, this option allows for a less strict damper mechanism.
Setting this option to x out of y causes the rule’s actions (simple and multiple-
severity rules) and alarms (multiple-severity rules only) to execute after x out
of y evaluations are true.
Example: A fixed number of positive evaluations in a row is not missing
positives matches, however their pattern of 2-0-2-1-0-2 consecutive positive
evaluations is not identified. Setting this option to 4 out of 8 allows for
identification of a problem across multiple evaluations while not relying on
them being consecutive.
• Wait at least [hh:mm:ss] hh:mm:ss after first evaluation:
Sometimes when evaluations are performed immediately after a topology
object creation, or the Foglight Management Server re-start, a number of false
positives can occur. There might be a startup-time factor or the monitored
entity simply needs to calm down for a minute or two, before reliable analysis
can be performed. This option specifies that the first evaluation and all
evaluations in the given time frame afterwards are ignored before evaluation
results are considered.
Setting this option causes the rule’s actions (simple and multiple-severity
rules) and alarms (multiple-severity rules only) to execute after the specified
period.
Working with Foglight Rules and Registry 505
Working with Rules

Example: When a new host becomes available online, a high network


utilization is expected, while updates are downloaded or application
synchronization commences. To avoid having newly-discovered hosts
generate alarms on their bandwidth usage, you can specify a time window, for
example, 15 minutes, during which the rule evaluating the network conditions
is on hold.
If multiple options are selected, the actions associated with the rule execute if all
of the selected options are true. For example:

Rule Selected alarm and action behavior options Behavior Rule


condition condition fires?
met at: met?

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.

Defining Rule-Level Variables


In addition to Foglight registry variables and severity-level variables, you can define
rule-level variables. If you are creating or editing a multiple-severity rule, you can
define a rule level variable and reference it in expressions of different severities in the
rule definition.
There are two types of rule-level variables:
506 Foglight
Administration and Configuration Guide

• Expressions. An expression is used to retrieve data. It can contain a registry


variable or a function.
• Messages. A message is typically a text string that can include other severity-
level variables, displaying dynamically-supplied data about your monitored
system.
For example:

Severity-Level Variables

Name Value Type

var1 scope.get("agent/host/name") Expression

var2 #CPU_Utilization# Expression

var3 #Run_Queue_Length# Expression

Text @var1: CPU Utilization Message

Subject CPU Utilization is at @var2% and the number Message


of process in the run queue is @var3. A CPU
Bottleneck is being detected on @var1.
Check the top processes (using the
Top_CPU_Table) to determine which processes
are the greatest contributors to CPU Loads,
or follow the Foglight online help to find
out if the system is CPU constrained.
Please use the following URL to obtain
alarm details. @foglight_rule_alarm_link

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.

1 Open the Rule Variables tab.


The Rule Variables tab opens in the display area.
Working with Foglight Rules and Registry 507
Working with Rules

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.

4 Specify the variable value.


Expressions can contain registry variables or functions while messages are text
strings that can make use of the existing severity-level variables.
For example:

Severity-Level Variables

Name Value Type

var1 scope.get("agent/host/name") Expression

Text @var1: CPU Utilization Message


508 Foglight
Administration and Configuration Guide

In the Expression/Message box, type the value of the variable.


5 Click Add.
The Rule Variables pane refreshes, showing the newly-added variable.

To delete a rule-level variable from the list, select the row containing that variable
in the Rule Variables pane, and click Delete Selected.

Rules Included with the Foglight Management Server


Foglight allows you to create flexible rules that can be applied to complex, interrelated
data from multiple sources within your distributed system. You can associate several
different actions with a rule, configure a rule so that it does not fire repeatedly, and
associate a rule with schedules to define when it should and should not be evaluated.
Different types of data can be used in rules, including registry variables, raw metrics,
derived metrics, and topology object properties.
There are two types of rules in Foglight: simple rules and multiple-severity rules. A
simple rule has a single condition, and can be in one of three states: Fire, Undefined, or
Normal. A multiple-severity rule can have up to five severity levels: Undefined, Fatal,
Critical, Warning, and Normal.
Rule conditions are regularly evaluated against monitoring data (metrics and topology
object properties collected from your monitored environment and transformed into a
standard format). 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.
Working with Foglight Rules and Registry 509
Working with Rules

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

Agent Health State 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

An agent’s health is in decline Warning

An agent is down Critical

BSM All Events rule

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

Catalyst Data Service Discarding Data rule

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

The Data Service discards one or more observations within a 15 Warning


minute interval

Catalyst Database Space Checking rule

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

Catalyst Free Space Checking for Oracle Tablespaces rule

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

Clear Old LogFilter Alarms rule

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

Email Reports Sample rule

Purpose
This rule directs all scheduled reports to their email recipients. A scheduled report can
have one or more email recipients.

Scope
None

Foglight Agent Type License Checker rule

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.

Foglight Garbage Collector rule

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

Foglight Memory Usage Check rule

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

The amount of memory that is available to the Foglight Management Critical


Server exceeds 95% of the total memory usage.

Foglight Topology Size Limit Reached rule

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.

Idle Agents rule

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

Remote Agent Manager State per Host rule

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

No instance of the Foglight Agent Manager on a monitored host. Warning

ServiceLevelEvaluation – FMSServiceSLP rule

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

An average availability during one hour period is below 95%. Warning

An average availability during one hour period is below 85%. Critical

An average availability during one hour period is below 70%. Fatal


518 Foglight
Administration and Configuration Guide

SNMP Forward rule

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

Example: Creating a Multiple-Severity Rule Scoped to an EJB


Instance
This section provides an example of a multiple-severity rule and describes the process
of creating it.
There is a specific EJB instance (called EJB_Instance1) in the application
MyApplication that you want to monitor; you would like to be alerted when the number
of rollbacks per minute exceeds a certain threshold.
To configure Foglight to monitor EJB_Instance1, you launch the Foglight
Administration Module and create a multiple-severity rule that is scoped to this specific
topology object and that has conditions set for the Fatal, Critical, and Warning levels.

Launching the Create Rule dashboard


To begin the process of creating the rule, in Foglight, in the Administration module,
open the Create Rule dashboard by choosing Rules & Notifications > Create Rule
from the navigation panel.

Setting basic rule properties


In the Rule Definition area of the Create Rule dashboard, you name the rule
EJB_Instance1-Rollbacks and add comments about the purpose of this rule. You
select Multiple-Severity Rule as the Rule Type. Since you want this rule to be
evaluated every time that metrics associated with EJB_Instance1 are sent to the
Working with Foglight Rules and Registry 519
Working with Rules

Foglight Management Server, you leave the Trigger Type at its default setting, Data
Driven.

Scoping the rule


Having set the basic rule properties, you scope the rule to the specific topology object
that you want to monitor. First, you select WebLogicEJBInstance from the Topology
Type box and then click the Append button ( ) to the right of the menu to insert the
name of this topology type into the Rule Scope box. After inserting the name of the
topology type, you must manually type a space in the Rule Scope box, followed by the
word where, followed by another space. Next, you specify the EJB instance and
application in this box using the query language.
Since you want this rule to apply to a specific EJB instance (EJB_Instance1), you
specify it by name in the Rule Scope box. To do so, you select the topology type
property name from the Property drop-down menu. You then place the cursor in the
Rule Scope box where you want your selection to be inserted and click the Append
button ( ) to the right of the Property menu. After inserting the property name, you
manually specify the value for the property as follows:
name=”EJB_Instance1”
You want to specify another property after the instance name, so you manually type a
space in the Rule Scope box, followed by the word and, followed by another space
after name=”EJB_Instance1”.
You then specify the application name in the Rule Scope box using the following
syntax:
ejb.application.name=”MyApplication”
When you finish editing the information in this box, the rule scope is specified as
follows:
WebLogicEJBInstance where name=”EJB_Instance1” and
ejb.application.name=”MyApplication”

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.

Example: Creating a Simple Data-Driven Rule Scoped to a


Topology Type that Triggers Email Actions
In this example, you create a simple, data-driven rule that sends emails to the Foglight
System Administrator when its condition is met. The rule is scoped to the JVM topology
type and it monitors its threadCount metric property. Its condition,
#threadCount#>10, implies that the rule enters the Fire state when any instance of the
JVM topology type has a thread count that is greater than ten. The number of threads in a
typical environment exceeds this number, resulting in a frequent execution of email
actions. The rule includes two severity variables:
• ThreadsNum, an expression containing the metric #threadCount#, the same
metric that is used in the condition
• ProblemSynopsis, a message that references the ThreadsNum expression, and
is set to Threads started count is too high: @ThreadsNum
An entering email action is assigned to this rule. The email action uses the
ProblemSynopsis message as the text of the email that is sent to the Foglight System
Working with Foglight Rules and Registry 521
Working with Rules

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.

The Foglight login page appears in the Web browser.

b Log into Foglight.


522 Foglight
Administration and Configuration Guide

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 editing email parameters, see Chapter 3,


“Editing Email Parameters” on page 123.
d Test your email configuration by clicking the Test Configuration button in
the Email Server view, followed by typing your email address and clicking
Send Test Email in the Test Configuration dialog box that appears.
Working with Foglight Rules and Registry 525
Working with Rules

A successful email configuration results in a test email arriving to your email


account after a few moments, with Test Email from Foglight as the
subject.
For complete information about testing an email configuration, see Chapter 3,
“Testing Email Configuration” on page 129.
3 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.
526 Foglight
Administration and Configuration Guide

For complete information about creating rules, see “Creating Rules” on


page 432
b Specify the rule name.
On the Create Rule dashboard, on the Rule Definition tab, in the Rule Name
box, type the rule name. For example, My Simple Rule.
Ensure that the Rule Type and Rule Triggering options are set to Simple
Rule and Data Driven, respectively.
For complete information about rule naming conventions, see “Getting started
with rule definitions” on page 434.
4 Scope the rule to the JVM topology type.
This ensures that the rule evaluates only the object instances of the JVM type.
On the Rule Definition tab, in the Rule Scope area, click Topology Type and
select JVM from the list that appears, followed by clicking on the right of the
Topology Type box.
The box immediately below the Topology Type box refreshes, showing the name
of the newly-selected type, JVM.
Working with Foglight Rules and Registry 527
Working with Rules

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

For complete information about writing conditions, see “Defining conditions


for data-driven and time-driven rules” on page 451.
b Start writing the condition by selecting threadCount, a metric property of
the JVM topology type to which the rule is scoped, in the Condition Editor.

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.

The Condition box refreshes, showing the newly-selected metric property of


the topology type to which the rule is scoped, JVM.

Close the Condition Editor dialog box.


530 Foglight
Administration and Configuration Guide

For complete information about inserting metrics into conditional expressions,


see Chapter 11, “Inserting metrics and topology object properties” on
page 794.
c Edit the condition to read as follows:
#threadCount#>10
The above condition causes the rule to enter the Fire state when the
threadcount metric property of any JVM instance becomes greater than ten.
For complete information about inserting relational operators into conditional
expressions, see Chapter 11, “Inserting operators” on page 792.
6 Add two severity level variables: ThreadNum, an expression that contains the
metric #threadCount#, and ProblemSynopsis, a message that references the
ThreadsNum expression:
Tip The ProblemSynopsis message will be used in the email action definition as the
email text sent to the Foglight System Administrator when the rule condition is met.

a In the Fire pane, open the Severity Level Variables tab.

b Add the ThreadNum and ProblemSynopsis variables using the following


settings. When you finish specifying the settings for either variable, click Add
to add it to the Severity Level Variables table.
Working with Foglight Rules and Registry 531
Working with Rules

Setting ThreadNums ProblemSynopsis


Variable

Type Expression Message

Name ThreadNum ProblemSynopsis

Expression/Message #threadCount# Thread count is


too high:
@ThreadNum

After adding the ThreadNum and ProblemSynopsis variables, they appear


in the Severity Level Variables table.

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

b Add an entering email action.


Click Action and select EmailAction from the list that appears, followed by
clicking Add.
The Action pane refreshes, showing a list of email action parameters.

c Ensure that the email is sent to the Foglight System Administrator.


Tip This value is set by the SYSADMIN registry variable.
Working with Foglight Rules and Registry 533
Working with Rules

In step 2, you added your email address to the System Administrator


Addresses parameter, thereby updating the value of the SYSADMIN registry
variable. In this step, you need to configure the mail.recipient parameter
of the email action to point to the SYSADMIN variable. That way all emails
resulting from this email action are sent to the email addresses specified by the
SYSADMIN variable.
On the Action tab, in the Action Parameters table, in the row containing the
mail.recipient entry, in the Value column, click the Default link.
The Action Parameter Editor dialog box appears.

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.

d Set the email message to the value of ProblemSynopsis severity level


variable that you added to the rule in step 6.
On the Action tab, in the Action Parameters table, in the row containing the
mail.message entry, in the Value column, click the Default link.

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

@ThreadNum, where @ThreadNum acts as a reference for the other severity-level


variable, ThreadNum, containing the current value of the scoped topology type’s
metric property threadCount. When you save the changes to this rule, an email
message is sent to your mail box with this message text, each time the rule
condition is met.

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

The Create Rule dashboard refreshes, showing the rule summary.

9 Check your email.


Your mailbox contains a new email message with the following content:
Working with Foglight Rules and Registry 539
Working with Rules

Thread count is too high: ThreadNum


Where ThreadNum is the current count of threads in your system. For example:
Thread count is too high: 155.00

Example: Creating Multiple-Severity Rules with a Topology


Scope
Suppose you want to monitor processor objects on a particular server (called
MyServer) based on the metric percentUserTime. You create a multiple-severity
rule to monitor these objects, and scope the rule to the Processor topology type. To
cause this rule to apply to the server that you are interested in, you specify in the scope
that the rule should apply to the Processor topology object whose host name
property is Server1:
Processor where host.name="MyServer"
You want to include all three severity levels (Fatal, Critical, and Warning) in the
rule. You set these levels’ conditions as follows:
• Warning: #percentUserTime#>5
• Critical: #percentUserTime#>10
• Fatal: #percentUserTime#>15
To create a multiple-severity rule scoped to a topology type property:
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.

The Foglight login page appears in the Web browser.


540 Foglight
Administration and Configuration Guide

b Log into Foglight.


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 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

For complete information about creating rules, see “Creating Rules” on


page 432.
b Specify the rule name.
On the Create Rule dashboard, on the Rule Definition tab, in the Rule Name
box, type the rule name. For example, My Multiple-Severity Rule.
Ensure that the Rule Type and Rule Triggering options are set to Multiple-
Severity Rule and Data Driven, respectively.
For complete information about rule naming conventions, see “Getting started
with rule definitions” on page 434.
3 Write a scoping query to evaluate only those instances of those Processor
objects that are running on the Host object whose name property is set to
MyServer.
On the Rule Definition tab, in the Rule Scope area, in the box immediately
below the Topology Type and Property boxes, type the following expression:
Processor where host.name="MyServer"
542 Foglight
Administration and Configuration Guide

For complete information about writing expressions that scope on topology


objects or their properties, see Chapter 11, “Specifying the scoping query
manually” on page 789.
4 Write the rule conditions.
a On the Create Rule dashboard, open the Condition, Alarms & Actions tab.
The Condition, Alarms & Actions tab appears, showing the five severity
levels: Undefined, Normal, Warning, Critical, and Fatal.

b Define the condition for the Warning severity.


On the Condition, Alarms & Actions tab, click the Warning (Not active)
bar.
The Warning (Not active) pane expands, allowing you to specify the rule
condition for the Warning severity.
Working with Foglight Rules and Registry 543
Working with Rules

Start writing the condition by selecting percentUserTime, a metric property


of the Processor topology type to which the rule is scoped, in the Condition
Editor.

In the Warning (Not Active ) pane, click , immediately above the


Condition box. In the Condition Editor dialog box that appears, open the
Metric/Property tab, and in the Type of Scope area, select Processor.
In the Metrics area that appears, select percentUserTime, followed by
clicking Insert.
544 Foglight
Administration and Configuration Guide

The Condition box refreshes, showing the newly-selected metric property of


the Processor type to which the rule is scoped.
Working with Foglight Rules and Registry 545
Working with Rules

Close the Condition Editor dialog box.


For complete information about inserting metrics into conditional expressions,
see Chapter 11, “Inserting metrics and topology object properties” on
page 794.
Edit the condition to read as follows:
#percentUserTime#>5
Activate the rule condition by selecting the Activate check box immediately
above the Condition box.
The newly-created condition causes the rule to enter the Warning severity
level when the percentUserTime metric property of the scoped type (a
Processor object instance that is running on the MyServer host) becomes
greater than five.
For complete information about inserting relational operators into conditional
expressions, see Chapter 11, “Inserting operators” on page 792.
c Define the condition for each of the Critical and Fatal severity levels
using the workflow described in step b, above.
Tip To open the appropriate pane, click Critical (Not active) or Fatal (Not active), as
required.

Use the appropriate conditional expression in each of the severity level, as follows:

Critical: #percentUserTime#>10
Fatal: #percentUserTime#>15

5 Save your changes to the newly-created rule.


In the Create Rule view, immediately above the rule definition tabs, click Finish.
546 Foglight
Administration and Configuration Guide

The Create Rule dashboard refreshes, showing the rule summary.


Working with Foglight Rules and Registry 547
Working with Rules

Example: Configuring Rule Action Parameters


You want to define rule actions for a rule severity level: a remote command action on a
monitored host and a script action on the Foglight Management Server.
To configure a rule’s action parameters:

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.

Example: Creating Rules Scoped to Different Topology Types


In this example, you will create two rules, Processor Load and Host Processor Load. For
the purpose of this example, the Processor Load rule is scoped to the Processor
topology type that monitors the utilization of all Processor objects instances in the
topology model, and fires when the utilization for a processor reaches 90% in a 24-hour
period. For instructions on how to create this rule, see “To scope a rule to the Processor
type:” on page 549.
Unlike the Processor Load rule that monitors all instances of the Processor type, the
Host Processor Load rule is scoped to the Host type that monitors all of the Processor
instances for a particular Host object, and fires if all of the Processor objects for the
scoped Host object reach the utilization of 90%. For instructions on how to create this
rule, see “To scope a rule to the Host type:” on page 556.
The following diagram illustrates the scope of each of the rules that you are about to
create from the topology model perspective.
Working with Foglight Rules and Registry 549
Working with Rules

Figure 6

Host Model

Host A Host B

Processor 1 Processor 1

percentUserTime percentUserTime

Processor 2 Processor 2

percentUserTime percentUserTime

Processor 3

percentUserTime

Rule: Host Processor Load

Rule: Processor Load

To scope a rule to the Processor type:


1 Create a simple, data-driven rule with the Processor scope.
a Start the browser interface and log into Foglight.
You can start the browser interface by opening a Web browser instance and
navigating to the following URL:
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.

The Foglight login page appears in the Web browser.


550 Foglight
Administration and Configuration Guide

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.

b Expand the condition editing pane by clicking the Fire bar.

c Click the Condition Editor button ( ).


The Condition Editor dialog box appears.
Working with Foglight Rules and Registry 553
Working with Rules

d In the Condition Editor dialog box, open the Metric/Property tab.


554 Foglight
Administration and Configuration Guide

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

g In the Metrics area, select percentUserTime and click Insert.


The Condition box in the display area refreshes, showing the newly-selected
metric.

h Edit the condition as follows:


#percentUserTime# > 0.9

i Click the Validate button ( ) above the Condition box.


A success message appears above the Condition box.
4 Refine the newly-created condition by adding a time constraint to it and a Groovy
function that retrieves a maximal value of the metric over a 24-hour period.
556 Foglight
Administration and Configuration Guide

Edit the condition as follows:


max(#percentUserTime for 24h#) > 0.9
5 Click Finish.
To scope a rule to the Host type:

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.

1 Create a simple, data-driven rule.


2 Scope the rule to the Host topology type.
3 Write a condition that generates an alarm each time the utilization of all of the
scoped host's processors are utilized over 90% using the Processor ’s
percentUserTime metric for each Processor object that is within the rule
scope, set to the Host type (see step 1).
For example:
min(#percentUserTime from Processor where host = $scope#)
> 0.9
4 Save your changes.

Example: Associating Command Actions with Rules


In this example, you will define a command action that calls a shell script and defines a
set of environment variables containing information about the agent instances in your
monitoring environment. Next, you will write the shell script that will print the content
of the command action variables to an output file.
When you save your changes, the command action calls the shell script, which
populates the output file with agent-related information whenever the rule condition is
met.
Alternatively, a command action can issue a command directly without referencing it in
a script by calling the command line directly.
To integrate a command action with a shell script:
1 Locate a rule that you want to associate with a command action and open it for
editing.
Working with Foglight Rules and Registry 557
Working with Rules

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:

The above example shows seven different severity-level variables:


• Subject, Text: Define the text that appears in the alarm message.
• var1: Retrieves the result of a query.
For example, the expression
queryResult = #Instance from OracleHost_Processes# returns the
value of the Instance field of the OracleHost_Processes table.
• var2: Retrieves the value of the Owner topology type using the scope
variable and its get() function.
• var3: Retrieves the value of a property of the scoped topology type,
Num_Objects.
• var4: Retrieves the value of the Foglight registry variable, OraDBWarning.
• var5: Retrieves the value of the monitored host name using the scope
variable and its get() function.
The expression scope.get("agent/host/name") obtains the name of a
monitored host that is being monitored by an agent object instance.
558 Foglight
Administration and Configuration Guide

• 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

6 Save your changes.


7 Create a shell script, ensuring that its name and location match the one you set in
the COMMAND_ACTION action parameter (see step 5).
8 Add a line to the shell script using the following command -line syntax:
/bin/echo ${variable_1}:${variable_2}:...:${variable_n} >
output_file_path_and_name
Working with Foglight Rules and Registry 559
Working with Rules

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.

This chapter contains the following sections:


About Schedules .......................................................................................................................562
Managing Schedules .................................................................................................................563
Creating Schedules ...................................................................................................................574
562 Foglight
Administration and Configuration Guide

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

Accessing the Manage Schedules Dashboard


The Manage Schedules dashboard includes a list of the schedules that exist in your
monitoring environment and includes an interface for adding and deleting schedules.
To access the Manage Schedules dashboard:

Note This procedure continues from “Logging in to Foglight” on page 22.

1 Ensure that the navigation panel is open.


To open the navigation panel, click the right-facing arrow on the left.
2 On the navigation panel, under Dashboards, choose Administration >
Schedules > Manage Schedules.
The Manage Schedules dashboard appears in the display area.
564 Foglight
Administration and Configuration Guide

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

Editing Schedule Permissions


Foglight allows you to control access to a schedule. For each schedule you can grant or
deny read, write, or control access to roles or users. For more information about security
concepts in Foglight, see Chapter 4, “Managing Users and Security” on page 197.
Foglight employs the following behavior when it comes to schedule permissions:
• If no one has a permission to the schedule, everyone has a permission.
• If one has a permission to the schedule, others with undefined permission do not
have any permission.
• Final permission is based on a combination of the role, user, and schedule defined
on the server side.
Use the Edit Permissions button ( ) on the Manage Schedules dashboard to navigate to
the Edit Permissions for Schedule area, that allows you to add or edit permissions to
roles and users, as outlined below. The Edit Permissions for Schedule area contains two
tables that show the permissions for each Foglight user or role.
566 Foglight
Administration and Configuration Guide

Figure 1
Permission granted
Permission denied
Permissions not assigned

To add permissions for 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 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

2 To add permissions to a schedule, complete the following steps.


a Click the role or user to which you want to assign permissions.
Tip The Not Assigned icons in the Permissions columns indicate that the role has no
permissions assigned to it.

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

3 To edit or delete permissions for a schedule, complete the following steps.


a Click the role or user whose permissions you want to edit.
Tip Three check marks in the Permissions columns indicate that the role already has
permissions assigned to it.

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.

2 If required, edit the newly-copied schedule.


For more information, see “Viewing and Editing Schedules” on page 573.
Using Schedules 571
Managing Schedules

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.

3 In the Schedule Delete Confirmation dialog box, click OK.


The Schedule Delete Confirmation dialog box closes.
4 Observe the Manage Schedules dashboard.
The newly-deleted schedule no longer appears in the list.
572 Foglight
Administration and Configuration Guide

Viewing Schedule Definitions


To view schedule definitions:

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.

2 View the definitions of the selected schedule.


In the Edit Schedule view, click the View Schedule button in the upper-right
corner.
The Business Hours dialog box appears.
Using Schedules 573
Managing Schedules

3 Observe the schedule definitions for a selected date.


In the Business Hours dialog box, use the calendar in the upper-left corner to
select a date.
On the right, the schedule for the selected date refreshes, showing the schedule’s
effective hours in blue.
When you finish observing schedule definitions, close the Business Hours dialog
box.

Viewing and Editing Schedules


You can edit the existing schedules by adding or removing recurrence patterns to it as
required. For example, if you have a schedule that runs 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 you want
574 Foglight
Administration and Configuration Guide

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.

2 Observe the schedule definitions.


3 Edit the schedule definitions as required.
For complete instructions, see “Adding or Removing Schedule Items” on
page 577.

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

Accessing the Create Schedule Dashboard


To access the Create Schedule dashboard:

Note This procedure continues from “Logging in to Foglight” on page 22.

1 Ensure that the navigation panel is open.


To open the navigation panel, click the right-facing arrow on the left.
2 Open the Create Schedule dashboard by completing one of the following steps:
• On the navigation panel, under Dashboards, choose Administration >
Schedules > Manage Schedules.
In the Manage Schedules dashboard that appears in the display area, click the
Add Schedule button in the lower-left corner.
or
• On the navigation panel, under Dashboards, choose Administration >
Schedules > Create Schedules.
The Create Schedule dashboard appears in the display area, showing the Step 1:
Create Schedule—Schedule Name and Description view.
576 Foglight
Administration and Configuration Guide

From here, you can proceed to “Getting Started with Schedule Definitions” on
page 576.

Getting Started with Schedule Definitions


To get started with schedule definitions:

Note This procedure continues from “Accessing the Create Schedule Dashboard” on page 575.

1 Specify the schedule name.


In the Create Schedule dashboard, in the Schedule Name box, type the name that
you want to assign to the schedule.
2 Optional. Add information that describes the schedule.
In the Description/Comments box, type the schedule description or comments as
required. For example:
A schedule that runs at the end of the day. This schedule is
used to trigger an activity. As a result it does not have a
significant duration.
3 Click Next.
Using Schedules 577
Creating Schedules

The Step 2: Create Schedule—Details of Schedule view appears in the Create


Schedule dashboard.

From here, you can proceed to “Adding or Removing Schedule Items” on page 577.

Adding or Removing Schedule Items


A schedule can contain one or more items, each describing a recurrence pattern. 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.
578 Foglight
Administration and Configuration Guide

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.

• In the Create Schedule dashboard, in the Step 2: Create Schedule—Details of


Schedule view, specify the start date, end date and duration (if applicable), and
the range of occurrence, as required.

For complete information on how to define a schedule item, see “Defining


Schedule Items” on page 582.
To add a schedule item to a newly-created schedule that already contains schedule
items:

Note This procedure continues from “Defining Schedule Items” on page 582.

1 Open the schedule for editing.


In the Step 3: Create Schedule—Schedule Added view, click Edit Schedule.
Using Schedules 579
Creating Schedules

The Edit Schedule view appears.


2 In the Edit Schedule view, click Add Schedule Item in the lower-right corner.

The Edit Schedule -> Add Schedule Item view appears, allowing you to define
another schedule item.
580 Foglight
Administration and Configuration Guide

For complete information on how to define a schedule item, see “Defining


Schedule Items” on page 582.
To add a schedule item to an existing schedule:

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

To delete a schedule item:

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.

2 In the Schedule Confirmation dialog box, click OK.


The Edit Schedule view refreshes, no longer showing the newly-deleted
schedule item in the list.
582 Foglight
Administration and Configuration Guide

Defining Schedule Items


There are six types of patterns that you can define in a schedule item, as listed below.

Pattern Allows you to create pattern that For instructions, see

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

Pattern Allows you to create pattern that For instructions, see

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

To define a schedule item that occurs once:

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.

4 Save the changes to the schedule item.


• New schedules. In the lower-right corner, click Add.
• Existing schedules. In the lower-right corner, click Save.
The Schedule Items table refreshes, showing the newly-added schedule item.
586 Foglight
Administration and Configuration Guide

5 Add one or more schedule items if required.


For details, see “Adding or Removing Schedule Items” on page 577.
To define a schedule item that occurs periodically:

Note This procedure continues from “Adding or Removing Schedule Items” on page 577.

1 In the Recurrence Pattern area, select the Periodical option.


The view refreshes, showing a set of controls that allow you to define a schedule
item that occurs periodically.

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.

3 Specify the recurrence pattern.


In the Recurrence Pattern area, use the Every [hh:mm] boxes to specify the
hour and minute of the start time.
Important The recurrence period must be longer than the duration specified in step 2.
For example, if the duration of the schedule item is three hours, the recurrence periods
should occur at intervals that are longer than three hours.
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.

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

5 Save the changes to the schedule item.


• New schedules. In the lower-right corner, click Add.
• Existing schedules. In the lower-right corner, click Save.
The Schedule Items table refreshes, showing the newly-added schedule item.

6 Add one or more schedule items if required.


For details, see “Adding or Removing Schedule Items” on page 577.
To define a schedule item that occurs daily:

Note This procedure continues from “Adding or Removing Schedule Items” on page 577.

1 In the Recurrence Pattern area, select the Periodical option.


The view refreshes, showing a set of controls that allow you to define a schedule
item that occurs on a daily basis.
590 Foglight
Administration and Configuration Guide

2 Specify the start date of the recurrence pattern.


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.

3 Specify the duration of the schedule item.


• If you want the schedule to occur for a part of the day, complete one of the
following steps.
Using Schedules 591
Creating Schedules

• 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 end time should occur after the start 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.

or

• Specify the start time and duration of the schedule item.


592 Foglight
Administration and Configuration Guide

• 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

4 Specify the recurrence pattern.


In the Recurrence Pattern area, use the Every box to specify the number of days
at which the schedule recurs.
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.

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.

6 Save the changes to the schedule item.


• New schedules. In the lower-right corner, click Add.
• Existing schedules. In the lower-right corner, click Save.
The Schedule Items table refreshes, showing the newly-added schedule item.

7 Add one or more schedule items if required.


For details, see “Adding or Removing Schedule Items” on page 577.
To define a schedule item that occurs weekly:

Note This procedure continues from “Adding or Removing Schedule Items” on page 577.
Using Schedules 595
Creating Schedules

1 In the Recurrence Pattern area, select the Weekly option.


The view refreshes, showing a set of controls that allow you to define a schedule
item that occurs on a weekly basis.

2 Specify the start date of the recurrence pattern.


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.

3 Specify the duration of the schedule item.


596 Foglight
Administration and Configuration Guide

• 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 end time should occur after the start 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.

or

• Specify the start time and duration of the schedule item.


Using Schedules 597
Creating Schedules

• 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

4 Specify the recurrence pattern.


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.

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.

6 Save the changes to the schedule item.


• New schedules. In the lower-right corner, click Add.
• Existing schedules. In the lower-right corner, click Save.
600 Foglight
Administration and Configuration Guide

The Schedule Items table refreshes, showing the newly-added schedule item.

7 Add one or more schedule items if required.


For details, see “Adding or Removing Schedule Items” on page 577.
To define a schedule item that occurs monthly:

Note This procedure continues from “Adding or Removing Schedule Items” on page 577.

1 In the Recurrence Pattern area, select the Monthly option.


The view refreshes, showing a set of controls that allow you to define a schedule
item that occurs that occurs on a monthly basis.
Using Schedules 601
Creating Schedules

2 Specify the start date of the recurrence pattern.


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.

3 Specify the duration of the schedule item.


602 Foglight
Administration and Configuration Guide

• 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 end time should occur after the start 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.

or

• Specify the start time and duration of the schedule item.


Using Schedules 603
Creating Schedules

• 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

4 Specify the recurrence pattern.


• To have the schedule occurring on a specified day of the month, at the rate of
one or more months, in the Recurrence Pattern area, ensure that the By Date
option is selected, and then specify the day of the month and the rate at which
it occurs.
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 every box accepts any positive values.

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.

6 Save the changes to the schedule item.


• New schedules. In the lower-right corner, click Add.
• Existing schedules. In the lower-right corner, click Save.
The Schedule Items table refreshes, showing the newly-added schedule item.

7 Add one or more schedule items if required.


For details, see “Adding or Removing Schedule Items” on page 577.
Using Schedules 607
Creating Schedules

To define a schedule item that occurs yearly:

Note This procedure continues from “Adding or Removing Schedule Items” on page 577.

1 In the Recurrence Pattern area, select the Yearly option.


The view refreshes, showing a set of controls that allow you to define a schedule
item that occurs on a yearly basis.

2 Specify the start date of the recurrence pattern.


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.
608 Foglight
Administration and Configuration Guide

3 Specify the duration of the schedule item.


Using Schedules 609
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 end time should occur after the start 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.

or

• Specify the start time and duration of the schedule item.


610 Foglight
Administration and Configuration Guide

• 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

4 Specify the recurrence pattern.


• To have the schedule occurring on a specified day of the month, at the rate of
one or more months, in the Recurrence Pattern area, ensure that the By Date
option is selected, and then specify the day of the month and the rate at which
it occurs.
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.

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.

• To have the schedule occurring on a particular day of the week, 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 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.

6 Save the changes to the schedule item.


• New schedules. In the lower-right corner, click Add.
• Existing schedules. In the lower-right corner, click Save.
The Schedule Items table refreshes, showing the newly-added schedule item.

7 Add one or more schedule items if required.


For details, see “Adding or Removing Schedule Items” on page 577.
614 Foglight
Administration and Configuration Guide
9
Working with Data

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.

This chapter contains the following sections:


About Data Management in Foglight .........................................................................................616
Adding Topology Types .............................................................................................................617
Working with Derived Metrics ....................................................................................................620
Working with Thresholds ...........................................................................................................642
Managing Retention Policies .....................................................................................................666
Enabling the Collection of Data with Older Timestamps ...........................................................697
616 Foglight
Administration and Configuration Guide

About Data Management in Foglight


Foglight models retain collected data and transform it into nodes, adding configuration
data to each node as properties, and attaching metric data to appropriate nodes as
metrics. Each metric is associated with a topology type or with a specific topology
object. In some cases you will need to create custom topology types that suit your
monitoring needs. For more information, see “Adding Topology Types” on page 617.
There are two types of metrics in Foglight:
• Raw metrics. They include the metrics collected directly from monitored hosts.
• Derived metrics. They are calculated from one or more raw or derived metrics.
Derived metrics are scoped to a topology type or its objects. You can create and
manage derived metrics using the Administration module. Derived metrics are
useful in situations when you need to reuse metric expressions in rules. For more
information on how to manage and create derived metrics, see “Working with
Derived Metrics” on page 620.
In Foglight, retention policies allow you to define time periods where monitoring data
can be sampled, aggregated, or purged from your system. Topology objects inherit
retention policies from their topology type. Foglight allows you to alter retention
policies for one or more topology types as required. For more information, see
“Managing Retention Policies” on page 666.
In addition to adding derived metrics and topology types, and altering the retention
policy for a topology type, Foglight allows you to assign threshold levels to metrics.
This feature is useful in case you need to reference these levels in rules or derived
metrics. For more information on how to create and manage thresholds, see “Working
with Thresholds” on page 642.
Working with Data 617
Adding Topology Types

Adding Topology Types


Foglight transforms monitoring data into models. A model is a set of objects and
relationships designed to represent a monitored resource and its parts. Topology
describes the logical and physical relationships between data nodes in a model. At run-
time, Foglight dynamically builds topology models based on data about your system
that is collected by Foglight agents. Topology models provide the context for the
metrics sent by the agents to the Foglight Management Server. The set of topology types
that exist in your environment depends on your monitoring needs, reflected in the type
and nature of cartridges that you use for data collection. If you need additional topology
types, you can add them to Foglight as required using the Adding Topology Types
dashboard.
Use the XML syntax when defining a topology type. For example:
<type name="ApacheSvr_Transactions" extends="F4Table">
<property name="IntervalTransactions" type="Metric"
is-containment="true" />
<property name="TransactionRate" type="Metric"
is-containment="true" />
<property name="TransactionTag" type="String"
is-identity="true" />
<property name="TransactionThroughput" type="Metric"
is-containment="true" />
<property name="TransactionThroughputRate" type="Metric"
is-containment="true" />
</type>

Important Topology types can only be removed by uninstalling the cartridge that contains the types
that you want to delete.

To add topology types:

Note This procedure continues from “Logging in to Foglight” on page 22.

1 Ensure that the navigation panel is open.


To open the navigation panel, click the right-facing arrow on the left.
2 On the navigation panel, under Dashboards, choose Administration > Data >
Add Topology Type.
The Add Topology Type dashboard appears in the display area.
618 Foglight
Administration and Configuration Guide

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.

6 Close Click Import Topology.


The Alert message box appears, this time indicating that the topology import was
successful.

Working with Derived Metrics


Foglight transforms collected data into nodes. It adds configuration and metric data to
each node as properties and metrics, respectively. A metric is a specific value that is
measured over time. Each metric is associated with a topology type or with a specific
topology object.
There are two types of metrics in Foglight:
• Raw Metrics. Raw metrics are collected directly from your monitored
environment by the agents and sent to the Foglight Management Server.
• Derived Metrics. Derived metrics are calculated from one or more (raw or
derived) metrics. They are scoped to a topology type and can optionally be
scoped to specific objects of that type. Many derived metrics come included with
Foglight and its cartridges. If required, you can create derived metrics and add
them to your environment.
There are many reasons why it can be useful to create derived metrics. For example,
creating derived metrics can make creating and managing rules simpler by allowing you
to reuse metric expressions (metrics and functions performed on metrics). For more
examples, see the following sections:
• “Example: Creating and Managing Multiple Rules with the Same Scope” on
page 640
Working with Data 621
Working with Derived Metrics

• “Example: Using a Single Derivation with Multiple Scoping or Multiple


Derivations” on page 641
• “Example: Optimizing Performance” on page 642
You create new derived metrics and manage the existing ones using the dashboards that
come with the Administration module. For complete information, see the following
sections:
• “Managing Derived Metrics” on page 621
• “Creating Derived Metrics” on page 632
• “Defining Derived Metrics” on page 633

Managing Derived Metrics


The Manage Derived Metrics dashboard contains a list of all derived metrics showing
their name and scope. The derived metrics that exist in your Foglight environment
appear on the Manage Derived Metrics dashboard. However, there is no distinction
between raw and derived metrics in other locations on the Administration module.
This dashboard also includes controls for filtering the list of derived metrics by the
metric name, scope, or cartridge. For instructions on how to use the Manage Derived
Metrics dashboard, see the following sections:
• “Accessing the Manage Derived Metrics dashboard” on page 621
• “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

Accessing the Manage Derived Metrics dashboard


The Manage Derived Metrics dashboard includes a list of the derived metrics that exist
in your monitoring environment and allows you to add or delete derived metrics and
perform other metric management operations.
To access the Manage Derived Metrics dashboard:

Note This procedure continues from “Logging in to Foglight” on page 22.

1 Ensure that the navigation panel is open.


622 Foglight
Administration and Configuration Guide

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.

5 View summary information about a derived metric.


Move the mouse pointer over the Derived Metric Name column in the row
containing the derived metric whose summary that you want to view.
A dwell appears, showing the summary about the derived metric.
624 Foglight
Administration and Configuration Guide

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

Editing permissions of derived metrics


Foglight allows you to control access to derived metrics. For each derived metric you
can grant or deny read, write, or control access to roles or users. For more information
about security concepts in Foglight, see Chapter 4, “Managing Users and Security” on
page 197.
Foglight employs the following behavior when it comes to permissions of derived
metrics:
• If no one has a permission to the derived metric, everyone has a permission.
• If one has a permission to the derived metric, others with undefined permission
do not have any permission.
• Final permission is based on a combination of the role, user, and derived metric
defined on the server side.
Use the Edit Permissions button ( ) on the Manage Derived Metrics dashboard to
navigate to the Edit Permissions for Derived Metric area, that allows you to add or edit
permissions to roles and users, as outlined below. The Edit Permissions for Derived
Metric area contains two tables that show the permissions for each Foglight user or role.
Working with Data 625
Working with Derived Metrics

Figure 1
Permission granted
Permission denied
Permissions not assigned

To add permissions for a derived metric:

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

2 To add permissions to a derived metric, complete the following steps.


a Click the role or user to which you want to assign permissions.
Tip The Not Assigned icons in the Permissions columns indicate that the role has no
permissions assigned to it.

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

3 To edit or delete permissions for a rule, complete the following steps.


a Click the role or user whose permissions you want to edit.
Tip Three check marks in the Permissions columns indicate that the role already has
permissions assigned to it.

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.

Copying derived metrics


Use the Copy Derived Metric button on the Manage Derived Metrics dashboard to copy
a derived metric, as outlined below.
To copy a derived metric:

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

2 In the Copy Derivation dialog box, click OK.


The Copy Derivation dialog box closes and the Create Derived Metric view
appears in the display area.

3 Provide a unique name for the destination metric.


In the Create Derived Metric view, in the Derived Metric Name box, type the
name of the derived metric.
4 If required, edit the settings of the newly-copied derived metric.
For more information, see “Defining Derived Metrics” on page 633.
630 Foglight
Administration and Configuration Guide

Deleting derived metrics


Use the Delete Selected button on the Manage Derived Metrics dashboard to delete a
derived metric, as outlined below.
To delete a derived metric:

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.

3 In the Delete Derivation dialog box, click OK.


The Delete Derivation dialog box closes.
4 Observe the Manage Derived Metrics dashboard.
The newly-deleted derived metrics no longer shows in the list.

Viewing and editing derived metrics


The Manage Derived Metrics dashboard shows all of the derived metrics that exist in
your monitoring environment. This includes the derived metrics that come with the
Foglight Management Server, any installed cartridges, and also any derived metrics that
you create using the Create Derived Metric dashboard. From here, you can drill down to
view the settings for a derived metric, and edit them, as required.
Working with Data 631
Working with Derived Metrics

To view or edit derived metric:

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.

2 Observe the metric definitions.


3 Edit the derived metric as required.
• To edit the rule derived metric name, type the desired values into the Derived
Metric Name box
• To make additional modifications, such as adding calculations, see “Adding
calculations to derived metrics” on page 634 for complete instructions.

Creating Derived Metrics


Foglight allows you to create derived metrics using the Create Derived Metric
dashboard. You can access this dashboard from the navigation panel, or through the
Manage Derived Metrics dashboard.
When you create a derived metric, Foglight changes the topology type to which the
derived metric is scoped by associating a new metric property to that topology type.
To create a derived metric:

Note This procedure continues from “Logging in to Foglight” on page 22.

1 Ensure that the navigation panel is open.


To open the navigation panel, click the right-facing arrow on the left.
2 Open the Create Derived Metric dashboard by completing one of the following
steps:
• On the navigation panel, under Dashboards, choose Administration > Data
> Manage Derived Metrics.
In the Manage Derived Metrics dashboard that appears in the display area,
click the Add Derived Metric button in the lower-left corner.
or
• On the navigation panel, under Dashboards, choose Administration > Data
> Create Derived Metric.
The Create Derived Metric dashboard appears in the display area.
Working with Data 633
Working with Derived Metrics

From here, you can proceed to “Defining Derived Metrics” on page 633.

Defining Derived Metrics


Derived metrics are calculated from one or more (raw or derived) metrics. They must be
scoped to a topology type and can optionally be scoped to specific objects of that type.
If a rule or derived metric is not scoped to specific objects, it applies to all objects of
that type. Many derived metrics are included with Foglight and its cartridges. You can
also create customized derived metrics from within the Administration module.
For instructions, see the following sections:
• “Getting started with derived metric definitions” on page 633
• “Adding calculations to derived metrics” on page 634
• “Triggering derived metrics” on page 637
• “Setting the value type” on page 639

Getting started with derived metric definitions


Once you create a derived metric, you can add name it and proceed to edit its settings as
required.
634 Foglight
Administration and Configuration Guide

To get started with derived metric definitions:

Note This procedure continues from “Creating Derived Metrics” on page 632.

• Provide a descriptive name for the derived metric.


In the Create Derived Metric dashboard, in the Derived Metric Name box, type
the name that you want to assign to the derived metric.
From here, you can proceed to “Adding calculations to derived metrics” on page 634.

Adding calculations to derived metrics


The scope of a derived metric defines the set of topology objects against which Foglight
calculates it. A derived metric is scoped to a topology type and can optionally be scoped
to specific topology objects of that type. If a derived metric is not scoped to specific
objects, it applies to all instances of that type. You specify the derived metric scope
using the query language. You can change the scope of a derived metric (the topology
type or one or more specific topology objects of that type to which it applies) after its
creation.
The Foglight Management Server processes the derived metric calculation in the order
they are listed, starting with the first one. Changing their order affects the behavior of
the actions that are associated with the derived metric.
For example, if there are two calculations whose conditions evaluate to True, the first
calculation listed takes precedence, causing one or more actions that are associated with
that metric to be generated before the next one.
For detail information on how to scope a rule or derived metric to one or more topology
objects, see “Using the Query Language” on page 763.
To get started with adding calculations to a derived metric:

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.

To move a threshold bound up or down, in the Derived Metric Calculations


table, in the Derived Metric Scope column, use the Move up ( ) or Move down
( ) buttons as required.
4 Specify the unit of the derived metric.
Use one or a combination of the two Unit boxes under the Derived Metric
Calculations list to specify the unit. Each box contains the following choices:
• billion
• billionth
• bit
• byte
• count
• day
• exabyte
• gigabyte
• hour
• kilobyte
• megabyte
• microsecond
• million
• millionth
• millisecond
• minute
• month
• nanosecond
• percent
• petabyte
• second
• terabyte
Working with Data 637
Working with Derived Metrics

• 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.

5 Define the data type of the derived metric.


A derived metric take over the form of a metric or an observation type. Click
Value Type and select one of the following values, as required:
• AgentStateObservation
• AlarmStateObservation
• CatalystPersistencePolicyRollupObservation
• HostTopCPUProcessObservation
• HostTopIOProcessObservation
• HostTopMemoryProcessObservation
• Metric
• RequestTraces
• SPIDefaultObservation
• StringListObservation
• StringObservation
Caution The derived metric data types that you define at metric creation time cannot
be changed.

6 Optional. Add comments about the newly-created derived metric.


From here, you can proceed to “Triggering derived metrics” on page 637.

Triggering derived metrics


An instance of a derived metric is created when its definition is triggered. A derived
metric is configured to have one of the following triggers:
638 Foglight
Administration and Configuration Guide

• Schedule-Driven Derived Metric. A schedule-driven derived metric is evaluated


based on a schedule created in the Administration Module. See Chapter 8, “Using
Schedules” on page 561 for information about schedules.
There are three trigger timing options for schedule-driven derived metrics:
• Enter and Exit. Causes the derived metric to be evaluated when the period
defined by the schedule begins and ends.
• Enter only. Causes the derived metric to be evaluated when the period defined
by the schedule begins.
• Exit only. Causes the derived metric to be evaluated when the period defined
by the schedule ends.
• Time-Driven Derived Metrics. A time-driven trigger causes the derived metric to
be evaluated once per pre-defined interval.
• Data-Driven Derived Metrics. If a derived metric has a data-driven trigger, it will
be evaluated every time that data that is used in the expression for the derived
metric is sent to the Foglight Management Server.
To assign a schedule-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 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

• Enter and Exit


• Enter only
• Exit only
4 To enable the trigger without data, select the Enable Trigger without Data check
box.
5 Save your changes.
To assign a time-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 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.

Setting the value type


Once you define the scope and trigger of the derived metric, you can specify the value
type for the derived metric. The value type for a derived metric dictates the appearance
of the derived metric. You can set the derived type to a metric, and specify its unit of
measurement, or to an observation.
640 Foglight
Administration and Configuration Guide

To set the value type for a derived metric:

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.

To set the value type to an observation:

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).

Example: Creating and Managing Multiple Rules with the Same


Scope
If you need to create multiple rules that are scoped to the same topology type and that
use the same metric expressions in their conditions, you can make the process of
Working with Data 641
Working with Derived Metrics

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.

Example: Using a Single Derivation with Multiple Scoping or


Multiple Derivations
Derivation definitions will allow multiple scoping query/expression pairs under a single
definition. For each topology object, the expression paired with the first scoping query
which matches the object will be calculated. This allows you to override a derivation
definition based on the scoping query where multiple derivations definitions exist.
Use the following guidelines to decide when to use one derivation with multiple scopes,
or when to use multiple derivation definitions:
• Choose a single derivation definition when you need the overriding behavior. If
you have a subset of a topology object type that requires a derivation to be
calculated differently, use a single derivation definition with additional scope/
expression pairs.
For example, you have a derivation freeMemory for topology type OS, with a
subtype Unix that requires a different freeMemory calculation. Define a single
derivation freeMemory create two scope/expression pairs (one for OS and the
other for Unix).
• Choose a multiple derivation definition when you are using the same observation
name for unrelated scoping queries.
For example, if you have a derivation freeMemory for the types OS and JVM,
create two separate derivations to avoid coupling the definitions.
• Choose multiple derivation definitions when you have alternate ways of
calculating the same observation for the same topology objects. If you keep the
calculations in the same derivation definition, only the first calculation in the list
will take affect.
642 Foglight
Administration and Configuration Guide

Example: Optimizing Performance


Derived metrics can also help you optimize performance by reducing the number of
calculations that need to be performed at run-time. For example, if there are multiple
rules that need to use the same complex metric expression in their conditions, creating a
derived metric with this expression and using it in these rules’ conditions would have a
positive impact on performance: the calculation specified in the metric expression
would only need to be performed each time an instance of the derived metric is created
instead of each time the rule is evaluated.

Working with Thresholds


Threshold levels in metrics are useful in situations when you need to reference a
specific metric value multiple times, for example in derived metrics or rules.
A metric can be associated with different types of threshold levels such as the levels that
refer to agent states, alarm severity, and others. 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. A bound level value can be associated with a constant
value, a registry variable, or another metric of the same topology type.
You create new thresholds metrics and manage the existing ones using the dashboards
that come with the Administration module. For complete information, see the following
sections:
• “Managing Thresholds” on page 642
• “Creating Thresholds” on page 650
• “Defining Thresholds” on page 651

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

Accessing the Manage Thresholds dashboard


The Manage Thresholds dashboard includes a list of the thresholds that exist in your
monitoring environment and includes mechanisms for adding and deleting thresholds.
To access the Manage Thresholds dashboard:

Note This procedure continues from “Logging in to Foglight” on page 22.

1 Ensure that the navigation panel is open.


To open the navigation panel, click the right-facing arrow on the left.
2 On the navigation panel, under Dashboards, choose Administration > Data >
Manage Thresholds.
The Manage Thresholds dashboard appears in the display area.

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

From here, you can proceed to any of the following procedures:


• “Editing threshold permissions” on page 644
• “Deleting thresholds” on page 647
• “Viewing and editing thresholds” on page 648

Editing threshold permissions


Foglight allows you to control access to thresholds. For each threshold you can grant or
deny read, write, or control access to roles or users. For more information about security
concepts in Foglight, see Chapter 4, “Managing Users and Security” on page 197.
Foglight employs the following behavior when it comes to threshold permissions:
• If no one has a permission to the threshold, everyone has a permission.
• If one has a permission to the threshold, others with undefined permission do not
have any permission.
• Final permission is based on a combination of the role, user, and threshold
defined on the server side.
Use the Edit Permissions for Threshold button ( ) on the Manage Thresholds
dashboard to navigate to the Edit Permissions for Threshold area, that allows you to add
or edit permissions to roles and users, as outlined below. The Edit Permissions for
Threshold area contains two tables that show the permissions for each Foglight user or
role.
Figure 2
Permission granted
Permission denied
Permissions not assigned

To add permissions for a threshold:

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.

2 To add permissions to a threshold, complete the following steps.


a Click the role or user to which you want to assign permissions.
Tip The Not Assigned icons in the Permissions columns indicate that the role does
not have permissions assigned to it.

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

3 To edit or delete permissions for a threshold, complete the following steps.


a Click the role or user whose permissions you want to edit.
Tip Three check marks in the Permissions columns indicate that the role already has
permissions assigned to it.

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

3 In the Delete Threshold dialog box, click OK.


The Delete Threshold dialog box closes.
4 Observe the Manage Thresholds dashboard.
The newly-deleted threshold no longer appears in the list.

Viewing and editing thresholds


The Manage Thresholds dashboard shows all of the thresholds that exist in your
monitoring environment. This includes the thresholds that come with the Foglight
Management Server, any installed cartridges, and also any thresholds that you create
using the Create Threshold dashboard. From here, you can drill down to view the
settings for a derived metric, and edit them, as required.
To view or edit a threshold:

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:

Note This procedure continues from “Logging in to Foglight” on page 22.

1 Ensure that the navigation panel is open.


To open the navigation panel, click the right-facing arrow on the left.
2 Open the Create Threshold dashboard by completing one of the following steps:
• On the navigation panel, under Dashboards, choose Administration > Data
> Manage Thresholds.
In the Manage Thresholds dashboard that appears in the display area, click the
Add Threshold button in the lower-left corner.
or
• On the navigation panel, under Dashboards, choose Administration > Data
> Create Threshold.
The Create Threshold dashboard appears in the display area.

From here, you can proceed to “Defining Thresholds” on page 651.


Working with Data 651
Working with Thresholds

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

Selecting metrics and threshold levels


To select a metric and its threshold level:

Note This procedure continues from “Creating Thresholds” on page 650.

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

In the Step 2: Create Threshold—Select Threshold Level area, click


Threshold Levels and choose one of the following predefined threshold levels
from the list that appears.

For example, to use an agent state as threshold level, select AgentState.


4 Click Next.
The Step 3: Create Threshold—Add Bounds area appears in the Create
Threshold dashboard.
Working with Data 653
Working with Thresholds

From here, you can proceed to “Adding bounds to threshold levels” on page 653.

Adding bounds to threshold levels


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. A bound level
value can be associated with a constant value, a registry variable, or another metric of
the same topology object.

Threshold Level Threshold Bound Level

AgentHealthState OK

Running Unexpectedly

Broken

Agent Info Not Present


654 Foglight
Administration and Configuration Guide

Threshold Level Threshold Bound Level

AgentState Unknown

Stopped

Starting

Stopping

Running

Collecting data

Running but not collecting data

AlarmChangeType Fire

Clear

Acknowledge

UserDefined Data

AlarmSeverity Undefined

Normal

Fire

Warning

Critical

Fatal
Working with Data 655
Working with Thresholds

Threshold Level Threshold Bound Level

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

Threshold Level Threshold Bound Level

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:

Type Severity level is bound to

Metric Threshold Bound Another metric

Registry Variable Threshold Bound A registry variable

Baseline Threshold Bound A baseline, defined in the baseline


cartridge that contain one or more
baseline patterns for the selected
metric
Note This 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.

Constant Threshold Bound A fixed value

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.

Threshold Bounds Applied Threshold Levels Observed Behavior

There are no
threshold level
overrides set for
any of the threshold
bounds.
658 Foglight
Administration and Configuration Guide

Threshold Bounds Applied Threshold Levels Observed Behavior

The Override flag


is set for the Fatal
threshold level
(column four in the
Threshold Bounds
table on the left),
causing it to take
precedence over
Warning.

The Override flag


is set for the
Normal and Fatal
threshold levels. ,
causing it to take
precedence over
Warning. In this
case, Normal takes
precedence over
Critical, and Fatal
takes precedence
over Warning.

To bind a threshold level to a metric:

Note This procedure continues from “Selecting metrics and threshold levels” on page 651 or
“Viewing and editing thresholds” on page 648.

1 Select the severity type of the threshold level.


Click Level and select a threshold level from the list that appears.
2 Select the Metric Threshold Bound option.
The display area refreshes, showing a set of controls that allow you to define the
metric to which you want to bind the severity level.
Working with Data 659
Working with Thresholds

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

To bind a threshold level to a registry variable:

Note This procedure continues from “Selecting metrics and threshold levels” on page 651 or
“Viewing and editing thresholds” on page 648.

1 Select the severity type of the threshold level.


Click Level and select a severity level from the list that appears.
2 Select the Registry Variable Threshold Bound option.
The Registry Variable Name box appears below the Bound Type options,
allowing you to specify the registry variable to which you want to bind the
severity level.

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.

To bind a threshold level to a baseline:

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.

1 Select the severity type of the threshold level.


Click Level and select a severity level from the list that appears.
662 Foglight
Administration and Configuration Guide

2 Select the Baseline Threshold Bound option.


The Baseline Name and Baseline Bound boxes appear below the Bound Type
options, allowing you to specify the baseline value to which you want to bind the
severity level.

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.

To bind a threshold level to a constant value:

Note This procedure continues from “Selecting metrics and threshold levels” on page 651 or
“Viewing and editing thresholds” on page 648.

1 Select the severity type of the threshold level.


Click Level and select a severity level from the list that appears.
2 Select the Constant Threshold Bound option.
The Value box appears below the Bound Type options, allowing you to specify
the constant value to which you want to bind the severity level
.

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.

To save your changes:

Note This procedure continues from any of the following sections:


• “To bind a threshold level to a metric:” on page 658
• “To bind a threshold level to a registry variable:” on page 660
• “To bind a threshold level to a constant value:” on page 663

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

To move a threshold bound up or down, in the Threshold Bounds table, in the


Info column, use the Move up this bound ( ) or Move down this bound ( )
buttons as required.
2 Complete one of the following steps:
• Existing thresholds. Click Save.
A list appears in the display area, showing the newly-added threshold bounds
for the selected threshold level.

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

Observe the Manage Thresholds dashboard.


The newly-added threshold appears in the list.

Managing Retention Policies


Topology is a representation of—and a way of understanding—the logical and physical
relationship between items in your monitored environment. At run-time, Foglight
dynamically builds topology models using the monitoring data about your system that is
collected by Foglight agents. A model is a set of objects and relationships designed to
represent a monitored resource and its parts. Foglight models retain collected data and
transform it into nodes, adding configuration data to each node as properties, and
attaching metric data to appropriate nodes as metrics. Topology models provide the
context for the metrics sent by the agents to the Foglight Management Server.
Retention policies allow you to define time periods where monitoring data can be
sampled, aggregated, or purged from your system. All topology objects in Foglight form
a hierarchy whose root is the super-type TopologyObject. Retention policies are
inherited from the object’s type. These policies may be overwritten, in which case the
modification applies to all child types in the hierarchy.
In addition to retention policies, the collected data has additional life-cycle properties
that are defined in the storage-config.xml file that is located in the directory
Working with Data 667
Managing Retention Policies

<foglight_home>/config. For example, according to the default retention policy for


TopologyObject, all data is rolled up to 15 minute periods after the age of 15 minutes,
then rolled up to one-hour periods after the age of four hours, and finally rolled up to
four-hour periods after the age of five days. Furthermore, the default settings in
storage-config.xml dictate that the 15-minute interval data is kept for three days
and is converted to one-hour interval data, while one-hour interval data is kept for two
weeks and then converted to four-hour interval data.
If there is no existing retention policy for a topology type, that type inherits the retention
policy from its parent type. If no policies exist within the entire hierarchy, the type
inherits the policy from the TopologyObject type. Conversely, setting a retention
policy for a topology type completely overwrites any policy it inherits from a super-
type, and is applied to all sub-types of that topology type. For an example of how to
configure a retention policy in cases where data storage is limited, see “Example:
Addressing Data Storage Concerns” on page 696.
In some cases your retention policies may cause an unacceptable increase in the
database size, which typically happens if the granularity is high and the data is not
frequently purged. Alternatively, the database size can be controlled by deleting specific
topology objects and any metrics that they contain. This can be done through the Data
Management dashboard. In addition to associating the default monitoring policies with
data storage cycles, this dashboard allows you to inspect the topology objects and to
delete them by applying specific retention policies to the collected data, or to purge
specific data objects as required. For more information about this dashboard, see the
Foglight User 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

About Retention Policy Mechanisms


While it is theoretically possible to create any retention policy that you desire in
Foglight 5, the design of the system constrains the easy-to-accomplish retention policies
to a narrow range of options. Specifically, the database design of Foglight provides a
structure that is capable of holding data in three different buckets, called generations,
that are defined in <foglight_home>/config/storage-config.xml. Each generation has a
predefined period of time in which it retains data. Without modification to the
generations, there are specific rules that must be followed when assigning retention
policies to ensure that you get the results you are expecting.
This section provides information on the key mechanisms involved in retention policies
and rules for defining retention policies that work effectively with the default database
configuration.
For complete information, see the following sections:
• “About database generations” on page 668
• “How Foglight populates database generations” on page 669
• “How retention policies interact with database generations” on page 669
• “Developing a retention policy: Example” on page 672

About database generations


Generations refer to the database structures that hold long-term data. For any given
metric, each generation can hold one aggregation level of data (for example, raw, hourly
averages, 4 hour averages, and so on). Out of the box, there are three generations, each
holding data for:
• Generation 1: Data for 0 – 3 days
• Generation 2: Data for 3 – 14 days
• Generation 3: Indefinite
Because data is constrained to the above aggregation periods, retention policies are also
constrained to a set of rules. In general, you can create retention policies that:
• Have 3 retention policies (including a purge), where:
• The first retention policy sets the granularity of data stored for 3 days in
generation 1.
• The second sets the granularity of data stored for 14 days in generation 2
Working with Data 669
Managing Retention Policies

• 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.

How Foglight populates database generations

Moving data from memory to the database


The data service periodically writes data from the short-term memory cache to
Generation 1. The frequency by which data are written is defined in the first retention
policy (for more information, see “How retention policies interact with database
generations” on page 669). This interval should not exceed 15 minutes to prevent the
Foglight Management Server memory from growing too large.

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”.

How retention policies interact with database generations


Both mechanisms for populating the repository (from memory to the database, database
roll-ups) use the retention policies defined in the Retention Policies dashboard as the
guidelines for how they store data.
A retention policy is the set of definitions, for a given object, that indicate how data is
stored. Each definition within a policy contains two parameters:
• Age: Specifies the age at which the data is eligible for a roll-up
• Roll-up period: Specifies the period of time over which the data is aggregated
670 Foglight
Administration and Configuration Guide

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 15 minutes After 15 minutes, store 15 minute average data to


Generation 1 (where they are stored for three days)
Roll-up 15 minutes

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

Developing a retention policy: Example


While the browser interface does not prevent you from setting policies that are in
conflict with the generations, setting policies that are outside of these boundaries does
not yield the expected results. Instead, the retention policy engine finds the most
optimal scheme for your data (ensuring that the lowest granularity is written to
Generation 1 and that longest duration data are written to Generation 3).
The table shows how to configure retention policies, at 1, 2 or 3 levels of aggregation,
following the specifications below.

Acceptable Acceptable Explanation


age values roll-up values

Three-level policy (including a purge)

Level 1 <= 15 minutes <= 15 minutes Data is persisted at the roll-up


interval defined in the Level 1
policy for three days.

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.

Purge > Level 3 Purge Data is never purged from the


Policy setting system before the age value of the
purge policy. Data may, however,
be retained for longer than the
setting as the system waits to find
an acceptable time to purge data.
Working with Data 673
Managing Retention Policies

Acceptable Acceptable Explanation


age values roll-up values

Two-level policy (including a purge)

Level 1 <= 15 minutes <= 15 minutes Data is persisted at the roll-up


interval defined in the Level 1
policy for either three or 14 days,
depending on the age of the Level
2 setting. If the age of the Level 2
setting is less than or equal to three
days, then the data is persisted for
three days. If the age of the Level 2
setting is between three and 14
days, the data is persisted for 14
days.

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.

Purge > Level 2 Purge Data is never purged from the


Policy setting system before the age value of the
purge policy. Data may, however,
be retained for longer than the
setting as the system waits to find
an acceptable time to purge data.

One-level policy (including a purge)

Level 1 <= 15 minutes <= 15 minutes Data is persisted at the roll-up


interval defined in the Level 1
policy indefinitely. A purge policy
will define a minimum length of
time that data must persist before it
is truncated.
674 Foglight
Administration and Configuration Guide

Acceptable Acceptable Explanation


age values roll-up values

Purge > 15 minutes Purge Data is never purged from the


Policy system before the age value of the
purge policy. Data may, however,
be retained for longer than the
setting as the system waits to find
an acceptable time to purge data.
Working with Data 675
Managing Retention Policies

Accessing the Manage Retention Policies Dashboard


Use the Manage Retention Policies dashboard to create and edit retention policies for
topology types and properties of topology types. Each policy specifies one or more time
periods after which the data is rolled up and the granularity of the roll-up.
In some cases your retention policies may cause an unacceptable increase in the
database size, which typically happens if the granularity is high and the data is not
frequently purged. Alternatively, the database size can be controlled by deleting specific
topology objects and any metrics that they contain. This can be done through the Data
Management dashboard. In addition to associating the default monitoring policies with
data storage cycles, this dashboard allows you to inspect the topology objects and to
delete them by applying specific retention policies to the collected data, or to purge
specific data objects as required. For more information about this dashboard, see the
Foglight User 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.

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.

Note Modifying or deleting an inherited policy converts it to a custom policy.

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

The super-type with default retention policies


A topology type with inherited retention policies
A topology type with a custom retention policy
678 Foglight
Administration and Configuration Guide

To access the Manage Retention Policies dashboard:

Note This procedure continues from “Logging in to Foglight” on page 22.

1 Ensure that the navigation panel is open.


To open the navigation panel, click the right-facing arrow on the left.
2 On the navigation panel, under Dashboards, choose Administration > Data >
Manage Retention Policies.
The Manage Retention Policies dashboard appears in the display area.

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.

From here, you can proceed to any of the following procedures:


• “Deleting Retention Policies” on page 680
680 Foglight
Administration and Configuration Guide

• “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

Deleting Retention Policies


Use the Delete Selected button on the Manage Retention Policies dashboard to delete
the retention policy associated with a particular topology object, as outlined below.
If a topology type directly references the default data storage cycle, such as the
TopologyObject super-type, its retention policies cannot be deleted. The default data
storage cycle can be modified using the Data Management dashboard. In addition to
associating the default monitoring policies with data storage cycles, this dashboard
allows you to inspect the topology objects and to delete them by applying specific
retention policies to the collected data, or to purge specific data objects as required. For
more information about this dashboard, see the Foglight User Guide.
Any types descending from TopologyObject that inherited its retention policies can
have their retention policies deleted. This also applies to the descendants that have
custom retention policies.

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.

a On the Manage Retention Policies dashboard, in the Topology Type—


Property Name column, click the row containing the topology type that has
inherited policies.
The Add Retention Policy dialog box appears.

b In the Add Retention Policy dialog box, click Save.


Tip Saving the inherited settings without making any changes to them converts an
inherited policy to a custom one.

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

2 Select one or more sampling periods that you want to delete.


On the Manage Retention Policies dashboard, in the row containing the topology
type whose retention policies you want to delete, select the check box on the left
of the Topology Type—Property Name column.
Tip To quickly select all periods defined for a property or type, select the check box in the
left-most column of the row containing that property or type. This causes all of the
periods of the selected property or type to be selected.
Working with Data 683
Managing Retention Policies

Selecting a topology type causes all of its periods to be selected

Selecting a property causes all of its periods to be selected

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.

3 Click the Delete Selected button at the bottom.


The Retention Policy Confirmation dialog box appears, asking you to confirm
the delete operation.
684 Foglight
Administration and Configuration Guide

4 In the Retention Policy Confirmation dialog box, click OK.


5 The Retention Policy Confirmation dialog box closes and the Manage
Retention Policies dashboard refreshes, no longer showing the newly-deleted
sampling periods.
Working with Data 685
Managing Retention Policies

Viewing the Hierarchy of Topology Types in the Database


Schema
Before you get started with editing retention policies, you need to identify the correct
topology type whose retention policies you want to edit. When you set a retention policy
for a topology type, the ancestors of that topology type inherit the newly-set retention
policy. It is therefore important to identify the ancestors of the topology type before
editing its retention policies.
The Manage Retention Policies dashboard lists all of the available topology types that
exists in the database schema and their properties but does not provide information on
their position in the schema, such as their ancestors, descendants, or object instances. To
identify the ancestors of a particular topology type, use the Schema Browser dashboard.
In addition to topology type ancestors, the Schema Browser dashboard can show the
properties, descendants, and instances for each topology type. For complete information
about the Schema Browser dashboard, see the Foglight User Guide.
Figure 5

List of topology types in the Manage Retention Policies Dashboard


686 Foglight
Administration and Configuration Guide

Figure 6

Ancestors of a topology type in the Schema Browser

To view the hierarchy of a topology type:


1 Ensure that the navigation panel is open.
To open the navigation panel, click the right-facing arrow on the left.
2 On the navigation panel, under Dashboards, choose Foglight > Schema >
Schema Browser.
The Schema Browser dashboard appears in the display area, and the Schema
Selector appears in the navigation panes
Working with Data 687
Managing Retention Policies

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.

Editing Retention Policies


The Manage Retention Policies dashboard allows you to edit an existing retention
policy period. If a topology type directly references the default data storage cycle, such
as the TopologyObject super-type, its retention policies cannot be modified. The
default data storage cycle can be adjusted using the Data Management dashboard. In
addition to associating the default monitoring policies with data storage cycles, this
dashboard allows you to inspect the topology objects and to delete them by applying
specific retention policies to the collected data, or to purge specific data objects as
required. For more information about this dashboard, see the Foglight User Guide.
Working with Data 689
Managing Retention Policies

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.

a On the Manage Retention Policies dashboard, in the Topology Type—


Property Name column, click the row containing the topology type that has
inherited policies.
The Add Retention Policy dialog box appears.
690 Foglight
Administration and Configuration Guide

b In the Add Retention Policy dialog box, click Save.


Tip Saving the inherited settings without making any changes to them converts an
inherited policy to a custom one.

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.

2 On the Manage Retention Policies dashboard, navigate to the topology type or


property whose retention policy you want to edit.
Topology types are listed in alphabetical order. To navigate to a desired type, use
the cartridge filter, page navigation controls, or change the number of table
entries, as required.
Working with Data 691
Managing Retention Policies

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

5 Edit the age of a retention policy period.


Choose a period and click its Age column.
The Edit Retention Policy Period dialog box appears.

6 Edit the existing data sampling period.


In the Edit Retention Policy Period dialog box, in the After column, specify the
duration and the measurement unit of the data sampling period. For example: 16
min.
7 Edit the existing roll-up period or configure the retention policy to purge the data.
In the Roll-up to column, specify the duration and the measurement unit of the
roll-up period. For example: 1 hour.
If you want the data to purge after the retention period, click the box on the right
and select purge from the list that appears.
8 Click Save.
Working with Data 693
Managing Retention Policies

The Edit Retention Policy Period dialog box closes and a message appears in
the upper-left, indicating the success of the edit operation.

9 Observe the Manage Retention Policies dashboard.


The newly-edited retention and roll-up periods appear in the list.

Creating Retention Policies


You can create new retention policies for the topology types listed in the table on the
Manage Retention Policies dashboard.
The super-type, TopologyObject, has a set of default retention policies that directly
reference the default data storage cycle. You cannot create additional policies for this
type. The default data storage cycle can be adjusted using the Data Management
dashboard. In addition to associating the default monitoring policies with data storage
cycles, this dashboard allows you to inspect the topology objects and to delete them by
applying specific retention policies to the collected data, or to purge specific data
objects as required.For more information about this 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 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

modified to include additional policies. However, adding a new policy to a set of


inherited default policies converts all of the type’s policies to custom.
To create a retention policy:

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

3 Add a data sampling period.


In the Add Retention Policy dialog box, in the After column, specify the
duration and the measurement unit of the data sampling period. For example: 20
min.
4 Add a roll-up period or configure the retention policy to purge the data.
In the Roll-up to column, specify the duration and the measurement unit of the
roll-up period. For example: 1 hour.
If you want the data to purge after the retention period, click the box on the right
and select purge from the list that appears.
5 To add another retention period, click the plus button ( ).
Another row appears in the table, allowing you to specify another set of data
sampling and retention periods.

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

7 Observe the Manage Retention Policies dashboard.


The newly-added data sampling and roll-up periods appear in the list.

Example: Addressing Data Storage Concerns


If you have data storage concerns, you may want to increase the default aggregation
periods or purge times. For example, the following settings will create a large data set:
after 15 minutes—roll up to 15 minutes
after 1 year—purge
The following example uses a one-day granularity, and therefore a smaller data set is
retained:
after 15 minutes—roll up to 15 minutes
after 1 week—roll up to 1 day
after 1 year—purge

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

Enabling the Collection of Data with Older Timestamps


By default, the Foglight Management Server accepts only the data that is collected
within one hour from the moment it is received. The one-hour window allows the server
to accept the data that agents collect during such short-term disruptions. When the
connection with the server is lost, Foglight agents continue to collect and store data
from monitored hosts, and forward that data to the server when the connection is
restored without any additional configuration of the agents or agent manager
components.
This feature is useful in situations when an agent temporarily loses a connection with
the server. However, in some situations, such as a longer-term network outage, you may
need to increase the one-hour time window to prevent the Foglight Management Server
to discard the data with timestamps that are older than one hour.
The length of that time window can be controlled with a virtual machine (VM) option,
foglight.data_service.max_past_timestamp_delta. Add this option to the
configuration file <foglight_home>/config/foglight.config to change the length of the
store-and-forward period in milliseconds.
Any data with older timestamps that is received and accepted by the Foglight
Management Server triggers data-driven rules and derived metrics. Time-driven rules
do not re-evaluate data with older timestamps, even if that data meets their conditions
and would cause them to fire if collected in real-time. For more information about rule
triggers, see Chapter 7, “Triggering rules” on page 438.
To enable the collection of data with older timestamps:
1 On the computer on which the Foglight Management Server is installed, locate
the <foglight_home>/config/foglight.config file and open it for editing.
2 In the foglight.config file, locate the following line of code:
# Uncomment the following lines starting with option0 to
adjust VM settings
Following the above line is a list of VM options, some of which may or may not
be used. A default installation does not have any of the VM options set:
#
# foglight.vm.option0 = "";
# foglight.vm.option1 = "";
# ...
# foglight.vm.option99 = "";
#
698 Foglight
Administration and Configuration Guide

3 Find an unused VM option and set it to a desired length in milliseconds.


a Remove the comment marker from the beginning of the line.
b Insert the foglight.data_service.max_past_timestamp_delta
option and the length of the store and forward period between the quotation
marks.
For example, to set the store and forward period to 8 hours, you should set the
foglight.data_service.max_past_timestamp_delta option to
28,800,000 milliseconds:
8 hours = 8 hours * 60 minutes * 60 seconds * 1,000 = 28,800,000
milliseconds
For example:
foglight.vm.option0="-Dfoglight.data_service.
max_past_timestamp_delta=28800000";
4 Save your changes.
Important In order for the changes to take effect, you need to restart the Foglight
Management Server.
10
Working with Foglight Tooling

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.

This chapter contains the following sections:


About Foglight Tooling ...............................................................................................................700
Building Script Agents ...............................................................................................................700
Retrieving Data with Queries and Scripts..................................................................................721
Merging Host Objects ................................................................................................................725
700 Foglight
Administration and Configuration Guide

About Foglight Tooling


The Foglight Management Server collects data from your monitored system and
organizes that data into a topology model. Each topology model is comprised of nodes.
The nodes and their relationship in the topology model represent the logical and
physical structure of the entities in your monitored environment. Furthermore, each
topology model includes a set of topology types to describe the nodes, or topology
objects, in that model.
The topology types that exist in your environment depend on the nature and complexity
of your monitoring environment and the type of Foglight cartridges and their agents that
you use to collect information from monitored hosts.
In addition to a wide offering of Foglight cartridges for a number of different
environment types, your business scenario may require additional custom agents.
Foglight allows you to add one or more script-based custom agents to address your
unique monitoring needs. For more information, see “Building Script Agents” on
page 700.
Furthermore, Foglight uses the query language that allows you to drill through the
topology model and select topology objects as required. You interact with the query
language when specifying rule conditions, derived metrics, and other Foglight entities.
You can take advantage of the query language to select a range of topology objects and
run a script against those objects to retrieve instant results. For more information, see
“Retrieving Data with Queries and Scripts” on page 721.

Building Script Agents


Custom script agents interact with the Foglight Agent Manager through the Foglight
collector executable. You can use any scripting language to write your scripts. Script-
based custom agents output to standard output (stdout) and the Foglight collector
reads the data and retransmits it to the Foglight Agent Manager.
There are two types of Script Agents:
• Type 1 scripts. The Foglight collector calls these scripts every time they need to
collect data. In Type 1 scripts, the collector executes the script, then stands by for
a time period specified in the agent properties. When the standby period ends, the
collector becomes active and reruns the script. Type 1 scripts are useful for
collecting data that does not require calculations from multiple collection periods.
Working with Foglight Tooling 701
Building Script Agents

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

Looking at the Script Syntax


When writing a script to create a custom agent, use the following syntax:
702 Foglight
Administration and Configuration Guide

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.

Script Element Definition

END_SAMPLE_PERIOD Sends the current collection sample to the database


and completes the transaction.
END_TABLE Closes the table.

field_name Contains the name of the field under which to store


the observation.

id Indicates that the property should be treated as an


identity.
LOG message Sends a status message to Foglight Agent Manager
logs with message specifying the message.
Working with Foglight Tooling 703
Building Script Agents

Script Element Definition

LOG severity message Sends an error message to Foglight Agent Manager


logs with message specifying the message and
severity set to one of the following values: FATAL,
WARNING, or CRITICAL.

NEXT_SAMPLE Sends multiple rows of field data in a single


transaction.

obs Indicates that the specified topology type is an


observation (such as StringObservation).
SLEEP sample_freq In Type 2 scripts, this element ends the script and
instructs the collector to wait for the specified time
before executing the script again.
Note In NT operating systems, use the rapssleep
command, as those systems do not have a sleep
facility:
rapssleep %sample_freq%

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.

type Specifies the topology type if it is not a metric.

unit Contains the name of the measurement unit to use for


metrics. If a unit is not specified, Foglight uses
“count” as the unit by default.

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

Accessing the Build Script Agent Dashboard


When you finish your script, navigate to the Build Script Agent dashboard. The Build
Script Agent dashboard allows you to upload an agent script to the Foglight
Management Server.
To access the Build Script Agent dashboard:

Note This procedure continues from “Logging in to Foglight” on page 22.

1 Ensure that the navigation panel is open.


To open the navigation panel, click the right-facing arrow on the left.
2 On the navigation panel, under Dashboards, choose Administration > Tooling
> Build Script Agent.
The Build Script Agent dashboard appears in the display area.

From here, you can go to “Uploading Agent Scripts and Building Agent Packages” on
page 705.
Working with Foglight Tooling 705
Building Script Agents

Uploading Agent Scripts and Building Agent Packages


Once you finish your script and get started with the Build Script Agent dashboard, you
can upload your script to the Foglight Management Server and build the agent package.
To upload an agent script:

Note This procedure continues from “Accessing the Build Script Agent Dashboard” on page 704.

1 Ensure that your agent script is valid and complete.


For information about the script syntax, see “Looking at the Script Syntax” on
page 701.
2 Locate your agent script.
In the Build Script Agent dashboard, click Browse.
Navigate to your script using the file browser that appears. When you close the
file browser and return to the Build Script Agent dashboard, the Upload Script
box refreshes, showing the path and name of the script file while the Script
Version boxes show the version number.

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.

Deploying Script Agent Packages


When you successfully upload the agent script and build the agent package, you can
deploy that package to the Foglight Agent Manager. Package deployment is identical to
the process you use to deploy any other agent package. One thing you need to pay
attention to is the package name and version: use the same name and version number
that you specify when uploading and building the package.
Use the Agent Status area in the Build Script Agent dashboard to deploy a script agent.
Alternatively, you can deploy the package using the command line. For complete
information on agent package deployment, see Chapter 6, “Deploying Agent Packages
to a Monitored Host” on page 312.
To deploy a script agent package:

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

For example: MyScriptAgent-1.2.0


4 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.
710 Foglight
Administration and Configuration Guide

5 Click OK to close the Deploy Agent Package dialog box.


From here, you can proceed to “Creating and Activating Script Agent Instances” on
page 710.

Creating and Activating Script Agent Instances


Once you have successfully deployed the package containing the script agent, you can
create one or more instances of your custom script agent. Instance creation is identical
to the process you use to create agent instances of any other type. However, you need to
ensure that the agent type you choose matches the one you build and deploy.
Use the Agent Status area in the Build Script Agent dashboard to create one or more
instances of your script agent. Alternatively, you can create agent instances using the
command line. For complete information on agent instance creation, see Chapter 6,
“Creating Agent Instances on a Monitored Host” on page 320.
To create and activate a script agent instance:

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

The Agent Status dashboard, refreshes, showing the newly-created agent


instance.

6 Activate the newly-added script agent instance.


a In the Agent Status list, select the row containing the script agent instance and
click Activate.
The Agent Operation dialog box appears, showing the status of the activation
process.
Working with Foglight Tooling 715
Building Script Agents

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

b In the Agent Operation dialog box, click OK.


The Agent Operation dialog box closes and the Agent Status area refreshes,
showing the Activated icon ( ) and Collecting Data icon ( ) in the row
containing the script agent indicating that the agent is active and collecting
data.

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

Editing Script Agent Properties


In some cases you might need to edit the properties of the newly-created script agent.
For example, Type 1 script agents control their standby periods using agent properties.
For more information, see “Building Script Agents” on page 700 and “Example: Type 1
Script” on page 719.
Use the Agent Status area in the Build Script Agent dashboard to begin editing agent
properties. For complete information on editing agent properties, see Chapter 6,
“Editing Agent Properties by Agent Instance” on page 296.
To edit the properties of a script agent:

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.

3 Click Modify these properties for this agent only.


The boxes in the agent properties area become enabled for editing.

4 In the agent properties area, edit the script agent properties as required.
Working with Foglight Tooling 719
Building Script Agents

5 Save your changes.


Click Save.
The Build Script Agent dashboard refreshes, showing a list of all agent instances.

Example: Type 1 Script


The following is an example of a Type I script:

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

Example: Type 2 Script


The following is an example of a Type II script:

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

echo stringObs.StringObservation.obs = abc


echo END_SAMPLE_PERIOD
echo END_TABLE
"../bin/rapssleep" %sample_freq%
goto :Loop
:EXIT

Retrieving Data with Queries and Scripts


Foglight query language allows you to drill down through the topology model in your
monitoring environment and retrieve data objects as required. Use the query language to
select one or more topology objects and run scripts against them to retrieve desired
results. For more information about the query language and its syntax, see “Using the
Query Language” on page 763.
You may be required to run scripts at the request of Quest Support or for other
maintenance functions. You can also test sample scripts from this window. This tool has
no restrictions, but is recommended for advanced users.
Use the Script Editor dashboard to display the instances of particular topology types in
your monitoring environment, and drill down through their objects to see detailed
information on each type. For instructions, see the following sections:
• “Accessing the Script Editor Dashboard” on page 721
• “Selecting Topology Objects” on page 722
• “Retrieving Data” on page 725

Accessing the Script Editor Dashboard


The Script Editor dashboard allows you to select topology objects that exist in your
monitoring environment and retrieve information about those objects.
To access the Script Editor dashboard:

Note This procedure continues from “Logging in to Foglight” on page 22.

1 Ensure that the navigation panel is open.


To open the navigation panel, click the right-facing arrow on the left.
722 Foglight
Administration and Configuration Guide

2 On the navigation panel, under Dashboards, choose Administration > Tooling


> Script Editor.
The Script Editor dashboard appears in the display area.

From here, you can go to “Selecting Topology Objects” on page 722.

Selecting Topology Objects


Once you access the Script Editor dashboard, you can use it to select the objects of a
particular topology type and view the data that they contain. When you select topology
objects, use the Query button to display the following information about a selected
topology type:
• Instances
Working with Foglight Tooling 723
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.

1 Select a topology type whose objects you want to query.


In the Script Editor dashboard, click Query, and select a topology type from the
list that appears. For example, to select all objects of the Host topology type,
select Host.
2 List all instances of the selected topology type.
Click List Instances.
The Instances area refreshes, showing all instances of the selected topology type
and also any objects whose type is inherited from the selected topology type. For
example, if you selected the Host topology type, the Instances area lists all
object instances of that type, showing the following information for each
topology object:
• Topology object ID
• Topology type
• Instance name.
724 Foglight
Administration and Configuration Guide

Topology object ID Topology type Instance name

3 View information about one of the listed topology objects.


In the Instances box, click a topology object ID.
The Object ID, Object Type Hierarchy, and Object Properties boxes refresh,
showing the information about the selected topology object instance.

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.

Merging Host Objects


Merging two or more hosts refers to the ability to consolidate data for those host objects
using host aliasing rules.A host aliasing rule includes one or more property matching
filters that select the topology objects that are to be merged, along with the logical
definition of the merge operation. 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 types, view the Schema Browser
dashboard; for more information about this dashboard, see the Foglight User Guide.
There are two types of host aliasing rules:
726 Foglight
Administration and Configuration Guide

• 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

Managing Host Aliasing Rules


Use the Manage Host Aliasing Rules dashboard to edit the priorities of host aliasing
rules, or to rename or delete host aliasing rules as required. For complete information,
see the following sections:
• “Accessing the Manage Host Aliasing Rules dashboard” on page 727
• “Changing the priorities of host aliasing rules” on page 730
• “Renaming host aliasing rules” on page 732
• “Deleting host aliasing rules” on page 734

Accessing the Manage Host Aliasing Rules dashboard


The Manage Host Aliasing Rules dashboard allows you to manage the existing host
merging rules, or to create new ones.
To access the Manage Host Aliasing Rules dashboard:

Note This procedure continues from “Logging in to Foglight” on page 22.

1 Ensure that the navigation panel is open.


To open the navigation panel, click the right-facing arrow on the left.
2 On the navigation panel, under Dashboards, choose Administration > Tooling
> Manage Host Aliasing Rules.
The Manage Host Aliasing Rules dashboard appears in the display area.
728 Foglight
Administration and Configuration Guide

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.

c To clear the filters, click Clear.


The Manage Host Aliasing Rules dashboard refreshes, showing the list of all
host aliasing rules.
730 Foglight
Administration and Configuration Guide

From here, you can proceed to any of the following procedures:


• “Managing Host Aliasing Rules” on page 727
• “Creating Host Aliasing Rules” on page 735

Changing the priorities of host aliasing rules


Each host aliasing rule has a priority assigned to it. The Foglight Management Server
processes host aliasing rules in the order of their priority, with the rules with higher
priority being executed first.
The rule priority is specified at the final step of rule creation. By default, Foglight
assigns the lowest priority to a new rule. This value can be changed during or after they
are added. This section explains the process of changing the priority of the existing rules
in the Manage Host Aliasing Rules dashboard. For more information about changing the
rule priority at creation time, see the appropriate section in “Creating Host Aliasing
Rules” on page 735.
Simple merging rules can have their priority changed after their creation. Advanced
merging rules consist of a group of individual rules that are executed in a pre-defined
order. It is possible to change the group priority, but not the priority of an individual rule
within the group. For example, an advanced rule has the group priority of 4.0, and it
consists of two individual rules, with their priorities set to 4.1 and 4.2 by default.
While the priority of the rules within the group cannot be changed, increasing the group
priority to 3.0 automatically increases the priority of the rules it is comprised of to 3.1
and 3.2.
Working with Foglight Tooling 731
Merging Host Objects

Figure 2

Priority of simple merging rules


Priority of advanced merging rules
Priorities of individual rules
within a group

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

A 2.0 None 2.0

B 3.0 Decrease by 1.0 4.0

C 4.0 None 3.0

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:

2 In that row, click the Priority column.


A dwell appears, allowing you to specify the rule priority.

3 In the dwell, change the rule priority, as required.


Important Changing a rule priority can affect the order in which other rules are executed.
Specifying a priority value that is already associated with another rule can change the
priority of that rule, moving it up or down the priority list.

• Use the arrow buttons to increase or decrease the priority indicator.


Clicking an arrow button once changes the priority indicator by one (1.0).
or
• In the Custom Priority box, type the rule priority, and click Apply.
Important This value must be a valid integer number.

The dwell closes, and the list of rules in the Manage Host Aliasing dashboard
refreshes, showing the newly-updated rule priority.

Renaming host aliasing rules


The Brief Description column on the Manage Host Aliasing Rules dashboard contains
rule names. Both simple and advanced merging rules can have their names changed, as
well as the individual rules that are a part of a group (advanced merging rules).
Working with Foglight Tooling 733
Merging Host Objects

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

Controls for renaming host


aliasing rules

To rename 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 rename.
2 In that row, click the Rename column .
The Change Rule Display Name Form dialog box appears.

3 Specify the new rule name.


In the Change Rule Display Name Form dialog box, in the New Name box,
type the new rule name as you want it to appear on the Manage Host Aliasing
dashboard, and click Rename.
The Change Rule Display Name Form dialog box closes, and the list of rules in
the Manage Host Aliasing dashboard refreshes, showing the newly-updated rule
name.
734 Foglight
Administration and Configuration Guide

Deleting host aliasing rules


Both simple and advanced merging rules can be deleted, as well as individual rules that
are a part of a group (advanced merging rules). For more information about the
differences between simple and advanced merging rules, see “Merging Host Objects”
on page 725.

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.

4 Confirm the delete operation.


In the Confirm Delete dialog box, click Yes.
The Confirm Delete dialog box closes, and the list of rules in the Manage Host
Aliasing dashboard refreshes, no longer showing the newly-deleted rule.
Working with Foglight Tooling 735
Merging Host Objects

Creating Host Aliasing Rules


Creating a host aliasing rule is the process of creating property matching filters that
select one or more host objects, and specifying a logical definition of the merge
operation to either merge existing objects, or to create new ones. This is useful in
situations when the regular merging process does not have information to match data
objects as they are collected.

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

Links to workflows for creating rules that::

Rename or change other host properties


Merge hosts

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

1 On the Manage Host Aliasing Rules dashboard, click .


The New Merging Rule Introduction dialog box appears.

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:

To Click For more information, see

Merge two host Create a focused rule for “Merging host objects” on
objects a single host page 738

Change the name or Create a broad rule “Changing the names or


another property of which works with many other host properties” on
one or more host hosts page 745
objects

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.

Merging host objects


Merging one host object with another consolidates the data collected by a source host
under a target host. This process involves creating property matching filters to select the
source and target hosts, and specifying a logical definition of the merge operation to
merge the source host with the target host. This is useful in situations when the regular
merging process does not have information to match data objects as they are collected.

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

Specify Target Host page in the Host Aliasing dialog box

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.

1 Specify a target host object using a particular property value.


a Ensure that the property you want to use for matching the host is selected. By
default, in the Host Aliasing dialog box, the name property appears selected.

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

mytargethost.mydomain.com, with the name property selected (Name:


String, see step a), type mytargethost.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.

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.

c In the Host Aliasing dialog box, click Next.


The Host Aliasing dialog box refreshes, showing the Specify Source Host
page.
742 Foglight
Administration and Configuration Guide

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.

b In the Host Aliasing dialog box, click Next.


The Host Aliasing dialog box refreshes, showing the Summary page.
744 Foglight
Administration and Configuration Guide

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.

c In the Summary page, review the overview of the merge process.


Tip To select different hosts, use the Previous button to return to a previous page, as
required.

d In the Host Aliasing dialog box, click Finish.


The Host Aliasing dialog box closes, and the Successful message box
appears, indicating a success.
Working with Foglight Tooling 745
Merging Host Objects

e Click Ok to close the message box.


The Manage Host Aliasing Rules dashboard refreshes, showing the newly-
added rule.

Changing the names or other host properties


Changing the name or another property of one or more host objects can be done using
literal or regular expressions. This process involves creating filters to select one or more
hosts whose properties are to be changed, and specifying an expression the property is
to be replaced with.

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

Specify Matching Parameters page in the Host Aliasing dialog box

From there, you specify the current and target names, and review the summary of the
merge process, as described below.

To Select this option and click Next For instructions, see

Remove characters Remove characters from the “To remove characters


from the end of host end of a host name from the end of host
names names:” on page 747

Replace characters in Replace characters in a host “To replace characters in


host names name host names:” on page 750

Use a regular Use a regular expression to “To use a regular


expression to rename convert a host name expression to rename
hosts hosts:” on page 753

Change other host Merge hosts by a property “To change host


properties other than name properties:” on page 757
Working with Foglight Tooling 747
Merging Host Objects

To remove characters from the end of host names:

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.

2 Select one or more hosts that you want to rename.


In the Host Aliasing dialog box, in the Host Names start with box, type a literal
expression containing one or more starting characters of the host name.
For example:
748 Foglight
Administration and Configuration Guide

Host Select this Expression Host


host? Selected?

my_host_1.company_a.com Yes my_host Yes

my_host_2.company_b.com Yes Yes

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:

Selected host Truncate Expression Host name


host name? truncated?

my_host_1.company_a.com Yes company_a.com Yes

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.

4 In the Host Aliasing dialog box, click Finish.


The Host Aliasing dialog box closes, and the Successful message box appears,
indicating a success.

5 Click Ok to close the message box.


The Manage Host Aliasing Rules dashboard refreshes, showing the newly-added
rule.
To replace characters in host names:

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.

2 Select one or more hosts that you want to rename.


In the Host Aliasing dialog box, in the Find box, type a literal expression that
you want to replace.
For example:

Host Select this Expression Host


host? Selected?

my_host_1.company_a.com Yes company_ Yes

my_host_2.company_b.com Yes Yes

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:

Selected host Replace Expression Characters


characters in in the host
the host name
name? replaced?

my_host_1.company_a.com Yes my_company Yes

my_host_2.company_b.com Yes Yes

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.

4 In the Host Aliasing dialog box, click Finish.


The Host Aliasing dialog box closes, and the Successful message box appears,
indicating a success.

5 Click Ok to close the message box.


The Manage Host Aliasing Rules dashboard refreshes, showing the newly-added
rule.
To use a regular expression to rename hosts:

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.

2 Select one or more hosts that you want to rename.


In the Host Aliasing dialog box, in the Regular Expression box, type a regular
expression that selects the host names that you want to replace.
For example:
Working with Foglight Tooling 755
Merging Host Objects

Host Select this Expression Host


host? Selected?

my_host_1.company_a.com Yes my_host* Yes

my_host_2.company_b.com Yes Yes

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:

Selected host Rename Expression Characters


host? in the host
name
replaced?

my_host_1.company_a.com Yes my_test_host Yes

my_host_2.company_b.com Yes Yes

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.

4 In the Host Aliasing dialog box, click Finish.


The Host Aliasing dialog box closes, and the Successful message box appears,
indicating a success.
Working with Foglight Tooling 757
Merging Host Objects

5 Click Ok to close the message box.


The Manage Host Aliasing Rules dashboard refreshes, showing the newly-added
rule.
To change host properties:

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

2 Specify the property whose value you want to change.


a In the Host Aliasing dialog box, click Select a Property.
A list appears, showing only those properties that can be changed.

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.

3 Select one or more hosts that you want to rename.


Working with Foglight Tooling 759
Merging Host Objects

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:

Host Select this Expression Host


host? Selected?

myhost_a.xyz.mydomain.com Yes (xyz.*)\.my Yes


domain.com
myhost_b.xyz.mydomain.com Yes Yes

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:

Selected host Rename Expression Characters


host in the host
property? name
replaced?

myhost_a.xyz.mydomain.com Yes $1.quest.com Yes

myhost_b.xyz.mydomain.com Yes Yes

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.

5 In the Host Aliasing dialog box, click Finish.


The Host Aliasing dialog box closes, and the Successful message box appears,
indicating a success.
Working with Foglight Tooling 761
Merging Host Objects

6 Click Ok to close the message box.


The Manage Host Aliasing Rules dashboard refreshes, showing the newly-added
rule.
762 Foglight
Administration and Configuration Guide
11
Using the Query Language

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

About the Query Language


Foglight gathers data from host systems and dynamically builds topology models at run-
time from the collected data. A topology model is a graph that contains topology nodes.
Each node represents an object instance of a topology type. The structure of the
topology model and the range of topology types that exist in your monitoring
environment reflect its nature and complexity.
For example, if you use Foglight to monitor JavaEE applications, in addition to the core
topology types that come with a basic installation of the Foglight Management Server,
your system includes the topology types that come with the Foglight Cartridge for
JavaEE. Furthermore, the structure and contents of your topology model reflect the
entities in your monitoring environment, including any hosts that you monitor and the
type of data or metrics that they collect.
Queries in rule and derived metric definitions allow you to target a specific subset of the
topology model. When you define the subset of the topology model that you want to
evaluate, you can write a script to implement your business logic in rule and derived
metric definitions.
The browser interface provides a number of dashboards that you can use to get detailed
information about the topology model, existing topology types, their properties, and
relationships. For more information, see “Viewing Topology Models” on page 764 and
“Viewing Topology Types” on page 767. For query language syntax rules and usage
examples, see “Query Language Reference” on page 773.

Viewing Topology Models


Foglight collects data from host systems and uses that data to build topology models at
run-time. Each monitoring environment can include one or more topology models.
Their structure and complexity depend on the type of the systems you monitor and the
range of installed cartridges. The basic building blocks of each topology model are
nodes, that represent object instances, and their relationships.
In the browser interface, the Data dashboard illustrates the dynamically-built topology
model, showing their nodes and the relationships between the nodes. You can use it to
better understand the collected data, before getting started with queries and scripts.
To view the structure of the topology model:

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.

1 In the browser interface, ensure that the navigation panel is open.


To open the navigation panel, click the right-facing arrow on the left.
2 On the navigation panel, under Dashboards, choose Configuration > Data.
The Data dashboard appears in the display area.

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

4 View a collection of metrics collected for the selected host.


Tip Metric properties are of the Metric data type.

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.

Viewing Topology Types


Foglight topology models are comprised of nodes. Each node in a topology model is an
instance of a topology type. The connections between nodes in a model illustrate the
relationships between object instances and the logical or physical entities that these
nodes represent.
768 Foglight
Administration and Configuration Guide

Each monitoring environment includes a collection of topology types.A basic


installation of the Foglight Management Server includes a set of core topology types;
while each cartridge adds to that collection as required.
In the browser interface, the Schema Browser dashboard shows the topology types and
allows you to view the parent-child relationships, properties, and instances for each
topology type. Use this dashboard as a reference point while you write scripts and
queries.
Figure 1

To view the details of a topology type in the database schema:

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.

1 In the browser interface, ensure that the navigation panel is open.


To open the navigation panel, click the right-facing arrow on the left.
2 On the navigation panel, under Dashboards, choose Foglight > Schema >
Schema Browser.
Using the Query Language 769
About the Query Language

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

The View by menu contains the following options: Properties, Ancestors,


Descendants, Instances, each allowing you to view the properties, ancestors,
descendants, and instances, respectively, of the selected topology type.
When you select a type in the upper pane, one of these options appears selected,
showing the corresponding details in the Details of Type pane.
6 View the details of a topology type.
• To view the properties of the selected topology type, in the View by menu of
the Details pane, ensure that the Properties option is selected.
Using the Query Language 771
About the Query Language

• 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.

Query Language Reference


The Query Service enables other Foglight services to make queries about metrics and
topology objects in a custom query language. This service is not really part of the
Topology Service because a query may contain specifications outside the domain of the
Topology Service. In these cases the Query Service does a complete parse of the query,
sends the Topology Service parts to the Topology Service and presents the rest of the
parse to the Query Service user.

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

queryTopologyObjects(topologyQuery, Retrieve the set of topology objects from


scopingObject); the Topology Service, with respect to the
current scoping object. If there is no
queryTopologyObjects(topologyQuery); current scoping object, for example if you
are querying for the scoping set of a rule,
use the method that runs without a scoping
definition.

queryObservations(observationQuery) Retrieves a set of metrics.

queryObservations(observationQuery, Retrieves a set of metrics for a query with


scopingObject) respect to an identified scoping topology
object.

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

(EJBInstance where name=’inst1-1’ and application =’app1-1-


uniqueId’)
The query language also supports ‘or’ and precedence with parentheses.
(EJBInstance where name=’inst1-1’ and (application = ’app1-1-
uniqueId’ or application = ’app2-2-uniqueId’))
The ‘and’ and ‘or’ keywords have convenient shortcuts. In place of an ‘and’ you can use
‘&’ or ‘&&’ and in place of an ‘or’ you can use ‘|’ or ‘||’. There is also an alternative
syntax for not equals (‘!=’), which is ‘<>’.
So far, we have only used exact string matching. We can also use limited regular
expressions with the like operator. To get all the EJBInstances where the name starts
with “inst”, write the following query:
!EJBInstance : name matches 'inst.*'
Besides the percent sign ‘%’, the other regular expression element that you can use is
the underscore '_', which is a required match to any character.
You can also ask for an exact match from within a set of strings.
(EJBInstance where name in {’inst1-1’,’inst2-3’} )

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%’)

How to write fast topology queries


It is worthwhile knowing how the Query Service works in order to write fast queries.
Let’s examine how a query is evaluated.
!EJBInstance : name = ‘inst1-1’
When the Query Service evaluates this, it first retrieves the set of all EJBInstance
objects, checks each one to see if the name is equal to inst1-1, and finally returns the
subset of objects that actually made the match. Without knowing anything about the
topology, it is impossible to say whether this will complete quickly or slowly. This
Using the Query Language 777
About the Query Language

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

startTime 9/26/2007 14:22

endTime 9/26/2007 14:59

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

invocationTime spanning 1.5 hours starting at 13:00 1 week ago


Time zones can optionally be added to a spanning clause.
invocationTime spanning 1.5 hours starting at 13:00 [PST] 1 week
ago
Examples of acceptable formats for the time zone are: "PST", "America/
Los_Angeles", "GMT-8:00". In general, any of the formats supported by
java.util.TimeZone.getTimeZone() can be handled here.
Instead of asking for a metric over a period of time, you can also single metric at an
instant. It works just like asking for the most recent metric, except the system pretends
that the wall clock is set to the time you have specified. The way you specify wall clock
time is by giving a 24 hour time value and a date. The 24 hour time value is optional and
the date may either be an absolute date or an offset of a number of days, weeks, months
or years into the past. The following examples show the different ways the syntax can
look.
This query takes the most recent metric, pretending that it is 1:00 PM on Monday, May
25.
invocationTime at 13:00 [PST] on 2009-05-25
The use of a 24 hour clock, although preferred, is not mandatory. You can use the
following expression to retrieve the same data set:
invocationTime at 1:00 PM [PST] on 2009-05-25
The following query retrieves the most recent metrics, pretending that it is 1:00pm, 2
days ago:
invocationTime at 13:00 2 days ago
The following query instructs the query engine to take the current wall clock time, apply
it to May 25, and find the most recent metric at that time.
invocationTime on 2009-05-25
And finally, the following query instructs the query engine to take the current wall clock
time from 2 days ago, and find the most recent metric at that time.
invocationTime 2 days ago
Although the last two forms of query exist for completeness sake, they are not thought
to be useful in a typical business scenario.
Using the Query Language 781
About the Query Language

Using abstract graphs to form queries


The topology can be thought of as a directed graph with nodes representing topology
objects and edges representing topology property relations. This section shows how to
form queries on an abstract graph regardless of how properties are set up, or in the
abstract world, edge direction. In the following graphs, it is assumed that a property of
name ‘x’ (lower case) is of type ‘X’ (upper case).
Consider a topology type ‘B’ that has an observation property ‘a’ and a regular property
‘c’. ‘c’ has a property ‘d’ that is a String. The graph for a topology object ‘b’ of the
topology type ‘B’ looks like this:
Figure 2

In the following queries, we will be retrieving ‘a’ using an important qualifier


consisting of a literal matching pattern between the 'd' property and the 'd' literal value
(d = 'd'). In the folowing examples, note how the positions of the nodes in each graph
are the same, while the edge directions are different.

Graph Query

‘a’ contains an observation

a from B where c.d = ‘d’

Explanation:
This query filters all topology objects of 'B'
type and retrieves their 'a' observations.
782 Foglight
Administration and Configuration Guide

Graph Query

a from (C where d = ‘d’).b

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.

‘a’ contains a topology object or an object property

(B where c.d = ‘d’).a

Explanation:
The query filters all topology objects of
type 'B' and then retrieves the ‘a’ objects
from that set of ‘b’ properties.

A where b.c.d = ‘d’

Explanation:
The query filters all topology objects of
type 'A'.

A where b in (C where d = ‘d’).b

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

Using the Query Language to Set the Rule or Derived


Metric Scope
The scope of a rule defines the set of topology objects against which it will run. The
scope of a derived metric defines the set of topology objects to which it applies. A rule
or derived metric must be scoped to a topology type and can optionally be scoped to
specific instances of that type (topology objects). If a rule or derived metric is not
scoped to specific objects, it applies to all objects of that type.
You specify the scope for a rule or derived metric using the query language. The
expression that sets the rule or derived metric scope is called a scoping query. For more
information, see “Setting the Scope for a Rule or Derived Metric” on page 784.

Setting the Scope for a Rule or Derived Metric


Foglight provides controls that allow you to insert the topology type, specific topology
objects, properties of the topology type, and syntactic elements of the scoping query
into the scoping expression.
You can use the controls described below to build the scoping query. You can also
specify all or part of the rule or derived metric scope manually. See “Specifying the
scoping query manually” on page 789 for examples of the syntax that must be used in a
scoping query.

Note The Rule Scope and Derived Metric Scope fields are case-sensitive.

Inserting topology types


A rule or derived metric can be scoped to a topology type.
To insert the topology type into a scoping query:
1 Click Topology Type and select a topology type from the list that appears.

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

• Scope down to a property of the selected topology type by proceeding to


“Inserting topology type property names” on page 785.
or
• Validate the rule scope by clicking the Validate Scope button ( ) to the right
of the Property box.
If the scope is valid, a confirmation message appears above the Topology
Type box while the name of the newly-selected topology type appears in the
box at the bottom.

Note You must select a topology type before you can use the Property drop-down menu or
launch the Scoping Query Editor.

Inserting topology type property names


You can optionally specify that a rule or derived metric be scoped to instances to the
selected topology type with a particular property value.
To insert a topology type property name into a scoping query:

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.

c Click the Append button ( ) to the right of the Property box.


786 Foglight
Administration and Configuration Guide

The name of the newly-selected property appears in the expression immediately


below the Property box.
3 Specify the property value for which you want to query.
In the above expression, select value and replace it with the property value.
4 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.

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.

Restricting the scope to topology objects


When you select a topology type, use the Scoping Query Editor dialog box to narrow
down the scope for a rule or derived metric. The controls in this dialog allow you to
select an instance of a topology type insert them into the scoping expression as required.
To open the Scoping Query Editor dialog box:

Note This procedure continues from “Inserting topology types” on page 784.

1 Click the Scoping Query Editor button ( ).


The Scoping Query Editor dialog box appears.
Using the Query Language 787
Using the Query Language to Set the Rule or Derived Metric Scope

From here, you can proceed to any of the following procedures:


• “Inserting topology object instances” on page 787
• “Filtering through topology type properties” on page 787

Inserting topology object instances


When you specify a topology type, you can select an object instance of that type and
insert it into the scoping query using the Scoping Query Editor dialog box.
To insert a topology object into the scoping query:

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.

Filtering through topology type properties


When you specify a topology type, you can select an object instance of that type using
the type’s property values as a filter and insert the instances whose properties match the
filter into the scoping query using the Scoping Query Editor dialog box.
788 Foglight
Administration and Configuration Guide

To specify topology type properties:

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.

2 To specify a comparison expression, complete the following steps.


a In the Filter tab, click Properties and select a property.
b Click is equal to on the right and select a logical operator from the list that
appears: is equal to, is not equal to, is like, or is not like.
c In the box to the right of the one containing the newly-selected logical
operator, type the property value that you want to use in the filter.
3 If you do not want to add more comparison expressions to the filter, click and on
the right and select the blank entry.
4 If you want to add more expressions to the filter, repeat step 2 and set the logical
operators at the end of each line as required.
Note If you need to define more than three expressions in the filter, you can add them
after closing the Scoping Query Editor dialog box.

5 Click Insert Query.


Using the Query Language 789
Using the Query Language to Set the Rule or Derived Metric Scope

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.

Specifying the scoping query manually


You can use the syntax shown in one of the examples below to manually specify all or
part of the scoping query in the box immediately below the Topology Type and
Property boxes.

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

where TopologyType is the name of the topology type of which Object is an


instance and Object is the specific instance to which you do not want the rule or
derived metric to be scoped.
• You can cause the rule or derived metric to be scoped to all topology objects of a
specific type except those that have names like that of a certain instance by using
the syntax
<TopologyType> where name ! like "%<Object>%"
where TopologyType is the name of the topology type of which the instances
with names like Object are instances. In the example shown above, the %
wildcards cause the rule or derived metric to be scoped to all topology objects (of
the specified type) with names that do not include 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 two named instances by using the syntax
<TopologyType> where name != "<Object1>" or name !=
"<Object2>"
where TopologyType is the name of the topology type of which Object1 and
Object2 are instances; Object1 and Object2 are the instances to which the
rule or derived metric will not be scoped.

Using the Query Language in Rule Conditions or Derived


Metric Expressions
A condition is the part of a rule that is evaluated against monitoring data. When creating
a simple rule or when configuring a severity level for a multiple-severity rule, you must
specify a condition using the query language.
The query language is also used to specify the expression for a derived metric. The
derived metric is calculated based on this expression.
For more information, refer to the following sections:
• “About the Query Language in Rule Expressions and Messages” on page 791
• “Specifying Rule Conditions or Derived Metric Expressions” on page 792
• “Using Functions with Conditions and Expressions” on page 801
Using the Query Language 791
Using the Query Language in Rule Conditions or Derived Metric Expressions

About the Query Language in Rule Expressions and Messages


You can create expressions and messages in the Expression/Message box on the Rule
Variables tab or the Severity Level Variables tab for a rule severity level.
Expressions must be specified using the query language, and the syntax
@expressionName must be used to reference expressions in messages.

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

Specifying Rule Conditions or Derived Metric Expressions


Foglight provides controls above the Condition field (for a rule) or the Expression
field (for a derived metric) that allow you to insert elements into the condition or
expression that are either part of the query language or have been formatted to use the
query language syntax. The process of writing expressions is described in the following
sections:
• “Inserting operators” on page 792
• “Editing conditions and expressions” on page 792
• “Validating conditions or expressions” on page 800

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.

Editing conditions and expressions


The Condition Editor (rules) and Expression Editor (derived metrics) dialog boxes
allow you to insert registry variables, metrics, and Groovy functions into rule conditions
or derived metric expression.
To get started with editing conditions or expressions:

Note This procedure continues from “Inserting operators” on page 792.

• 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

From here, you can proceed to any of the following procedures:


• “Inserting registry variables” on page 793
• “Inserting metrics and topology object properties” on page 794
• “Inserting Groovy functions” on page 797

Inserting registry variables

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.

Inserting metrics and topology object properties


The Metric/Property tab in the Condition Editor (rules) and Expression Editor (derived
metrics) dialog box lists the metrics and topology object properties that are available
based on the scope of the rule or derived metric. This tab allows you to navigate through
lists of topologies, metrics, and instances associated with the rule.
The initial view of this tab lists three groups of topology types:
• Scoping Topology: Shows a single scoping topology type included in this
category. If the rule or derived metric is not scoped, this area is empty.
• Child Topology: Lists the descendents of the scoped topology type.
• Other Topology: Lists the following topology types:
• Core Foglight topologies
• All topology types that belong to the same cartridge containing the rule or
derived metric whose condition or expression you are editing. If the rule or
derived metric does not belong to a cartridge, this area includes all topology
types without a cartridge association.
Using the Query Language 795
Using the Query Language in Rule Conditions or Derived Metric Expressions

• Parent types of the scoping topology type that descend from


TopologyObject.
To insert a metric or property 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 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.

3 Choose a topology type and display its metrics and instances.


Select a topology type from one of the following panes Scoping Topology, Child
Topology, or Other Topology.
796 Foglight
Administration and Configuration Guide

The Metric/Property tab refreshes, showing the instances and metrics for the
selected topology type.

4 Choose a metric or an instance.


The Metric/Property tab displays only two columns at a time, causing the initial
list of topology types to shift to the left. Use the arrow buttons in the upper-left to
navigate through the window. A breadcrumb trail displays the metrics and
properties you have chosen
• To select a metric, in the Metrics pane, click the metric.
Note If you choose a metric, you cannot navigate further in this dialog box.

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.

Inserting Groovy functions


The Function tab in the Condition Editor (rules) and Expression Editor (derived
metrics) dialog box includes controls for inserting Groovy functions into rule conditions
or derived metric expressions. It lists the functions that you can use in conditions and
expressions. The functions that you see on this tab are defined in the Foglight database.

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.

5 Click the Insert button.


The dialog box closes and the Condition (rules) or Expression (derived metrics)
box refreshes, showing the newly-added function.
From here, you can proceed to “Validating conditions or expressions” on page 800T
800 Foglight
Administration and Configuration Guide

Validating conditions or expressions


When you have finished editing the rule condition or derived metric expression, you can
validate its syntax.
To validate a condition or expression:

Note This procedure continues from “Editing conditions and expressions” on page 792.

• Click the Validate button ( ) above the Condition (rules) or Expression


(derived metrics) box.
If the syntax is correct, a success message appears above the Condition (rules) or
Expression (derived metrics) box.
Examples
• You are configuring the Critical severity level for an existing rule that scoped to
all requests with names that include the element jdbc (the rule scope is
RequestType where name like "%jdbc%"). You want an alarm to be fired
for this level if the average execution time (over the last hour) for a request in the
rule scope exceeds the limit set by the registry variable ExecuteTimeCritical.
You select the rule from the Manage Rules dashboard to open it for editing and
use the fields and controls on the Critical pane to create the condition for this
severity level.
After launching the Condition Editor dialog box, open the Function tab and
select avg from the Function Name box. You then specify the argument for the
selected function in the Arg1 field. For example, specify the execution time as an
argument for this function by typing #executionTime for 1 hour# in the
Arg1 field. Then click Insert to insert the function. The function and its
parameter appear in the Condition field.
To complete the condition, you need to insert the appropriate operator and the
registry variable. You place the cursor at the end of the condition and insert the
the greater than ‘>’ operator. In the Condition Editor dialog box, you switch to
the Registry Variable tab, select ExecuteTimeCritical from the list, and click
Insert. The condition appears as follows:
avg(#executionTime for 1
hour#)>registry("ExecuteTimeCritical")

• 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

rules to perform the same function (rate) on the same metric


(#passivationCount#). Instead of doing this manually for each rule, you
decide to create a derived metric that you can use in all of these rules’ conditions.
You use the fields and controls on the Create Derived Metric dashboard (Data >
Create Derived Metric) to create a derived metric expression that calculates the
passivation rate for EJBs.
After launching the Expression Editor dialog box, you open the Function tab
and select rate from the Function Name box. You then specify the argument for
this function in the Arg1 field. For example, specify the passivation count as an
argument for this function by typing #passivationCount# in the Arg1 field.
Then click Insert to insert the function. The function and its parameter appear in
the Condition field.
rate(#passivationCount#)

Using Functions with Conditions and Expressions


Derived metric expressions and rule conditions and expressions are matched against
monitoring data. Foglight can perform functions on this data. Functions cause
calculations to be performed on the data specified in conditions and expressions,
allowing the data to be modified before it is matched.
Most of the default functions available with Foglight cause calculations to be performed
on metrics. In addition, the functions alarmCount, changeSummary, descendents,
findObservationEntries, getContainedObjects, and getObservationTrend
cause values to be returned for topology objects (based on a specified scope). In most
cases, you specify scope as the parameter for one of these functions; using the scope
variable causes the function to be performed on the topology objects included in the rule
or derived metric scope. However, there may be situations in which you want to specify
an alternate scope. See “Advanced scripting example” on page 805 for more
information.
The following functions are supported by Foglight for use with rule conditions and
expressions and 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

• getContainedComponentsPropertyName: Returns the property name of the


contained component.
• getContainedObjects: Returns the set of topology objects of the specified
type that are directly contained by each topology object referenced by this
function’s scope parameter.
• getImpactedServices: Returns a list of impacted services.
• getInstalledAgentList: Returns a list of installed agent types that are
compatible with and can be installed on a host, given the host’s Foglight Agent
Manager ID.
• getMonitoredComponentRuleInfoList: Returns a list of rules that are
scoped to a monitored component.
• getObservationTrend: Returns an observation trend.
• getPropertyObject: Returns the value of property for the topology object with
the given ID.
• getPropertyValueAtGivenTimesOfGivenTopologyObjects: Returns the
values of a given property for a list of TopologyObjects at a given list of times.
• getPropertyValuesOfTopologyObjectAtGivenTimes: Returns the values
of a given property for a list of TopologyObjects at a given time.
• getRuleAlarmSeveritiesConfigured: Returns the existing alarm severities
that are configured for a rule.
• getRuleBasedView: Returns a rule-based view.
• getRuleBasedViewInput: Returns a rule-based view input.
• getRuleBasedViewName: Returns a rule-based view name.
• getRuleComment: Returns a rule comment.
• getRuleInfoUsingId: Returns a rule comment given an ID.
• getSeverityConditions: Returns a list of severity conditions for a rule.
• getTopologyPropertyValue: Returns the value of a topology property for a
scoping object at a given date and time
• help: Returns a list of supporting information such as scripts or methods as
specified by the parameter.
• histogram: keeps a histogram to measure the distribution of metric values (for
example, for a set of topology objects or for a single object over a specified
period of time).
804 Foglight
Administration and Configuration Guide

• isNotNull: Determines whether a given data object is set to null.


• last: Returns a
com.quest.nitro.service.scripting.ObservedDataQueryResult
object which contains the latest metrics for the scoping object if there are any
observations made during a given period.
• max: Calculates a maximum from metric values.
• metricDifference: Returns the difference percentile between two given
metric values.
• min: calculates a minimum from metric values.
• period: calculates the total length of a period of time from a series of metrics
and returns a value in seconds.
• positive_delta: Returns the difference between the maximal values of the
most recent two metric values for a scoping object.
• positive_delta_rate: Returns the difference between the maximal values of
the most recent two metric values for a scoping object divided by the time period
in seconds of the more recent metric value.
• rate: calculates the rate of a metric value per second.
• returnIncludeOrExcludeGivenABoolean: Determines whether to include
or exclude the object given a boolean value.
• returnObjectsSatisfyingNameFilter: Returns a given number of objects
whose name matches a string pattern specified by the parameter.
• returnObjectsSatisfyingTypeNameFilter: Returns a given number of
objects whose name matches a string pattern specified by the parameter.
• stddev: Calculates the standard deviation from multiple metric values.
• sum: Calculates the sum of metric values.
• updateHostModel: Updates the Host Model.
Examples
• You are creating a multiple-severity rule that applies to requests for a specific
JSP. You want this rule to generate a Warning alarm when there are more than ten
requests of this type per second.
In the Condition box on the Condition tab of the rule’s Warning pane, you
specify the following:
rate(#count#)>10
Using the Query Language 805
Using the Query Language FAQ

• 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;}

Advanced scripting example


In most cases, you use the scope variable as a parameter for the functions
alarmCount, descendents, and getContainedObjects. However, there may be a
situation in which you need to create a condition or expression that uses one of these
functions but want the function to be performed on an object outside of the rule or
derived metric scope.
For example, if you wanted to compare the alarm count for objects within the scope of a
rule with the alarm count for a specific server that is not within this scope, you could
specify a condition using the following syntax:
alarmCount(scope) > alarmCount(#!CatalystServer where name =
"Server_IP:1099"#.getTopologyObjects()[0])
Where Server_IP is the IP address of the server. For example:
alarmCount(scope) > alarmCount(#!CatalystServer where name =
"10.4.112.155:1099"#.getTopologyObjects()[0])

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.

Using the Query Language FAQ


This section provides answers to the following FAQs:
• “How do I reference a topology object property in an expression?” on page 806
806 Foglight
Administration and Configuration Guide

• “How do I export metrics from the command line?” on page 806


How do I reference a topology object property in an expression?
If the rule is scoped to the topology object that has that property, you can reference the
property using the scope variable. This variable contains a reference to the topology
object against which the expression runs.
For example, you are interested in the property filesystemName, you can use the
following in an expression to obtain the property value:
"File system " + scope.get("filesystemName") + " is now full"
If you want to reference the topology object from within a string or embedded query,
you must prefix the scope variable with the dollar sign ‘$’. For example:
"File system $scope is now full"
or
#Filesystem where name = $scope.get("filesystemName")#

How do I export metrics from the command line?


The fglcmd tool includes a command that allows you to export metric observations to a
file using a metric query. The metricexport command can be used to export metrics
to a CSV or XML file.
For example, the following command exports the values of the Process metric
collected in the past two hours to a CSV file.
C:\Quest_Software\Foglight\bin>fglcmd -usr foglight -pwd foglight
-cmd util:metricexport -output_format csv -metric_query
"Processes from Windows_System_System_Table for 2
hours" -f my_metric_query.csv
For complete details on how to configure fglcmd, and about the util:metricexport
command, see the Command-Line Reference Guide.
A
Appendix: Foglight Client
Reference

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.

This appendix contains the following sections:


Starting the Foglight Client ........................................................................................................808
Viewing the Content of a Foglight Client Support Bundle..........................................................808
Browser Interface ...................................................................................................................... 811
Command-Line Interface ...........................................................................................................814
808 Foglight
Administration and Configuration Guide

Starting the Foglight Client


To start the Foglight Client:
• To start the Foglight Client, you run the spid executable that is located in the
Foglight Client installation directory. Alternatively, to start the Client on
Windows platforms, choose Start > Programs > Quest Software > Foglight
SPID 5.5.0 > Start SPID.
For more information, refer to the Installation and Setup Guide.

Note For information on how to start the Foglight Agent Manager, see “Logging in to Foglight” on
page 22.

Viewing the Content of a Foglight Client Support Bundle


When you create a client support bundle using the support_bundle command,
Foglight saves this data in a ZIP file in the <foglight_home>/support/<user_name>
directory on the computer hosting the Foglight Client. For more information about this
command, see the Command-Line Reference Guide.
Client support bundles contain diagnostic data about a Foglight Client.
To view the content of a client support bundle:

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>/

SPI.xml SPID configuration file

SPINetwork/

SPINetwork

<AGENT_NAME>/

Orb.xml JacORB configuration

OrbInitRefs.xml FMS server location details

logs/

<CARTRIDGE>/

<VERSION>/

logs/ All log files from all deployed


agents (OSCartridge, SPID,
Oracle, SQL2005, etc) are in
this folder.
Additional logs may be
present in other directories,
depending on the agent and/or
platform
810 Foglight
Administration and Configuration Guide

manifests/ OPTIONAL (may be present


for specific platforms)

<CARTRIDGE>_file_manifest.txt A file manifest for every


cartridge deployed to this
SPID installation

osfiles/ OPTIONAL (may be present


for specific platforms)

* Various OS configuration files


like “/etc/hosts”, depending
on the OS platform.

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

Agent Properties dashboard


Figure 1

Adapter pane Types pane Agent pane List pane

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.

Agent Status dashboard


The Agent Status dashboard shows an entry for the SPINetwork agent that comes with
the Foglight Client.
812 Foglight
Administration and Configuration Guide

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

Agent Adapters dashboard


Figure 3

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.

Deploying agent packages

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.

To deploy an agent package using the command line:

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.

1 Open a Command Prompt window (Windows) or a terminal window (Unix or


Linux) and navigate to the directory on your computer that contains the
uncompressed fglcmd package. For example, <foglight_home>/bin.
Note For complete information on how to get started with fglcmd, see the Command-Line
Reference Guide.

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.

Creating agent instances

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.

To create an agent instance using the command line:

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

1 Open a Command Prompt window (Windows) or a terminal window (Unix or


Linux) and navigate to the directory on your computer that contains the
uncompressed fglcmd package. For example, <foglight_home>/bin.
Note For complete information on how to get started with fglcmd, see the Command-Line
Reference 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

Retrieving agent logs

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.

To retrieve an agent log using the command line:


1 Open a Command Prompt window (Windows) or a terminal window (Unix or
Linux) and navigate to the directory on your computer that contains the
uncompressed fglcmd package. For example, <foglight_home>/bin.
Note For complete information on how to get started with fglcmd, 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

If successful, this command does not generate any output.


Note If you pull agent logs into the <foglight_home>/logs directory, they will be packaged
as part of the server support bundle. For more information about server support
bundles, see Chapter 3, “Managing Support Bundles” on page 139.

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.

Foglight Client IDs


Some commands (for example agent:create) require a Foglight Agent Manager ID
as a parameter. 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.
The Foglight Agent Manager IDs use the following syntax:
<hostname>#SPI://HostName:0/MS
<hostname>#SPI://HostName:0
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 MyHost
Client ID: MyHost#SPI://MyHost:0/MS
Client Name: MS
Agent Types:
------------------------------------
Client ID: MyHost#SPI://MyHost:0
Client Name: SPI://MyHost:0
Agent Types:
Windows_System
WebMonitor
AppMonitor
LogFilter
------------------------------------

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

Client ID: tor012991.prod.quest.corp#cf238d96-3a56-45d6-a33e-


b88bb7d4ff55
Installer ID: tor012991.prod.quest.corp#cf238d96-3a56-45d6-a33e-
b88bb7d4ff55#FglAM:tor012991.prod.quest.corp/cf238d96-3a56-
45d6-a33e-b88bb7d4ff55/installer
Agent Package ID: OSCartridge-WindowsXP-5.5.0-OSCartridge-
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.*/
Agent Package OS Architecture: ia32,x86_64
------------------------------------

C:\Quest_Software\Foglight\bin>fglcmd -usr foglight -pwd foglight


-cmd agent:packages -clientid MyHost.#SPI://MyHost:0
Installer ID: MyHost#SPI://MyHost:0#SpiInstaller/admin
Agent Package ID: C:\<foglight_home>\dist\tmp\cartridge.exploded\
OSCartridge-usrnsupported-WindowsXP-5_1 HEAD_20090208_0630\I
nstallers-5_1 HEAD_20090208_0630\OSCartridge-Agent-WindowsXP
.zip
820 Foglight
Administration and Configuration Guide

Agent Package Cartridge Name: OSCartridge-usrnsupported-WindowsXP


Agent Package Cartridge Version: 5.5.0 HEAD_20090208_0630
------------------------------------

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

A 211, 220, 221, 228, 232, 243, 251, 253, 267,


about Foglight 12 278, 281, 294, 344, 352, 354, 358, 364, 365,
about Quest Software 16 377, 390, 401, 407, 409, 432, 433, 434, 439,
Action Parameter Editor dialog box 496, 497, 468, 470, 474, 518, 522, 525, 540, 550, 562,
498, 533, 534, 535, 536 563, 575, 616, 617, 621, 622, 632, 633, 642,
Add Hosts from Host Model dialog box 76, 77 643, 650, 678, 704, 722, 727, 765, 794, 807
Add Retention Policy dialog box 681, 689, Administration dashboard 37
690, 694, 695 about 38
Add Role Permission dialog box 370, 413, accessing 57
567, 626, 645 Agents dashboards 277
Add Topology Type dashboard 41, 44, 617, about 278
618, 619 Agent Adapters 353
Add Topology Type node in navigation Agent Blackouts 357
panel 617 Agent Hosts 342
Add User Permission dialog box 370, 413, Agent Properties 279
567, 626, 645 Agent Status 292
Administration dashboard 29, 37, 38, 39, 57, browser interface 26
58, 59, 60, 61, 62, 63, 64, 65 administration dashboards 31
Audited Activities view 39, 57, 65, 66 Welcome page 26
Current Statistics view 39, 45, 46, 47, 48, 49, building script agents 700
50, 51, 53, 55, 60, 61, 62 script syntax 701
Currently Licensed Capabilities view 39, 51, Cartridges dashboards 249
63 about 250
Federation view 39, 54, 56, 65 cartridge components 250
Foglight Server Topology view 55, 65 Cartridge Inventory 251
License Information view 39, 52, 54, 63, 64 Components for Download 265
Navigation view 39, 40, 59 Data dashboards 615, 620, 642
Administration module 12, 19, 21, 22, 27, 30, about 616
31, 32, 34, 35, 36, 37, 38, 57, 58, 66, 95, 96, adding topology types 617
117, 122, 133, 140, 151, 156, 197, 201, 210, managing derived metrics 621
822 Foglight
Administration and Configuration Guide

managing retention policies 666 managing licenses 119, 133


managing thresholds 642 managing support bundles 139
downloading agent components 265 viewing audit information 150
getting started 19 viewing connection status 96
logging in 22 viewing Foglight configuration 98
models and scope 20 setting up monitoring configuration 67
installing and managing agents on a single about 68
host 292 accessing Extend Your Monitoring Reach
installing and managing cartridges 251 dashboard 70
managing agent blackouts 357 completing configuration interviews 72
managing agent properties 279 completing configuration tasks 89
managing agents 277 viewing configuration plans 84
about 278 Setup & Support dashboards 95
managing agents on multiple hosts 342 about 96
managing cartridges 249 Connection Status 96
about 250 Email Configuration 119
cartridge components 250 Foglight Configuration 98
managing derived metrics 621 Manage Licenses 133
managing groups 210 Manage Support Bundles 139
managing registry variables 365 View Audit Information 150
managing retention policies 666 Tooling dashboards 699
managing roles 219, 227, 231 about 700
managing rules 408 Build Script Agent 700
managing schedules 563 Manage Host Aliasing Rules 725
managing thresholds 642 merging hosts or other topology objects 727
managing users 199 Script Editor 721
managing users and security 197 Users & Security dashboards 197
about 198 about 198
merging hosts or other topology objects 725, Configure Directory Services 231
727 Configure Password Settings 227
retrieving data 721 Manage Groups 210
Rules & Notifications dashboards 363, 364, Manage Roles 219
406 Manage Users 199
about 364 using schedules 561
managing registry variables 365 about 562
managing rules 408 viewing agent adapters 353
Schedules dashboards 561 viewing the Administration dashboard 57
about 562 working with data 615
managing schedules 563 about 616
setting up Foglight 95 adding topology types 617
about 96 collecting data with older timestamps 697
Index 823

working with derived metrics 620 creating 320, 324, 815


working with Foglight tooling 699 creating on multiple hosts 348
about 700 agent logs
working with registry 363, 364 retrieving 338, 339, 340, 817
about 364 Agent Operation dialog box 328, 329, 330,
working with rules 363, 406 331, 332, 333, 334, 335, 336, 714, 715, 716
about 364 agent packages
working with thresholds 642 deploying 313, 316, 814
Administration node in navigation panel 57, 58 deploying to a single host 312
agent adapters deploying to multiple hosts 345
accessing Agent Adapters dashboard 354 agent properties
activating 356 cloning
deactivating 356 lists in secondary properties 285, 304
viewing 353 editing 296
Agent Adapters dashboard 40, 353, 354, 355, choosing edit scope 300
356, 357, 813 lists in secondary properties 287, 305
accessing 354 primary properties 302
activating agent adapters 356 primary type-specific agent properties 284
deactivating agent adapters 356 type-specific agent properties 283
Agent Adapters node in navigation panel 354 removing
Agent Blackouts dashboard 40, 357, 358, 359, cloned lists from secondary agent
361 properties 309
Blackout Schedule Results dialog box 361 cloned lists from secondary properties 289
Selected Agents dialog box 360 Agent Properties dashboard 40, 59, 279, 280,
Agent Blackouts node in navigation panel 358 281, 282, 283, 284, 286, 287, 289, 290, 296,
agent components 811
downloading 265 accessing 280
266 cloning lists in secondary properties 285
accessing Cartridge Inventory view 270 editing lists in secondary properties 287
downloading agent packages remotely 269 editing primary type-specific properties 284
using Components for Download view 270 editing type-specific properties 283
Agent Hosts dashboard 40, 59, 293, 312, 320, Namespace > Type view 281, 282, 290
342, 343, 344, 345, 346, 348 Properties view 282, 283, 284, 285, 286,
accessing 343 287, 289, 290, 291
Create Agent dialog box 349, 350, 352 removing cloned lists from secondary
Create Agent Results dialog box 350, 351 properties 289
creating agent instances 348 Agent Properties node in navigation panel 281
Deploy Agent Package dialog box 346, 347 Agent Status dashboard 30, 35, 41, 46, 60,
deploying agent packages 345 280, 292, 293, 294, 295, 296, 297, 298, 300,
Agent Hosts node in navigation panel 344 301, 303, 304, 306, 309, 310, 311, 312, 313,
agent instances
824 Foglight
Administration and Configuration Guide

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

accessing 280 editing primary agent properties 302


cloning lists in secondary properties 285 removing cloned lists from secondary agent
editing lists in secondary properties 287 properties 309
editing primary type-specific properties 284 retrieving agent logs 338, 339
editing type-specific properties 283 starting agents’ data collection 331
Namespace > Type view 281, 282, 290 stopping agents’ data collection 331
Properties view 282, 283, 284, 285, 286, Stopping Data Collection dialog box 335,
287, 289, 290, 291 336
removing cloned lists from secondary Agents node in navigation panel 12, 13, 30,
properties 289 32, 278, 281, 294, 344, 352, 354, 358
Agent Status 30, 35, 41, 46, 60, 280, 292, Alarm Message Editor dialog box 454, 455,
293, 294, 295, 296, 297, 298, 300, 301, 463
303, 304, 306, 309, 310, 311, 312, 313, Alarms dashboard 28
318, 320, 321, 324, 326, 327, 328, 329, Alarms dashboards
330, 331, 332, 334, 335, 336, 337, 338, Alarms 28
339, 340, 343, 345, 348, 352, 714, 811 audit information
accessing 293 viewing 150
activating agents 327 accessing View Audit Information
Agent Operation dialog box 328, 329, 330, dashboard 151
331, 332, 333, 334, 335, 336, 714, 715, audit logs
716 filtering 155
choosing edit scope of agent property viewing 156
changes 300 Audited Activities view 39, 57, 65, 66
cloning lists in secondary agent
properties 304 B
Create Agent dialog box 321, 323, 324,
backing up Foglight 157
711, 712
about 157
Create Agent Results dialog box 323, 712,
Blackout Schedule Results dialog box 361
713
browser interface
creating agent instances 320
about 26
deactivating agents 327
administration dashboards 31
Delete Agent dialog box 337
Welcome page 26
deleting agents 337
Build Script Agent dashboard 43, 701, 704,
Deploy Agent Package dialog box 313,
705, 706, 707, 708, 710, 711, 717, 719
314, 315, 316, 708
accessing 704
deploying agent packages 312, 313
Build Script Agent dialog box 706
Edit Tags dialog box 310, 311
building agent packages 705
editing agent properties 296
Confirm Script Upload dialog box 705, 706
editing agent tags 310
Create Agent dialog box 711
editing lists in secondary agent
creating agent instances 710
properties 305
826 Foglight
Administration and Configuration Guide

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

viewing content 808 Configure Directory Services node in navigation


collecting data with older timestamps 697 panel 232, 243
completing configuration interviews 72 Configure Password Services dashboard 45
completing configuration tasks 89 Configure Password Settings dashboard 208,
Components for Download dashboard 41, 265, 227, 228, 229, 230
266, 267, 268, 269, 312, 345 accessing 228
accessing 266 editing password settings 229
downloading agent components 268 Configure Password Settings node in naviga-
Components for Download node in navigation tion panel 228
panel 267 Confirm Delete dialog box 209, 210
Components for Download view Confirm Force Password-Change dialog
downloading agent components box 207
remotely 272 Confirm Script Upload dialog box 705, 706
Components form Download view 269, 270, Confirm Unlock dialog box 208
271, 272 connection status
accessing remotely 270 viewing 96
Condition Editor dialog box 528, 529, 543, Connection Status dashboard 96
545, 552, 553, 792, 793, 794, 795, 797, 798, Connection Status node in navigation panel 96
800, 801 contacting Quest 17
conditions Copy Derivation dialog box 628, 629
and functions 801 Copy Registry Variable dialog box 372, 373
specifying 792 Copy Schedule dialog box 569
using the query language 790 core 15
Configuration 765 Create Agent dialog box 321, 323, 324, 349,
Configuration dashboards 350, 352, 711, 712
Data 765 Create Agent Results dialog box 323, 350,
Configuration Interview Complete view 82 351, 712, 713
configuration interviews Create Dashboard dialog box 30
completing 72 Create Derived Metric dashboard 44, 629, 630,
configuration plans 632, 634
creating 72 adding calculations to derived metrics 634
viewing 84 defining derived metrics 633
Configuration Plans view 82, 86, 87 Expression Editor dialog box 792, 793, 794,
configuration tasks 795, 797, 798, 801
completing 89 getting started with defining derived
Configure Directory Services metrics 633
accessing 232 Scoping Query Editor dialog box 785, 786,
Configure Directory Services dashboard 45, 787, 788, 789
231, 232, 236, 239, 243, 244, 245 setting derived metric value types 639
editing directory settings 234 triggering derived metrics 637
828 Foglight
Administration and Configuration Guide

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

Create Threshold node in navigation panel 650 713


creating configuration plans 72 Delete Agent dialog box 337
Current Statistics view 39, 45, 46, 47, 48, 49, Deploy Agent Package dialog box 313,
50, 51, 53, 55, 60, 61, 62 314, 315, 316, 708
Currently Licensed Capabilities 39 Edit Tags dialog box 310, 311
Currently Licensed Capabilities view 39, 51, Stopping Data Collection dialog box 335,
63 336
Alarms 28
D Build Script Agent 43, 701, 704, 705, 706,
707, 708, 710, 711, 717, 719
dashboards
Build Script Agent dialog box 706
Add Topology Type 41, 44, 617, 618, 619
Confirm Script Upload dialog box 705, 706
Administration 29, 37, 38, 39, 57, 58, 59, 60,
Create Agent dialog box 711
61, 62, 63, 64, 65
Deploy Agent Package dialog box 708,
Agent Adapters 40, 353, 354, 355, 356, 357,
709, 710
813
Cartridge Inventory 41, 47, 61, 251, 252,
Agent Blackouts 40, 357, 358, 359, 361
253, 256, 257, 259, 260, 261, 262, 263,
Blackout Schedule Results dialog box 361
264, 265
Selected Agents dialog box 360
Cartridge Confirmation dialog box 263,
Agent Hosts 40, 59, 293, 312, 320, 343,
264, 265
344, 345, 346, 348
Cartridge Operation Result message
Create Agent dialog box 349, 350, 352
box 260, 261
Create Agent Results dialog box 350, 351
View Cartridge Details view 255, 256
Deploy Agent Package dialog box 346, 347
Check Registry Value 390
Agent Properties 40, 59, 280, 281, 282, 283,
Show columns dialog box 395, 396, 397
284, 286, 287, 289, 290, 296, 811
View Registry Variable view 390, 391,
Namespace > Type view 281, 282, 290
392, 393, 394
Properties view 282, 283, 284, 285, 286,
Components for Download 41, 265, 266,
287, 289, 290, 291
267, 268, 269, 312, 345
Agent Status 30, 35, 41, 46, 60, 280, 292,
Configure Directory Services 45, 231, 232,
293, 294, 295, 296, 297, 298, 300, 301,
236, 239, 243, 244, 245
303, 304, 306, 309, 310, 311, 312, 313,
Configure Password Services 45
318, 320, 321, 324, 326, 327, 328, 329,
Configure Password Settings 208, 227, 228,
330, 331, 332, 334, 335, 336, 337, 338,
229, 230
339, 340, 343, 345, 348, 352, 714, 811
Connection Status
Agent Operation dialog box 328, 329, 330,
Connection Status dashboard 42, 96
331, 332, 333, 334, 335, 336, 714, 715,
Create Derived Metric 44, 629, 630, 632,
716
634
Create Agent dialog box 321, 323, 324,
Expression Editor dialog box 792, 793,
711, 712
794, 795, 797, 798, 801
Create Agent Results dialog box 323, 712,
Scoping Query Editor dialog box 785, 786,
830 Foglight
Administration and Configuration Guide

787, 788, 789 Email Alias Group view 471


Create Registry Variable 44, 375, 376, 377, Email Routing view 120, 121
383, 391, 474 Email Server view 471
Step 1: Create Registry Variable view 474 Successful dialog box 131, 132
Step 2: Registry Variable Added view 475, Test Configuration dialog box 131, 132,
476 524
Create Rule 44, 429, 431, 432, 433, 518, Email Server Configuration
525, 526, 527, 538, 540, 541, 542, 546, Email Server Configuration view 120, 129,
550, 551, 552 130, 131
Action Parameter Editor dialog box 496, Extend Your Monitoring Reach 12, 27, 67,
497, 498, 533, 534, 535, 536 68, 69, 70, 73, 84, 86, 251, 252, 253, 278,
Alarm Message Editor dialog box 454, 455, 292, 293, 294, 343, 344
463 about 68
Condition Editor dialog box 528, 529, 543, accessing 70
545, 552, 553, 792, 793, 794, 795, 797, Add Hosts from Host Model dialog box 76,
798, 800, 801 77
Scoping Query Editor dialog box 785, 786, completing configuration interviews 72
787, 788, 789 completing configuration tasks 89
Create Schedule 44, 574, 575, 576, 577, Configuration Interview Complete view 82
578 Configuration Plans view 82, 86, 87
Edit Schedule view 579 List Hosts to Monitor view 74, 75, 77
Edit Schedule—Add Schedule Item Select Database Platforms view 78
view 579 Select Hosts For Standard Host Monitoring
Schedule Confirmation dialog box 581 view 78
Step 1: Create Schedule—Schedule Name Select Java EE Application Server Type
and Description view 575 view 80
Step 2: Create Schedule— Details of Sched- Select Technology Types view 73, 74
ule view 577 viewing configuration plans 84
Step 2: Create Schedule—Details of Sched- Foglight Configuration 42, 50, 51, 62, 98, 99,
ule view 577, 578 100, 101, 102, 103, 104, 106, 117, 118,
Step 3: Create Schedule—Schedule Added 468, 469, 470
view 578 Database view 101, 118
Create Threshold 44, 648, 650, 651, 652 Federation Configuration view 100
Data 765 Federation view 99
Data Management 667, 675, 676, 680, 688, JVM view 102
693 Mail (Global Settings) view 105
Do More with Foglight page 29 OS view 103
Domains 28 Ports view 106, 107
Email Configuration 27, 28, 29, 119, 120, Server view 50, 51, 99
122, 123, 124, 126, 127, 128, 130, 468, WCF view 104
470, 471, 521, 522, 523 Hosts 28
Index 831

Manage Derived Metrics 41, 434, 621, 622, 402, 403


623, 624, 625, 628, 630, 631, 632 Create Registry Value—Step 2 view 388,
Add Role Permission dialog box 626 403
Add User Permission dialog box 626 Edit Registry Variable view 375, 376, 381,
Copy Derivation dialog box 628, 629 382, 402, 472, 473, 476, 477
Delete Derivation dialog box 630 Edit Role Permission dialog box 371
Edit Derived Metric view 631 Edit User Permission dialog box 371
Edit Role Permission dialog box 627 Registry Variable Confirmation dialog
Edit User Permission dialog box 627 box 375
Expression Editor dialog box 792, 793, Manage Retention Policies 41, 667, 675,
794, 795, 797, 798, 801 676, 678, 679, 680, 681, 682, 684, 688,
Scoping Query Editor dialog box 785, 786, 689, 690, 693, 694, 696
787, 788, 789 Add Retention Policy dialog box 681, 689,
Manage Groups 43, 204, 210, 211, 212, 690, 694, 695
213, 214, 215, 216, 217, 218, 219, 220, Edit Retention Policy Period dialog
224 box 692, 693, 695
Create Group dialog box 214 Retention Policy Confirmation dialog
Edit Roles dialog box 216, 217 box 684
Edit Users dialog box 215, 216 Manage Roles 216, 220, 221, 223, 224,
Manage Host Aliasing Rules 726, 727, 728, 225, 226
729, 730, 731, 732, 733, 734, 735, 737, 43
745, 750, 753, 757, 761 Create Role dialog box 223, 224
Host Aliasing dialog box 737, 739, 740, Edit Groups dialog box 224, 225
741, 742, 743, 744, 745, 746, 747, 748, Manage Rules 42, 48, 61, 62, 408, 409, 410,
749, 750, 751, 752, 753, 754, 755, 756, 411, 412, 415, 416, 417, 418, 419, 420,
757, 758, 759, 760 421, 422, 423, 424, 426, 428, 429, 430,
New Merging Rule Introduction dialog 432, 481, 520, 800
box 735, 737, 738, 745 Action Parameter Editor dialog box 496,
Manage Host Finder Rules 497, 498, 533, 534, 535, 536
Host Finder dialog box 741, 742, 743 Add Role Permission dialog box 413
Manage Licenses 42, 52, 53, 64, 133, 134, Add User Permission dialog box 413
137, 138 Alarm Message Editor dialog box 454, 455,
License Confirmation dialog box 138, 139 463
Manage Registry Variables 42, 365, 366, Condition Editor dialog box 528, 529, 543,
367, 368, 369, 372, 374, 375, 377, 381, 545, 552, 553, 792, 793, 794, 795, 797,
400, 401, 402, 403, 404, 418, 433, 471, 798, 800, 801
472, 473, 474, 477, 481, 794 Delete Rule Confirmation dialog box 418,
Add Role Permission dialog box 370 419, 420
Add User Permission dialog box 370 Edit Role Permission dialog box 414
Copy Registry Variable dialog box 372, 373 Edit Rule view 425, 426, 427, 428, 429,
Create Registry Value—Step 1 view 387, 557
832 Foglight
Administration and Configuration Guide

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

Expression Editor dialog box 792, 793, accessing 643


794, 795, 797, 798, 801 Add Role Permission dialog box 645
Scoping Query Editor dialog box 785, 786, Add User Permission dialog box 645
787, 788, 789 adding bounds to metric threshold
Manage Derived Metrics 41, 434, 621, 622, levels 653
623, 624, 625, 628, 630, 631, 632 creating thresholds 650
accessing 621 defining thresholds 651
Add Role Permission dialog box 626 Delete Threshold dialog box 647, 648
Add User Permission dialog box 626 deleting thresholds 647
adding calculations to derived metrics 634 Edit Role Permission dialog box 646
Copy Derivation dialog box 628, 629 Edit Threshold view 648, 649
copying derived metrics 628 Edit User Permission dialog box 646
creating derived metrics 632 editing threshold definitions 648
defining derived metrics 633 editing threshold permissions 644
Delete Derivation dialog box 630 selecting metrics and levels in
deleting derived metrics 630 thresholds 651
Edit Derived Metric view 631 viewing threshold definitions 648
Edit Role Permission dialog box 627 managing derived metrics 621
Edit User Permission dialog box 627 managing retention policies 666
editing derived metric definitions 630 managing thresholds 642
editing derived metric permissions 624 Data Management dashboard 667, 675, 676,
getting started with defining derived 680, 688, 693
metrics 633 Data Management view 41
setting derived metric value types 639 Data node in navigation panel 12, 33, 617,
triggering derived metrics 637 622, 632, 643, 650, 678, 765
viewing derived metric definitions 630 database
Manage Retention Policies 41, 667, 675, changing database credentials 230
676, 678, 679, 680, 681, 682, 684, 688, database management
689, 690, 693, 694, 696 about 193
accessing 675 managing database size with retention
Add Retention Policy dialog box 681, 689, policies 193
690, 694, 695 monitoring database size 193
creating retention policies 693 reclaiming table space 195
deleting retention policies 680 viewing observations to estimate required
Edit Retention Policy Period dialog size 194
box 692, 693, 695 Database view 101, 118
editing retention policies 688 Delete Agent dialog box 337
Retention Policy Confirmation dialog Delete Derivation dialog box 630
box 684 Delete dialog box 86
Manage Thresholds 41, 643, 644, 645, 647, Delete Rule Confirmation dialog box 418, 419,
648, 650, 666 420
834 Foglight
Administration and Configuration Guide

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

Host Aliasing 737, 739, 740, 741, 742, 743, E


744, 745, 746, 747, 748, 749, 750, 751, Edit Derived Metric view 631
752, 753, 754, 755, 756, 757, 758, 759, Edit Registry Variable view 375, 376, 381, 382,
760 402, 472, 473, 476, 477
Host Finder 741, 742, 743 Edit Retention Policy Period dialog box 692,
License Confirmation 138, 139 693, 695
New Merging Rule Introduction 735, 737, Edit Role Permission dialog box 371, 414, 568,
738, 745 627, 646
Registry Variable Confirmation 375 Edit Roles dialog box 216, 217
Retention Policy Confirmation 684 Edit Rule view 425, 426, 427, 428, 429, 557
Rule Confirmation 415, 416, 421, 422, 423, Edit Schedule view 570, 572, 574, 579, 580,
424 581
Schedule Confirmation 581 Edit Schedule—Add Schedule Item view 579
Schedule Delete Confirmation 571 Edit Tags dialog box 310, 311
Scoping Query Editor 785, 786, 787, 788, Edit Threshold view 648, 649
789 Edit User Permission dialog box 371, 414,
Selected Agents 360 568, 627, 646
Show columns 152, 153, 395, 396, 397 Edit Users dialog box 215, 216
Stopping Data Collection 335 email actions
Successful 131, 132 configuring 119
Temporarily Suspend Rule Actions 422, 423 accessing Email Configuration
Temporarily Suspend Rule Alarms 420, 421 dashboard 120
Test Configuration 131, 132, 524 editing email configuration parameters 123
directory services testing email configuration 129
configuring 231 Email Alias Group view 471
accessing Configure Directory Services Email Configuration dashboard 27, 28, 29,
dashboard 232 119, 120, 122, 123, 124, 126, 127, 128, 130,
directory settings 468, 470, 471, 521, 522, 523
editing 234 accessing 120
Do More with Foglight page 29 editing email configuration parameters 123
documentation 14, 15, 16 Email Alias Group view 471
Domains dashboard 28 Email Routing view 120, 121
downloading agent packages remotely Email Server Configuration view 120, 129,
using Components for Download view 270, 130, 131
272 Email Server view 471
accessing Components for Download testing email configuration 129
view 270 Email Configuration node in navigation
using URLs 274 panel 27, 29, 122, 470, 522
Email Routing view 120, 121
836 Foglight
Administration and Configuration Guide

Email Server Configuration view 120, 129, accessing 70


130, 131 completing configuration interviews 72
Email Server view 471 completing configuration tasks 89
Expression Editor dialog box 792, 793, 794, viewing configuration plans 84
795, 797, 798, 801
expressions F
and functions 801
Federation Configuration view 100
Extend Your Monitoring Reach
Federation view 39, 54, 56, 65, 98, 99
Add Hosts from Host Model dialog box 76, 77
feedback 16
Configuration Interview Complete view 82
Foglight Agent Manager IDs 325, 818
Configuration Plans view 82, 86, 87
Foglight Agent Manager support bundles 139
List Hosts to Monitor view 74, 75, 77
viewing content 148
Select Database Platforms view 78
Foglight configuration
Select Hosts For Standard Host Monitoring
viewing 98
view 78
Foglight Configuration dashboard 42, 50, 51,
Select Java EE Application Server Type
62, 98, 99, 100, 101, 102, 103, 104, 106,
view 80
117, 118, 468, 469, 470
Select Technology Types view 73, 74
accessing 117
Extend Your Monitoring Reach dashboard 12,
Database view 101, 118
27, 67, 68, 69, 70, 73, 84, 86, 251, 252, 253,
Federation Configuration view 100
278, 292, 293, 294, 343, 344
Federation view 98, 99
Add Hosts from Host Model dialog box 76, 77
JVM view 102
Configuration Interview Complete view 82
Mail (Global Settings) view 104, 105, 468,
Configuration Plans view 82, 86, 87
469, 470
List Hosts to Monitor view 74, 75, 77
OS view 103
Select Database Platforms view 78
Ports view 106, 107
Select Hosts For Standard Host Monitoring
Server view 50, 51, 99
view 78
viewing
Select Java EE Application Server Type
accessing Foglight Configuration
view 80
dashboard 117
Select Technology Types view 73, 74
WCF view 104
extending monitoring reach 67
Foglight Configuration node in navigation
about 68
panel 117, 468
accessing Extend Your Monitoring Reach
Foglight module 686, 768
dashboard 70
Foglight Server Topology view 55, 65, 99
completing configuration interviews 72
functions
completing configuration tasks 89
using with conditions 801
viewing configuration plans 84
using with expressions 801
Extending Your Monitoring Reach
dashboard 67
about 68
Index 837

G Manage Schedules dashboard 563


groups Manage Support Bundles dashboard 140
assigning roles to groups 216 Manage Users dashboard 200
creating 214 Script Editor dashboard 721
deleting internal groups 218 View Audit Information dashboard 151
editing role groups 224 access Manage Licenses dashboard 133
editing users in groups 215 activate
managing 210 agent adapters 356
accessing Manage Groups dashboard 211 agent instances 328
script agent instances 710
add
H actions to rules 487
Host Aliasing dialog box 737, 739, 740, 741, metrics to a condition 794
742, 743, 744, 745, 746, 747, 748, 749, 750, metrics to a derived metric expression 794
751, 752, 753, 754, 755, 756, 757, 758, 759, permissions for accessing registry
760 variables 369
Host Finder dialog box 741, 742, 743 permissions for derived metrics 625
Hosts dashboard 28 permissions for rules 412
Hosts dashboards permissions for schedules 566
Hosts 28 permissions for thresholds 644
how to registry variables to a condition 793
access schedule items to a newly-created schedule
Administration dashboard 58 that already contains schedule items 578
Agent Adapters dashboard 354 schedule items to a newly-created schedule
Agent Hosts dashboard 344 that has no other schedule items 578
Build Script Agent dashboard 704 schedule items to an existing schedule 580
Cartridge Inventory dashboard 253 schedules to performance calendars 386
Components for Download dashboard 266 severity-level variables to rules 445
Configure Directory Services topology object properties to a
dashboard 232 condition 794
Create Schedule dashboard 575 topology object properties to a derived metric
Email Configuration dashboard 122 expression 794
Extend Your Monitoring Reach topology types 617
dashboard 70 users to groups 205, 215
Manage Groups dashboard 211 assign
Manage Host Aliasing Rules data -driven triggers to derived metrics 639
dashboard 727 data-driven triggers to rules 440
Manage Registry Variables dashboard 365 event-driven triggers to rules 440
Manage Retention Policies dashboard 678 roles to groups 216
Manage Roles dashboard 221 schedule-driven triggers to derived
Manage Rules dashboard 409 metrics 638
838 Foglight
Administration and Configuration Guide

time -driven triggers to derived metrics 639 create


time-driven triggers to rules 439 agent instances 320, 326, 815
associate agent instances on multiple hosts 349
rules with schedules 501 derived metrics 632
back up groups 214
embedded Foglight MySQL database with registry variables 377
InnoDB Hot Backup 171 retention policies 694
Foglight installation directory on Unix 162 roles 223
Foglight installation directory on rules 432
Windows 162 script agent instances 710
Foglight MS SQL database 163 server support bundles 142
Foglight MySQL database 170 thresholds 650
Foglight Oracle database 168 users 203
back up Foglight deactivate
on Unix 161 agent adapters 357
on Windows 160 agent instances 330
bind decrease
threshold levels to constant values 663 size of table space 195
threshold levels to metrics 658 define
threshold levels to registry variables 660, alarm and action behavior 503
661 rule conditions 451, 459
build rule types 438
agent packages 705 rule-level variables 506
change schedule items that occur daily 589
priorities of host aliasing rules 731 schedule items that occur monthly 600
users’ passwords 206 schedule items that occur once 583
choose schedule items that occur periodically 586
edit scope of agent property changes 300 schedule items that occur weekly 594
clone schedule items that occur yearly 607
secondary properties 286, 304 delete
complete agent instances 337
configuration interview 73 custom agent properties 298
configuration tasks 90 derived metrics 630
configure host aliasing rules 734
SNMP trap actions 481 internal groups 218
copy internal roles 226
derived metrics 628 internal users 209
registry variables 372 registry variables 374
rule conditions 464, 499 retention policies 680
rules 415 rules 418
schedules 569 schedule items 581
Index 839

schedules 571 with rule definitions 435


secondary properties 289 with schedule definitions 576
thresholds 647 with specifying rule scope 441
delete licenses 138 get started with creating
deploy host aliasing rules 736
agent packages 313, 318, 814 insert
agent packages to multiple hosts 345 a Groovy function into derived metric
script agent packages 707 expression 797
disable Groovy function into rule condition 797
cartridges 262 operators into a condition 792
rules 418 operators into a derived metric
download expression 792
agent components 269 install
edit cartridges 259
default retention policy periods 689 licenses 135
derived metrics 631 log in to Foglight 22
directory settings 236 manage
email parameters 126 agent blackouts 358
lists in secondary properties 287, 306 merge
password settings 229 host objects 739
primary properties 302 obtain
primary type-specific properties 284 LDAP information 240
role groups 224 remotely access
rule definitions 429 Components for Download view 270
schedules 574 remotely download
script agent properties 717 agent components 272
thresholds 648 remove
variable definitions 375 cartridges 264
enable characters from the end of host names 747
cartridges 261 cloned lists 309
collection of data with older timestamps 697 rename
rules 419 host aliasing rules 733
filter replace
audit logs 155 characters in host names 750
force restore
password changes 207 embedded Foglight MySQL database with
get started InnoDB Hot Backup 192
with adding calculations to derived MS SQL database from database export
metrics 634 file 178
with derived metric definitions 634 MySQL database from database export
with editing registry variables 381 file 190
840 Foglight
Administration and Configuration Guide

Oracle database from database export upload


file 191 agent scripts 705
previous Foglight installation 178 use
previous Foglight installation directory 192 regular expressions to rename hosts 753
resume view
rule actions 423 Administration dashboard 58
rule alarms 421 audit logs 156
retrieve client support bundle content 808
agent logs 339, 341, 817 configuration plans 85
data from topology 725 connection status 96
server support bundles 144 derived metrics 631
save details of topology types 768
changes to threshold levels 664 FglAMAdapter agent properties 290
scope Foglight Agent Manager support bundle
registry values to topology 387 content 148
select license capabilities 137
metrics and levels in thresholds 651 rule definitions 429
topology objects 723 rule schedules 424
set rule summary 426
derived metric value type to an schedule definitions 572
observation 640 schedules 574
derived metric value types 640 server support bundle content 145
the scope for a derived metric 784 structure of topology models 764
the scope for a rule 784 thresholds 648
specify values of registry variables 390
registry variable values 383 variable definitions 375
topology type properties in the Scoping Que-
ry Editor 788 J
start
JVM view 102
data collection for agents 332
stop
data collection for agents 334 L
suspend License 138, 139
rule actions 422 License Confirmation dialog box 138, 139
rule alarms 420 License Information view 39, 52, 54, 63, 64
tag licenses
agents 310 deleting 138
test installing 134
email configuration 130 managing 133
unlock accessing Manage Licenses
passwords 208 dashboard 133
Index 841

viewing capabilities 136 assigning roles to groups 216


List Hosts to Monitor view 74, 75, 77 Create Group dialog box 214
logging in to Foglight 22 creating groups 214
deleting internal groups 218
M Edit Roles dialog box 216, 217
Edit Users dialog box 215, 216
Mail (Global Settings) view 104, 105, 468, 469,
editing users in groups 215
470
Manage Groups node in navigation panel 211
Manage 643
Manage Host Aliasing Rules dashboard 726,
Manage Derived Metrics dashboard 41, 434,
727, 728, 729, 730, 731, 732, 733, 734, 735,
621, 622, 623, 624, 625, 628, 630, 631, 632
737, 745, 750, 753, 757, 761
accessing 621
accessing 727
Add Role Permission dialog box 626
creating rules 735
Add User Permission dialog box 626
changing names or other host
adding calculations to derived metrics 634
properties 745
Copy Derivation dialog box 628, 629
merging hosts 738
copying derived metrics 628
deleting rules 734
creating derived metrics 632
editing rule permissions 730
defining derived metrics 633
Host Aliasing dialog box 737, 739, 740, 741,
Delete Derivation dialog box 630
742, 743, 744, 745, 746, 747, 748, 749,
deleting derived metrics 630
750, 751, 752, 753, 754, 755, 756, 757,
Edit Derived Metric view 631
758, 759, 760
Edit Role Permission dialog box 627
New Merging Rule Introduction dialog
Edit User Permission dialog box 627
box 735, 737, 738, 745
editing derived metric definitions 630
renaming rules 732
editing derived metric permissions 624
Manage Host Aliasing Rules node in navigation
Expression Editor dialog box 792, 793, 794,
panel 727
795, 797, 798, 801
Manage Host Finder Rules dashboard
getting started with defining derived
Host Finder dialog box 741, 742, 743
metrics 633
Manage Licenses dashboard 42, 52, 53, 64,
Scoping Query Editor dialog box 785, 786,
133, 134, 137, 138
787, 788, 789
accessing 133
setting derived metric value types 639
deleting licenses 138
triggering derived metrics 637
installing licenses 134
viewing derived metric definitions 630
License Confirmation dialog box 138, 139
Manage Derived Metrics node in navigation
viewing license capabilities 136
panel 434, 622, 632
Manage Licenses node in navigation panel 133
Manage Groups dashboard 43, 204, 210, 211,
Manage Registry Variables dashboard 42, 365,
212, 213, 214, 215, 216, 217, 218, 219, 220,
366, 367, 368, 369, 372, 374, 375, 377, 381,
224
400, 401, 402, 403, 404, 418, 433, 471, 472,
accessing 211
473, 474, 477, 481, 794
842 Foglight
Administration and Configuration Guide

accessing 365 Manage Retention Policies node in navigation


Add Role Permission dialog box 370 panel 678
Add User Permission dialog box 370 Manage Roles dashboard 43, 216, 219, 220,
Copy Registry Variable dialog box 372, 373 221, 223, 224, 225, 226
copying registry variables 372 accessing 221
Create Registry Value—Step 1 view 387, Create Role dialog box 223, 224
402, 403 creating roles 223
Create Registry Value—Step 2 view 388, 403 deleting internal roles 225
creating registry variables 377 Edit Groups dialog box 224, 225
deleting registry variables 374 editing role groups 224
Edit Registry Variable view 375, 376, 381, Manage Roles node in navigation panel 221
382, 402, 472, 473, 476, 477 Manage Rules dashboard 42, 48, 61, 62, 408,
Edit Role Permission dialog box 371 409, 410, 411, 412, 415, 416, 417, 418, 419,
Edit User Permission dialog box 371 420, 421, 422, 423, 424, 426, 428, 429, 430,
editing registry variables 381 432, 481, 520, 800
editing variable definitions 375 accessing 408
editing variable permissions 368 Action Parameter Editor dialog box 496, 497,
getting started with editing registry 498, 533, 534, 535, 536
variables 381 action types 466
Registry Variable Confirmation dialog actions 466
box 375 Add Role Permission dialog box 413
scoping registry variables to topology 387 Add User Permission dialog box 413
specifying registry variable values 383 adding actions to rules 486
using performance calendars in registry adding severity-level variables to rules 444
variables 385 Alarm Message Editor dialog box 454, 455,
viewing variable definitions 375 463
Manage Registry Variables node in navigation associating rules with schedules 500
panel 365, 377, 401, 794 Condition Editor dialog box 528, 529, 543,
Manage Retention Policies dashboard 41, 667, 545, 552, 553, 792, 793, 794, 795, 797,
675, 676, 678, 679, 680, 681, 682, 684, 688, 798, 800, 801
689, 690, 693, 694, 696 copying rule actions 498
accessing 675 copying rule conditions 464
Add Retention Policy dialog box 681, 689, copying rules 415
690, 694, 695 copying severity-level variables 498
creating retention policies 693 creating rules 432
deleting retention policies 680 defining alarm and action behavior 503
Edit Retention Policy Period dialog box 692, defining rule actions 466
693, 695 defining rule conditions 451, 455
editing retention policies 688 defining rule conditions, alarms, and
Retention Policy Confirmation dialog box 684 actions 442
defining rule scope 441
Index 843

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

viewing threshold definitions 648 Delete dialog box 86


Manage Thresholds node in navigation Successful dialog box 131, 132
panel 643, 650 Test Configuration dialog box 131, 132, 524
Manage Users dashboard 43, 49, 199, 200, Monitoring Wizard dashboard
201, 203, 204, 205, 206, 207, 208, 209, 210, Monitoring Setup
215, 218, 226, 232 Delete dialog box 86
accessing 200
adding users to groups 204 N
Change Password dialog box 206, 207
Namespace > Type view 281, 282, 290
changing user passwords 206
Navigation view 39, 40, 59
Confirm Delete dialog box 209, 210
New Merging Rule Introduction dialog box 735,
Confirm Force Password-Change dialog
737, 738, 745
box 207
nodes in navigation panel
Confirm Unlock dialog box 208
Add Topology Type 617
Create User dialog box 203, 204
Administration 57, 58
creating users 203
Agent Adapters 354
Edit Groups dialog box 205, 206
Agent Blackouts 358
forcing password changes 207
Agent Hosts 344
unlocking passwords 207
Agent Properties 281
Manage Users node in navigation panel 201
Agent Status 30, 35, 294, 352
managing database size with retention
Agents 12, 13, 30, 32, 278, 281, 294, 344,
policies 193
352, 354, 358
message boxes
Build Script Agent 704
Cartridge Operation Result 260, 261
Cartridge Inventory 253
models
Cartridges 12, 13, 32, 251, 253, 267
about 20
Check Registry Value 390
modules in navigation panel
Components for Download 267
Administration 12, 19, 21, 22, 27, 30, 31, 32,
Configure Directory Services 232, 243
34, 35, 36, 37, 38, 57, 58, 66, 95, 96, 117,
Configure Password Settings 228
122, 133, 140, 151, 156, 197, 201, 210,
Connection Status 96
211, 220, 221, 228, 232, 243, 251, 253,
Create Derived Metric 632
267, 278, 281, 294, 344, 352, 354, 358,
Create Registry Variable 377, 474
364, 365, 377, 390, 401, 407, 409, 432,
Create Rule 433, 518, 525, 540, 550
433, 434, 439, 468, 470, 474, 518, 522,
Create Schedule 575
525, 540, 550, 562, 563, 575, 616, 617,
Create Threshold 650
621, 622, 632, 633, 642, 643, 650, 678,
Data 12, 33, 617, 622, 632, 643, 650, 678,
704, 722, 727, 765, 794, 807
765
Configuration 765
Email Configuration 27, 29, 122, 470, 522
Foglight 686, 768
Foglight Configuration 117, 468
monitoring database size 193
Manage Derived Metrics 434, 622, 632
Monitoring Setup dashboard
Index 845

Manage Groups 211 unlocking 207


Manage Host Aliasing Rules 727 Ports view 106, 107
Manage Licenses 133 Properties view 282, 283, 284, 285, 286, 287,
Manage Registry Variables 365, 377, 401, 289, 290, 291
794
Manage Retention Policies 678 Q
Manage Roles 221
query language
Manage Rules 409, 432
using in conditions 790
Manage Schedules 563, 575
using in scoping queries 784
Manage Support Bundles 140
Manage Thresholds 643, 650
Manage Users 201 R
Rules & Notifications 12, 13, 33, 365, 377, reclaiming table space 195
390, 401, 409, 432, 433, 474, 518, 525, Registry Variable Confirmation dialog box 375
540, 550 registry variables
Schedules 12, 13, 33, 563, 575 creating 377
Schema 686, 768 editing 381
Schema Browser 686, 768 getting started with editing registry
Script Editor 722 variables 381
Service Builder 30 scoping to topology 387
Services 30 specifying values 383
Setup & Support 12, 13, 27, 29, 33, 95, 96, using performance calendars 385
117, 122, 133, 140, 151, 468, 470, 522 examples
Tooling 12, 13, 34, 699, 704, 722, 727 assigning multiple values to a registry
Users & Security 12, 13, 34, 201, 210, 211, variable 399
221, 228, 232, 243 using performance calendars 399
View Audit Information 151 managing 365
accessing Manage Registry Variables
O dashboard 365
copying registry variables 372
OS view 103
deleting registry variables 374
editing variable definitions 375
P editing variable permissions 368
p 575 viewing variable definitions 375
passwords restoring Foglight 178
changing 206 about 157
configuring password settings 227 retention policies
accessing Configure Password Settings creating 693
dashboard 228 editing 688
editing password settings 229 examples
forcing password changes 207 addressing data storage concerns 696
846 Foglight
Administration and Configuration Guide

managing 666 defining 433


accessing Manage Retention Policies conditions, alarms, and actions 442
dashboard 675 getting started 434
deleting retention policies 680 rule scope 441
managing database size 193 rule triggers 438
mechanisms 668 rule types 435
Retention Policy Confirmation dialog box 684 disabling 418
roles enabling 418
assigning roles to groups 216 examples
creating 223 creating a multiple-severity rule scoped to an
deleting internal roles 225 EJB instance 518
editing role groups 224 creating a simple rule 520
managing 219 creating multiple-severity rules with a topolo-
accessing Manage Roles dashboard 221 gy scope 539
Rule Confirmation dialog box 415, 416, 421, managing 408
422, 423, 424 accessing Manage Rules dashboard 408
Rule Scope field copying rules 415
editing 784 editing rule permissions 411
rules editing rules 429
actions resuming rule actions 422
defining behavior 503 resuming rule alarms 420
adding rules 417
severity-level variables 444 suspending rule actions 422
alarms suspending rule alarms 420
defining behavior 503 viewing rule definitions 429
associating with schedules 500 viewing rule schedules 424
conditions rule-level variables
action types 466 defining 505
actions 466 viewing rule summary 425
adding actions to rules 486 Rules & Notifications dashboards 363, 364,
copying 464 406
copying actions 498 about 364
defining 451, 455 Check Registry Value 390
defining actions 466 Show columns dialog box 395, 396, 397
setting expression scope 450 View Registry Variable view 390, 391,
using trigger-specific variables in 392, 393, 394
expressions 494 Create Registry Variable 44, 375, 376, 377,
writing 449 383, 391, 474
copying creating registry variables 377
severity-level variables 498 scoping registry variables to topology 387
creating 432 specifying registry variable values 383
Index 847

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

V Email Server Configuration 120, 129, 130,


View Audit Information dashboard 42, 57, 150, 131
151, 152, 155, 156 Federation 39, 54, 56, 65, 98, 99
accessing 151 Federation Configuration 100
audit logs Foglight Server Topology 55, 65, 99
filtering 155 JVM 102
viewing 156 License Information 39, 52, 54, 63, 64
Show columns dialog box 152, 153 List Hosts to Monitor 74, 75, 77
View Audit Information node in navigation Mail (Global Settings) 104, 105, 468, 469,
panel 151 470
View Cartridge Details view 255, 256 Namespace > Type 281, 282, 290
View Registry Variable view 390, 391, 392, Navigation 39, 40, 59
393, 394 OS 103
View Your Enterprise Health page 27 Ports 106, 107
viewing configuration plans 84 Properties 282, 283, 284, 285, 286, 287,
views 289, 290, 291
Audited Activities 39, 57, 65, 66 Select Database Platforms 78
Components form Download 269, 270, 271, Select Hosts For Standard Host
272 Monitoring 78
accessing remotely 270 Select Java EE Application Server Type 80
Configuration Interview Complete 82 Select Technology Types 73, 74
Configuration Plans 82, 86, 87 Selected Installer Details 272
Create Registry Value—Step 1 387, 402, Server 50, 51, 99
403 Server Licensing Error 25
Create Registry Value—Step 2 388, 403 Step 1: Create Registry Variable 474
Current Statistics 39, 45, 46, 47, 48, 49, 50, Step 1: Create Schedule—Schedule Name
51, 53, 55, 60, 61, 62 and Description 575
Currently Licensed Capabilities 39, 51, 63 Step 2: Registry Variable Added 475, 476
Data Management 41 Step 3: Create Schedule—Schedule
Database 101, 118 Added 578
Edit Derived Metric 631 Support Bundle Inventory 143, 144
Edit Registry Variable 375, 376, 381, 382, Unlicensed Server View 25
402, 472, 473, 476, 477 View Cartridge Details 255, 256
Edit Rule 425, 426, 427, 428, 429, 557 View Registry Variable 390, 391, 392, 393,
Edit Schedule 570, 572, 574, 579, 580, 581 394
Edit Schedule—Add Schedule Item 579 WCF 104
Edit Threshold 648, 649
Email Alias Group 471 W
Email Routing 120, 121 WCF view 104
Email Server 471 Welcome page 19, 23, 24, 26, 27, 30, 122

Vous aimerez peut-être aussi