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.
LogAsLiteral(absl::string_view s ABSL_ATTRIBUTE_LIFETIME_BOUND)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_
76