Logging Components

An overview of logging in the Google Cloud C++ client libraries.

Introduction

The client libraries never use logging to report errors, but logging can be enabled to help troubleshoot problems when the last error message does not provide a good enough indication of the root cause.

In general, we abide by the following principles:

  • Logging should be controlled by the application developer. Unless explicitly instructed, the libraries produce no output to the console, except to emit a message to std::clog immediately before a GCP_LOG(FATAL) terminates the process.
  • Logging should have very low cost:
    • It should be possible to disable logs at compile time. They should disappear as-if there were #ifdef/#endif directives around them.
    • A log line at a disabled log level should be about as expensive as an extra if() statement. At the very least it should not incur additional memory allocations or locks.
  • It should be easy to log complex objects.
  • The logging framework should play well with the C++ iostream classes.
  • The application should be able to intercept log records and re-direct them to their own logging framework.

Enabling logs

The application needs to do two things to enable logging:

  • First, to configure the destination of the logs you must add a backend (see AddBackend) to the default LogSink.
  • Second, you must configure what gets logged. Typically, you initialize the *Connection object with a LoggingComponentsOption. Consult the documentation for each *Client class to find what tracing components are available.

At run-time, setting the GOOGLE_CLOUD_CPP_ENABLE_CLOG to a non-empty value configures a LogBackend that uses std::clog. Likewise, setting the GOOGLE_CLOUD_CPP_ENABLE_TRACING=a,b will enable tracing for components a and b across all client objects. The most common components are auth, rpc, and rpc-streams.

Note that while std::clog is buffered, the framework will flush any log message at severity WARNING or higher.

Example: Logging From Library

Use the GCP_LOG() macro to log from a Google Cloud Platform C++ library:

void LibraryCode(ComplexThing const& thing) {
  GCP_LOG(INFO) << "I am here";
  if (thing.is_bad()) {
    GCP_LOG(ERROR) << "Poor thing is bad: " << thing;
  }
}

Example: Enable Logs to std::clog

To enable logs to std::clog the application can call:

void AppCode() {
  google::cloud::LogSink::EnableStdClog();
}

As previously noted, this can be switched at run-time using the GOOGLE_CLOUD_CPP_ENABLE_CLOG environment variable.