Update how to use Jfr4Jdbc

README.ja.md

@@ -1,10 +1,4 @@
-# Jfr4Jdbc
-
-## 動作環境
-- JDBC 4.3 準拠
-- OpenJDK 11 以降
-
-## Jfr4Jdbc とは
+# 概要
 Jfr4Jdbc はデータベースサーバの種類を問わず利用できる JDBC のラッパーライブラリです。
 Jfr4Jdbc を使うとユーザはシステムの性能問題が Java アプリケーションとデータベースのどちらで起きているか簡単に分かるようになります。
 
@@ -13,36 +7,115 @@ Jfr4Jdbc は JDBC に対する操作をイベントとして JDK Flight Recorder
 ユーザは JFR をダンプし、そのダンプファイルを JDK Mission Control で開くと GUI でデータベース操作を確認できます。
 これによってユーザは全てのデータベース処理の問題点をグラフィカルに解析できるようになります。
 
-ユーザは JFR が有効になっているアプリケーションで、Jfr4Jdbc を依存関係に追加し、接続文字列に`jfr:`を追加するだけです。
-一部のフレームワークでは依存関係を足すだけで使えます。
-一部のデータベース接続だけを分析する場合には、Jfr4Jdbcのデータソースやコネクションオブジェクトを作成し、分析したい JDBC オブジェクトをラップします。
+ユーザは JFR が有効になっているJVMで、これをライブラリとして追加し、JDBCの接続文字列に`jfr:`を追加するだけで、使用できます。
+このドライバを使用すると、接続、ステートメント、コミットなどのデータベースアクセスの情報をJFRのイベントとして取得できます。
+
+また、APIによるきめ細かな制御もサポートされています。例えば、一部のデータベース接続のみを分析したい場合、分析したいJDBCオブジェクト（DataSourceやConnectionなど）をJfr4jdbcDataSourceなどのJfr4Jdbcが提供するJDBCオブジェクトでラップして使用します。
 
-## なにが見られるか
+# なにが見られるか
 
 Jfr4Jdbc を使用するとスレッドが処理しているうち、どの時間にデータベースに対する処理をしているかが分かるようになります。
 この機能によって接続、ステートメントの実行、コミットなどデータベースに対する操作のうちどの処理に時間が掛かっているかを視覚的に判断できます。
 ![スレッドレーン](img/ThreadLane.png)
 
 Jfr4Jdbc を使用すると、コネクションがどれだけ使用されていて、どれくらいの数のスレッドがコネクションの割り当て待ちで処理が止まっているかを解析できます。
-これはデータソースに所属しているコネクションはデータソースごとにグループ化されます。
+これはデータソースに管理されているコネクションはデータソースごとにグループ化されます。
 これによって、どのコネクションプールが不足しているか、どのデータベースへの接続に時間が掛かっているかを特定できます。
 ![リソース使用量](img/ConResource.png)
 
-## 記録されるイベント
+# 記録されるイベント
 
-Jfr4Jdbc では下記のイベントが記録されます。
-
-- コネクションの接続
-- コネクションのクローズ
-- ステートメント
-- 結果セット
+APIを使用してデータベースにアクセスするたびに、以下の情報を取得できます。
+- データソースから接続を取得する
+- データベースへの接続を確立する
+- 接続を閉じる
+- ステートメントの実行
+- 結果セットの取得
 - コミット
 - ロールバック
 - キャンセル
-- 接続の割り当て待ち
+
+さらに、デフォルトで1秒ごとに以下の数値を取得できます。
+- 使用中の接続数
+- 割り当て待ちの接続
+
+# サポートされる環境
+- JDBC 4.2 と OpenJDK 8 update 272
+- JDBC 4.3 と OpenJDK 11以降
+
+Oracle JDKのような公開されていないJDKはサポートしていません。
+
+# ダウンロード方法
+[Maven Central](https://search.maven.org/artifact/dev.jfr4jdbc/jfr4jdbc-driver) からJARファイルをダウンロードできます。
+
+Maven や Gradle などのビルド自動化ツールで依存関係を管理している方は、依存関係に以下を追加してください。
+### Maven
+```xml
+<dependency>
+  <groupId>dev.jfr4jdbc</groupId>
+  <artifactId>jfr4jdbc-driver</artifactId>
+  <version>1.3.0</version>
+</dependency>
+```
+
+### Gradle
+```xml
+implementation 'dev.jfr4jdbc:jfr4jdbc-driver:1.3.0'
+```
+
+### Scala SBT
+```xml
+libraryDependencies += "dev.jfr4jdbc" % "jfr4jdbc-driver" % "1.3.0"
+```
+
+### Bazel
+```
+maven_jar(
+    name = "jfr4jdbc-driver",
+    artifact = "dev.jfr4jdbc:jfr4jdbc-driver:1.3.0",
+    sha1 = "669dd4fa8797e04a79ab5e13e29d646e2863d76d",
+)
+```
+
+# 使い方
+Jfr4jdbc は後述のAPIを使用して統合できますが、最も簡単な方法は、JDBCの接続文字列に `jfr:` を追加することです。
+
+アプリケーションフレームワークとして Quarkus や Spring Boot を使用している場合は、以下のように`jfr:`を追加します。
+
+### Quarkus
+```properties
+quarkus.datasource.jdbc.url=jdbc:jfr:postgresql://localhost:5432/xxx
+```
+
+### Spring Boot
+```properties
+spring.datasource.url=jdbc:jfr:postgresql://postgres:5432/xxx
+```
+
+# コード上での使い方
+このAPIでは、キャプチャするイベントをより細かく制御できます。
+
+## javax.sql.DataSourceと使う
+Jfr4jdbcDataSourceのコンストラクタ引数にjavax.sql.DataSourceのインスタンスを渡すことで、このデータソースが管理するすべての接続とそれが生成したすべてのステートメントのイベントを記録できます。
+
+```java
+OracleDataSource ds = new OracleDataSource();  
+ds.setURL("jdbc:oracle:thin:user/passwd@localhost:1521:XE");  
+Jfr4jdbcDataSource jds = new Jfr4jdbcDataSource(ds);  
+Connection con = jds.getConnection();
+```
+
+## java.sql.Driverと使う
+JDBC接続文字列の `jdbc:` の後ろに `jfr:` を追加してください。
+この接続で生成されたすべてのステートメントに対してイベントを記録できます。
+
+```java
+String url = "jdbc:jfr:oracle:thin:user/passwd@localhost:1521:XE";  
+Driver driver = DriverManager.getDriver(url);  
+Connection con = driver.connect(url, null);  
+```
 
 ## 使用方法
 
-- [SpringBootとの統合](doc/SpringJPA_jp.md)
 - [Quarkusとの統合](doc/Quarkus_jp.md)
 - [特定の処理だけで使う方法](doc/Wrap_jp.md)

README.md

@@ -1,47 +1,115 @@
-# Jfr4Jdbc
-
-## Attention
-**Jfr4Jdbc is NOT Oracle product. It requires Java Flight Recorder. If you would like to know the license of Java Flight Recorder, please check the BCL For Java SE or, please contact the Oracle. **  
-BCL For Java SE
-http://www.oracle.com/technetwork/java/javase/terms/license/index.html  
-Contact Oracle 
-https://www.oracle.com/corporate/contact/index.html
-
-### Introduction
-Jfr4Jdbc is a wrapper library for JDBC. If you use the Jfr4Jdbc, you will get the information of JDBC(connection , statement, commit,etc) as an event of Java Flight Recorder. 
-
-The following events are recorded.
-- Connecting
-- Connection Close
-- Statement
-- ResultSet
+# Introduction
+Jfr4Jdbc is a JDBC wrapper library that can be used with any type of database server.
+Jfr4Jdbc makes it easy for users to determine whether a system performance problem is occurring in the Java application or in the database.
+
+Jfr4Jdbc records operations on JDBC as events in the JDK Flight Recorder (JFR).
+The load on this logging is slight.
+Users can dump the JFR and open the dump file with JDK Mission Control to see the database operations in the GUI.
+This allows the user to graphically analyze all database processing problems.
+
+In a JVM with JFR enabled, you can benefit by simply adding this as a library and adding `jfr:` to your jdbc configurations.
+Using this driver, you can obtain information about your database access, such as connection , statement, commit etc., as an JFR events.
+
+Fine-grained control via API is also supported. 
+For example, if you want to analyze only some database connections, you can wrap the JDBC objects, such as DataSource or Connection, you want to analyze with the JDBC objects provided by Jfr4Jdbc, such as Jfr4jdbcDataSource.
+
+# What you can see
+You will be able to see which threads are processing to the database and when.
+This feature allows you to visually determine which operations on the database, such as connecting, executing statements, committing, etc., are taking the most time.
+
+![Thread Lane](img/ThreadLane.png)
+
+You can analyze how many connections are in use and how many threads are stuck waiting for connection assignments.
+Connections belonging to data sources are grouped by data source.
+You can identify which connection pools are missing and which databases are taking a long time to connect to.
+![Usage](img/ConResource.png)
+
+
+# Recorded Event
+
+Each time you use the API to access the database, you will get the following information
+- Getting connection from DataSource
+- Establish a connection to the Database
+- Closing connection
+- Executing statement
+- Fetching ResultSet
 - Commit
 - Rollback
 - Cancel
 
-You can choose how to use javax.sql.DataSource and java.sql.Driver.
+Additionally, you can also get the following numbers every second by default.
+- connections being used
+- connections waiting to be assigned
+
+# Supported Environment
+- JDBC 4.2 with OpenJDK 8 update 272
+- JDBC 4.3 with OpenJDK 11+ 
+
+Closed JDKs such as Oracle JDK are not supported.
+
+# How to download
+You can download Jfr4Jdbc as a JAR file from [Maven Central](https://search.maven.org/artifact/dev.jfr4jdbc/jfr4jdbc-driver)
 
-### How to use the javax.sql.DataSource
-You pass javax.sql.DataSource instance to the construct argument of Jfr4JdbcDataSource.
+Those who use build automation tools such as Maven or Gradle to manage dependencies should add the following to their dependencies
+### Maven
+```xml
+<dependency>
+  <groupId>dev.jfr4jdbc</groupId>
+  <artifactId>jfr4jdbc-driver</artifactId>
+  <version>1.3.0</version>
+</dependency>
+```
+
+### Gradle
+```xml
+implementation 'dev.jfr4jdbc:jfr4jdbc-driver:1.3.0'
+```
+
+### Scala SBT
+```xml
+libraryDependencies += "dev.jfr4jdbc" % "jfr4jdbc-driver" % "1.3.0"
+```
+
+### Bazel
+```
+maven_jar(
+    name = "jfr4jdbc-driver",
+    artifact = "dev.jfr4jdbc:jfr4jdbc-driver:1.3.0",
+    sha1 = "669dd4fa8797e04a79ab5e13e29d646e2863d76d",
+)
+```
+
+# How to use
+Jfr4Jdbc can be integrated using the API described below, but the easiest way is to add `jfr:` to the JDBC configuration.
+
+Those using Quarkus or Spring Boot as application frameworks should add `jfr:` as follows
+### Quarkus
+```properties
+quarkus.datasource.jdbc.url=jdbc:jfr:postgresql://localhost:5432/xxx
+```
+
+### Spring Boot
+```properties
+spring.datasource.url=jdbc:jfr:postgresql://postgres:5432/xxx
+```
+
+# How to use in code
+The API allows more fine-grained control over the events to be captured.
+
+## Use with javax.sql.DataSource
+You can pass an instance of javax.sql.DataSource to the constructor argument of Jfr4JdbcDataSource to record events for all connections managed by this data source and all statements generated by it.
 
-#### Sample of DataSource：
 ```java
 OracleDataSource ds = new OracleDataSource();  
 ds.setURL("jdbc:oracle:thin:user/passwd@localhost:1521:XE");  
 Jfr4jdbcDataSource jds = new Jfr4jdbcDataSource(ds);  
 Connection con = jds.getConnection();
 ```
 
-### How to use the java.sql.Driver
+## Use with java.sql.Driver
 Add the "jfr:" in the back of "jdbc:" of the JDBC connection string.
+You can record events for all statements generated by this connection.
 
-##### Before changing  
-```java
-String url = "jdbc:oracle:thin:user/passwd@localhost:1521:XE";  
-Driver driver = DriverManager.getDriver(url);  
-Connection con = driver.connect(url, null);  
-```
-##### After changing.
 ```java
 String url = "jdbc:jfr:oracle:thin:user/passwd@localhost:1521:XE";  
 Driver driver = DriverManager.getDriver(url);