Maximize Agent Performance

1. Maximize Agent Performance Dave Hatter & Tim Bankes Libertas Technologies, LLC

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

3. 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 A Little About Us

4. 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 Factors Affecting Performance

5. 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? Agent Execution

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

7. 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? Server Based Agents Defined

8. 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? Local Agents Defined

9. 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? Personal vs. Shared Agents

10. 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? Foreground & Background Agents

11. 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? Embedded Agents & Web Agents

12. 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 Can an Agent Run Faster/Reliably? Web Agents

13. Domino provides numerous coding options when building agents • Java • LotusScript • Formula Language • Simple Actions Agent Coding Options

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

15. 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 Coding Options

16. 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 Restrictions

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

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

19. 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 Agent Queues

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

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

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

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

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

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

26. 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 Agent Manager

27. Agent Debugging Options • Agent Manager debugging • Agent Log • Agent Test • NotesLog Class • Server Console • Remote Debugger • Router agent debugging Debugging Agents

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

29. p - agent performance statistics r - agent execution reports s - Agent Manager scheduling v - verbose mode * - all of the above c - agent control parameters e - Agent Manager events l - agent loading reports m - agent memory warnings • Debug_Amgr=flag • Available flags are ... Debugging Agents

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

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

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

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

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

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

36. 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 Debugging Agents Router Initiated Agents

37. 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" Performance Tips Web Agents

38. 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 Domino 6 Agent Overview

39. 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 Resources

40. 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 The 7 Key Points to Take Home

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