userver: components::Logging Class Reference
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages Concepts
components::Logging Class Referencefinal

#include <userver/logging/component.hpp>

Detailed Description

Logging component

Allows to configure the default logger and/or additional loggers for your needs.

Static options:

Name Description Default value
fs-task-processor task processor for disk I/O operations engine::current_task::GetBlockingTaskProcessor()
loggers.<logger-name>.file_path path to the log file -
loggers.<logger-name>.level log verbosity info
loggers.<logger-name>.format log output format, one of tskv, ltsv, json, json_yadeploy tskv
loggers.<logger-name>.flush_level messages of this and higher levels get flushed to the file immediately warning
loggers.<logger-name>.message_queue_size the size of internal message queue, must be a power of 2 65536
loggers.<logger-name>.overflow_behavior message handling policy while the queue is full: discard drops messages, block waits until message gets into the queue discard
loggers.<logger-name>.testsuite-capture if exists, setups additional TCP log sink for testing purposes {}
loggers.<logger-name>.fs-task-processor task processor for disk I/O operations for this logger top-level fs-task-processor option

default logger is the one used for LOG_*.

Logs output

You can specify where logs are written in the file_path option:

  • Use file_path: '@stdout' to write your logs to standard output stream;
  • Use file_path: '@stderr' to write your logs to standard error stream;
  • Use file_path: '@null' to suppress sending of logs;
  • Use file_path: /absolute/path/to/log/file.log to write your logs to file. Use USR1 signal or server::handlers::OnLogRotate to reopen files after log rotation;
  • Use file_path: 'unix:/absolute/path/to/logs.sock' to write your logs to unix socket. Socket must be created before the service starts and closed by listener after service is shut down.

For sending logs directly to an otlp (opentelemetry) sink, see opentelemetry.

Customization of log sinks beyond the ones listed above is not supported at the moment.

Logs format

You can specify in what format logs are written in the format option:

  • Use format: tskv for traditional optimized userver-flavoured TSKV representation. See utils::encoding::TskvParser for the exact format specification;
  • Use format: ltsv for the same format, with : instead of = for key-value separator;
  • Use format: raw for TSKV logs with timestamp and other default tags stripped, useful for custom loggers;
  • Use format: json for JSON logs. logging::JsonString can be used with this format for rich hierarchical log tags;
  • Use format: json_yadeploy for JSON logs with a slightly different structure.

When sending logs using opentelemetry, logs are written to otlp protobuf messages.

Customization of log formats beyond the ones listed above is not supported at the moment.

testsuite-capture options:

Name Description Default value
loggers.<logger-name>.testsuite-capture.host testsuite hostname, e.g. localhost -
loggers.<logger-name>.testsuite-capture.host testsuite port -

Static configuration examples:

Writing logs to stderr:

logging:
fs-task-processor: fs-task-processor
loggers:
default:
file_path: '@stderr'
level: info

Advanced configuration showing options for access logs and a custom opentracing logger:

# yaml
logging:
fs-task-processor: fs-task-processor
loggers:
default:
file_path: $default_log_path
level: $log_level
level#fallback: debug
overflow_behavior: discard
access:
file_path: $access_log_path
overflow_behavior: discard
format: raw
access-tskv:
file_path: $access_tskv_log_path
overflow_behavior: discard
format: raw
tracer:
file_path: '@stdout'
overflow_behavior: discard

Definition at line 97 of file component.hpp.

+ Inheritance diagram for components::Logging:

Public Member Functions

 Logging (const ComponentConfig &, const ComponentContext &)
 The component constructor.
 
logging::LoggerPtr GetLogger (const std::string &name)
 Returns a logger by its name.
 
logging::TextLoggerPtr GetTextLogger (const std::string &name)
 Returns a text logger by its name.
 
void SetLogger (const std::string &name, logging::LoggerPtr logger)
 Sets a logger.
 
logging::LoggerPtr GetLoggerOptional (const std::string &name)
 Returns a logger by its name.
 
void StartSocketLoggingDebug (const std::optional< logging::Level > &log_level)
 
void StopSocketLoggingDebug (const std::optional< logging::Level > &log_level)
 
void OnLogRotate ()
 Reopens log files after rotation.
 
void TryReopenFiles ()
 
void WriteStatistics (utils::statistics::Writer &writer) const
 
virtual ComponentHealth GetComponentHealth () const
 
virtual void OnLoadingCancelled ()
 
virtual void OnAllComponentsLoaded ()
 
virtual void OnAllComponentsAreStopping ()
 

Static Public Member Functions

static yaml_config::Schema GetStaticConfigSchema ()
 

Static Public Attributes

static constexpr std::string_view kName = "logging"
 The default name of components::Logging component.
 

Member Function Documentation

◆ GetComponentHealth()

virtual ComponentHealth components::RawComponentBase::GetComponentHealth ( ) const
inlinevirtualinherited

Reimplemented in components::ComponentBase, and server::handlers::Restart.

Definition at line 49 of file raw_component_base.hpp.

◆ GetLogger()

logging::LoggerPtr components::Logging::GetLogger ( const std::string & name)

Returns a logger by its name.

Parameters
nameName of the logger
Returns
Pointer to the Logger instance
Exceptions
std::runtime_errorif logger with this name is not registered

◆ GetLoggerOptional()

logging::LoggerPtr components::Logging::GetLoggerOptional ( const std::string & name)

Returns a logger by its name.

Parameters
nameName of the logger
Returns
Pointer to the Logger instance, or nullptr if not registered

◆ GetTextLogger()

logging::TextLoggerPtr components::Logging::GetTextLogger ( const std::string & name)

Returns a text logger by its name.

Parameters
nameName of the logger
Returns
Pointer to the Logger instance
Exceptions
std::runtime_errorif logger with this name is not registered
std::runtime_errorif logger is not a text logger

◆ OnAllComponentsAreStopping()

virtual void components::RawComponentBase::OnAllComponentsAreStopping ( )
inlinevirtualinherited

◆ OnAllComponentsLoaded()

virtual void components::RawComponentBase::OnAllComponentsLoaded ( )
inlinevirtualinherited

◆ OnLoadingCancelled()

virtual void components::RawComponentBase::OnLoadingCancelled ( )
inlinevirtualinherited

Reimplemented in components::ComponentBase.

Definition at line 51 of file raw_component_base.hpp.

◆ SetLogger()

void components::Logging::SetLogger ( const std::string & name,
logging::LoggerPtr logger )

Sets a logger.

Parameters
nameName of the logger
loggerLogger to set

The documentation for this class was generated from the following file: