Oracle® Text Reference 11g Release 2 (11.2) Part Number E16593-04 |
|
|
PDF · Mobi · ePub |
This chapter provides reference information for using the CTX_OUTPUT
PL/SQL package.
CTX_OUTPUT
contains the following stored procedures:
Name | Description |
---|---|
ADD_EVENT | Adds an event to the index log. |
ADD_TRACE | Enables tracing. |
DISABLE_QUERY_STATS | Turns off the gathering of query stats for the index. |
ENABLE_QUERY_STATS | Enables gathering of query stats for the index. |
END_LOG | Halts logging of index and document services requests. |
END_QUERY_LOG | Stops logging queries into a logfile. |
GET_TRACE_VALUE | Returns the value of a trace. |
LOG_TRACES | Prints traces to logfile. |
LOGFILENAME | Returns the name of the current log file. |
REMOVE_EVENT | Removes an event from the index log. |
REMOVE_TRACE | Disables tracing. |
RESET_TRACE | Clears a trace. |
START_LOG | Starts logging index and document service requests. |
START_QUERY_LOG | Creates a log file of queries. |
Use this procedure to add an event to the index log for more detailed log output or to enable error tracing for Oracle Text errors.
CTX_OUTPUT.ADD_EVENT(event in NUMBER, errnum in NUMBER := null);
Specify the type of index event to log. You can add the following events:
CTX_OUTPUT.EVENT_INDEX_PRINT_ROWID
, which logs the rowid of each row after it is indexed. This is useful for debugging a failed index operation.
CTX_OUTPUT.EVENT_OPT_PRINT_TOKEN
, which prints each token as it is being optimized.
CTX_OUTPUT.EVENT_INDEX_PRINT_TOKEN
, which prints the each token as it is being indexed.
CTX_OUTPUT.EVENT_DRG_DUMP_ERRORSTACK
, which prints the stack trace for the specified DRG error in the log. An error will be raised if errnum
is not specified.
Specify the DRG error number for a CTX_OUTPUT.EVENT_DRG_DUMP_ERRRORSTACK
event.
begin CTX_OUTPUT.ADD_EVENT(CTX_OUTPUT.EVENT_INDEX_PRINT_ROWID); end;
See Also:
"REMOVE_EVENT"Use this procedure to enable a trace. If the trace has not been enabled, this call adds the trace to the list of active traces and resets its value to 0. If the trace has already been enabled, an error is raised.
CTX_OUTPUT.ADD_TRACE(trace_id BINARY_INTEGER);
Specify the ID of the trace to enable. See Table 10-1 for possible trace values.
Table 10-1 shows the available traces:
Symbol | ID | Metric |
---|---|---|
|
1 |
Time spent executing user datastore |
|
2 |
Time spent invoking the |
|
3 |
Time spent executing the |
|
4 |
Time spent fetching from |
|
5 |
Total number of rows whose token metadata was fetched from |
|
6 |
Time spent fetching the |
|
7 |
Time spent reading |
|
8 |
Number of rows whose |
|
9 |
Number of bytes read from |
|
10 |
Time spent fetching and reading |
|
11 |
Time spent in |
|
15 |
Time spent fetching and reading |
Tracing is independent of logging. Logging does not have to be on to start tracing, and vice-versa.
Traces are associated with a session—they can measure operations that take place within a single session, and conversely, cannot make measurements across sessions.
During parallel sync or optimize, the trace profile will be copied to the slave sessions if and only if tracing is currently enabled. Each slave will accumulate its own traces and implicitly write all trace values to the slave logfile before termination.
See Also:
"REMOVE_TRACE", "GET_TRACE_VALUE", "LOG_TRACES",and "RESET_TRACE", as well as Oracle Text Application Developer's GuideDisables gathering of query stats for the index.
ctx_output.disable_query_stats( index_name IN VARCHAR2 );
The name of the index on which query stats collection is to be disabled.
Turn off gathering of query stats for the index myindex
.
CTX_OUTPUT.DISABLE_QUERY_STATS(myindex);
Once the query stats is disabled for an index, gathering and storing query-related metadata is stopped for that index. All the entries corresponding to that index are cleared from the dictionary tables. An error is returned if you call this procedure on an index where query stats is not enabled.
CTX_OUTPUT.ENABLE_QUERY_STATS, and CTX_REPORT.INDEX_STATS.
Enables gathering of query stats for the index. To have query-related metadata stored for the index, use this procedure to enable collection of statistics on that index. You can only access the gathered metadata when ctx_output.enable_query_stats
is turned on for the index.
Note:
Accessing the query stats metadata only works whenctx_output.enable_query_stats
is turned on for the index. Please see CTX_REPORT.INDEX_STATS for the list of gathered query stats metadata.ctx_output.enable_query_stats( index_name IN VARCHAR2 );
The name of the index on which query stats collection is to be enabled.
Turn on gathering of query stats for the index myindex
.
CTX_OUTPUT.ENABLE_QUERY_STATS(myindex);
The information that shows whether query stats is enabled on an index is available in the views: CTX_INDEXES
and CTX_USER_INDEXES
under the column idx_query_stats_enabled
, which is in both of these views. If query_stats
is enabled for an index, then the column displays YES; if not, then the column displays NO.
The data corresponding to the query statistics will be stored in persistent dictionary tables. Once statistics
has been enabled for a particular index, query statistics will be collected for that index from all sessions.
If you call this procedure for an index where query stats is already enabled, then an error is thrown.
Statistics collection has a minimal effect on query performance.
CTX_OUTPUT.DISABLE_QUERY_STATS, and CTX_REPORT.INDEX_STATS.
This procedure halts logging index and document service requests.
ctx_output.end_log;
begin CTX_OUTPUT.END_LOG; end;
Use this procedure to stop logging queries into a logfile created with CTX_OUTPUT.START_QUERY_LOG.
ctx_output.end_query_log;
begin
CTX_OUTPUT.START_QUERY_LOG('mylog1'); < get queries > CTX_OUTPUT.END_QUERY_LOG;
end;
Use this procedure to programmatically retrieve the current value of a trace.
CTX_OUTPUT.GET_TRACE_VALUE(trace_id BINARY_INTEGER);
Specify the trace ID whose value you want. See Table 10-1, "Available Traces" for possible values.
This sets the value of the variable value:
value := ctx_output.get_trace_value(trace_id);
You can also retrieve trace values through SQL:
select * from ctx_trace_values;
See "CTX_TRACE_VALUES" for the entries in the CTX_TRACE_VALUES
view.
If the trace has not been enabled, an error is raised.
Traces are not reset to 0 by this call.
Traces are associated with a session—they can measure operations that take place within a single session, and conversely, cannot make measurements across sessions.
See Also:
"REMOVE_TRACE", "ADD_TRACE", "LOG_TRACES",and "RESET_TRACE", as well as the Oracle Text Application Developer's GuideUse this procedure to print all active traces to the logfile.
CTX_OUTPUT.LOG_TRACES;
If logging has not been started, an error is raised.
Traces are not reset to 0 by this call.
This procedure looks for the logfile in the directory specified by the LOG_DIRECTORY
system parameter, which is $ORACLE_HOME/ctx/log
on UNIX. You can query the CTX_PARAMETERS
view to find the current setting.
See Also:
"REMOVE_TRACE", "GET_TRACE_VALUE", "ADD_TRACE", and "RESET_TRACE", as well as the Oracle Text Application Developer's GuideReturns the filename for the current log. This procedure looks for the logfile in the directory specified by the LOG_DIRECTORY
system parameter, which is $ORACLE_HOME/ctx/log
on UNIX. You can query the CTX_PARAMETERS
view to find the current setting.
CTX_OUTPUT.LOGFILENAME RETURN VARCHAR2;
Log file name.
declare logname varchar2(100); begin logname := CTX_OUTPUT.LOGFILENAME; dbms_output.put_line('The current log file is: '||logname); end;
Use this procedure to remove an event from the index log.
CTX_OUTPUT.REMOVE_EVENT(event in NUMBER);
Specify the type of index event to remove from the log. You can remove the following events:
CTX_OUTPUT.EVENT_INDEX_PRINT_ROWID
, which logs the rowid of each row after it is indexed. This is useful for debugging a failed index operation.
CTX_OUTPUT.EVENT_OPT_PRINT_TOKEN
, which prints each token as it is being optimized.
CTX_OUTPUT.EVENT_INDEX_PRINT_TOKEN
, which prints the each token as it is being indexed.
begin
CTX_OUTPUT.REMOVE_EVENT(CTX_OUTPUT.EVENT_INDEX_PRINT_ROWID);
end;
See Also:
"ADD_EVENT"Use this procedure to disable a trace.
CTX_OUTPUT.REMOVE_TRACE(trace_id BINARY_INTEGER);
Specify the ID of the trace to disable. See Table 10-1, "Available Traces" for possible values.
If the trace has not been enabled, an error is raised.
See Also:
"GET_TRACE_VALUE", "ADD_TRACE", "LOG_TRACES",and "RESET_TRACE", as well as the Oracle Text Application Developer's GuideUse this procedure to clear a trace (that is, reset it to 0).
CTX_OUTPUT.RESET_TRACE(trace_id BINARY_INTEGER);
Specify the ID of the trace to reset. See Table 10-1, "Available Traces" for possible values.
If the trace has not been enabled, an error is raised.
See Also:
"REMOVE_TRACE", "GET_TRACE_VALUE", "ADD_TRACE", "LOG_TRACES", as well as the Oracle Text Application Developer's GuideBegin logging index and document service requests.
CTX_OUTPUT.START_LOG(logfile in varchar2, overwrite in default true);
Specify the name of the log file. The log is stored in the directory specified by the system parameter LOG_DIRECTORY
.
Specify whether you want to overwrite or append to the original query log file specified by logfile, if it already exists. The default is to overwrite the original query log file.
begin CTX_OUTPUT.START_LOG('mylog1'); end;
Logging is independent of tracing. Logging does not have to be on to start tracing, and vice-versa.
Logging is associated with a session—it can log operations that take place within a single session, and, conversely, cannot make measurements across sessions.
Filenames used in CTX_OUTPUT.START_LOG
are restricted to the following characters: alphanumeric, minus, period, space, hash, underscore, single and double quotes. Any other character in the filename will raise an error.
Begin logging query requests into a query log file.
Use CTX_OUTPUT.END_QUERY_LOG
to stop logging queries. Use CTX_REPORT.QUERY_LOG_SUMMARY
to obtain reports on logged queries, such as which queries returned successfully the most times.
The query log includes the query string, the index name, and the timestamp of the query, as well as whether or not the query successfully returned a hit. A successful query for the phrase Blues Guitarists made at 6:46 (local time) on November 11th, 2003, would be entered into the query log in this form:
<QuerySet><TimeStamp>18:46:51 02/04/03</TimeStamp><IndexName> IDX_SEARCH_TABLE</IndexName><Query>Blues Guitarists</Query><ReturnHit>Yes</ReturnHit></QuerySet>
CTX_OUTPUT.START_QUERY_LOG(logfile in varchar2, overwrite in default true);
Specify the name of the query log file. The query log is stored in the directory specified by the system parameter LOG_DIRECTORY
.
Specify whether you want to overwrite or append to the original query log file specified by logfile, if it already exists. The default is to overwrite the original query log file.
begin
CTX_OUTPUT.START_QUERY_LOG('mylog1'); < get queries > CTX_OUTPUT.END_QUERY_LOG;
end;
Filenames used in CTX_OUTPUT.START_QUERY_LOG
are restricted to the following characters: alphanumeric, minus, period, space, hash, underscore, single and double quotes. Any other character in the filename will raise an error.
Logging is associated with a session—it can log operations that take place within a single session, and, conversely, cannot make measurements across sessions.