Maximize Agent Performance

Dave Hatter & Tim BankesLibertas Technologies, LLC

•Looking for performance•Providing appropriate Agent security•Coding choices, it makes a difference•Managing Agents -- the Agent manager•Debugging Agents•Optimizing Agent performance

What We'll Cover ...

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 is dependent upon ...• Database ACL

•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 a Web client• Agent Manager is not involved• 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 language has many advantages• Very fast

•Fastest 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 use?• LotusScript

•Supports more Domino functionality "out-of-the box"•Has better debugging facilities

• Java •Is not proprietary, is highly extensible, and faster when multi-

threading•Servlets are generally faster than agents

• Bottom line -- Choose the language that provides the best ROI and performance

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 of Agent queues• Eligible to execute

•Waiting for an AMGR process to run them• Scheduled to execute

•Waiting for their time to run

• Event-triggered agents •Waiting for an event

• For event triggered Agents, there are 3 trigger types Scheduled New/updated documents Mail-triggered

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•Default is 1 minute

• If the scheduler isn't running often enough, check this setting

• 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 SchedulesNew/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 agentsafter 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 the Debug_Amgr parameter to the Notes.INI file•Add 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 statisticsr - agent execution reportss - Agent Manager

schedulingv - verbose mode* - all of the above

c - agent control parameters e - Agent Manager eventsl - agent loading reportsm - agent memory

warnings

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 runs overwrite the log• Select an 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 AgentsRouter 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 TipsWeb 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 the log regularly for the error "Agent did not complete within the time limit"

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 editor@SearchDomino.com.