Maximize Agent Performance
Dave Hatter & Tim Bankes
Libertas Technologies, LLC
What We'll Cover ...
• Looking
for performance
• Providing appropriate Agent security
• Coding choices, it makes a difference
• Managing Agents -- the Agent manager
• Debugging Agents
• Optimizing Agent performance
A Little About Us
•Dave Hatter
• Partner, Libertas Technologies, LLC
• Numerous certifications:
•PCLP Application Developer R4, R5, D6
•CompTIA i-Net+, Network+, e-Biz+
•Master Certified Internet Webmaster (CIW) Designer
•MCP -- Windows NT
• SearchDomino.com Expert/Speaker
• Author/Co-Author of numerous Domino books and Tech Editor of
several Domino books
•Tim Bankes
• Partner, Libertas Technologies, LLC
• Numerous certifications:
•PCLP Application Developer R4, R5, D6
•CompTIA i-Net+
•Certified Internet Webmaster (CIW) Associate
• SearchDomino.com Speaker
• Author/Co-Author of numerous Domino books
Factors Affecting Performance
• Security
• Pro: Agents are constrained by the Notes/Domino security
model
• Con: Agents won't run without proper authorization
• Scheduling
• Pro: Agents can be invoked on a schedule
• Con: Requires coordination to ensure schedule does not
conflict with other server tasks
• Logging
• Pro: Agents provide extensive logging capability
• Con: creates disk I/O, which takes time and consumes space
• Coding choices
• There are pros and cons to each of the languages
• Formula
language, LotusScript, Java
Can an Agent Run?
Agent Execution
• There
are many security factors that can impact the
execution of an agent, including:
•
•
•
•
ACL permissions
Server permissions
Agent context
Agent coding choice
Can an Agent Run?
Server Based Agents
• Agent execution
• Database ACL
is dependent upon ...
• Reader
access is required to run an agent
• Public Access users can run an agent if granted the authority
• If the agent invoker has the authority to run the agent, the permissions of the
creator of the agent dictate what the agent can do
•
Server restrictions
• Settings
in the Security tab of the Server document dictate if a user can run
a specific type of agent
• Agent
context can determine whether the agent can
run, and/or whether it can run reliably
•
•
•
•
Desktop or server
Foreground or background
Personal or shared
Notes client or Web client
Can an Agent Run?
Server Based Agents Defined
• Server
Based agents run from a database on a
Domino server
•
Invoked in a number of different ways
• Agent
Manager (AMGR)
• The RunOnServer method
• The HTTP Task
• Agents called from Web browser such as a WebQueryOpen or WebQuerySave
agent, or directly from a URL
• The Router Task
• When agents are run as a result of e-mail delivery, for example an "After new
mail has arrived" agent
Can an Agent Run?
Local Agents Defined
• Local
agents run from a database on a Notes client
workstation
•
•
"Local" is specified for the "Run on" setting in a scheduled
agent
It is invoked from the Actions menu, the Agent list or the
"When documents Have Been Pasted" trigger
• Personal agents
• Can only be run by their creator
• Are not accessible by browser clients
• Are controlled by the "Run personal agents" field in the
"Agent Restrictions" section of the "Security" tab of the
Server document
• Can't do anything their creator can't do
Can an Agent Run?
Personal vs. Shared Agents
• Shared agents
• Can be run by any user who can access the database
containing the agents
• Are constrained by the ACL of a database
• Can't be used by any user with less than Reader access in
the database ACL
• May have other restrictions based on the coding option of
the agent
Can an Agent Run?
Foreground & Background Agents
• Foreground
agents are invoked by a user through
the Notes client
•
•
•
•
Via the Actions menu or Agents list
Security restrictions are not checked
Front-end classes are supported
Foreground agents will "lock-up" the client while running.
This is not the case in ND6
• Background
agents are launched on a schedule or
triggered by certain events such as before new
mail arrives
•
•
•
Security restrictions ARE checked
Front-end classes are NOT supported
Run with the permissions of the agent creator
Can an Agent Run?
Embedded Agents & Web Agents
• Embedded
Agents are Agents called by another
agent
•
Rights and restrictions of the calling agent are applied to the
called agent
• Web Agents are invoked by
• Agent Manager is not involved
a Web client
•
Run with the permission of the creator
• Unless the Agent property "Run as Web User" is enabled
•
Three types of Web Agents
• WebQueryOpen
• WebQuerySave
• Invoked
via URL
Can an Agent Run Faster/Reliably?
Web Agents
• Server
document settings that control Web
agents
•
Internet Protocols/ HTTP/Web Agents section
•Run
•
•
Web agents concurrently
Determines if more than one Web agent can be executed at the
same time
Same effect as the DominoAsynchronizeAgents parameter in the
Notes.INI file
•Web agent timeout
• Specifies how long Web agents can run
Agent Coding Options
• Domino
provides numerous coding options
when building agents
•
•
•
•
Java
LotusScript
Formula Language
Simple Actions
Agent Coding Options
• The Formula
• Very fast
• Fastest
•
•
•
•
language has many advantages
when updating more than 15% of docs in a DB
Can accomplish many complex tasks easily with minimal
code
Easy to learn
Vast number of experienced developers
Leverage existing expertise
• LotusScript
has the added ability to access
virtually all of Domino's capabilities through the
back-end classes
•
•
•
Fastest when updating less than 15% of docs in a DB
Extensive debugging and logging capability
Support for COM/OLE
Agent Coding Options
• Java
also has the ability to access virtually all of
Domino's capabilities through the back-end
classes (NOI)
•
•
•
•
Multi-threaded
Robust logging capability
Servlets only load once
Support for CORBA, IIOP and JDBC
• Which do you
• LotusScript
use?
• Supports
more Domino functionality "out-of-the box"
• Has better debugging facilities
•
Java
•
Bottom line -- Choose the language that provides the best
ROI and performance
• Is
not proprietary, is highly extensible, and faster when multi-threading
• Servlets are generally faster than agents
Agent Restrictions
• LotusScript
and Java agents are classified as
Restricted or Unrestricted
•
Unrestricted agents can perform low-level
operations such as
•File
I/O
•Network I/O
•Calling external programs
•Changing the system date and time
•
Set in the Server document
•Under
Security --> Agent Restrictions
Agent Manager
• AMGR
controls various aspects of scheduled
and event-driven agents
•
•
•
•
•
•
When agents run
Security
Agent context and loading
Where agents run
Error handling and logging
Resources used
Agent Manager
• AMGR
is configured through Server document
settings and Notes.ini parameters
•A
list of all scheduled and event-triggered agents is queued based on the
configured settings
• Agent manager periodically checks to see if new agents should be queued
• Scheduled agents are executed when their thresholds are met
• There are three types
• Eligible to execute
• Waiting
for an AMGR process to run them
•
Scheduled to execute
•
Event-triggered agents
• Waiting
• Waiting
of Agent queues
for their time to run
for an event
• For event triggered
Scheduled
Mail-triggered
Agents, there are 3 trigger types
New/updated documents
Agent Manager
Agent Queues
• To
display a list of scheduled agents, issue the Tell
Amgr Schedule command
•
Shows information about agents scheduled during the
current day
• Queue
Type
• Trigger type
• Time scheduled to run
• Agent name
• The database on which the agent runs
•
Agent Queues
• "E"
- Eligible to execute
• "S" - Scheduled to execute
• "V"
•
- Event-triggered agents waiting for an event
Trigger types
• "S"
- Scheduled
• "M" - Mail-triggered
• "U" - New/updated document-triggered
Agent Manager
• Factors
•
•
•
•
that control agent execution in AMgr
Threshold for AMgr queuing
AMGR schedules
Load on AMgr
Number of concurrent agents allowed to run
on the server
Agent Manager
• The
AMgr_SchedulingInterval INI variable specifies
how often the Agent Manager moves agents from
the Scheduled queue to the Eligible queue
•
Enter a value between 1 to 60 minutes
•
If the scheduler isn't running often enough, check this
setting
• Default
is 1 minute
• The
AMgr_UntriggeredMailInterval INI variable
specifies the delay between running the AMGR
check for "untriggered" mail
•
Untriggered mail is put into a database by replication
• Enter
•
a value between 1 to 1440 minutes
Default is 60 minutes
Agent Manager
• AMgr
Schedules
New/modified event-driven agents are scheduled
immediately
After first run of an agent, two types of
parameters control event-driven agent scheduling
•Delay
Parameters
•Interval Parameters
Agent Manager
• Delay Parameters
• AMgr_NewMailEventDelay
• Delay
of execution in the schedule for a new mail-triggered agent
after a new mail message is delivered
• The default is 1 minute
•
AMgr_DocUpdateEventDelay
• Delay
of execution in the schedule for document update-triggered agents
after a document update event
• Default is 5 minutes
Agent Manager
• Interval Parameters
• Interval Parameters control a delay between the execution of
the same event-triggered agent
• If the minimum interval has not elapsed when an agent is
triggered, AMGR schedules the agent to run at its last run
time plus the minimum interval
• AMgr_NewMailAgentMinInterval
• Delay
of execution in the schedule for a new mail-triggered agent after a
new mail message is delivered. The default is 1 minute.
•
AMgr_DocUpdateAgentMinInterval
• Delay
of execution in the schedule for document update-triggered agents
after a document update event. Default is 5 minutes.
Agent Manager
• AMgr Load
• Agent execution is also constrained by available resources and
resource allocation
• Settings
•
•
•
in the Server document that have an impact
Max Concurrent Agents
Max LotusScript/Java Execution Time
If agents are being scheduled faster than they can be run, you
may see ...
• "AMgr:
Agent scheduling is paused"
• May need to increase the number of concurrent agents
• Max Concurrent agents
• Allows more than one agent to run at the same time
• Can improve AMGR performance, but consumes additional resources
• Maximum number of concurrent agents is 10
Daytime default is 1 and night time is 2
• Each Agent is run by a separate Agent Executive (AMGR),
creating a stable, fault tolerant environment
•
Agent Manager
• Minimum AMgr delays
• Agent execution delays can be minimized by tweaking the
user-defined AMgr parameters in the Notes.INI file
• Certain minimum delays are built into AMgr so that setting
all user-defined parameters to zero will not allow the server
to consume too many resources
Debugging Agents
• Agent
•
•
•
•
•
•
•
Debugging Options
Agent Manager debugging
Agent Log
Agent Test
NotesLog Class
Server Console
Remote Debugger
Router agent debugging
Debugging Agents
• Agent
Manager debugging
•
Can help in troubleshooting problems with
scheduled and event-triggered agents
• Provides extensive debugging information
• Agent Manager logging will be directed to the
console and the Notes log
• Three options
• Add
• Add
the Debug_Amgr parameter to the Notes.INI file
Log_AgentManager parameter to the Notes.INI file
• Add DEBUG_OUTFILE to the Notes.INI file
Debugging Agents
• Debug_Amgr=flag
•
Available flags are ...
p - agent performance
c - agent control
statistics
parameters
e - Agent Manager events r - agent execution reports
s - Agent Manager
l - agent loading reports
scheduling
m - agent memory
v - verbose mode
warnings
* - all of the above
Debugging Agents
• Log_AgentManager
•
Provides less information, but consumes less
resources than Debug_Amgr
• Form is Log_AgentManager=flag
•0
- do not show logging
•1 - partial and complete successes
•2 - complete successes only
•
Debug_Amgr will override Log_AgentManager
Debugging Agents
• DEBUG_OUTFILE
•
•
•
•
•
Writes server console messages to a specified
file.
Form is DEBUG_OUTFILE=path
Use this sparingly as it generates additional
disk I/O
For local agents, add this parameter to the
workstation's Notes.INI file.
May be easier to search and send to Lotus for
support
Debugging Agents
• Server
•
Console Options
Use TELL commands to interact with AMgr- the
supported commands are
•Tell
AMgr Pause
•Tell AMgr Resume
•Tell AMgr Schedule
•Tell AMgr Status
•Tell AMgr Debug
•Tell AMgr Quit
Debugging Agents
• Agent
•
Log
Each time an agent is executed, it creates a
brief report that includes
•Date
and time of run
•Number of documents processed
•Actions taken
• Subsequent
• Select an
runs overwrite the log
agent and choose Agent/Log from
the menu in the Designer client to view its log
Debugging Agents
• Developers
can include code that will help in
debugging an agent
•
LotusScript Specific Options
• Message Box function
• Print Statement
•
Java Specific Options
•println
method
•Agent Runner
Debugging Agents
• NotesLog Class
• Powerful, easy to use debugging tool
• Can be used with LotusScript or Java agents to write both
status and error messages
• Works with both foreground and background agents
• Highly configurable
• Good idea to add to agents with any complexity
• Choice of output options
•A
Notes database
• A mail memo
• A file (for scripts that run locally)
• An agent log
Debugging Agents
Router Initiated Agents
• Router
•
agents are not managed by AMGR
The level of errors logged is set in the
Configuration Settings document
•Router/SMTP
•
--> Advanced --> Controls
Options are
•Minimal
•Normal
(default)
•Informational
•Verbose
Performance Tips
Web Agents
• Allow
Web Agents to run concurrently
•
Run Web Agents Concurrently setting in the Internet
Protocols --> HTTP tab
of the Server document
• Daytime
•
vs. Nighttime settings
Make sure there is not a gap in the beginning and end times
between daytime and nighttime hours
• No
Agents will run during the gap time
• Maximum
•
Agent Execution Time
Agents may timeout if set too low
• Check
limit"
the log regularly for the error "Agent did not complete within the time
Domino 6 Agent Overview
• New
•
•
•
•
•
•
•
agent features in ND6
Converting shared and private agents
User Activation
New Restrictions
Script Library Signing
Server agents can access other servers
New Console Commands for AMGR
Remote Debugging
Resources
• Books
at Amazon.com
•
•
Lotus Notes Domino Essential Reference
Fast Track CLP: Lotus Notes and Domino R5
Application Development
• Lotus Notes and Domino 6 Development
• Articles
•
•
LDD Today -- all articles by Julie Kadashavich
In THE VIEW
• Agents
in Notes/Domino 6: A Comprehensive Preview for
Administrators and Developers, Julie Kadashavich, May/June
2002
The 7 Key Points to Take Home
•
•
•
•
•
•
•
You can control & improve agent performance
Coding choices can impact performance
It is critical to understand when and how
different types of agent will be run
AMGR is a powerful ally for agent performance
and monitoring
You can tweak AMGR through the Notes.ini,
Server and Server Configuration documents
There are many useful agent debugging tools
Security has a major impact on agents
Submit your questions now by clicking the
Ask a Question button on the bottom left
corner of your presentation screen.
Thank you!
You can send additional questions to
Dave Hatter and Tim Bankes via
[email protected].