From 0c4e6861b1818610859f87b448c3305e76c16b6d Mon Sep 17 00:00:00 2001 From: Xavi Lee Date: Sat, 15 Jul 2023 13:44:37 +0800 Subject: [PATCH 1/4] docs: convert logging to md format --- src/site/es/markdown/logging.md | 235 +++++++++++++++++++++++ src/site/es/xdoc/logging.xml | 299 ----------------------------- src/site/ja/markdown/logging.md | 235 +++++++++++++++++++++++ src/site/ja/xdoc/logging.xml | 302 ------------------------------ src/site/ko/markdown/logging.md | 219 ++++++++++++++++++++++ src/site/ko/xdoc/logging.xml | 321 -------------------------------- src/site/zh/markdown/logging.md | 235 +++++++++++++++++++++++ src/site/zh/xdoc/logging.xml | 299 ----------------------------- 8 files changed, 924 insertions(+), 1221 deletions(-) create mode 100644 src/site/es/markdown/logging.md delete mode 100644 src/site/es/xdoc/logging.xml create mode 100644 src/site/ja/markdown/logging.md delete mode 100644 src/site/ja/xdoc/logging.xml create mode 100644 src/site/ko/markdown/logging.md delete mode 100644 src/site/ko/xdoc/logging.xml create mode 100644 src/site/zh/markdown/logging.md delete mode 100644 src/site/zh/xdoc/logging.xml diff --git a/src/site/es/markdown/logging.md b/src/site/es/markdown/logging.md new file mode 100644 index 00000000000..c1112d60760 --- /dev/null +++ b/src/site/es/markdown/logging.md @@ -0,0 +1,235 @@ +title: MyBatis 3 | Logging +author: Clinton Begin, Eduardo Macarron + +## Logging + +MyBatis proporciona información de logging mediante el uso interno de una factoría. La factoría interna delega la información de logging en alguna de las siguientes implementaciones. + +- SLF4J +- Apache Commons Logging +- Log4j 2 +- Log4j (deprecated since 3.5.9) +- JDK logging + +La solución de logging elegida se basa en una introspección en tiempo de ejecución de la propia factoría interna de MyBatis. La factoría usará la primera implementación de logging que encuentre (el orden de búsqueda es el de la lista de más arriba). Si no se encuentra ninguna, el logging se desactivará. + +Muchos entornos vienen con Commons Logging incluido como pare del classpath del servidor (por ejemplo Tomcat y WebSphere). Es importante conocer que en esos entorno, MyBatis usará JCL como implementación de logging. En un entorno como WebSphere esto significa que tu configuración de log4j será ignorada dado que WebSphere proporciona su propia implementación de JCL. Esto puede ser muy frustrante porque parece que MyBatis está ignorando tu configuración de logging (en realidad, MyBatis está ignorando tu configuración de log4j porque está usando JCL en dicho entorno). Si tu aplicación se ejecuta en un entorno que lleva JCL incluido pero quieres usar un método distinto de logging puedes añadir un setting a tu fichero mybatis-config.xml: + +```xml + + + ... + + ... + + +``` + +Los valores válidos son: SLF4J, LOG4J, LOG4J2, JDK\_LOGGING, COMMONS\_LOGGING, STDOUT\_LOGGING, NO\_LOGGING o un nombre de clase plenamente cualificado que implemente `org.apache.ibatis.logging.Log` y reciba un string como parametro de constructor. + +Tambien puedes seleccionar el método de logging llamando a uno de los siguientes métodos: + +```java +org.apache.ibatis.logging.LogFactory.useSlf4jLogging(); +org.apache.ibatis.logging.LogFactory.useLog4JLogging(); +org.apache.ibatis.logging.LogFactory.useLog4J2Logging(); +org.apache.ibatis.logging.LogFactory.useJdkLogging(); +org.apache.ibatis.logging.LogFactory.useCommonsLogging(); +org.apache.ibatis.logging.LogFactory.useStdOutLogging(); +``` + +Si eliges llamar a alguno de estos métodos, deberías hacerlo antes de llamar a ningún otro método de MyBatis. Además, estos métodos solo establecerán la implementación de log indicada si dicha implementación está disponible en el classpath. Por ejemplo, si intentas seleccionar log4j2 y log4j2 no está disponible en el classpath, MyBatis ignorará la petición y usará su algoritmo normal de descubrimiento de implementaciones de logging. + +Los temas específicos de JCL, Log4j y el Java Logging API quedan fuera del alcance de este documento. Sin embargo la configuración de ejemplo que se proporciona más abajo te ayudará a comenzar. Si quieres conocer más sobre estos frameworks, puedes obtener más información en las siguientes ubicaciones: + +- [SLF4J](https://www.slf4j.org/) +- [Apache Commons Logging](https://commons.apache.org/proper/commons-logging/) +- [Apache Log4j 2.x](https://logging.apache.org/log4j/2.x/) +- [JDK Logging API](https://docs.oracle.com/javase/8/docs/technotes/guides/logging/overview.html) + +### Configuración + +Para ver el log de las sentencias debes activar el log en un paquete, el nombre plenamente cualificado de una clase, un namespace o un nombre plenamente cualificado de un mapped statement. + +Nuevamente, cómo hagas esto es dependiente de la implementación de logging que se esté usando. Mostraremos cómo hacerlo con SLF4J(Logback). Configurar los servicios de logging es simplemente cuestión de añadir uno o varios ficheros de configuración (por ejemplo `logback.xml`) y a veces un nuevo JAR. El ejemplo siguiente configura todos los servicios de logging para que usen SLF4J(Logback) como proveedor. Sólo son dos pasos: + +#### Paso 1: Añade el fichero SLF4J + Logback JAR + +Dado que usamos SLF4J(Logback), necesitaremos asegurarnos que el fichero JAR está disponible para nuestra aplicación. Para usar SLF4J(Logback), necesitas añadir el fichero JAR al classpath de tu aplicación. + +En aplicaciones Web o de empresa debes añadir tu fichero `logback-classic.jar` ,`logback-core.jar` and `slf4j-api.jar` a tu directorio `WEB-INF/lib`, y en una aplicación standalone simplemente añádela al parámetro `–classpath` de la JVM. + +If you use the maven, you can download jar files by adding following settings on your `pom.xml`. + +```xml + + ch.qos.logback + logback-classic + 1.x.x + +``` + +#### Paso 2: Configurar Logback + +Configurar Logback es sencillo. Supongamos que quieres habilitar el log para este mapper: + +```java +package org.mybatis.example; +public interface BlogMapper { + @Select("SELECT * FROM blog WHERE id = #{id}") + Blog selectBlog(int id); +} +``` + +Crea un fichero con nombre logback.xml como el que se muestra a continuación y colocalo en tu classpath: + +```xml + + + + + + + %5level [%thread] - %msg%n + + + + + + + + + + + +``` + +El fichero anterior hará que SLF4J(Logback) reporte información detallada para `org.mybatis.example.BlogMapper` e información de errores para el resto de las clases de tu aplicación. + +Si quieres activar un nivel más fino de logging puedes activar el logging para statements específicos en lugar de para todo un mapper. La siguiente línea activa el logging sólo para el statement `selectBlog`: + +```xml + + + +``` + +Si por el contrario quieres activar el log para un grupo de mappers debes añadir un logger para el paquete raiz donde residen tus mappers: + +```xml + + + +``` + +Hay consultas que pueden devolver una gran cantidad de datos. En esos casos puedes querer ver las sentencias SQL pero no los datos. Para conseguirlo las sentencias se loguean con nivel DEBUG (FINE en JDK) y los resultados con TRACE (FINER en JDK), por tanto si quieres ver la sentencia pero no el resultado establece el nivel a DEBUG + +```xml + + + +``` + +Y si estás usando ficheros XML como este? + +```xml + + + + + +``` + +En tal caso puedes activar el logging de todo el fichero añadiendo un logger para el namespace como se muestra a continuación: + +```xml + + + +``` + +O para un statement específico: + +```xml + + + +``` + +Sí, como ya te habrás dado cuenta, no hay ninguna diferencia entre configurar el logging para un mapper o para un fichero XML. + +NOTA Si usas SLF4J o Log4j 2 MyBatis le llamará usando `MYBATIS` como marker. + +El resto de la configuración sirve para configurar los appenders, lo cual queda fuera del ámbito de este documento. Sin embargo, puedes encontrar más información en el site de [Logback](https://logback.qos.ch/). O, puedes simplemente experimentar para ver los efectos que consigues con las distintas opciones de configuración. + +#### Configuration example for Log4j 2 + +```xml + + + org.apache.logging.log4j + log4j-core + 2.x.x + +``` + +```xml + + + + + + + + + + + + + + + + + + +``` + +#### Configuration example for Log4j + +```xml + + + log4j + log4j + 1.2.17 + +``` + +```properties +# log4j.properties +log4j.rootLogger=ERROR, stdout + +log4j.logger.org.mybatis.example.BlogMapper=TRACE + +log4j.appender.stdout=org.apache.log4j.ConsoleAppender +log4j.appender.stdout.layout=org.apache.log4j.PatternLayout +log4j.appender.stdout.layout.ConversionPattern=%5p [%t] - %m%n +``` + +#### Configuration example for JDK logging + +```properties +# logging.properties +handlers=java.util.logging.ConsoleHandler +.level=SEVERE + +org.mybatis.example.BlogMapper=FINER + +java.util.logging.ConsoleHandler.level=ALL +java.util.logging.ConsoleHandler.formatter=java.util.logging.SimpleFormatter +java.util.logging.SimpleFormatter.format=%1$tT.%1$tL %4$s %3$s - %5$s%6$s%n +``` diff --git a/src/site/es/xdoc/logging.xml b/src/site/es/xdoc/logging.xml deleted file mode 100644 index c0b72174672..00000000000 --- a/src/site/es/xdoc/logging.xml +++ /dev/null @@ -1,299 +0,0 @@ - - - - - - MyBatis 3 | Logging - Clinton Begin - Eduardo Macarron - - - -
-

-

MyBatis proporciona información de logging mediante el uso interno de una factoría. La factoría interna delega la información de logging en alguna de las siguientes implementaciones. -

-
    -
  • - SLF4J -
    • -
  • - Apache Commons Logging -
    • -
  • - Log4j 2 -
    • -
  • - Log4j (deprecated since 3.5.9) -
    • -
  • - JDK logging -
    • -
-

La solución de logging elegida se basa en una introspección en tiempo de ejecución de la propia factoría interna de MyBatis. La factoría usará la primera implementación de logging que encuentre (el orden de búsqueda es el de la lista de más arriba). Si no se encuentra ninguna, el logging se desactivará. -

-

Muchos entornos vienen con Commons Logging incluido como pare del classpath del servidor (por ejemplo Tomcat y WebSphere). Es importante conocer que en esos entorno, MyBatis usará JCL como implementación de logging. En un entorno como WebSphere esto significa que tu configuración de log4j será ignorada dado que WebSphere proporciona su propia implementación de JCL. Esto puede ser muy frustrante porque parece que MyBatis está ignorando tu configuración de logging (en realidad, MyBatis está ignorando tu configuración de log4j porque está usando JCL en dicho entorno). Si tu aplicación se ejecuta en un entorno que lleva JCL incluido pero quieres usar un método distinto de logging puedes añadir un setting a tu fichero mybatis-config.xml: -

- - - ... - - ... - - -]]> -

Los valores válidos son: SLF4J, LOG4J, LOG4J2, JDK_LOGGING, COMMONS_LOGGING, STDOUT_LOGGING, NO_LOGGING o - un nombre de clase plenamente cualificado que implemente org.apache.ibatis.logging.Log y reciba - un string como parametro de constructor. -

-

Tambien puedes seleccionar el método de logging llamando a uno de los siguientes métodos: -

- -

Si eliges llamar a alguno de estos métodos, deberías hacerlo antes de llamar a ningún otro método de MyBatis. Además, estos métodos solo establecerán la implementación de log indicada si dicha implementación está disponible en el classpath. Por ejemplo, si intentas seleccionar log4j2 y log4j2 no está disponible en el classpath, MyBatis ignorará la petición y usará su algoritmo normal de descubrimiento de implementaciones de logging. -

-

Los temas específicos de JCL, Log4j y el Java Logging API quedan fuera del alcance de este documento. Sin embargo la configuración de ejemplo que se proporciona más abajo te ayudará a comenzar. Si quieres conocer más sobre estos frameworks, puedes obtener más información en las siguientes ubicaciones: -

- - -

Para ver el log de las sentencias debes activar el log en un paquete, el nombre plenamente cualificado de una clase, un namespace o un nombre plenamente cualificado de un mapped statement.

-

Nuevamente, cómo hagas esto es dependiente de la implementación de logging que se esté usando. Mostraremos cómo hacerlo con SLF4J(Logback). Configurar los servicios de logging es simplemente cuestión de añadir uno o varios ficheros de configuración (por ejemplo logback.xml) y a veces un nuevo JAR. El ejemplo siguiente configura todos los servicios de logging para que usen SLF4J(Logback) como proveedor. Sólo son dos pasos: -

-

Paso 1: Añade el fichero SLF4J + Logback JAR -

-

Dado que usamos SLF4J(Logback), necesitaremos asegurarnos que el fichero JAR está disponible para nuestra aplicación. Para usar SLF4J(Logback), necesitas añadir el fichero JAR al classpath de tu aplicación. -

-

En aplicaciones Web o de empresa debes añadir tu fichero logback-classic.jar - ,logback-core.jar and slf4j-api.jar a tu directorio WEB-INF/lib, y en una aplicación standalone simplemente añádela al parámetro –classpath de la JVM. -

-

If you use the maven, you can download jar files by adding following settings on your pom.xml. -

- - ch.qos.logback - logback-classic - 1.x.x - -]]> - -

- Paso 2: Configurar Logback -

-

Configurar Logback es sencillo. Supongamos que quieres habilitar el log para este mapper:

- -

Crea un fichero con nombre logback.xml - como el que se muestra a continuación y colocalo en tu classpath: -

- - - - - - - - %5level [%thread] - %msg%n - - - - - - - - - - - -]]> - -

El fichero anterior hará que SLF4J(Logback) reporte información detallada para org.mybatis.example.BlogMapper e información de errores para el resto de las clases de tu aplicación.

-

Si quieres activar un nivel más fino de logging puedes activar el logging para statements específicos en lugar de para todo un mapper. La siguiente línea activa el logging sólo para el statement selectBlog:

- - - - -]]> - -

Si por el contrario quieres activar el log para un grupo de mappers debes añadir un logger para el paquete raiz donde residen tus mappers:

- - - - -]]> - -

Hay consultas que pueden devolver una gran cantidad de datos. En esos casos puedes querer ver las sentencias SQL pero no los datos. Para conseguirlo las sentencias se loguean con nivel DEBUG (FINE en JDK) y los resultados con TRACE (FINER en JDK), por tanto si quieres ver la sentencia pero no el resultado establece el nivel a DEBUG

- - - - -]]> - -

Y si estás usando ficheros XML como este?

- - - - - - -]]> - -

En tal caso puedes activar el logging de todo el fichero añadiendo un logger para el namespace como se muestra a continuación:

- - - - -]]> - -

O para un statement específico:

- - - - -]]> - -

Sí, como ya te habrás dado cuenta, no hay ninguna diferencia entre configurar el logging para un mapper o para un fichero XML.

- -

NOTA Si usas SLF4J o Log4j 2 MyBatis le llamará usando MYBATIS como marker.

- -

El resto de la configuración sirve para configurar los appenders, lo cual queda fuera del ámbito de este documento. Sin embargo, puedes encontrar más información en el site de Logback. O, puedes simplemente experimentar para ver los efectos que consigues con las distintas opciones de configuración.

- -

-

- Configuration example for Log4j 2 -

- -

pom.xml

- - - org.apache.logging.log4j - log4j-core - 2.x.x - -]]> - -

log4j2.xml

- - - - - - - - - - - - - - - - - - -]]> - -

-

- Configuration example for Log4j -

- -

pom.xml

- - - log4j - log4j - 1.2.17 - -]]> - -

log4j.properties

- - - - -

-

- Configuration example for JDK logging -

- -

logging.properties

- - - - -
- - diff --git a/src/site/ja/markdown/logging.md b/src/site/ja/markdown/logging.md new file mode 100644 index 00000000000..211a6e98671 --- /dev/null +++ b/src/site/ja/markdown/logging.md @@ -0,0 +1,235 @@ +title: MyBatis 3 | Logging +author: Clinton Begin, Iwao AVE! + +## ロギング + +MyBatis は、内部の Log Factory を通してログ情報を出力します。この Log Factory は、ログ情報を次に挙げる実装のいずれかに委譲（delegate）します。 + +- SLF4J +- Apache Commons Logging +- Log4j 2 +- Log4j (3.5.9以降非推奨) +- JDK logging + +実際に使用されるのは、MyBatis 内部の Log Factory が検出した実装になります。MyBatis の Log Factory は上に挙げた順番でロギング実装を検索し、最初に見つけた実装を使用します。上記の実装が検出できなかった場合、ログは出力されません。 + +アプリケーションサーバーでは、出荷時のクラスパスに Commons Logging が含まれていることがよくあります（Tomcat や WebSphere は良い例でしょう）。重要なのは、このような環境では MyBatis は Commons Logging を使用するということです。これはつまり、独自の Commons Logging 実装を使う WebSphere のような環境では、あなたが追加した Log4J の設定は無視されるということを意味しています。この現象が厄介なのは、MyBatis が Log4J の設定を無視しているように見えるということです（実は、このような環境では MyBatis が Commons Loggin を使用するため、Log4J の設定が無視されているのです）。クラスパスに Commons Logging を含む環境で動作するアプリケーションでも、mybatis-config.xml に設定を追加することで別のロギング実装を使用することができます。 + +```xml + + + ... + + ... + + +``` + +指定可能な値は SLF4J, LOG4J, LOG4J2, JDK\_LOGGING, COMMONS\_LOGGING, STDOUT\_LOGGING, NO\_LOGGING ですが、`org.apache.ibatis.logging.Log` インターフェイスを実装し、コンストラクター引数として String を受け取る独自に実装したクラスの完全修飾クラス名を指定することもできます。 + +下記のメソッドを呼び出すことでロギング実装を指定することも可能です。 + +```java +org.apache.ibatis.logging.LogFactory.useSlf4jLogging(); +org.apache.ibatis.logging.LogFactory.useLog4JLogging(); +org.apache.ibatis.logging.LogFactory.useLog4J2Logging(); +org.apache.ibatis.logging.LogFactory.useJdkLogging(); +org.apache.ibatis.logging.LogFactory.useCommonsLogging(); +org.apache.ibatis.logging.LogFactory.useStdOutLogging(); +``` + +これらのメソッドは、他の MyBatis のメソッドより前に呼び出す必要があります。また、要求された実装が実行時のクラスパスに含まれている場合にのみ切り替えることが可能です。例えば、Log4J2 に切り替えようとして、実行時に Log4J2 が見つからない場合、MyBatis は切り替えの要求を無視して通常のアルゴリズムでロギング実装を検索します。 + +SLF4J, Apache Commons Logging, Apache Log4J, JDK Logging API についての詳細はこのドキュメントの範囲外となりますが、後述の設定例は参考になると思います。これらのフレームワークについての詳しい情報は、以下の各サイトを参照してください。 + +- [SLF4J](https://www.slf4j.org/) +- [Apache Commons Logging](https://commons.apache.org/proper/commons-logging/) +- [Apache Log4j 2.x](https://logging.apache.org/log4j/2.x/) +- [JDK Logging API](https://docs.oracle.com/javase/8/docs/technotes/guides/logging/overview.html) + +### Logging Configuration + +実行されるステートメントのログを出力するためには、パッケージ、Mapper の完全修飾名、ネームスペース、あるいはステートメントの完全修飾名に対してログ出力を有効にしてください。 + +具体的な設定方法は使用するロギング実装によります。以下は SLF4J(Logback) での設定例です。ロギングサービスの設定は、単純にいくつかの設定ファイル（例えば `logback.xml`）と、場合によっては新しい JARを追加するだけのことです。以下は、SLF4J(Logback) をプロバイダーとして完全なロギングサービスを設定する手順です。 + +#### ステップ１: SLF4J + Logback の JAR ファイルを追加する。 + +SLF4J(Logback) を使うので、SLF4J(Logback) の JAR ファイルがアプリケーションから利用できるようにしておく必要があります。SLF4J(Logback) の JAR ファイルをダウンロードしてあなたのアプリケーションのクラスパスに追加してください。 + +Web あるいはエンタープライズアプリケーションの場合は、ダウンロードした `logback-classic.jar` ,`logback-core.jar`, `slf4j-api.jar` を `WEB-INF/lib` ディレクトリに追加します。スタンドアローンアプリケーションの場合は起動時の JVM 引数 `-classpath` に追加するだけです。 + +Mavenを利用している場合は、`pom.xml`に以下のような設定を追加することでJARファイルをダウンロードすることができます。 + +```xml + + ch.qos.logback + logback-classic + 1.x.x + +``` + +#### ステップ２: Logback を設定する。 + +Logback の設定はシンプルです。例えば次の Mapper のログを出力する場合： + +```java +package org.mybatis.example; +public interface BlogMapper { + @Select("SELECT * FROM blog WHERE id = #{id}") + Blog selectBlog(int id); +} +``` + +次のテキストを含む `logback.xml` というファイルを作成し、クラスパスに配置します。 + +```xml + + + + + + + %5level [%thread] - %msg%n + + + + + + + + + + + +``` + +上記のように設定すると、SLF4J(Logback) は `org.mybatis.example.BlogMapper` について詳細なログを出力し、それ以外のクラスについてはエラーのみを出力します。 + +ログに出力される情報を細かく調整したいのなら、Mapper ファイル全体ではなく特定のステートメントを指定することもできます。 + +```xml + + + +``` + +逆に、複数の Mapper に対するログを有効化したい場合もあるでしょう。その場合は、対象となる Mapper を含むパッケージを指定することができます。 + +```xml + + + +``` + +クエリが大量の結果セットを返すようなケースでSQLステートメントのみを出力したい場合に対応できるよう、SQLステートメントは DEBUG（JDK logging では FINE）レベル、結果は TRACE（JDK logging では FINER）レベルで出力されるようになっています。SQLステートメントのみを出力したい場合、ログレベルに DEBUG を設定します。 + +```xml + + + +``` + +Mapper インターフェイスを使っていない場合、例えば次のような Mapper XML ファイルを使っていたらどうすれば良いのでしょうか。 + +```xml + + + + + +``` + +この場合、次のようにネームスペースを指定することでこの XML ファイル全体のログを有効化することができます。 + +```xml + + + +``` + +特定のステートメントのみを対象とする場合は次のように指定します。 + +```xml + + + +``` + +お気づきのように、Mapper インターフェイスと XML のどちらを使っている場合でも、設定方法に違いはありません。 + +NOTE SLF4J or Log4j 2 をお使いの場合、MyBatis のログは `MYBATIS` というマーカーで出力されます。 + +上記の `logback.xml` の残りの部分はアペンダーの設定になっていますが、このドキュメントでは説明しません。[Logback](https://logback.qos.ch/) のサイトを参照してください。あるいは、設定値を変更してみてどのような結果になるか試してみるのも良いでしょう。 + +#### Log4j 2の設定例 + +```xml + + + org.apache.logging.log4j + log4j-core + 2.x.x + +``` + +```xml + + + + + + + + + + + + + + + + + + +``` + +#### Log4jの設定例 + +```xml + + + log4j + log4j + 1.2.17 + +``` + +```properties +# log4j.properties +log4j.rootLogger=ERROR, stdout + +log4j.logger.org.mybatis.example.BlogMapper=TRACE + +log4j.appender.stdout=org.apache.log4j.ConsoleAppender +log4j.appender.stdout.layout=org.apache.log4j.PatternLayout +log4j.appender.stdout.layout.ConversionPattern=%5p [%t] - %m%n +``` + +#### JDK Loggingの設定例 + +```properties +# logging.properties +handlers=java.util.logging.ConsoleHandler +.level=SEVERE + +org.mybatis.example.BlogMapper=FINER + +java.util.logging.ConsoleHandler.level=ALL +java.util.logging.ConsoleHandler.formatter=java.util.logging.SimpleFormatter +java.util.logging.SimpleFormatter.format=%1$tT.%1$tL %4$s %3$s - %5$s%6$s%n +``` diff --git a/src/site/ja/xdoc/logging.xml b/src/site/ja/xdoc/logging.xml deleted file mode 100644 index 43dc41a6c29..00000000000 --- a/src/site/ja/xdoc/logging.xml +++ /dev/null @@ -1,302 +0,0 @@ - - - - - - MyBatis 3 | ロギング - Clinton Begin - Iwao AVE! - - - -
-

-

MyBatis は、内部の Log Factory を通してログ情報を出力します。この Log Factory は、ログ情報を次に挙げる実装のいずれかに委譲（delegate）します。 -

-
    -
  • - SLF4J -
    • -
  • - Apache Commons Logging -
    • -
  • - Log4j 2 -
    • -
  • - Log4j (3.5.9以降非推奨) -
    • -
  • - JDK logging -
    • -
-

実際に使用されるのは、MyBatis 内部の Log Factory が検出した実装になります。MyBatis の Log Factory は上に挙げた順番でロギング実装を検索し、最初に見つけた実装を使用します。上記の実装が検出できなかった場合、ログは出力されません。 -

-

アプリケーションサーバーでは、出荷時のクラスパスに Commons Logging が含まれていることがよくあります（Tomcat や WebSphere は良い例でしょう）。重要なのは、このような環境では MyBatis は Commons Logging を使用するということです。これはつまり、独自の Commons Logging 実装を使う WebSphere のような環境では、あなたが追加した Log4J の設定は無視されるということを意味しています。この現象が厄介なのは、MyBatis が Log4J の設定を無視しているように見えるということです（実は、このような環境では MyBatis が Commons Loggin を使用するため、Log4J の設定が無視されているのです）。クラスパスに Commons Logging を含む環境で動作するアプリケーションでも、mybatis-config.xml に設定を追加することで別のロギング実装を使用することができます。 -

- - - ... - - ... - - -]]> -

指定可能な値は SLF4J, LOG4J, LOG4J2, JDK_LOGGING, COMMONS_LOGGING, STDOUT_LOGGING, NO_LOGGING ですが、org.apache.ibatis.logging.Log インターフェイスを実装し、コンストラクター引数として String を受け取る独自に実装したクラスの完全修飾クラス名を指定することもできます。 -

-

下記のメソッドを呼び出すことでロギング実装を指定することも可能です。 -

- -

これらのメソッドは、他の MyBatis のメソッドより前に呼び出す必要があります。また、要求された実装が実行時のクラスパスに含まれている場合にのみ切り替えることが可能です。例えば、Log4J2 に切り替えようとして、実行時に Log4J2 が見つからない場合、MyBatis は切り替えの要求を無視して通常のアルゴリズムでロギング実装を検索します。 -

-

SLF4J, Apache Commons Logging, Apache Log4J, JDK Logging API についての詳細はこのドキュメントの範囲外となりますが、後述の設定例は参考になると思います。これらのフレームワークについての詳しい情報は、以下の各サイトを参照してください。 -

- - -

実行されるステートメントのログを出力するためには、パッケージ、Mapper の完全修飾名、ネームスペース、あるいはステートメントの完全修飾名に対してログ出力を有効にしてください。 -

-

具体的な設定方法は使用するロギング実装によります。以下は SLF4J(Logback) での設定例です。ロギングサービスの設定は、単純にいくつかの設定ファイル（例えば logback.xml）と、場合によっては新しい JARを追加するだけのことです。以下は、SLF4J(Logback) をプロバイダーとして完全なロギングサービスを設定する手順です。 -

-

-

- ステップ１: SLF4J + Logback の JAR ファイルを追加する。 -

-

SLF4J(Logback) を使うので、SLF4J(Logback) の JAR ファイルがアプリケーションから利用できるようにしておく必要があります。SLF4J(Logback) の JAR ファイルをダウンロードしてあなたのアプリケーションのクラスパスに追加してください。 -

-

Web あるいはエンタープライズアプリケーションの場合は、ダウンロードした logback-classic.jar - ,logback-core.jar, slf4j-api.jar を WEB-INF/lib ディレクトリに追加します。スタンドアローンアプリケーションの場合は起動時の JVM 引数 -classpath に追加するだけです。 -

- -

Mavenを利用している場合は、pom.xmlに以下のような設定を追加することでJARファイルをダウンロードすることができます。 -

- - ch.qos.logback - logback-classic - 1.x.x - -]]> - -

-

- ステップ２: Logback を設定する。 -

-

Logback の設定はシンプルです。例えば次の Mapper のログを出力する場合： -

- -

次のテキストを含む logback.xml というファイルを作成し、クラスパスに配置します。 -

- - - - - - - - %5level [%thread] - %msg%n - - - - - - - - - - - -]]> - -

上記のように設定すると、SLF4J(Logback) は org.mybatis.example.BlogMapper について詳細なログを出力し、それ以外のクラスについてはエラーのみを出力します。

-

ログに出力される情報を細かく調整したいのなら、Mapper ファイル全体ではなく特定のステートメントを指定することもできます。

- - - - -]]> - -

逆に、複数の Mapper に対するログを有効化したい場合もあるでしょう。その場合は、対象となる Mapper を含むパッケージを指定することができます。

- - - - -]]> - -

クエリが大量の結果セットを返すようなケースでSQLステートメントのみを出力したい場合に対応できるよう、SQLステートメントは DEBUG（JDK logging では FINE）レベル、結果は TRACE（JDK logging では FINER）レベルで出力されるようになっています。SQLステートメントのみを出力したい場合、ログレベルに DEBUG を設定します。

- - - - -]]> - -

Mapper インターフェイスを使っていない場合、例えば次のような Mapper XML ファイルを使っていたらどうすれば良いのでしょうか。 -

- - - - - - -]]> - -

この場合、次のようにネームスペースを指定することでこの XML ファイル全体のログを有効化することができます。

- - - - -]]> - -

特定のステートメントのみを対象とする場合は次のように指定します。

- - - - -]]> - -

お気づきのように、Mapper インターフェイスと XML のどちらを使っている場合でも、設定方法に違いはありません。

- -

NOTE SLF4J or Log4j 2 をお使いの場合、MyBatis のログは MYBATIS というマーカーで出力されます。

- -

上記の logback.xml の残りの部分はアペンダーの設定になっていますが、このドキュメントでは説明しません。Logback のサイトを参照してください。あるいは、設定値を変更してみてどのような結果になるか試してみるのも良いでしょう。 -

- -

-

- Log4j 2の設定例 -

- -

pom.xml

- - - org.apache.logging.log4j - log4j-core - 2.x.x - -]]> - -

log4j2.xml

- - - - - - - - - - - - - - - - - - -]]> - -

-

- Log4jの設定例 -

- -

pom.xml

- - - log4j - log4j - 1.2.17 - -]]> - -

log4j.properties

- - - -

-

- JDK Loggingの設定例 -

- -

logging.properties

- - - - -
- - diff --git a/src/site/ko/markdown/logging.md b/src/site/ko/markdown/logging.md new file mode 100644 index 00000000000..717d63f4251 --- /dev/null +++ b/src/site/ko/markdown/logging.md @@ -0,0 +1,219 @@ +title: 마이바티스 3 | 로깅 +author: Clinton Begin, 이동국(한국어 번역) + +## Logging + +마이바티스는 내부 로그 팩토리를 사용하여 로깅 정보를 제공한다. 내부 로그 팩토리는 로깅 정보를 다른 로그 구현체 중 하나에 전달한다. + +- SLF4J +- Apache Commons Logging +- Log4j 2 +- Log4j (deprecated since 3.5.9) +- JDK logging + +로깅 솔루션은 내부 마이바티스 로그 팩토리의 런타임 체크를 통해 선택된다. 마이바티스 로그 팩토리는 가능하면 첫번째 구현체를 사용할 것이다(위 로깅 구현체의 나열 순서는 내부적으로 선택하는 우선순위이다). 만약 마이바티스가 위 구현체중 하나도 찾지 못한다면 로깅을 하지 않을 것이다. + +많은 환경은 애플리케이션 서버(좋은 예는 톰캣과 웹스피어)의 클래스패스의 일부로 JCL 을 사용한다. 이러한 환경을 아는 것이 중요하다. 마이바티스는 로깅 구현체로 JCL 을 사용할 것이다. 웹스피어와 같은 환경에서 Log4J 설정은 무시될 것이다. 왜냐하면 웹스피어는 자체 JCL 구현체를 제공하기 때문이다. 이러한 사항은 불만스러울수 있다. 왜냐하면 마이바티스는 당신의 Log4J 설정을 무시하는 것처럼 보일수도 있기 때문이다. (사실 마이바티스는 당신의 Log4J 설정을 무시한다. 왜냐하면 마이바티스는 이러한 환경에서 JCL 을 사용할 것이기 때문이다.) 만약 당신의 애플리케이션이 클래스패스에 JCL 을 포함한 환경에서 돌아가지만 다른 로깅 구현체 중 하나를 더 선호한다면 다음의 메소드 중 하나를 호출하여 다른 로깅 구현체를 선택 할 수 있다. + +```java +org.apache.ibatis.logging.LogFactory.useSlf4jLogging(); +org.apache.ibatis.logging.LogFactory.useLog4JLogging(); +org.apache.ibatis.logging.LogFactory.useLog4J2Logging(); +org.apache.ibatis.logging.LogFactory.useJdkLogging(); +org.apache.ibatis.logging.LogFactory.useCommonsLogging(); +org.apache.ibatis.logging.LogFactory.useStdOutLogging(); +``` + +마이바티스가 메소드를 호출하기 전에 위 메소드 중 하나를 호출해야 한다. 이 메소드들은 런타임 클래스패스에 구현체가 존재하면 그 로그 구현체를 사용하게 한다. 예를들어 Log4J2 로깅을 선택했지만 런타임에 Log4J2 구현체가 클래스패스에 없다면 마이바티스는 Log4J2 구현체의 사용을 무시하고 로깅 구현체를 찾아 다시 사용할 것이다. + +SLF4J, Jakarta Commons 로깅, Log4J 그리고 JDK 로깅 API 에 대한 설명은 이 문서의 범위를 벗어난다. 이러한 로깅 관련 프레임워크에 대해 좀더 알고 싶다면 개별 위치에서 좀더 많은 정보를 얻을 수 있을 것이다. + +- [SLF4J](https://www.slf4j.org/) +- [Apache Commons Logging](https://commons.apache.org/proper/commons-logging/) +- [Apache Log4j 2.x](https://logging.apache.org/log4j/2.x/) +- [JDK Logging API](https://docs.oracle.com/javase/8/docs/technotes/guides/logging/overview.html) + +### Logging Configuration + +마이바티스 로깅 구문을 보기 위해서 패키지, 매퍼의 전체 경로, 구문명의 명명공간에 대해 활성화해주어야 할것이다. + +다시 얘기해서 사용할 로깅 구현체에 따라야 하고 우리는 SLF4J(Logback)를 사용하는 방법을 보여줄 것이다. 로깅 설정은 대부분 하나 이상의 설정파일(예를들면, `logback.xml`)과 몇개의 새로운 jar파일을 다룬다. 다음의 설정예제는 SLF4J(Logback)를 사용하여 설정하고 2단계로 설정한다. + +#### 첫번째 단계 : SLF4J + Logback JAR 파일 추가하기 + +SLF4J(Logback)를 사용하기 때문에 애플리케이션에 JAR 파일이 있어야 한다. Log4J 를 사용하기 위해 애플리케이션의 클래스패스에 JAR 파일을 추가할 필요가 있다. 위 URL 에서 SLF4J(Logback) 를 다운로드 할 수 있다. + +웹이나 기업용 애플리케이션에서는 `WEB-INF/lib` 디렉터리에 `logback-classic.jar` ,`logback-core.jar` and `slf4j-api.jar` 파일을 추가할 수 있다. 단독으로 실행되는 애플리케이션에서는 JVM의 `-classpath` 시작 파라미터에서 간단히 추가할 수 있다. + +If you use the maven, you can download jar files by adding following settings on your `pom.xml`. + +```xml + + ch.qos.logback + logback-classic + 1.x.x + +``` + +#### 두번째 단계 : Logback 설정하기 + +Logback 를 설정하는 것은 간단하다. 다음의 매퍼를 위한 로깅을 활성화하려고 한다고 해보자. + +```java +package org.mybatis.example; +public interface BlogMapper { + @Select("SELECT * FROM blog WHERE id = #{id}") + Blog selectBlog(int id); +} +``` + +아래처럼 `logback.xml`파일을 만들어서 클래스패스에 두자. + +```xml + + + + + + + %5level [%thread] - %msg%n + + + + + + + + + + + +``` + +위 파일은 `org.mybatis.example.BlogMapper`의 상세한 로그와 애플리케이션의 에러들을 출력할 것이다. + +finer레벨로 로깅을 하고자 한다면 전체 매퍼 파일대신 특정 구문만을 로깅할 수 있다. 다음 줄은 `selectBlog`구문의 로그를 출력하도록 한다. + +```xml + + + +``` + +반대로 특정 매퍼들에 대해 로깅을 원할 수 있다. 이 경우 매퍼의 가장 상위 패키지에 로거를 추가할 수 있다. + +```xml + + + +``` + +큰 결과를 리턴할 수 있는 쿼리가 있다. 이 경우 결과가 아닌 SQL구문만을 보고자 할 수 있다. 이러한 목적으로 SQL구문은 DEBUG레벨(JDK로깅에서는 FINE)로 지정하고 결과에 대해서는 TRACE레벨(JDK로깅에서는 FINER)로 지정한다. 결과가 아닌 구문만 보고자 하는 경우에는 DEBUG로 레벨을 설정하자. + +```xml + + + +``` + +다음처럼 매퍼 인터페이스가 아닌 매퍼 XML을 사용하다면 어떻게 해야 할까? + +```xml + + + + + +``` + +이런 경우에는 아래처럼 명명공간을 추가해서 XML파일 전체를 로깅할 수 있다. + +```xml + + + +``` + +또는 특정 구문만을 로깅하기 위해서는 + +```xml + + + +``` + +앞서 언급한것처럼 매퍼 인터페이스와 XML매퍼 파일간의 차이는 없다. + +`logback.xml` 파일의 나머지는 어펜더(appender)를 설정하기 위해 사용했다. 어펜더는 이 문서의 범위를 넘어선다. [Logback](https://logback.qos.ch/) 웹사이트에서 좀더 많은 정보를 얻을 수 있다. 설정파일간의 차이는 실행을 해보면 간단히 확인할 수 있다. + +#### Configuration example for Log4j 2 + +```xml + + + org.apache.logging.log4j + log4j-core + 2.x.x + +``` + +```xml + + + + + + + + + + + + + + + + + + +``` + +#### Configuration example for Log4j + +```xml + + + log4j + log4j + 1.2.17 + +``` + +```properties +# log4j.properties +log4j.rootLogger=ERROR, stdout + +log4j.logger.org.mybatis.example.BlogMapper=TRACE + +log4j.appender.stdout=org.apache.log4j.ConsoleAppender +log4j.appender.stdout.layout=org.apache.log4j.PatternLayout +log4j.appender.stdout.layout.ConversionPattern=%5p [%t] - %m%n +``` + +#### Configuration example for JDK logging + +```properties +# logging.properties +handlers=java.util.logging.ConsoleHandler +.level=SEVERE + +org.mybatis.example.BlogMapper=FINER + +java.util.logging.ConsoleHandler.level=ALL +java.util.logging.ConsoleHandler.formatter=java.util.logging.SimpleFormatter +java.util.logging.SimpleFormatter.format=%1$tT.%1$tL %4$s %3$s - %5$s%6$s%n +``` diff --git a/src/site/ko/xdoc/logging.xml b/src/site/ko/xdoc/logging.xml deleted file mode 100644 index a946a0544d1..00000000000 --- a/src/site/ko/xdoc/logging.xml +++ /dev/null @@ -1,321 +0,0 @@ - - - - - - 마이바티스 3 | 로깅 - Clinton Begin - 이동국(한국어 번역) - - - -
-

-

마이바티스는 내부 로그 팩토리를 사용하여 로깅 정보를 제공한다. - 내부 로그 팩토리는 로깅 정보를 다른 로그 구현체 중 하나에 전달한다. -

-
    -
  • - SLF4J -
    • -
  • - Apache Commons Logging -
    • -
  • - Log4j 2 -
    • -
  • - Log4j (deprecated since 3.5.9) -
    • -
  • - JDK logging -
    • -
-

로깅 솔루션은 내부 마이바티스 로그 팩토리의 런타임 체크를 통해 선택된다. - 마이바티스 로그 팩토리는 가능하면 첫번째 구현체를 사용할 것이다(위 로깅 구현체의 나열 순서는 내부적으로 선택하는 우선순위이다). - 만약 마이바티스가 위 구현체중 하나도 찾지 못한다면 로깅을 하지 않을 것이다. -

-

많은 환경은 애플리케이션 서버(좋은 예는 톰캣과 웹스피어)의 클래스패스의 일부로 JCL 을 사용한다. - 이러한 환경을 아는 것이 중요하다. - 마이바티스는 로깅 구현체로 JCL 을 사용할 것이다. - 웹스피어와 같은 환경에서 Log4J 설정은 무시될 것이다. - 왜냐하면 웹스피어는 자체 JCL 구현체를 제공하기 때문이다. - 이러한 사항은 불만스러울수 있다. - 왜냐하면 마이바티스는 당신의 Log4J 설정을 무시하는 것처럼 보일수도 있기 때문이다. - (사실 마이바티스는 당신의 Log4J 설정을 무시한다. - 왜냐하면 마이바티스는 이러한 환경에서 JCL 을 사용할 것이기 때문이다.) - 만약 당신의 애플리케이션이 클래스패스에 JCL 을 포함한 환경에서 돌아가지만 다른 로깅 구현체 중 하나를 더 선호한다면 - 다음의 메소드 중 하나를 호출하여 다른 로깅 구현체를 선택 할 수 있다. -

- -

마이바티스가 메소드를 호출하기 전에 위 메소드 중 하나를 호출해야 한다. - 이 메소드들은 런타임 클래스패스에 구현체가 존재하면 그 로그 구현체를 사용하게 한다. - 예를들어 Log4J2 로깅을 선택했지만 런타임에 Log4J2 구현체가 클래스패스에 없다면 - 마이바티스는 Log4J2 구현체의 사용을 무시하고 로깅 구현체를 찾아 다시 사용할 것이다. -

-

SLF4J, Jakarta Commons 로깅, Log4J 그리고 JDK 로깅 API 에 대한 설명은 이 문서의 범위를 벗어난다. - 이러한 로깅 관련 프레임워크에 대해 좀더 알고 싶다면 개별 위치에서 좀더 많은 정보를 얻을 수 있을 것이다. -

- - -

마이바티스 로깅 구문을 보기 위해서 패키지, 매퍼의 전체 경로, 구문명의 명명공간에 대해 활성화해주어야 할것이다. -

-

다시 얘기해서 사용할 로깅 구현체에 따라야 하고 우리는 SLF4J(Logback)를 사용하는 방법을 보여줄 것이다. - 로깅 설정은 대부분 하나 이상의 설정파일(예를들면, logback.xml)과 몇개의 새로운 jar파일을 다룬다. - 다음의 설정예제는 SLF4J(Logback)를 사용하여 설정하고 2단계로 설정한다. -

-

-

- 첫번째 단계 : SLF4J + Logback JAR 파일 추가하기 -

-

SLF4J(Logback)를 사용하기 때문에 애플리케이션에 JAR 파일이 있어야 한다. - Log4J 를 사용하기 위해 애플리케이션의 클래스패스에 JAR 파일을 추가할 필요가 있다. - 위 URL 에서 SLF4J(Logback) 를 다운로드 할 수 있다. -

-

웹이나 기업용 애플리케이션에서는 WEB-INF/lib 디렉터리에 logback-classic.jar - ,logback-core.jar and slf4j-api.jar 파일을 추가할 수 있다. - 단독으로 실행되는 애플리케이션에서는 JVM의 -classpath 시작 파라미터에서 간단히 추가할 수 있다. -

- -

If you use the maven, you can download jar files by adding following settings on your pom.xml. -

- - ch.qos.logback - logback-classic - 1.x.x - -]]> - -

-

- 두번째 단계 : Logback 설정하기 -

-

Logback 를 설정하는 것은 간단하다. - 다음의 매퍼를 위한 로깅을 활성화하려고 한다고 해보자. -

- -

아래처럼 logback.xml파일을 만들어서 클래스패스에 두자. -

- - - - - - - - %5level [%thread] - %msg%n - - - - - - - - - - - -]]> - -

- 위 파일은 org.mybatis.example.BlogMapper의 상세한 로그와 애플리케이션의 에러들을 출력할 것이다. -

-

- finer레벨로 로깅을 하고자 한다면 전체 매퍼 파일대신 특정 구문만을 로깅할 수 있다. - 다음 줄은 selectBlog구문의 로그를 출력하도록 한다. -

- - - - -]]> - -

반대로 특정 매퍼들에 대해 로깅을 원할 수 있다. - 이 경우 매퍼의 가장 상위 패키지에 로거를 추가할 수 있다.

- - - - -]]> - -

큰 결과를 리턴할 수 있는 쿼리가 있다. - 이 경우 결과가 아닌 SQL구문만을 보고자 할 수 있다. - 이러한 목적으로 SQL구문은 DEBUG레벨(JDK로깅에서는 FINE)로 지정하고 결과에 대해서는 TRACE레벨(JDK로깅에서는 FINER)로 지정한다. - 결과가 아닌 구문만 보고자 하는 경우에는 DEBUG로 레벨을 설정하자. -

- - - - -]]> - -

다음처럼 매퍼 인터페이스가 아닌 매퍼 XML을 사용하다면 어떻게 해야 할까? -

- - - - - - -]]> - -

이런 경우에는 아래처럼 명명공간을 추가해서 XML파일 전체를 로깅할 수 있다.

- - - - -]]> - -

또는 특정 구문만을 로깅하기 위해서는

- - - - -]]> - -

앞서 언급한것처럼 매퍼 인터페이스와 XML매퍼 파일간의 차이는 없다.

- -

logback.xml 파일의 나머지는 어펜더(appender)를 설정하기 위해 사용했다. - 어펜더는 이 문서의 범위를 넘어선다. - Logback 웹사이트에서 좀더 많은 정보를 얻을 수 있다. - 설정파일간의 차이는 실행을 해보면 간단히 확인할 수 있다. -

- -

-

- Configuration example for Log4j 2 -

- -

pom.xml

- - - org.apache.logging.log4j - log4j-core - 2.x.x - -]]> - -

log4j2.xml

- - - - - - - - - - - - - - - - -]]> - -

-

- Configuration example for Log4j -

- -

pom.xml

- - - log4j - log4j - 1.2.17 - -]]> - -

log4j.properties

- - - -

-

- Configuration example for JDK logging -

- -

logging.properties

- - - - -
- - diff --git a/src/site/zh/markdown/logging.md b/src/site/zh/markdown/logging.md new file mode 100644 index 00000000000..7f557794db4 --- /dev/null +++ b/src/site/zh/markdown/logging.md @@ -0,0 +1,235 @@ +title: MyBatis 3 | 日志 +author: Clinton Begin, Nan Lei + +## 日志 + +Mybatis 通过使用内置的日志工厂提供日志功能。内置日志工厂将会把日志工作委托给下面的实现之一： + +- SLF4J +- Apache Commons Logging +- Log4j 2 +- Log4j（3.5.9起废弃） +- JDK logging + +MyBatis 内置日志工厂基于运行时自省机制选择合适的日志工具。它会使用第一个查找得到的工具（按上文列举的顺序查找）。如果一个都未找到，日志功能就会被禁用。 + +不少应用服务器（如 Tomcat 和 WebShpere）的类路径中已经包含 Commons Logging，所以在这种配置环境下的 MyBatis 会把它作为日志工具，记住这点非常重要。这将意味着，在诸如 WebSphere 的环境中，它提供了 Commons Logging 的私有实现，你的 Log4J 配置将被忽略。MyBatis 将你的 Log4J 配置忽略掉是相当令人郁闷的（事实上，正是因为在这种配置环境下，MyBatis 才会选择使用 Commons Logging 而不是 Log4J）。如果你的应用部署在一个类路径已经包含 Commons Logging 的环境中，而你又想使用其它日志工具，你可以通过在 MyBatis 配置文件 mybatis-config.xml 里面添加一项 setting 来选择别的日志工具。 + +```xml + + + ... + + ... + + +``` + +logImpl 可选的值有：SLF4J、LOG4J、LOG4J2、JDK_LOGGING、COMMONS_LOGGING、STDOUT_LOGGING、NO_LOGGING，或者是实现了接口 org.apache.ibatis.logging.Log 的，且构造方法是以字符串为参数的类的完全限定名。（译者注：可以参考org.apache.ibatis.logging.slf4j.Slf4jImpl.java的实现） + +你也可以调用如下任一方法来使用日志工具： + +```java +org.apache.ibatis.logging.LogFactory.useSlf4jLogging(); +org.apache.ibatis.logging.LogFactory.useLog4JLogging(); +org.apache.ibatis.logging.LogFactory.useLog4J2Logging(); +org.apache.ibatis.logging.LogFactory.useJdkLogging(); +org.apache.ibatis.logging.LogFactory.useCommonsLogging(); +org.apache.ibatis.logging.LogFactory.useStdOutLogging(); +``` + +如果你决定要调用以上某个方法，请在调用其它 MyBatis 方法之前调用它。另外，仅当运行时类路径中存在该日志工具时，调用与该日志工具对应的方法才会生效，否则 MyBatis 一概忽略。如你环境中并不存在 Log4J2，你却调用了相应的方法，MyBatis 就会忽略这一调用，转而以默认的查找顺序查找日志工具。 + +关于 SLF4J、Apache Commons Logging、Apache Log4J 和 JDK Logging 的 API 介绍不在本文档介绍范围内。不过，下面的例子可以作为一个快速入门。关于这些日志框架的更多信息，可以参考以下链接： + +- [SLF4J](https://www.slf4j.org/) +- [Apache Commons Logging](https://commons.apache.org/proper/commons-logging/) +- [Apache Log4j 2.x](https://logging.apache.org/log4j/2.x/) +- [JDK Logging API](https://docs.oracle.com/javase/8/docs/technotes/guides/logging/overview.html) + +### 日志配置 + +你可以对包、映射类的全限定名、命名空间或全限定语句名开启日志功能来查看 MyBatis 的日志语句。 + +再次说明下，具体怎么做，由使用的日志工具决定，这里以 SLF4J(Logback) 为例。配置日志功能非常简单：添加一个或多个配置文件（如 logback.xml），有时需要添加 jar 包。下面的例子将使用 SLF4J(Logback) 来配置完整的日志服务，共两个步骤： + +#### 步骤 1：添加 SLF4J + Logback 的 jar 包 + +因为我们使用的是 SLF4J(Logback)，就要确保它的 jar 包在应用中是可用的。要启用 SLF4J(Logback)，只要将 jar 包添加到应用的类路径中即可。SLF4J(Logback) 的 jar 包可以在上面的链接中下载。 + +对于 web 应用或企业级应用，则需要将 `logback-classic.jar`, `logback-core.jar` and `slf4j-api.jar` 添加到 `WEB-INF/lib` 目录下；对于独立应用，可以将它添加到JVM 的 `-classpath` 启动参数中。 + +如果你使用 maven, 你可以通过在 `pom.xml` 中添加下面的依赖来下载 jar 文件。 + +```xml + + ch.qos.logback + logback-classic + 1.x.x + +``` + +#### 步骤 2：配置 Logback + +配置 Logback 比较简单，假如你需要记录这个映射器接口的日志： + +```java +package org.mybatis.example; +public interface BlogMapper { + @Select("SELECT * FROM blog WHERE id = #{id}") + Blog selectBlog(int id); +} +``` + +在应用的类路径中创建一个名称为 `logback.xml` 的文件，文件的具体内容如下： + +```xml + + + + + + + %5level [%thread] - %msg%n + + + + + + + + + + + +``` + +添加以上配置后，SLF4J(Logback) 就会记录 `org.mybatis.example.BlogMapper` 的详细执行操作，且仅记录应用中其它类的错误信息（若有）。 + +你也可以将日志的记录方式从接口级别切换到语句级别，从而实现更细粒度的控制。如下配置只对 `selectBlog` 语句记录日志： + +```xml + + + +``` + +与此相对，可以对一组映射器接口记录日志，只要对映射器接口所在的包开启日志功能即可： + +```xml + + + +``` + +某些查询可能会返回庞大的结果集，此时只想记录其执行的 SQL 语句而不想记录结果该怎么办？为此，Mybatis 中 SQL 语句的日志级别被设为DEBUG（JDK 日志设为 FINE），结果的日志级别为 TRACE（JDK 日志设为 FINER)。所以，只要将日志级别调整为 DEBUG 即可达到目的： + +```xml + + + +``` + +要记录日志的是类似下面的映射器文件而不是映射器接口又该怎么做呢？ + +```xml + + + + + +``` + +如需对 XML 文件记录日志，只要对命名空间增加日志记录功能即可： + +```xml + + + +``` + +要记录具体语句的日志可以这样做： + +```xml + + + +``` + +你应该注意到了，为映射器接口和 XML 文件添加日志功能的语句毫无差别。 + +注意 如果你使用的是 SLF4J 或 Log4j 2，MyBatis 将以 `MYBATIS` 这个值进行调用。 + +配置文件 `log4j.properties` 的余下内容是针对日志输出源的，这一内容已经超出本文档范围。关于 Logback 的更多内容，可以参考[Logback](https://logback.qos.ch/) 的网站。不过，你也可以简单地做做实验，看看不同的配置会产生怎样的效果。 + +#### Log4j 2 配置示例 + +```xml + + + org.apache.logging.log4j + log4j-core + 2.x.x + +``` + +```xml + + + + + + + + + + + + + + + + + + +``` + +#### Log4j 配置示例 + +```xml + + + log4j + log4j + 1.2.17 + +``` + +```properties +# log4j.properties +log4j.rootLogger=ERROR, stdout + +log4j.logger.org.mybatis.example.BlogMapper=TRACE + +log4j.appender.stdout=org.apache.log4j.ConsoleAppender +log4j.appender.stdout.layout=org.apache.log4j.PatternLayout +log4j.appender.stdout.layout.ConversionPattern=%5p [%t] - %m%n +``` + +#### JDK logging 配置示例 + +```properties +# logging.properties +handlers=java.util.logging.ConsoleHandler +.level=SEVERE + +org.mybatis.example.BlogMapper=FINER + +java.util.logging.ConsoleHandler.level=ALL +java.util.logging.ConsoleHandler.formatter=java.util.logging.SimpleFormatter +java.util.logging.SimpleFormatter.format=%1$tT.%1$tL %4$s %3$s - %5$s%6$s%n +``` diff --git a/src/site/zh/xdoc/logging.xml b/src/site/zh/xdoc/logging.xml deleted file mode 100644 index 910b3e9618d..00000000000 --- a/src/site/zh/xdoc/logging.xml +++ /dev/null @@ -1,299 +0,0 @@ - - - - - - MyBatis 3 | 日志 - Clinton Begin - Nan Lei - - - -
-

Mybatis 通过使用内置的日志工厂提供日志功能。内置日志工厂将会把日志工作委托给下面的实现之一：

-
    -
  • - SLF4J -
    • -
  • - Apache Commons Logging -
    • -
  • - Log4j 2 -
    • -
  • - Log4j （3.5.9 起废弃） -
    • -
  • - JDK logging -
    • -
-

MyBatis 内置日志工厂基于运行时自省机制选择合适的日志工具。它会使用第一个查找得到的工具（按上文列举的顺序查找）。如果一个都未找到，日志功能就会被禁用。

-

不少应用服务器（如 Tomcat 和 WebShpere）的类路径中已经包含 Commons Logging，所以在这种配置环境下的 MyBatis 会把它作为日志工具，记住这点非常重要。这将意味着，在诸如 WebSphere 的环境中，它提供了 Commons Logging 的私有实现，你的 Log4J 配置将被忽略。MyBatis 将你的 Log4J 配置忽略掉是相当令人郁闷的（事实上，正是因为在这种配置环境下，MyBatis 才会选择使用 Commons Logging 而不是 Log4J）。如果你的应用部署在一个类路径已经包含 Commons Logging 的环境中，而你又想使用其它日志工具，你可以通过在 MyBatis 配置文件 mybatis-config.xml 里面添加一项 setting 来选择别的日志工具。

- - - ... - - ... - - -]]> -

logImpl 可选的值有：SLF4J、LOG4J、LOG4J2、JDK_LOGGING、COMMONS_LOGGING、STDOUT_LOGGING、NO_LOGGING，或者是实现了接口 org.apache.ibatis.logging.Log 的，且构造方法是以字符串为参数的类的完全限定名。（译者注：可以参考org.apache.ibatis.logging.slf4j.Slf4jImpl.java的实现） -

-

你也可以调用如下任一方法来使用日志工具： -

- -

如果你决定要调用以上某个方法，请在调用其它 MyBatis 方法之前调用它。另外，仅当运行时类路径中存在该日志工具时，调用与该日志工具对应的方法才会生效，否则 MyBatis 一概忽略。如你环境中并不存在 Log4J2，你却调用了相应的方法，MyBatis 就会忽略这一调用，转而以默认的查找顺序查找日志工具。 -

-

关于 SLF4J、Apache Commons Logging、Apache Log4J 和 JDK Logging 的 API 介绍不在本文档介绍范围内。不过，下面的例子可以作为一个快速入门。关于这些日志框架的更多信息，可以参考以下链接：

- - -

你可以对包、映射类的全限定名、命名空间或全限定语句名开启日志功能来查看 MyBatis 的日志语句。 -

-

再次说明下，具体怎么做，由使用的日志工具决定，这里以 SLF4J(Logback) 为例。配置日志功能非常简单：添加一个或多个配置文件（如 logback.xml），有时需要添加 jar 包。下面的例子将使用 SLF4J(Logback) 来配置完整的日志服务，共两个步骤： -

-

-

- 步骤 1：添加 SLF4J + Logback 的 jar 包 -

-

因为我们使用的是 SLF4J(Logback)，就要确保它的 jar 包在应用中是可用的。要启用 SLF4J(Logback)，只要将 jar 包添加到应用的类路径中即可。SLF4J(Logback) 的 jar 包可以在上面的链接中下载。 -

-

对于 web 应用或企业级应用，则需要将 logback-classic.jar, logback-core.jar and slf4j-api.jar 添加到 WEB-INF/lib 目录下；对于独立应用，可以将它添加到JVM 的 -classpath 启动参数中。 -

-

如果你使用 maven, 你可以通过在 pom.xml 中添加下面的依赖来下载 jar 文件。 -

- - ch.qos.logback - logback-classic - 1.x.x - -]]> - -

-

- 步骤 2：配置 Logback -

-

配置 Logback 比较简单，假如你需要记录这个映射器接口的日志： -

- -

在应用的类路径中创建一个名称为 logback.xml 的文件，文件的具体内容如下： -

- - - - - - - - %5level [%thread] - %msg%n - - - - - - - - - - - -]]> - -

添加以上配置后，SLF4J(Logback) 就会记录 org.mybatis.example.BlogMapper 的详细执行操作，且仅记录应用中其它类的错误信息（若有）。

-

你也可以将日志的记录方式从接口级别切换到语句级别，从而实现更细粒度的控制。如下配置只对 selectBlog 语句记录日志： -

- - - - -]]> - -

与此相对，可以对一组映射器接口记录日志，只要对映射器接口所在的包开启日志功能即可：

- - - - -]]> - -

某些查询可能会返回庞大的结果集，此时只想记录其执行的 SQL 语句而不想记录结果该怎么办？为此，Mybatis 中 SQL 语句的日志级别被设为DEBUG（JDK 日志设为 FINE），结果的日志级别为 TRACE（JDK 日志设为 FINER)。所以，只要将日志级别调整为 DEBUG 即可达到目的： -

- - - - -]]> - -

要记录日志的是类似下面的映射器文件而不是映射器接口又该怎么做呢？ -

- - - - - - -]]> - -

如需对 XML 文件记录日志，只要对命名空间增加日志记录功能即可： -

- - - - -]]> - -

要记录具体语句的日志可以这样做：

- - - - -]]> - -

你应该注意到了，为映射器接口和 XML 文件添加日志功能的语句毫无差别。 -

- -

注意 如果你使用的是 SLF4J 或 Log4j 2，MyBatis 将以 MYBATIS 这个值进行调用。

- -

配置文件 log4j.properties 的余下内容是针对日志输出源的，这一内容已经超出本文档范围。关于 Logback 的更多内容，可以参考Logback 的网站。不过，你也可以简单地做做实验，看看不同的配置会产生怎样的效果。 -

- -

-

- Log4j 2 配置示例 -

- -

pom.xml

- - - org.apache.logging.log4j - log4j-core - 2.x.x - -]]> - -

log4j2.xml

- - - - - - - - - - - - - - - - - - -]]> - -

-

- Log4j 配置示例 -

- -

pom.xml

- - - log4j - log4j - 1.2.17 - -]]> - -

log4j.properties

- - - -

-

- JDK logging 配置示例 -

- -

logging.properties

- - - - -
- - From 54038e4d1b4d13c84ce1c9707da12445c62bfe08 Mon Sep 17 00:00:00 2001 From: Iwao AVE! Date: Sun, 30 Jul 2023 18:44:21 +0900 Subject: [PATCH 2/4] Update logging.md Missing code blocks --- src/site/zh/markdown/logging.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/site/zh/markdown/logging.md b/src/site/zh/markdown/logging.md index 7f557794db4..027fd2a4285 100644 --- a/src/site/zh/markdown/logging.md +++ b/src/site/zh/markdown/logging.md @@ -25,7 +25,7 @@ MyBatis 内置日志工厂基于运行时自省机制选择合适的日志工具 ``` -logImpl 可选的值有：SLF4J、LOG4J、LOG4J2、JDK_LOGGING、COMMONS_LOGGING、STDOUT_LOGGING、NO_LOGGING，或者是实现了接口 org.apache.ibatis.logging.Log 的，且构造方法是以字符串为参数的类的完全限定名。（译者注：可以参考org.apache.ibatis.logging.slf4j.Slf4jImpl.java的实现） +logImpl 可选的值有：SLF4J、LOG4J、LOG4J2、JDK_LOGGING、COMMONS_LOGGING、STDOUT_LOGGING、NO_LOGGING，或者是实现了接口 `org.apache.ibatis.logging.Log` 的，且构造方法是以字符串为参数的类的完全限定名。（译者注：可以参考org.apache.ibatis.logging.slf4j.Slf4jImpl.java的实现） 你也可以调用如下任一方法来使用日志工具： @@ -51,7 +51,7 @@ org.apache.ibatis.logging.LogFactory.useStdOutLogging(); 你可以对包、映射类的全限定名、命名空间或全限定语句名开启日志功能来查看 MyBatis 的日志语句。 -再次说明下，具体怎么做，由使用的日志工具决定，这里以 SLF4J(Logback) 为例。配置日志功能非常简单：添加一个或多个配置文件（如 logback.xml），有时需要添加 jar 包。下面的例子将使用 SLF4J(Logback) 来配置完整的日志服务，共两个步骤： +再次说明下，具体怎么做，由使用的日志工具决定，这里以 SLF4J(Logback) 为例。配置日志功能非常简单：添加一个或多个配置文件（如 `logback.xml`），有时需要添加 jar 包。下面的例子将使用 SLF4J(Logback) 来配置完整的日志服务，共两个步骤： #### 步骤 1：添加 SLF4J + Logback 的 jar 包 From a252ff385bd3171eb2df5310c51addccee8eee0f Mon Sep 17 00:00:00 2001 From: Iwao AVE! Date: Sun, 30 Jul 2023 18:46:56 +0900 Subject: [PATCH 3/4] Update logging.md --- src/site/ja/markdown/logging.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/site/ja/markdown/logging.md b/src/site/ja/markdown/logging.md index 211a6e98671..61d7e97ffb9 100644 --- a/src/site/ja/markdown/logging.md +++ b/src/site/ja/markdown/logging.md @@ -1,4 +1,4 @@ -title: MyBatis 3 | Logging +title: MyBatis 3 | ロギング author: Clinton Begin, Iwao AVE! ## ロギング From c6d2be7653b5736c08048c127597e70d2cddad7c Mon Sep 17 00:00:00 2001 From: Iwao AVE! Date: Sun, 30 Jul 2023 18:49:28 +0900 Subject: [PATCH 4/4] Missing code block --- src/site/es/markdown/logging.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/site/es/markdown/logging.md b/src/site/es/markdown/logging.md index c1112d60760..d82a4d6a370 100644 --- a/src/site/es/markdown/logging.md +++ b/src/site/es/markdown/logging.md @@ -81,7 +81,7 @@ public interface BlogMapper { } ``` -Crea un fichero con nombre logback.xml como el que se muestra a continuación y colocalo en tu classpath: +Crea un fichero con nombre `logback.xml` como el que se muestra a continuación y colocalo en tu classpath: ```xml