Diagnosing Issues with Agents

Managing Usage Tracking 9-3 ■ BUFFER_SIZE. This parameter indicates how much memory the BI Server should allocate for buffering the insert statements. Such a buffer lets the BI Server submit multiple insert statements as part of a single transaction, improving Usage Tracking insert throughput. It also means that ordinary analyses do not have to wait on Usage Tracking insertions, which improves average query response time. You might want to adjust this value based on available memory and memory utilization on the server computer. ■ BUFFER_TIME_LIMIT_SECONDS. This parameter indicates the maximum amount of time that an insert statement remains in the buffer before the Usage Tracking subsystem attempts to issue it. This time limit ensures that the BI Server issues the insert statements quickly, even during periods of extended quiescence. ■ NUM_INSERT_THREADS. This parameter indicates the number of threads that remove insert statements from the buffer and issue them to the Usage Tracking database. Assuming separate connection pools for readers and inserters, the number of insert threads should typically equal the Maximum Connections setting in the connection pool. ■ MAX_INSERTS_PER_TRANSACTION. This parameter indicates the maximum number of insert statements that the Usage Tracking subsystem attempts to issue as part of a single transaction. The larger this number, the greater potential throughput for UsageMarathon Tracking inserts. However, a larger number also increases the likelihood of transactions failing due to deadlocks. A small value for BUFFER_TIME_LIMIT_SECONDS can limit the number of inserts per transaction. See Appendix A, NQSConfig.INI File Configuration Settings for additional information about the usage tracking configuration parameters.

9.1.2 Setting Up a Log File to Collect Information for Usage Tracking

Log file collection is an alternate method for configuring usage tracking. Although this feature is supported, it is recommended that you use direct insertion to collect information for usage tracking. See Section 9.1.1, Setting Up Direct Insertion to Collect Information for Usage Tracking for details. The following sections explain how to configure log file collection for usage tracking. Before you configure the log file parameters, you must set the ENABLE parameter in the Usage Tracking section of the NQSConfig.INI file to YES to enable usage tracking. See Appendix A, NQSConfig.INI File Configuration Settings for more information about the usage tracking configuration parameters. This section contains the following topics: ■ Section 9.1.2.1, Selecting an Output Location ■ Section 9.1.2.2, File Naming Conventions ■ Section 9.1.2.3, Output File Format ■ Section 9.1.2.4, Performance Considerations

9.1.2.1 Selecting an Output Location

The STORAGE_DIRECTORY parameter in the Usage Tracking section of the NQSConfig.INI file determines the location of usage tracking log files. If usage tracking is enabled, but no storage folder is specified, then the files are written in the logs folder in the software installation folder for example, in \OBI11g\logs. 9-4 System Administrators Guide for Oracle Business Intelligence Enterprise Edition Current files are periodically written to disk, and new files are created. The CHECKPOINT_INTERVAL_MINUTES parameter controls the frequency with which usage tracking data is flushed to disk, and the FILE_ROLLOVER_INTERVAL_ MINUTES parameter controls the frequency with which the current usage tracking log file is closed and a new file is created. When usage tracking is enabled, every query is logged to a usage tracking log file. This might require a large amount of available storage. For example, assume an average of 300 bytes of data output for each query and 10 queries per second over an 8 hour day. This results in approximately 83 MB of usage tracking data that is written to storage per day. If this example is extended to a 24 x 7 operation, then the result is approximately .25 GB of storage per day. The BI Server has no limit on the size or quantity of usage tracking log files that can exist in the specified location. You must ensure that sufficient space is available and that you remove or archive old usage tracking files.

9.1.2.2 File Naming Conventions

The file naming scheme for the usage tracking log files is NQAcct.yyyymmdd.hhmmss.log, where yyyy is the year, mm is the month, dd is the day, hh is the hour, mm is the minute, and ss is the second of the timestamp when the file was created. For example, if the server creates the usage tracking log file at 07:15:00 a.m. on February 12, 2010, the file name would be NQAcct.20100212.071500.log. After the specified rollover interval, this file is flushed to disk and closed and a new log file, with the current date and timestamp, is created.

9.1.2.3 Output File Format

The usage tracking log files are text files, in semicolon-delimited ; format. A semicolon is used as the column delimiter because the logical SQL text contains commas. A line feed delimits the end of each row of data. Although there is no guaranteed unique key for the usage tracking data, a combination of User name, Node ID, Start timestamp, and Query text is usually sufficient. Query_Key can be used as an unique key but Query_Key is available only in direct insert. For information about sample scripts to help you extract data from usage tracking log files and load it to appropriately formatted relational database tables, see Chapter 9, Managing Usage Tracking. See also Section 9.2, Description of the Usage Tracking Data for more information about the contents of each column. Table 9–1 shows the format of the usage tracking output file. Caution: Insufficient storage space might cause you to lose usage tracking data. If the BI Server encounters an error while accessing a usage tracking output file, then it immediately discontinues the collection of usage tracking statistics and issues an error message to the nqserver.log and, on Windows, to the Windows Event log. Even if additional storage space is made available, the collection of usage tracking statistics does not resume until the server is restarted. Table 9–1 Usage Tracking Output File Format Column Number Column Name Data Type Max Data Size Nullable 1 User name Varchar 128 No Managing Usage Tracking 9-5 Table 9–1 describes the schema. The following list contains more detail about Integer data types, Timestamp columns, and the Query Text column: ■ Integers data types. All data in the output file is in character format. The data in columns 12 through 18 are output as text representations of integer numbers. Therefore, they behave more like Varchar10 columns than integers. For example, if the row count is one million rows, then 1000000 appears in the output file in column 13 Row count. This constitutes 7 bytes of data, even though the data represents a 4-byte internal integer value. In column 12, a Success indicator value of 0 signifies a successful query. All nonzero values indicate failure. The following failure indicators are currently defined: – 1 indicates timeout – 2 indicates row limit violation – 3 indicates unknown error 2 Repository name Varchar 128 No 3 Subject area name Varchar 128 No 4 Node ID Varchar 15 No 5 Start timestamp Char Timestamp 19 No 6 Start date Char yyyy-mm-dd 10 No 7 Start hourMin Char hh:mm 5 No 8 End timestamp Char Timestamp 19 No 9 End date Char yyyy-mm-dd 10 No 10 End hourMin Char hh:mm 5 No 11 Query Text Varchar 1024 No 12 Success indicator Integer 4 No 13 Row count Integer 4 Yes 14 Total time secs Integer 4 Yes 15 Compilation time secs Integer 4 Yes 16 Number of database queries Integer 4 Yes 17 Cumulative db time secs Integer 4 Yes 18 Cumulative db rows Integer 4 Yes 19 Cache indicator Char 1 No 20 Query source Varchar 30 No 21 Presentation Catalog path Varchar 250 No 22 Dashboard name Varchar 150 Yes Table 9–1 Cont. Usage Tracking Output File Format Column Number Column Name Data Type Max Data Size Nullable