accesslog: add %TRACE_ID% formatter

changelogs/current.yaml

@@ -163,6 +163,9 @@ new_features:
   change: |
     added support for :ref:`%UPSTREAM_HOST_NAME% <config_access_log_format_upstream_host_name>` for the upstream host
     identifier.
+- area: access_loggers
+  change: |
+    Added ``TRACE_ID`` :ref:`access log formatter <config_access_log_format>`.
 - area: healthcheck
   change: |
     Added support to healthcheck with ProxyProtocol in TCP Healthcheck by setting

docs/root/configuration/observability/access_log/usage.rst

@@ -1210,3 +1210,9 @@ UDP
 %ENVIRONMENT(X):Z%
   Environment value of environment variable X. If no valid environment variable X, '-' symbol will be used.
   Z is an optional parameter denoting string truncation up to Z characters long.
+
+%TRACE_ID%
+  HTTP
+    The trace ID of the request. If the request does not have a trace ID, this will be an empty string.
+  TCP/UDP
+    Not implemented ("-").

source/common/formatter/http_specific_formatter.cc

@@ -197,6 +197,17 @@ HeadersByteSizeFormatter::formatValueWithContext(const HttpFormatterContext& con
       context.requestHeaders(), context.responseHeaders(), context.responseTrailers()));
 }
 
+ProtobufWkt::Value TraceIDFormatter::formatValueWithContext(const HttpFormatterContext& context,
+                                                            const StreamInfo::StreamInfo&) const {
+  return ValueUtil::stringValue(context.activeSpan().getTraceIdAsHex());
+}
+
+absl::optional<std::string>
+TraceIDFormatter::formatWithContext(const HttpFormatterContext& context,
+                                    const StreamInfo::StreamInfo&) const {
+  return context.activeSpan().getTraceIdAsHex();
+}
+
 GrpcStatusFormatter::Format GrpcStatusFormatter::parseFormat(absl::string_view format) {
   if (format.empty() || format == "CAMEL_STRING") {
     return GrpcStatusFormatter::CamelString;
@@ -390,6 +401,10 @@ HttpBuiltInCommandParser::getKnownFormatters() {
 
            return std::make_unique<RequestHeaderFormatter>(main_header, alternative_header,
                                                            max_length);
+         }}},
+       {"TRACE_ID",
+        {CommandSyntaxChecker::COMMAND_ONLY, [](const std::string&, absl::optional<size_t>&) {
+           return std::make_unique<TraceIDFormatter>();
          }}}});
 }
 

source/common/formatter/http_specific_formatter.h

@@ -143,6 +143,19 @@ class ResponseTrailerFormatter : public FormatterProvider, HeaderFormatter {
                          const StreamInfo::StreamInfo& stream_info) const override;
 };
 
+/**
+ * FormatterProvider for trace ID.
+ */
+class TraceIDFormatter : public FormatterProvider {
+public:
+  absl::optional<std::string>
+  formatWithContext(const HttpFormatterContext& context,
+                    const StreamInfo::StreamInfo& stream_info) const override;
+  ProtobufWkt::Value
+  formatValueWithContext(const HttpFormatterContext& context,
+                         const StreamInfo::StreamInfo& stream_info) const override;
+};
+
 class GrpcStatusFormatter : public FormatterProvider, HeaderFormatter {
 public:
   enum Format {

test/common/formatter/substitution_formatter_test.cc

@@ -25,6 +25,7 @@
 #include "test/mocks/network/mocks.h"
 #include "test/mocks/ssl/mocks.h"
 #include "test/mocks/stream_info/mocks.h"
+#include "test/mocks/tracing/mocks.h"
 #include "test/mocks/upstream/cluster_info.h"
 #include "test/test_common/environment.h"
 #include "test/test_common/printers.h"
@@ -2144,6 +2145,29 @@ TEST(SubstitutionFormatterTest, responseTrailerFormatter) {
   }
 }
 
+TEST(SubstitutionFormatterTest, Trac) {
+  StreamInfo::MockStreamInfo stream_info;
+  Http::TestRequestHeaderMapImpl request_header{};
+  Http::TestResponseHeaderMapImpl response_header{};
+  Http::TestResponseTrailerMapImpl response_trailer{};
+  std::string body;
+
+  Tracing::MockSpan active_span;
+  EXPECT_CALL(active_span, getTraceIdAsHex())
+      .WillRepeatedly(Return("ae0046f9075194306d7de2931bd38ce3"));
+
+  HttpFormatterContext formatter_context(&request_header, &response_header, &response_trailer, body,
+                                         AccessLogType::NotSet, &active_span);
+
+  {
+    TraceIDFormatter formatter{};
+    EXPECT_EQ("ae0046f9075194306d7de2931bd38ce3",
+              formatter.formatWithContext(formatter_context, stream_info));
+    EXPECT_THAT(formatter.formatValueWithContext(formatter_context, stream_info),
+                ProtoEq(ValueUtil::stringValue("ae0046f9075194306d7de2931bd38ce3")));
+  }
+}
+
 /**
  * Populate a metadata object with the following test data:
  * "com.test": {"test_key":"test_value","test_obj":{"inner_key":"inner_value"}}