Google Cloud C++ Client  2.2.1
C++ Client Library for Google Cloud Platform
Classes | Namespaces | Macros | Enumerations | Functions
log.h File Reference

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

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

Go to the source code of this file.


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...


 Contains all the Google Cloud C++ Library APIs.


#define GOOGLE_CLOUD_CPP_PP_CONCAT(a, b)   a##b
 Concatenate two pre-processor tokens. More...
 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...


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 ,
 Define the severity levels for Google Cloud Platform C++ Libraries logging. More...


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:

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;
#define GCP_LOG(level)
Log a message with the Google Cloud Platform C++ Libraries logging framework.
Definition: log.h:166
Example: Enable Logs to std::clog
To enable logs to std::clog the application can call:
void AppCode() {
static void EnableStdClog(Severity min_severity=Severity::GCP_LS_LOWEST_ENABLED)
Enable std::clog on LogSink::Instance().
Definition: log.h:331

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(
if (record.severity >= google::cloud::Severity::CRITICAL) {
std::cerr << record << "\n";
// Use "id" to remove the capture.
Represents a single log message.
Definition: log.h:220
Severity severity
Definition: log.h:221

Definition in file log.h.

Macro Definition Documentation


#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 166 of file log.h.


#define GOOGLE_CLOUD_CPP_LOG_I (   level,
::google::cloud::Severity::level)> \
::google::cloud::Severity::level, __func__, __FILE__, __LINE__, \
sink); \
static constexpr bool CompileTimeEnabled(Severity level)
Return true if the severity is enabled at compile time.
Definition: log.h:253
Define the class to capture a log message.
Definition: log.h:384
Create a unique, or most likely unique identifier.
Definition: log.h:116

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 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 147 of file log.h.



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 116 of file log.h.



Definition at line 170 of file log.h.


)    a##b

Concatenate two pre-processor tokens.

Definition at line 105 of file log.h.