structured.h (3018B)
1 // Copyright 2022 The Abseil Authors. 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // https://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 // 15 // ----------------------------------------------------------------------------- 16 // File: log/structured.h 17 // ----------------------------------------------------------------------------- 18 // 19 // This header declares APIs supporting structured logging, allowing log 20 // statements to be more easily parsed, especially by automated processes. 21 // 22 // When structured logging is in use, data streamed into a `LOG` statement are 23 // encoded as `Value` fields in a `logging.proto.Event` protocol buffer message. 24 // The individual data are exposed programmatically to `LogSink`s and to the 25 // user via some log reading tools which are able to query the structured data 26 // more usefully than would be possible if each message was a single opaque 27 // string. These helpers allow user code to add additional structure to the 28 // data they stream. 29 30 #ifndef ABSL_LOG_STRUCTURED_H_ 31 #define ABSL_LOG_STRUCTURED_H_ 32 33 #include <ostream> 34 35 #include "absl/base/attributes.h" 36 #include "absl/base/config.h" 37 #include "absl/log/internal/structured.h" 38 #include "absl/strings/string_view.h" 39 40 namespace absl { 41 ABSL_NAMESPACE_BEGIN 42 43 // LogAsLiteral() 44 // 45 // Annotates its argument as a string literal so that structured logging 46 // captures it as a `literal` field instead of a `str` field (the default). 47 // This does not affect the text representation, only the structure. 48 // 49 // Streaming `LogAsLiteral(s)` into a `std::ostream` behaves just like streaming 50 // `s` directly. 51 // 52 // Using `LogAsLiteral()` is occasionally appropriate and useful when proxying 53 // data logged from another system or another language. For example: 54 // 55 // void Logger::LogString(absl::string_view str, absl::LogSeverity severity, 56 // const char *file, int line) { 57 // LOG(LEVEL(severity)).AtLocation(file, line) << str; 58 // } 59 // void Logger::LogStringLiteral(absl::string_view str, 60 // absl::LogSeverity severity, const char *file, 61 // int line) { 62 // LOG(LEVEL(severity)).AtLocation(file, line) << absl::LogAsLiteral(str); 63 // } 64 // 65 // `LogAsLiteral` should only be used as a streaming operand and not, for 66 // example, as a local variable initializer. 67 inline log_internal::AsLiteralImpl LogAsLiteral( 68 absl::string_view s ABSL_ATTRIBUTE_LIFETIME_BOUND) { 69 return log_internal::AsLiteralImpl(s); 70 } 71 72 ABSL_NAMESPACE_END 73 } // namespace absl 74 75 #endif // ABSL_LOG_STRUCTURED_H_