11 CTX_OUTPUTパッケージ
この章では、PL/SQLパッケージCTX_OUTPUT
の使用方法について説明します。
CTX_OUTPUT
には、次のストアド・プロシージャが含まれています。
名前 | 説明 |
---|---|
索引ログにイベントを追加します。 |
|
トレースを使用可能にします。 |
|
索引の問合せ統計の収集をオフに切り替えます。 |
|
索引の問合せ統計の収集を使用可能にします。 |
|
索引およびドキュメント・サービスの要求のロギングを停止します。 |
|
ログ・ファイルへの問合せのロギングを停止します。 |
|
トレースの値を戻します。 |
|
トレースをログ・ファイルに出力します。 |
|
現在のログ・ファイルの名前を戻します。 |
|
索引ログからイベントを削除します。 |
|
トレースを使用不可にします。 |
|
トレースをクリアします。 |
|
索引およびドキュメント・サービスの要求のロギングを開始します。 |
|
問合せのログ・ファイルを作成します。 |
ノート:
CTX_OUTPUT
パッケージのAPIは、スキーマまたは所有者名を接頭辞として使用する識別子をサポートしていません。
11.1 ADD_EVENT
このプロシージャを使用して、詳細なログ出力を表示するためにイベントを索引ログに追加するか、またはOracle Textエラーのエラー・トレースを使用可能にします。索引ログが、データベース・トレース・ファイルに追加されます。
構文
CTX_OUTPUT.ADD_EVENT(event in NUMBER, errnum in NUMBER := null);
- event
-
ロギングする索引イベントの型を指定します。次のイベントを追加できます。
-
CTX_OUTPUT.EVENT_INDEX_PRINT_ROWID
: 索引付けが終了した各行のROWIDをロギングします。これは、失敗した索引操作のデバッグに有効です。 -
CTX_OUTPUT.EVENT_INDEX_PRINT_TOKEN
: 各トークンが索引付けされるたびに出力します。 -
CTX_OUTPUT.EVENT_DRG_DUMP_ERRORSTACK
: ログの指定されたDRGエラーのスタック・トレースを出力します。errnum
が指定されないと、エラーが発生します。
ノート:
CTX_OUTPUT.EVENT_OPT_PRINT_TOKEN
は、最適化されるたびに各トークンを出力し、CTX_OUTPUT.EVENT_INDEX_PRINT_TOKEN
は、索引付けされるたびに各トークンを出力します。これらは、PDBロックダウン・プロファイルCTX_PROTOCOLS
を使用する場合、使用不可になります。 -
- errnum
-
CTX_OUTPUT.EVENT_DRG_DUMP_ERRRORSTACK
イベントのDRGエラー番号を指定します。
例
begin CTX_OUTPUT.ADD_EVENT(CTX_OUTPUT.EVENT_INDEX_PRINT_ROWID); end;
関連項目
11.2 ADD_TRACE
トレースを使用可能にします。トレースが使用可能でない場合、このコールにより、トレースがアクティブなトレースのリストに追加され、値が0(ゼロ)にリセットされます。トレースがすでに使用可能になっている場合、エラーが発生します。
構文
CTX_OUTPUT.ADD_TRACE(trace_id BINARY_INTEGER);
- trace_id
-
使用可能にするトレースのIDを指定します。有効なトレース値は、表11-1を参照してください。
ノート
表11-1は、有効なトレースを示しています。
表11-1 有効なトレース
記号 | ID | メトリック |
---|---|---|
|
1 |
ユーザー・データストアの実行に要した時間 |
|
2 |
|
|
3 |
|
|
4 |
|
|
5 |
トークン・メタデータが |
|
6 |
|
|
7 |
|
|
8 |
|
|
9 |
|
|
10 |
|
|
11 |
|
|
15 |
|
|
19 |
|
|
23 |
|
|
25 |
ドキュメントからスニペットを抽出する際に費やした時間 |
|
26 |
ドキュメント・サービスのプロシージャ(スニペット、ハイライト、マークアップ)によって費やされた時間 |
トレースはロギングから独立しています。トレースの開始にはロギングがオンになっている必要はなく、その逆も同じです。
トレースはセッションに関連付けられています。1つのセッション内で発生する操作は測定できますが、逆にセッション全体にわたる測定はできません。
パラレル同期化または最適化の際、トレースが現在有効になっている場合にかぎり、トレース・プロファイルはワーカー・セッションにコピーされます。各ワーカーは独自のトレースを蓄積し、終了前にすべてのトレース値をワーカー・ログ・ファイルに暗黙的に書き込みます。
11.3 DISABLE_QUERY_STATS
索引の問合せ統計の収集を使用不可にします。
例
索引myindex
の問合せ統計の収集をオフに切り替えます。
CTX_OUTPUT.DISABLE_QUERY_STATS(myindex);
ノート
索引の問合せ統計を使用不可にすると、その索引の問合せに関連するメタデータの収集と格納が停止されます。その索引に対応するすべてのエントリは、ディクショナリ表からクリアされます。問合せ統計が使用可能でない索引に対してこのプロシージャをコールすると、エラーが戻ります。
11.4 ENABLE_QUERY_STATS
索引の問合せ統計の収集を使用可能にします。索引の問合せに関連するメタデータを保存する場合は、このプロシージャを使用して、その索引に対する統計の収集を使用可能にします。索引のctx_output.enable_query_stats
がオンになっている場合にのみ、収集されたメタデータにアクセスできます。
ノート:
問合せ統計メタデータへのアクセスは、索引のctx_output.enable_query_stats
がオンになっている場合にのみ機能します。収集される問合せ統計メタデータのリストは、CTX_REPORT.「INDEX_STATS」を参照してください。
例
索引myindex
の問合せ統計の収集をオンに切り替えます。
CTX_OUTPUT.ENABLE_QUERY_STATS(myindex);
ノート
索引の問合せ統計が使用可能かどうかを示す情報は、CTX_INDEXES
ビューおよびCTX_USER_INDEXES
ビューのidx_query_stats_enabled
列で確認できます。索引のquery_stats
が使用可能な場合は、その列に「YES」が表示され、使用可能でない場合は「NO」が表示されます。
問合せ統計に対応するデータは、永続的なディクショナリ表に格納されます。特定の索引に対してstatistics
が使用可能になると、その索引について全セッションから問合せ統計が収集されます。
問合せ統計がすでに使用可能になっている索引に対してこのプロシージャをコールすると、エラーが発生します。
統計収集は、問合せのパフォーマンスにわずかな影響を与えます。
11.6 END_QUERY_LOG
このプロシージャを使用して、問合せのログのデータベースのトレース・ファイルへの出力を中止します。
構文
ctx_output.end_query_log;
例
begin
CTX_OUTPUT.START_QUERY_LOG('mylog1'); < get queries > CTX_OUTPUT.END_QUERY_LOG;
end;
11.7 GET_TRACE_VALUE
トレースの現行値をプログラムによって取得します。
構文
CTX_OUTPUT.GET_TRACE_VALUE(trace_id BINARY_INTEGER);
- trace_id
-
値を取得するトレースIDを指定します。有効な値は、表11-1を参照してください。
例
これにより、変数valueの値を設定します。
value := ctx_output.get_trace_value(trace_id);
ノート
SQLを使用してもトレース値を取得できます。
select * from ctx_trace_values;
CTX_TRACE_VALUES
ビューのエントリは、「CTX_TRACE_VALUES」を参照してください。
トレースが使用可能でない場合は、エラーが発生します。
このコールでは、トレースは0(ゼロ)にリセットされません。
トレースはセッションに関連付けられています。1つのセッション内で発生する操作は測定できますが、逆にセッション全体にわたる測定はできません。
11.8 LOG_TRACES
このプロシージャを使用して、すべてのアクティブなトレースをRDBMSトレース・ファイルに出力します。
構文
CTX_OUTPUT.LOG_TRACES;
ノート
このコールでは、トレースは0(ゼロ)にリセットされません。
トレースは、データベースのトレース・ファイルに出力されます。
11.9 LOGFILENAME
現行のセッションのトレース・ファイル名を返します。ログの出力が開始しない場合、エラーが発生します。
構文
CTX_OUTPUT.LOGFILENAME RETURN VARCHAR2;
戻り値
ログ・ファイルの名前
例
declare logname varchar2(100); begin logname := CTX_OUTPUT.LOGFILENAME; dbms_output.put_line('The current log file is: '||logname); end;
11.10 REMOVE_EVENT
このプロシージャを使用して、ctx_output.add_event
を使用して追加したイベントを削除します。
構文
CTX_OUTPUT.REMOVE_EVENT(event in NUMBER);
例
begin
CTX_OUTPUT.REMOVE_EVENT(CTX_OUTPUT.EVENT_INDEX_PRINT_ROWID);
end;
関連項目
11.11 REMOVE_TRACE
トレースを使用不可にします。
構文
CTX_OUTPUT.REMOVE_TRACE(trace_id BINARY_INTEGER);
- trace_id
-
使用不可にするトレースのIDを指定します。有効な値は、表11-1を参照してください。
ノート
トレースが使用可能でない場合は、エラーが発生します。
11.12 RESET_TRACE
トレースをクリアします(つまり0(ゼロ)にリセットします)。
構文
CTX_OUTPUT.RESET_TRACE(trace_id BINARY_INTEGER);
- trace_id
-
リセットするトレースのIDを指定します。有効な値は、表11-1を参照してください。
ノート
トレースが使用可能でない場合は、エラーが発生します。
11.13 START_LOG
索引およびドキュメント・サービスの要求のロギングを開始します。索引ログはデータベース・トレース・ファイルに書き込まれます。
構文
CTX_OUTPUT.START_LOG(logfile in varchar2, overwrite in default true);
- logfile
-
ログ・ファイルの名前を指定します。Oracle Database 12cリリース2 (12.2)以降では、logfileパラメータは無視されます。ログが、データベース・トレース・ファイルに追加されます。
V$DIAG_INFO
およびV$PROCESS
などのディクショナリ・ビューを使用して、現行セッションのトレース・ファイルへのパス、または各Oracle Databaseプロセスのトレース・ファイルへのパスを検索します。自動診断リポジトリ・コマンド・インタプリタ(ADRCI)ユーティリティは、トレース・ファイルへのアクセスにも使用できます。
- overwrite
-
logfileで指定された元の問合せログ・ファイル(すでに存在する場合)を上書きするか、またはそこに追加するかを指定します。Oracle Database 12cリリース2 (12.2)以上では、このパラメータは無視されます。デフォルトでは、すべてのログがデータベース・トレース・ファイルに追加されます。
例
begin CTX_OUTPUT.START_LOG('mylog1'); end;
索引ログを表示するには、次のようにして、ビューV$DIAG_TRACE_FILE_CONTENTS
のCOMPONENT_NAME=’CONTEXT_INDEX’
を検索します。
select PAYLOAD from V$DIAG_TRACE_FILE_CONTENTS where COMPONENT_NAME='CONTEXT_INDEX' and TRACE_FILENAME = trc_name;
問合せログを表示するには、次のようにして、ビューV$DIAG_TRACE_FILE_CONTENTS
のCOMPONENT_NAME=’CONTEXT_QUERY’
を検索します。
select PAYLOAD from V$DIAG_TRACE_FILE_CONTENTS where COMPONENT_NAME='CONTEXT_QUERY' and TRACE_FILENAME = trc_name;
パラレル問合せ(PQ)ワーカーのトレース・ファイル名のタイプは、SID_
pxxx
_PID.trc
です。パラレル・ワーカー内のトレースを表示するには:
select TRACE_FILENAME, PAYLOAD from V$DIAG_TRACE_FILE_CONTENTS where COMPONENT_NAME='CONTEXT_INDEX' and TRACE_FILENAME LIKE '%p00%';
ノート
PDBロックダウン・プロファイルCTX_LOGGING
が有効な場合、ログは書き込まれません。
トレースの開始にはロギングがオン
になっている必要はなく、その逆も同じです。
ロギングはセッションに関連付けられています。1つのセッション内で発生する操作はログに記録できますが、逆に複数セッションにわたる操作はログに記録できません。
CTX_OUTPUT.START_LOG
に使用されるファイル名の文字は、英数字、マイナス記号、ピリオド、スペース、ハッシュ記号、アンダースコア、一重引用符および二重引用符に制限されています。ファイル名にその他の文字が使用されていると、エラーが発生します。
11.14 START_QUERY_LOG
ロギング問合せのリクエストを開始します。Oracle Database 12c リリース2 (12.2)以降では、問合せログはデータベース・トレース・ファイルに書き込まれます。
問合せのロギングを停止するには、CTX_OUTPUT.END_QUERY_LOG
を使用します。どの問合せが最も頻繁に正常に戻されたかなど、ログに記録された問合せに関するレポートを取得するには、CTX_REPORT.QUERY_LOG_SUMMARY
を使用します。
問合せログには、問合せ文字列、索引名、問合せのタイムスタンプ、および問合せがヒットを戻したかどうかが含まれます。2003年11月11日6:46 (現地時間)にBlues Guitaristsという句に対する問合せが成功した場合、問合せログに次の形式で入力されます。
<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);
- logfile
-
問合せログ・ファイルの名前を指定します。Oracle Database 12cリリース2 (12.2)以降では、
logfile
パラメータは無視されます。そのかわり、ログが、データベース・トレース・ファイルに追加されます。V$DIAG_INFO
およびV$PROCESS
などのディクショナリ・ビューを使用して、現行セッションのトレース・ファイルへのパス、または各Oracle Databaseプロセスのトレース・ファイルへのパスを検索します。自動診断リポジトリ・コマンド・インタプリタ(ADRCI)ユーティリティは、トレース・ファイルへのアクセスにも使用できます。
- overwrite
-
logfile
で指定された元の問合せログ・ファイル(すでに存在する場合)を上書きするか、またはそこに追加するかを指定します。Oracle Database 12cリリース2 (12.2)以上では、このパラメータは無視されます。デフォルトでは、すべてのログがデータベース・トレース・ファイルに追加されます。
例
begin
CTX_OUTPUT.START_QUERY_LOG('mylog1'); < get queries > CTX_OUTPUT.END_QUERY_LOG;
end;
ノート
PDBロックダウン・プロファイルCTX_LOGGING
が有効な場合、ログは書き込まれません。
CTX_OUTPUT.START_QUERY_LOG
に使用されるファイル名の文字は、英数字、マイナス記号、ピリオド、スペース、ハッシュ記号、アンダースコア、一重引用符および二重引用符に制限されています。ファイル名にその他の文字が使用されていると、エラーが発生します。
ロギングはセッションに関連付けられています。1つのセッション内で発生する操作はログに記録できますが、逆に複数セッションにわたる操作はログに記録できません。