Google Cloud Platform C++ Libraries logging framework. More...

#include "google/cloud/version.h"
#include <atomic>
#include <chrono>
#include <cstdlib>
#include <functional>
#include <iostream>
#include <map>
#include <memory>
#include <mutex>
#include <sstream>
#include <string>
#include <thread>

Classes
struct	google::cloud::LogRecord
	Represents a single log message. More...

class	google::cloud::LogBackend
	The logging backend interface. More...

class	google::cloud::LogSink
	A sink to receive log records. More...

struct	google::cloud::NullStream
	Implements operator<< for all types, without any effect. More...

class	google::cloud::Logger< CompileTimeEnabled >
	Define the class to capture a log message. More...

class	google::cloud::Logger< false >
	Define the logger for a disabled log level. More...

Namespaces
	google

	google::cloud
	Contains all the Google Cloud C++ Library APIs.

Macros
#define	GOOGLE_CLOUD_CPP_PP_CONCAT(a, b) a##b
	Concatenate two pre-processor tokens. More...

#define	GOOGLE_CLOUD_CPP_LOGGER_IDENTIFIER GOOGLE_CLOUD_CPP_PP_CONCAT(google_cloud_cpp_log_, __LINE__)
	Create a unique, or most likely unique identifier. More...

#define	GOOGLE_CLOUD_CPP_LOG_I(level, sink)
	The main entry point for the Google Cloud Platform C++ Library loggers. More...

#define	GCP_LOG(level) GOOGLE_CLOUD_CPP_LOG_I(GCP_LS_##level, ::google::cloud::LogSink::Instance())
	Log a message with the Google Cloud Platform C++ Libraries logging framework. More...

#define	GOOGLE_CLOUD_CPP_LOGGING_MIN_SEVERITY_ENABLED GCP_LS_DEBUG

Enumerations
enum class	google::cloud::Severity : int { google::cloud::GCP_LS_TRACE , google::cloud::GCP_LS_DEBUG , google::cloud::GCP_LS_INFO , google::cloud::GCP_LS_NOTICE , google::cloud::GCP_LS_WARNING , google::cloud::GCP_LS_ERROR , google::cloud::GCP_LS_CRITICAL , google::cloud::GCP_LS_ALERT , google::cloud::GCP_LS_FATAL , google::cloud::GCP_LS_HIGHEST = GCP_LS_FATAL , google::cloud::GCP_LS_LOWEST = GCP_LS_TRACE , google::cloud::GCP_LS_LOWEST_ENABLED = GOOGLE_CLOUD_CPP_LOGGING_MIN_SEVERITY_ENABLED }
	Define the severity levels for Google Cloud Platform C++ Libraries logging. More...

Functions
std::ostream &	google::cloud::operator<< (std::ostream &os, Severity x)
	Streaming operator, writes a human readable representation. More...

std::ostream &	google::cloud::operator<< (std::ostream &os, LogRecord const &rhs)
	Default formatting of a LogRecord. More...

Detailed Description

Google Cloud Platform C++ Libraries logging framework.

Some of the libraries need to log information to simplify troubleshooting. The functions and macros used for logging are defined in this file. In general, we abide by the following principles:

Logging should 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 library 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.

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();
}

Alternatively, the application can enable logging to std::clog without any code changes or recompiling by setting the "GOOGLE_CLOUD_CPP_ENABLE_CLOG" environment variable before the program starts. The existence of this variable is all that matters; the value is ignored.

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

Example: Capture Logs: The application can implement simple backends by wrapping a functor:

void AppCode() {
  auto id = google::cloud::LogSink::AttachFunctor(
      [](google::cloud::LogRecord record) {
          if (record.severity >= google::cloud::Severity::CRITICAL) {
            std::cerr << record << "\n";
          }
      });
  // Use "id" to remove the capture.
}

Definition in file log.h.

Macro Definition Documentation

◆ GCP_LOG

#define GCP_LOG ( level ) GOOGLE_CLOUD_CPP_LOG_I(GCP_LS_##level, ::google::cloud::LogSink::Instance())

Log a message with the Google Cloud Platform C++ Libraries logging framework.

Definition at line 165 of file log.h.

◆ GOOGLE_CLOUD_CPP_LOG_I

#define GOOGLE_CLOUD_CPP_LOG_I	(	level,
		sink
	)

Value:

  for (::google::cloud::Logger<::google::cloud::LogSink::CompileTimeEnabled(   \
           ::google::cloud::Severity::level)>                                  \
           GOOGLE_CLOUD_CPP_LOGGER_IDENTIFIER(                                 \
               ::google::cloud::Severity::level, __func__, __FILE__, __LINE__, \
               sink);                                                          \
       GOOGLE_CLOUD_CPP_LOGGER_IDENTIFIER.enabled();                           \
       GOOGLE_CLOUD_CPP_LOGGER_IDENTIFIER.LogTo(sink))                         \
  GOOGLE_CLOUD_CPP_LOGGER_IDENTIFIER.Stream()

The main entry point for the Google Cloud Platform C++ Library loggers.

Typically this used only in tests, applications should use GCP_LOG(). This macro introduces a new scope (via the for-loop) with a single new identifier: GOOGLE_CLOUD_CPP_LOG_RECORD_IDENTIFIER We use a for-loop (as opposed to an if-statement, or a do-while), because then we can say:

GCP_LOG(WARNING) << a << b << c;

and the variables are scoped correctly. The for-loop also affords us an opportunity to check that the log level is enabled before entering the body of the loop, and if disabled we can minimize the cost of the log. For example, disabled logs do not create an iostream at all.

Finally, the type of the GOOGLE_CLOUD_CPP_LOG_RECORD_IDENTIFIER changes if the log level is disabled at compile-time. For compile-time disabled log levels the compiler should be able to determine that the loop will not execute at all, and completely eliminate the code (we verified this using godbolt.org with modern GCC and Clang versions).

Note the use of fully-qualified class names, including the initial ::, this is to prevent problems if anybody uses this macro in a context where Logger is defined by the enclosing namespaces.

Definition at line 146 of file log.h.

◆ GOOGLE_CLOUD_CPP_LOGGER_IDENTIFIER

#define GOOGLE_CLOUD_CPP_LOGGER_IDENTIFIER GOOGLE_CLOUD_CPP_PP_CONCAT(google_cloud_cpp_log_, __LINE__)

Create a unique, or most likely unique identifier.

In GCP_LOG() we need an identifier for the logger, we can easily create a C++ scope to make it work with any name, say "foo". However the user may have a variable called "foo" that they want to use in the scope (for example, to log the value of "foo". We try to make it unlikely that there will be collision by using an identifier that has a long prefix and depends on the line number.

Definition at line 115 of file log.h.

◆ GOOGLE_CLOUD_CPP_LOGGING_MIN_SEVERITY_ENABLED

#define GOOGLE_CLOUD_CPP_LOGGING_MIN_SEVERITY_ENABLED GCP_LS_DEBUG

Definition at line 169 of file log.h.

◆ GOOGLE_CLOUD_CPP_PP_CONCAT

#define GOOGLE_CLOUD_CPP_PP_CONCAT	(	a,
		b
	)	a##b

Concatenate two pre-processor tokens.

Definition at line 104 of file log.h.

Classes

Namespaces

Macros

Enumerations