※ 本記事は、Nirmala Sundarappaによる”One Oracle JDBC JAR for All Use Cases (23ai onwards)“を翻訳したものです。

すべてのユース・ケースに1つのOracle JDBC JAR (ojdbc17.jarまたはojdbc11.jarまたはojdbc8.jar)

Oracle Cloud Database Servicesを使用して、診断性、セキュリティおよびユーザー・エクスペリエンスを簡素化し、Javaアプリケーションの生産性を向上させるために、お客様は本番Oracle JDBC Thinドライバ(ojdbcX.jar)を使用して診断を可能にします。Oracle Database 23ai以降では、JDKビルドごとに1つのJDBC jarファイル(ojdbc17.jar、ojdbc11.jarまたはojdbc8.jar)が提供され、本番、デバッグおよびDMSのユース・ケースがサポートされます。これにより、デバッグ目的で本番jar (ojdbcX.jar)からデバッグjar (ojdbcX_g.jar、ojdbcXdms.jarまたはojdbcXdms_g.jar、dms.jar)に切り替える必要がなくなるため、Javaアプリケーションのデバッグが簡略化されます。

改善された自己主導型の診断機能には、次の機能が含まれます:

• 観測性: これにより、JDBCの外部のユーザーは、JDBCの実行およびパフォーマンスに関するサマリー情報にアクセスできます。
• 診断機能: 障害が発生した場合のクリティカルな実行状態を記録します。理想的には、このような状態は、最初に発生した障害を診断し、障害の原因となる問題の解決策を考え出すのに十分です。記録された状態情報の量と、そのような状態を記録するコストとのバランスを取る必要があります。
• 実行トレース: 実行順序の詳細が記録されます。実行トレースには多大なコストがかかるため、限られたコンテキストでのみ有効にする必要があります。

最初の障害時の診断機能: 

「最初の障害時の診断」は、最初に発生した障害のログを取得できる新機能です。この機能では、最も可能性の高い問題を診断する妥当な機会を提供する最も重要な情報のみが取得されます。この機能はデフォルトで有効になっています。これを無効にするには、プロパティをfalseに設定します。
oracle.jdbc.diagnostic.enableDiagnoseFirstFailure=false 、またはプロパティ CONNECTION_PROPERTY_ENABLE_DIAGNOSE_FIRST_FAILURE = FALSE を使用するか、DiagnosticsMXBeanインタフェースを介して関連する操作を使用します。

詳細は、『JDBC開発者ガイド』の40.2 第1障害機能の診断に関する章を参照してください。

パブリック・モードおよび機密モードを使用した診断:

診断機能には、publicとsensitiveの2つのモードがあります。publicモードでは、デバッグ機能は機密情報を記録したり保持したりしません。sensitiveモードでは、デバッグ機能は機密情報を記録し、保持します。sensitiveモードを有効にするには、特権ユーザー・アクセス権が必要です。sensitiveモードは、この2つのプロパティによって制御されます。

-Doracle.jdbc.diagnostic.permitSensitiveDiagnostics=true --> To permit sensitive diagnostics
-Doracle.jdbc.diagnostic.enableSensitiveDiagnostics=true --> To enable sensitive diagnostics
機密診断は、DiagnosticsMXBeanで定義された関連操作を起動して有効化または無効化することもできます。

ロガーおよびロギング・レベルの詳細

ロギングは、パッケージ・レベルおよびロギング・レベルで制御できます。パッケージ・レベルでは、含めるパッケージを指定でき、適切なロギング・レベルを選択すると、生成されるログのボリュームを制御できます。詳細は次を参照してください。

1. 使用できる様々なロガー

ログの量は、トレースする特定のパッケージを選択することで制限できます。以下は、ロガーとその説明のリストです。また、ルート・ロガーは、すべてのパッケージを含む空の文字列として提供され、選択した場合は多くのログが生成されます。たとえば、.level = SEVEREです。

JDBC Related Packages:
oracle.jdbc: ほぼすべてのOracle JDBCメッセージ
oracle.jdbc.driver: コア・ドライバ・コード
oracle.jdbc.pool: DataSourcesおよび接続プーリング
oracle.jdbc.aq: アドバンスト・キューイング
oracle.jdbc.rowset: RowSets 
oracle.jdbc.xa: 分散トランザクション
oracle.sql: 複雑なSQLデータ型

UCP Related Packages:
oracle.ucp: 接続プール機能の実装に使用される必須コールバック・インタフェースとオプション・コールバック・インタフェースの両方が含まれます。
oracle.ucp.admin: 接続プール・マネージャを使用するためのインタフェースと、JMX操作を使用したMBeansが含まれます。
oracle.ucp.jdbc: JDBC接続を使用するインタフェースおよびクラスが含まれます。

2. 異なるロギング・レベルifferent Logging Levels

異なるロギング・レベルによって生成されるログの量が制御されるため、要件に基づいて選択する必要があります。FINERよりも高いレベルでは、大量のログが生成されます。たとえば、ログ詳細の量を減らすには、実行されたSQLおよびエラーや警告をログに記録するCONFIGを選択できます。OFFロギング・レベルを使用すると、ロギングをオフにできます。

ユース・ケース: FileHandlerを使用したJDBCおよびUCPロギングの有効化

FileHandlerは、ファイルにログを取得する場合に使用します。最初のステップでは、logging.configファイルを作成し、正しいハンドラ、ログ名、レベル、サイズなどを選択します。プロパティのリストは、FileHander.htmlを参照してください。次の手順では、次に示すように2つのシステムプロパティーを使用してロギングを有効にします。フォーマッタを指定しない場合は、XMLSimpleFormatterのデフォルト・フォーマッタが使用されます。
-Doracle.jdbc.diagnostic.enableLogging=true (23ai onwards)
-Djava.util.logging.config.file=./logging.config

ノート: プロパティ名(-Doracle.jdbc.Trace=true)は、23aiより前の古いJDBCリリースでロギングを有効にするために異なっていました。23aiでのロギングを有効にするためにこのプロパティを使用することはできません。

# Contents of the logging.config file
handlers = java.util.logging.FileHandler

# Formats into a standard XML format - Default formatter
#java.util.logging.FileHandler.formatter=oracle.jdbc.diagnostics.XMLSimpleFormatter
# Standard format 
java.util.logging.FileHandler.formatter= oracle.jdbc.diagnostics.OracleSimpleFormatter 
# Custom Formatter for UCP 
#java.util.logging.FileHandler.formatter=oracle.ucp.util.logging.UCPFormatter

# For using a directory, [DIR]\\<filename> in case of windows
java.util.logging.FileHandler.pattern = client.log 
# File size is 100MB 
java.util.logging.FileHandler.limit = 100000000 
java.util.logging.FileHandler.count = 1000
java.util.logging.FileHandler.level = FINEST

# Choose different loggers based on the use case
oracle.ucp.level = FINEST 
oracle.jdbc.level = FINEST 

#sample for class level
oracle.ucp.jdbc.oracle.OracleDatabaseInstanceInfo.level = ALL
oracle.ucp.jdbc.oracle.OracleDatabaseInstanceInfoList.level = ALL

ユース・ケース2: ConsoleHandlerを使用したJDBCおよびUCPロギングの有効化

基本構成(ConsoleHandler)は、ログをコンソールに出力します。最初のステップでは、logging.configファイルを作成し、適切なハンドラ、ログ名、レベル、サイズなどを選択します。使用できるプロパティの説明は、ConsoleHander.htmlを参照してください。次に、次の2つのシステム・プロパティを使用してロギングを有効にします。

-Doracle.jdbc.diagnostic.enableLogging=true (23ai onwards)
-Djava.util.logging.config.file=./logging.config

ノート: プロパティ名(-Doracle.jdbc.Trace=true)は、23aiより前の古いJDBCリリースでロギングを有効にするために異なっていました。23aiでのロギングを有効にするためにこのプロパティを使用することはできません。

# Contents of the logging.config file
handlers = java.util.logging.ConsoleHandler

# Formats into a standard XML format - Default formatter
#java.util.logging.ConsoleHandler.formatter= oracle.jdbc.diagnostics.XMLSimpleFormatter 
# Standard format
java.util.logging.ConsoleHandler.formatter = oracle.jdbc.diagnostics.OracleSimpleFormatter
# Custom Formatter for UCP 
#java.util.logging.ConsoleHandler.formatter=oracle.ucp.util.logging.UCPFormatter

# For using directory, [DIR]\\<Filename>
java.util.logging.ConsoleHandler.pattern = client.log
java.util.logging.ConsoleHandler.level = FINEST
# Choose different loggers based on the usecase
oracle.ucp.level = FINEST
oracle.jdbc.level = FINEST 

ユース・ケース3: JDBCおよびUCPパケット/SQLnetトレースの有効化

一部のシナリオでは、JDBCロギング・メッセージによって問題が明らかになりません。ドライバがサーバーと交換するネットワーク・パケットを確認すると役立ちます。ネットワーク・レベルのトレース情報を生成するには、logging.configファイルでルート・ロガー(.level = ALL)を使用し、次の2つのプロパティを設定してネットワーク・トレースを有効にします。この2つのステップは、Usecase 1およびユースケース2で強調表示されているステップに加えられています。ネットワーク・トレースでは、ネットワークを横切るすべてのパケットのバイト・コンテンツが記録され、ログ・ボリュームが高くなることに注意してください。

# Enable network-level logging
.level = ALL // Use the Root logger 

-Doracle.jdbc.diagnostic.permitSensitiveDiagnostics=true 
-Doracle.jdbc.diagnostic.enableSensitiveDiagnostics=true

ユース・ケース4: プログラムによるロギングの有効化

JDBCおよびUCPロギングは、次に示すようにプログラムで構成できます。APIを使用してロガーとレベルを設定する必要があります。

import java.util.*;
import java.util.logging.*;
  
try{  
  // set the file handler
  handler= new FileHandler("client.log");
 } catch(Exception e)
 { System.out.println(e);}
 // designate the module to be traced
 Logger logger = Logger.getLogger("oracle.jdbc");     
 // set the tracing level
 logger.setLevel(Level.ALL);     
 SimpleFormatter format=new SimpleFormatter();
 handler.setFormatter(format);     
 // Add file handler to the desired logger
 logger.addHandler(handler);

ユース・ケース5: MBeansを使用したJDBCおよびUCPロギングの有効化

ロギングは、com.oracle.jdbc.diagnosability JDBC MBeanを使用して動的に有効にできます。このMBeanは、enableLogging、disableLogging、enableLoggingByConnectionIdPrefixなどの複数の操作を定義します。これらの操作はすべて、関連する操作を呼び出してプログラム的に呼び出すこともできます。

void enableLogging(boolean enable) {
try {
  Object loader = oracle.jdbc.driver.OracleDriver.class.getClassLoader();
  String loaderName = (loader == null ? "nullLoader" : loader.getClass().getName());
  String name = loaderName + "@" + Integer.toHexString((loader == null ? 0 : loader.hashCode()));
  // If the same class loader loads the JDBC drivers multiple times, then each
  // subsequent MBean increments the value of the loader.hashCode() method, so as to
  // create a unique name. It may be problematic to identify which MBean is
  // associated with which JDBC driver instance.

  javax.management.ObjectName diagnosticMBeanObjectName = new                           javax.management.ObjectName("com.oracle.jdbc:type=diagnosability,name=" + name);

  // get the MBean server
  javax.management.MBeanServer mbs = java.lang.management.ManagementFactory.getPlatformMBeanServer(); 
  // find out if logging is enabled or not
  System.out.println("LoggingEnabled = " + mbs.getAttribute(diagnosticMBeanObjectName, "LoggingEnabled")); 
  // enable logging
  if(enable)
    mbs.invoke(diagnosticMBeanObjectName, "enableLogging", null, null);
  else
    mbs.invoke(diagnosticMBeanObjectName, "disableLogging", null, null);
  } catch (Exception e) {
     e.printStackTrace();
  }
}

最終的な考察

Open Telemetryは、トレース、メトリック、ログなどのテレメトリ・データの生成、エクスポートおよび収集を容易にするために設計された可観測性フレームワークおよびtoolkitです。オープンソースであり、JaegarやPrometheusなどの可観測性バックエンドで使用できます。

Oracle JDBC Open Telemetry Providerは、Oracle JDBCドライバとOpen Telemetryの統合を提供します。プロバイダは、ドライバでデータベース・イベントがトリガーされたときに通知を受け取るTraceEventListenerインタフェースを実装します。これらのイベントは、Open Telemetryに公開されます。現在サポートされているイベントは次のとおりです。より多くのイベントが続きます。

• roundtrips to the database server
• AC begin and sucess
• VIP down event

参照: 

JDBCおよびUCPランディング・ページ
JDBC開発者ガイド – JDBCでの診断機能 
Episode 8: Explore Oracle JDBC Logging and Packet Tracing
Episode 9: How to enable Oracle UCP Logging?