• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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/config.h"
36 #include "absl/log/internal/structured.h"
37 #include "absl/strings/string_view.h"
38 
39 namespace absl {
40 ABSL_NAMESPACE_BEGIN
41 
42 // LogAsLiteral()
43 //
44 // Annotates its argument as a string literal so that structured logging
45 // captures it as a `literal` field instead of a `str` field (the default).
46 // This does not affect the text representation, only the structure.
47 //
48 // Streaming `LogAsLiteral(s)` into a `std::ostream` behaves just like streaming
49 // `s` directly.
50 //
51 // Using `LogAsLiteral()` is occasionally appropriate and useful when proxying
52 // data logged from another system or another language.  For example:
53 //
54 //   void Logger::LogString(absl::string_view str, absl::LogSeverity severity,
55 //                          const char *file, int line) {
56 //     LOG(LEVEL(severity)).AtLocation(file, line) << str;
57 //   }
58 //   void Logger::LogStringLiteral(absl::string_view str,
59 //                                 absl::LogSeverity severity, const char *file,
60 //                                 int line) {
61 //     LOG(LEVEL(severity)).AtLocation(file, line) << absl::LogAsLiteral(str);
62 //   }
LogAsLiteral(absl::string_view s)63 inline log_internal::AsLiteralImpl LogAsLiteral(absl::string_view s) {
64   return log_internal::AsLiteralImpl(s);
65 }
66 
67 ABSL_NAMESPACE_END
68 }  // namespace absl
69 
70 #endif  // ABSL_LOG_STRUCTURED_H_
71