Content Manager OnDemand Content Manager OnDemand ODWEK – Enabling tracing, logging and requirements This presentation covers enabling diagnostics and troubleshooting ODWEK. Purpose Purpose Provide an overview of enabling ODWEK logging and tracing analysis and ODWEK requirements The purpose of this presentation is to provide an overview of enabling ODWEK logging and tracing analysis and ODWEK requirements. Enabling ODWEK tracing and logging Enabling ODWEK tracing and logging In ODWEK V7.1.2.5, a new trace mechanism was introduced Previous versions used logging (arswww.log) ODWEK trace file is archived and renamed when ODWEK application is restarted ODWEK Java™ APIs will archive and rename the arswww.trace file if all ODServer objects are currently terminated Archived and renamed to arswww.trace A new trace mechanism was introduced in ODWEK version 7.1.2.5. Previous versions used ODWEK logging. When the ODWEK application is restarted, the ODWEK trace file is archived and renamed. The ODWEK Java™ APIs will archive and rename the trace file if all ODServer objects are currently terminated. When ODWEK archives the trace file, the timestamp is appended to the arswww.trace file name. Enabling ODWEK tracing and logging (continued) Enabling ODWEK tracing and logging (continued) Enabling ODWEK tracing will have a noticeable performance impact ODWEK trace file not maintained and can grow very large (hundreds of MBs, GBs) As with any trace, enabling ODWEK tracing will have a noticeable impact on performance. Since the ODWEK trace file is not maintained, the file size can grow very large, possibly hundreds of MBs, or GBs. Enabling ODWEK tracing and logging (continued) Enabling ODWEK tracing and logging (continued) Enabling ODWEK tracing (ODWEK V7.1.2.5 or later) Instructions to enable: http://www-1.ibm.com/support/docview.wss?rs=129&context=SSEPCD&context=SSEPC6&q1=odwek+trace&uid=swg21240220&loc=en_US&cs=utf-8&lang=en If using the ODConfig object in the Java APIs, set the TraceLevel parameter accordingly (values of 1-4) To enable ODWEK tracing when using ODWEK V7.1.2.5 or later, follow the instructions on the “How do I enable DB2® Content Manager OnDemand Web Enablement Kit (ODWEK) trace?” page. The address is displayed on this slide. If using the ODConfig object in the Java APIs, set the TraceLevel parameter accordingly (values of 1-4). Enabling ODWEK tracing and logging (continued) Enabling ODWEK tracing and logging (continued) Enabling ODWEK logging (ODWEK V7.1.2.4 or earlier) Add/uncomment this debug stanza [debug] log=1 logdir=/ars/tmp The log file, arswww.log is written into the directory referenced by ‘logdir’ For ODWEK servlet implementations, you will need to restart the servlet for the arswww.ini change to be reflected To enable ODWEK logging when using ODWEK V7.1.2.4 or earlier, add or uncomment the debug stanza so it reflects the code as shown on the slide. The log file, arswww.log, is written into the directory referenced by ‘logdir’. For ODWEK servlet implementations, you will need to restart the servlet for the arswww.ini to see the change. ODWEK requirements: arswww.ini ODWEK requirements: arswww.ini Each instance of ODWEK in the same environment, must reference its own: arswww.ini CacheDir TempDir TraceDir If using ODConfig object instead of arswww.ini, the TempDir and TraceDir should be unique per ODWEK application For ODWEK requirements for arswww.ini, each instance of ODWEK (CGI, servlet, or Java API) in the same environment must reference its own unique arswww.ini, CacheDir, TempDir, and TraceDir parameter values. For example, if a customer has two ODWEK Java API applications deployed in WebSphere® on the same machine, each ODWEK application must have its own unique arswww.ini, CacheDir, TempDir, and TraceDir. To avoid unexpected results, a customer using the ODConfig object should have a unique TempDir and TraceDir per ODWEK application. ODWEK requirements: installation or upgrade ODWEK requirements: installation or upgrade ODWEK (CGI, servlet, or Java API) must be installed using the InstallShield or native install packages Copying ODWEK files from one machine to another is not supported Install using root or Windows® Administrator account If ODWEK CGI or servlet was upgraded CacheDir and TempDir contents need to be deleted following an upgrade In regards to ODWEK installation and upgrade requirements, ODWEK (CGI, servlet, or Java API) must be installed using the InstallShield or native install packages. Copying ODWEK files from one machine to another is not supported. You must install using root or a Windows Administrator account. If ODWEK CGI or servlet was upgraded, the CacheDir and TempDir contents need to be deleted in order to avoid unexpected results, or at worse, an ODWEK abend. ODWEK requirements: Native heap ODWEK requirements: Native heap ODWEK Servlet and Java API native heap requirement Two * (average uncompressed document size) * (average number of concurrent document retrievals) ODWEK Servlet and Java API Java heap requirement (average uncompressed document size) * (average number of concurrent document retrievals) In general, the ODWEK native heap requirement is two times the average uncompressed document size multiplied by the average # of concurrent document retrievals. Also, in general, the ODWEK Java heap requirement is the average uncompressed document size multiplied by the average number of concurrent document retrievals. ODWEK requirements: Native heap (continued) ODWEK requirements: Native heap (continued) ODWEK requires more native heap then Java heap ODWEK will abend if unable to allocate enough contiguous native heap for the requested operation Memory not allocated or reserved to Java heap is available as native heap JVM reserves the maximum Java heap (Xmx) on initialization ODWEK is not a pure Java application, most of ODWEK’s processing is performed in the native C shared library (libarswwwsl or ars3wapi). For this reason, ODWEK requires more native heap then Java heap. If ODWEK cannot allocate enough contiguous native heap for the requested operation, ODWEK will typically abend. To avoid an abend, ensure that the Java maximum heap (Xmx) is not set too high. Memory not allocated or reserved to Java heap is available as native heap. On initialization, the JVM allocates the entire Java heap in a single contiguous area of virtual storage. The amount that is allocated is determined by the setting of the -Xmx parameter. No virtual space from the heap is ever freed back to the native operating system. When the heap shrinks, it shrinks inside the original virtual space. ODWEK requirements: Native heap (continued) ODWEK requirements: Native heap (continued) A single process can allocate up to 4GB of memory (232 address space) in a 32-bit environment Varying amounts of this 4GB address space is reserved for the user process (Java) and kernel AIX® – user process can allocate up to 2.5GB (configurable up to 3.25GB) Linux® - OS reserves 1GB for kernel and 3GB for user process Windows - OS reserves 2GB for kernel and 2GB for user process Solaris – 3GB for user process (depends on how much physical memory) In a 32-bit environment, the maximum amount of memory a single process can allocate is 4GBs, but depending on the OS, this 4GB address space is shared between the user process and the kernel. This leaves much less memory for the user process, Java, for Java heap and native heap allocations. For example, the maximum amount of memory a user process can allocate when using AIX is 2.5GBs, which can be configured up to 3.25GBs. For Linux, the OS reserves 1GB for kernel and allows 3GB for the user process. The OS reserves 2GBs for kernel and allows 2GBs for the user process in a Windows environment. And in general for Solaris, a 3GB address space can be allocated by a user process; however this depends on how much physical memory exists. Another example is if a 32-bit environment has 10GBs of virtual memory. A single process can only allocate a theoretical 4GB amount. To use more virtual memory, either a 64-bit environment should be considered or running a clustered application server environment. This will allow multiple Java processes to be launched, each independently hosting the same ODWEK application. ODWEK requirements: Native heap (continued) ODWEK requirements: Native heap (continued) Document retrievals are the most native memory intensive operations ODWEK requires native heap for the entire document to be in memory for processing ODWEK was not designed to be used to retrieve very large documents (several hundred MB) Large documents can be archived into OnDemand with Large Object support instead. There are ODWEK Java APIs to retrieve directly to file instead (no native heap is used) ODHit.retrieve (viewer, file name) ODHit.retrieveSegment (segment, file name) ODHit.getDocument (file name, allSegs) Document retrievals are the most native memory intensive operations, as ODWEK requires native heap for the entire document to be in memory for processing. ODWEK was not designed to be used to retrieve very large documents, for example, several hundred megabytes. Instead, it is recommended to load large documents under Large Object support which is only supported with an ACIF, OS/390®, or OS/400® indexers. Large Object breaks the document into logical segments, which are retrieved on the fly as needed by ODWEK. For the ODWEK Java APIs, there are APIs to retrieve documents directly to file as well. No native heap is used. ODWEK requirements: Native heap (continued) ODWEK requirements: Native heap (continued) AFP resources are also cached in native heap compressed ODWEK caches unique AFP resources per application group Not recommended to use large AFP resources (larger then a few MB) For ODWEK Java API, only occurs when ODHit.retrieve API is used to retrieve documents ODWEK servlet and Java APIs cache retrieved AFP resources, compressed, in native heap. Unique AFP resources are cached on a per application group level. It is not recommended to utilize large AFP resources for this reason – memory requirements will be higher. In general, large AFP resources are not optimal for storage, memory, and document print and or retrieval performance in OnDemand. If using the ODWEK Java APIs, AFP resource caching will only occur if the ODHit.retrieve API is used to retrieve documents. ODWEK requirements: Native heap (continued) ODWEK requirements: Native heap (continued) AFP resources are freed from native heap in the following situations: When the ODWEK servlet is stopped When using the ODWEK Java API, all ODServer objects are terminated at a given time (ODServer.terminate) ODWEK Java APIs provide an API (ODHit.getResources) to implement your own AFP resource caching scheme instead AFP resources are freed from native heap in the following situations: -When the ODWEK servlet is stopped. -When using the ODWEK Java API, all ODServer objects are terminated at a given time (ODServer.terminate). If you want to implement your own AFP resource caching scheme instead, the ODWEK Java APIs provide an API to retrieve resources ODHit.getResources. The ODHit.getDocument API can then be used to retrieve just the document data. Concatenating the AFP resource and document data together will form the entire AFP document. ODWEK requirements: Native heap (continued) ODWEK requirements: Native heap (continued) When more memory is required, ODWEK Java APIs can be upgraded to ODWEK V8.4 on UNIX® ODWEK can be run in 64 bit mode (requires 64 bit application server and OS) ODWEK Java APIs are only provided as 32 bit on Windows ODWEK servlet and CGI can only be run in 32 bit mode on any platform If further memory is required, customers using the ODWEK Java APIs can upgrade to ODWEK V8.4 on UNIX as ODWEK can be run in 64 bit mode. ODWEK V8.4 requires a 64 bit application server and OS. ODWEK Java APIs are only provided as 32 bit on Windows and ODWEK servlet and CGI can only be run in 32 bit mode on any platform. Feedback Feedback Your feedback is valuable You can help improve the quality of IBM Education Assistant content to better meet your needs by providing feedback. Did you find this module useful? Did it help you solve a problem or answer a question? Do you have suggestions for improvements? Click to send e-mail feedback: mailto:iea@us.ibm.com?subject=Feedback_about_ODWEK_LoggingTracing2.ppt This module is also available in PDF format at: ../ODWEK_LoggingTracing2.pdf You can help improve the quality of IBM Education Assistant content by providing feedback. Trademarks