Enabling logging

    Note

    The article is being updated.

    Below are examples of code that enables logging in different YDB SDKs.

    There are several ways to enable logs in an application that uses ydb-go-sdk:

    • Set the environment variable YDB_LOG_SEVERITY_LEVEL=info (possible values: trace, debug, info, warn, error, fatal, and quiet, defaults to quiet).
      This environment variable enables the built-in ydb-go-sdk logger (synchronous, non-block) with output to the standard output stream.

    • Connect a third-party logger `go.uber.org/zap`
      package main
      
      import (
          "context"
      
          "go.uber.org/zap"
      
          ydbZap "github.com/ydb-platform/ydb-go-sdk-zap"
          "github.com/ydb-platform/ydb-go-sdk/v3"
          "github.com/ydb-platform/ydb-go-sdk/v3/trace"
      )
      
      func main() {
          ctx, cancel := context.WithCancel(context.Background())
          defer cancel()
          var log *zap.Logger // zap-logger with init out of this scope
          db, err := ydb.Open(ctx,
              os.Getenv("YDB_CONNECTION_STRING"),
              ydbZap.WithTraces(
                  log,
                  ydbZap.WithDetails(trace.DetailsAll),
              ),
          )
          if err != nil {
              panic(err)
          }
          defer func() {
              _ = db.Close(ctx)
          }()
      }
      
    • Connect a third-party logger `go.uber.org/zap`
      package main
      
      import (
          "context"
          "os"
      
          "github.com/rs/zerolog"
      
          ydbZerolog "github.com/ydb-platform/ydb-go-sdk-zerolog"
          "github.com/ydb-platform/ydb-go-sdk/v3"
          "github.com/ydb-platform/ydb-go-sdk/v3/trace"
      )
      
      func main() {
          ctx, cancel := context.WithCancel(context.Background())
          defer cancel()
          var log zerolog.Logger // zap-logger with init out of this scope
          db, err := ydb.Open(ctx,
              os.Getenv("YDB_CONNECTION_STRING"),
              ydbZerolog.WithTraces(
                  log,
                  ydbZerolog.WithDetails(trace.DetailsAll),
              ),
          )
          if err != nil {
              panic(err)
          }
          defer func() {
              _ = db.Close(ctx)
          }()
      }
      
    • Connect your own logger implementation `github.com/ydb-platform/ydb-go-sdk/v3/log.Logger`
      package main
      
      import (
          "context"
          "os"
      
          "github.com/ydb-platform/ydb-go-sdk/v3"
          "github.com/ydb-platform/ydb-go-sdk/v3/log"
          "github.com/ydb-platform/ydb-go-sdk/v3/trace"
      )
      
      func main() {
          ctx, cancel := context.WithCancel(context.Background())
          defer cancel()
          var logger log.Logger // logger implementation with init out of this scope
          db, err := ydb.Open(ctx,
              os.Getenv("YDB_CONNECTION_STRING"),
              ydb.WithLogger(
                  trace.DetailsAll,
                  ydb.WithExternalLogger(logger),
              ),
          )
          if err != nil {
              panic(err)
          }
          defer func() {
              _ = db.Close(ctx)
          }()
      }
      
    • Implement your own logging package based on the github.com/ydb-platform/ydb-go-sdk/v3/trace tracing package.

    In the YDB Java SDK, logging is done using the slf4j library. It lets you use different logging levels (error, warn, info, debug, and trace) for one or more loggers. The following loggers are available in the current implementation:

    • The com.yandex.ydb.core.grpc logger provides information about the internal implementation of gRPC.

      • At the debug level, all operations are logged using gRPC. This level is recommended for debugging only.
      • Use the info level by default.
    • The com.yandex.ydb.table.impl logger at the debug level lets you monitor the internal state of the ydb driver, including session pool performance.

    • The com.yandex.ydb.table.SessionRetryContext logger at the debug level provides information about the number of retries, the results of executed queries, the execution time of individual retries, and the total execution time of the entire operation.

    • The com.yandex.ydb.table.Session logger at the debug level provides information about the query text, response status, and execution time for various session operations.

    Enabling and configuring Java SDK loggers depends on the slf4j-api implementation used.
    Below is an example of the log4j2 configuration for the log4j-slf4j-impl library.

    <Configuration status="WARN">
        <Appenders>
            <Console name="Console" target="SYSTEM_OUT">
                <PatternLayout pattern="%d{HH:mm:ss.SSS} [%t] %-5level %logger{36} - %msg%n"/>
            </Console>
        </Appenders>
    
        <Loggers>
            <Logger name="io.netty" level="warn" additivity="false">
                <AppenderRef ref="Console"/>
            </Logger>
            <Logger name="io.grpc.netty" level="warn" additivity="false">
                <AppenderRef ref="Console"/>
            </Logger>
            <Logger name="com.yandex.ydb.core.grpc" level="info" additivity="false">
                <AppenderRef ref="Console"/>
            </Logger>
            <Logger name="com.yandex.ydb.table.impl" level="info" additivity="false">
                <AppenderRef ref="Console"/>
            </Logger>
            <Logger name="com.yandex.ydb.table.SessionRetryContext" level="debug" additivity="false">
                <AppenderRef ref="Console"/>
            </Logger>
            <Logger name="com.yandex.ydb.table.Session" level="debug" additivity="false">
                <AppenderRef ref="Console"/>
            </Logger>
    
            <Root level="debug" >
                <AppenderRef ref="Console"/>
            </Root>
        </Loggers>
    </Configuration>