Project: Envoy (Orchestration & Management / Service Proxy)
File: logging.md

Envoy uses the for logging through a variety of Envoy specific macros. Log messages are emitted with a log level chosen from one of the following: trace debug info warn error critical This log level can be used to restrict which log messages are actually shown via the `setLevel()` method of `Envoy::Logger::Logger` or via the command line argument `--l <level>`. Any messages which has a level less than the specified level will be squelched. In addition, the log level is typically show in the emitted log line. For example in the following line, you can see the level is `debug`: ``` [source/common/connpool/connpool_base.cc:293] [C18299946955195659044] attaching to next stream ``` In addition the the level, every log is emitted with an ID. This ID is not a numeric ID (like a stream ID or a connection ID) but is instead a token that is used to groups log messages in by category. The list of known ID is defined in `ALLLOGGERIDS` from `source/common/common/logger.h`. Similar to level, these IDs show up in log lines. For example in the following line, you can see the ID is `pool`: ``` [source/common/connpool/connpool_base.cc:293] [C18299946955195659044] attaching to next stream ``` Most log messages in Envoy are generated via the `ENVOY_LOG()` macro. For example: ``` ENVOY_LOG(debug, "subset lb: fallback load balancer disabled"); ``` This macro takes the log level as the first argument and the log message as the second argument. However the ID is not explicitly specified. Instead, the ID typically comes via the class inheriting from `Logger::Loggable<ID>`. By doing this, `ENVOY_LOG()` calls are able to find the relevant log ID. Under some circumstances, code will not be in a method of a class which extends `Loggable`. In those cases, there are a couple of options. One is to use `ENVOYLOGTO_LOGGER` and pass in an existing

This logger can come via the caller, or by requesting the logger for a specific ID. For example: ``` ENVOYLOGTO_LOGGER(Envoy::Logger::Registry::getLog(Envoy::Logger::Id::pool), warn, "Failed to create Http/3 client. Transport socket " "factory is not configured correctly."); ``` As a last resort, the `ENVOYLOGMISC` macro can be used to log with the `misc` ID. For example: ``` ENVOYLOGMISC(warn, "failed to enable core dump"); ``` However, it is usually much better to log to a more specific ID. There is another API which can be used specifically for `Connection` or `Stream` related log messages. `ENVOYCONNLOG` takes an additional `Connection` argument and `ENVOYSTREAMLOG` takes an additional `Stream` argument. These macros work like `ENVOY_LOG` except that they prepend the log message with `[C123]` or `[C123][S456` based on the connection/stream ID of the specified argument. Note that the IDs here are the Envoy IDs NOT the on-the-wire IDs from HTTP/2 or HTTP/3. The following logging API allows the call site to pass a key-value object (``std::map``) with additional context information that would be printed in the final log line. Unless JSON application logging is enabled, the output log line will prepend the log tags in the following format: '[Tags: "key1":"value1","key2":"value2"]'. When JSON application logging is enabled, the output JSON log will also include the key-values as additional properties in the JSON struct. Example: ``` std::map<std::string, std::string> log_tags{{"key1","value1"},{"key2","value2"}}; ENVOYTAGGEDLOG(debug, log_tags, "failed to perform the operation"); // output: [debug] [Tags: "key1":"value1","key2":"value2"] failed to perform the operation ``` These logging APIs support all the properties as described for ENVOYTAGGEDLOG, but allow the call site to pass additional objects to add a connection ID or stream ID (with respect to the relevant macro). When using these macros, an additional log tag will be added with the key "ConnectionId" or "StreamId" (or both). Example: ``` std::map<std::string, std::string> log_tags{{"key1","value1"},{"key2","value2"}}; ENVOYTAGGEDLOG(debug, logtags, conn, "failed to perform the operation"); ENVOYTAGGEDLOG(debug, logtags, stream, "failed to perform the operation"); // output: [debug] [Tags: "ConnectionId":"10","StreamId":"11","key1":"value1","key2":"value2"] failed to perform the operation ```