absl/log/structured.h

0001 // Copyright 2022 The Abseil Authors.
0002 //
0003 // Licensed under the Apache License, Version 2.0 (the "License");
0004 // you may not use this file except in compliance with the License.
0005 // You may obtain a copy of the License at
0006 //
0007 //      https://www.apache.org/licenses/LICENSE-2.0
0008 //
0009 // Unless required by applicable law or agreed to in writing, software
0010 // distributed under the License is distributed on an "AS IS" BASIS,
0011 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
0012 // See the License for the specific language governing permissions and
0013 // limitations under the License.
0014 //
0015 // -----------------------------------------------------------------------------
0016 // File: log/structured.h
0017 // -----------------------------------------------------------------------------
0018 //
0019 // This header declares APIs supporting structured logging, allowing log
0020 // statements to be more easily parsed, especially by automated processes.
0021 //
0022 // When structured logging is in use, data streamed into a `LOG` statement are
0023 // encoded as `Value` fields in a `logging.proto.Event` protocol buffer message.
0024 // The individual data are exposed programmatically to `LogSink`s and to the
0025 // user via some log reading tools which are able to query the structured data
0026 // more usefully than would be possible if each message was a single opaque
0027 // string.  These helpers allow user code to add additional structure to the
0028 // data they stream.
0029
0030 #ifndef ABSL_LOG_STRUCTURED_H_
0031 #define ABSL_LOG_STRUCTURED_H_
0032
0033 #include <ostream>
0034
0035 #include "absl/base/config.h"
0036 #include "absl/log/internal/structured.h"
0037 #include "absl/strings/string_view.h"
0038
0039 namespace absl {
0040 ABSL_NAMESPACE_BEGIN
0041
0042 // LogAsLiteral()
0043 //
0044 // Annotates its argument as a string literal so that structured logging
0045 // captures it as a `literal` field instead of a `str` field (the default).
0046 // This does not affect the text representation, only the structure.
0047 //
0048 // Streaming `LogAsLiteral(s)` into a `std::ostream` behaves just like streaming
0049 // `s` directly.
0050 //
0051 // Using `LogAsLiteral()` is occasionally appropriate and useful when proxying
0052 // data logged from another system or another language.  For example:
0053 //
0054 //   void Logger::LogString(absl::string_view str, absl::LogSeverity severity,
0055 //                          const char *file, int line) {
0056 //     LOG(LEVEL(severity)).AtLocation(file, line) << str;
0057 //   }
0058 //   void Logger::LogStringLiteral(absl::string_view str,
0059 //                                 absl::LogSeverity severity, const char *file,
0060 //                                 int line) {
0061 //     LOG(LEVEL(severity)).AtLocation(file, line) << absl::LogAsLiteral(str);
0062 //   }
0063 inline log_internal::AsLiteralImpl LogAsLiteral(absl::string_view s) {
0064   return log_internal::AsLiteralImpl(s);
0065 }
0066
0067 ABSL_NAMESPACE_END
0068 }  // namespace absl
0069
0070 #endif  // ABSL_LOG_STRUCTURED_H_