Google Cloud C++ Client  1.32.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 <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.

Classes

struct  google::cloud::v1::LogRecord
 Represents a single log message. More...
 
class  google::cloud::v1::LogBackend
 The logging backend interface. More...
 
class  google::cloud::v1::LogSink
 A sink to receive log records. More...
 
struct  google::cloud::v1::NullStream
 Implements operator<< for all types, without any effect. More...
 
class  google::cloud::v1::Logger< CompileTimeEnabled >
 Define the class to capture a log message. More...
 
class  google::cloud::v1::Logger< false >
 Define the logger for a disabled log level. More...
 

Namespaces

 google
 
 google::cloud
 Contains all the Google Cloud C++ Library APIs.
 
 google::cloud::v1
 The Google Cloud C++ Library inlined, versioned namespace.
 

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::v1::Severity : int {
  google::cloud::v1::GCP_LS_TRACE , google::cloud::v1::GCP_LS_DEBUG , google::cloud::v1::GCP_LS_INFO , google::cloud::v1::GCP_LS_NOTICE ,
  google::cloud::v1::GCP_LS_WARNING , google::cloud::v1::GCP_LS_ERROR , google::cloud::v1::GCP_LS_CRITICAL , google::cloud::v1::GCP_LS_ALERT ,
  google::cloud::v1::GCP_LS_FATAL , google::cloud::v1::GCP_LS_HIGHEST = int(GCP_LS_FATAL) , google::cloud::v1::GCP_LS_LOWEST = int(GCP_LS_TRACE) , google::cloud::v1::GCP_LS_LOWEST_ENABLED = int(GOOGLE_CLOUD_CPP_LOGGING_MIN_SEVERITY_ENABLED)
}
 Define the severity levels for Google Cloud Platform C++ Libraries logging. More...
 

Functions

std::ostream & google::cloud::v1::operator<< (std::ostream &os, Severity x)
 Streaming operator, writes a human readable representation. More...
 
std::ostream & google::cloud::v1::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:165
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:330

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:219

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::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()
Define the class to capture a log message.
Definition: log.h:383
#define GOOGLE_CLOUD_CPP_LOGGER_IDENTIFIER
Create a unique, or most likely unique identifier.
Definition: log.h:115

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,
 
)    a##b

Concatenate two pre-processor tokens.

Definition at line 104 of file log.h.