fastly::log Namespace Reference

Classes
class	Endpoint
class	LoggerBuilder

Typedefs
using	LogLevel = fastly::sys::log::LogLevel
using	LogLevelFilter = fastly::sys::log::LogLevelFilter

Functions
template<typename... Args>
void	error (std::format_string< Args... > fmt, Args &&...args)
template<typename... Args>
void	error_to (std::string_view dest, std::format_string< Args... > fmt, Args &&...args)
template<typename... Args>
void	warn (std::format_string< Args... > fmt, Args &&...args)
template<typename... Args>
void	warn_to (std::string_view dest, std::format_string< Args... > fmt, Args &&...args)
template<typename... Args>
void	info (std::format_string< Args... > fmt, Args &&...args)
template<typename... Args>
void	info_to (std::string_view dest, std::format_string< Args... > fmt, Args &&...args)
template<typename... Args>
void	debug (std::format_string< Args... > fmt, Args &&...args)
template<typename... Args>
void	debug_to (std::string_view dest, std::format_string< Args... > fmt, Args &&...args)
template<typename... Args>
void	trace (std::format_string< Args... > fmt, Args &&...args)
template<typename... Args>
void	trace_to (std::string_view dest, std::format_string< Args... > fmt, Args &&...args)
void	set_max_level (LogLevelFilter level)
	Set the global maximum log level.
LogLevelFilter	max_level ()
void	init_simple (Endpoint endpoint, LogLevelFilter level)
void	init_simple (std::string_view endpoint, LogLevelFilter level)
void	init_simple (Endpoint endpoint)
void	init_simple (std::string_view endpoint)

Detailed Description

Logger implementation for Fastly Compute.

With this logger configured, the various log statements, like fastly::log::error(), fastly::log::debug(), etc will send log messages to your chosen Real-Time Log Streaming endpoints. You should initialize the logger as soon as your program starts. Logging statements will not do anything before initialization.

See the Fastly documentation for more information about configuring logging endpoints for your service.

Getting started

All you need to get started is your endpoint name and the level of log messages you want to emit. For example, if you have an endpoint called my_endpoint, and you only want to emit log messages at the LogLevel::Warn or LogLevel::Error level, you can use fastly::log::init_simple():

fastly::log::init_simple("my_endpoint", fastly::log::LogLevelFilter::Warn);
fastly::log::warn("This will be written to my_endpoint...");
fastly::log::info("...but this won't");

Advanced configuration

For more precise control, including multiple endpoints and default endpoints for different logging levels, use the LoggerBuilder interface. The first example is equivalent to:

fastly::log::LoggerBuilder()
    .max_level(fastly::log::LogLevelFilter::Warn)
    .default_endpoint("my_endpoint")
    .init();

The LoggerBuilder::max_level() option sets the most verbose level of logging that will be emitted. Logging statements above that level, like info() in the first example, will do nothing.

Note: The default level is LevelFilter::Off, which emits no logging at all. You'll want to change this for most configurations.

LoggerBuilder::default_endpoint() sets the endpoint used whenever a plain logging statement is called (the ones not suffixed with _to) to specify its endpoint. With the default endpoint set to my_endpoint, the logging statements in the first example are equivalent to:

fastly::log::warn_to(
  "my_endpoint",
  "This will be written to my_endpoint..."
);
fastly::log::info_to("my_endpoint", "...but this won't");

Use with Compute Log Tailing

Compute Log Tailing is helpful for getting debugging output quickly from a Compute program under development by capturing output from stdout or stderr. To configure logging to output to stdout or stderr in addition to the specified log endpoint, enable echoing when building the logger:

fastly::log::LoggerBuilder()
    .max_level(fastly::log::LogLevelFilter::Warn)
    .default_endpoint("my_endpoint")
    .echo_stdout(true)
    .init();

Multiple endpoints

Setting an endpoint as the default will automatically register it for use with the logger, but you can register additional endpoints with LoggerBuilder::endpoint():

fastly::log::LoggerBuilder()
    .max_level(log::LogLevelFilter::Warn)
    .default_endpoint("my_endpoint")
    .endpoint("my_other_endpoint")
    .init();
log::warn_to("my_endpoint", "This will be written to my_endpoint...");
log::warn_to(
  "my_other_endpoint",
  "...but this will be written to my_other_endpoint"
);

Per-endpoint logging levels

You can also set a per-endpoint logging level, though levels higher than max_level are always ignored:

fastly::log::LoggerBuilder()
    .max_level(log::LogLevelFilter::Warn)
    .default_endpoint("my_endpoint")
    .endpoint_level("my_other_endpoint", fastly::log::LogLevelFilter::Trace)
    .endpoint_level("error_only", fastly::log::LogLevelFilter::Error)
    .init();
fastly::log::warn_to(
  "my_other_endpoint",
  "This will be written to my_other_endpoint..."
);
fastly::log::trace_to(
  "my_other_endpoint",
  "...but this won't, because max_level wins"
);
fastly::log::error_to(
  "error_only",
  "This will be written to error_only..."
);
fastly::log::warn_to(
  "error_only",
  "...but this won't, because the endpoint's level is lower"
);

Per-level default endpoints

In the previous examples, the same endpoint is set as the default for all logging levels. You can also specify default endpoints for individual levels using LoggerBuilder::default_level_endpoint(). The defaults are combined in order, so you can specify an overall default endpoint, and then as many level-specific endpoints as you need:

fastly::log::LoggerBuilder()
    .max_level(log::LogLevelFilter::Info)
    .default_endpoint("my_endpoint")
    .default_level_endpoint("error_only", fastly::log::Level::Error)
    .init();
fastly::log::info("This will be written to my_endpoint...");
fastly::log::warn(".. and this will too.");
fastly::log::error("But this will be written to error_only");

Registering endpoints

All endpoints used by your logging statements must be registered when the logger is created. The following functions automatically register an endpoint if it is not already registered.

• init_simple()
• LoggerBuilder::endpoint()
• LoggerBuilder::endpoint_level()
• LoggerBuilder::default_endpoint()
• LoggerBuilder::default_level_endpoint()

You can pass the endpoint name as an std::string_view-able, or an explicit fastly::log::Endpoint value. The following examples are equivalent:

fastly::log::init_simple("my_endpoint", fastly::log::LogLevelFilter::Info);

fastly::log::init_simple(
    fastly::log::Endpoint::from_name("my_endpoint").value(),
    fastly::log::LogLevelFilter::Info,
);

If a logging statement uses one of the _to-suffixed versions with "my_endpoint" but my_endpoint is not registered, the message will be logged to the default endpoint for that level, if one exists.

Typedef Documentation

LogLevel

using fastly::log::LogLevel = fastly::sys::log::LogLevel

LogLevelFilter

using fastly::log::LogLevelFilter = fastly::sys::log::LogLevelFilter

Function Documentation

debug()

template<typename... Args>

void fastly::log::debug	(	std::format_string< Args... >	fmt,
		Args &&...	args )

Send a Debug-level message to the configured default endpoint. Supports C++20 format strings.

Logging must be initialized in order for this to do anything. See init_simple() and LoggerBuilder for more information.

Example

fastly::log::init_simple("my_log_endpoint");
fastly::log::debug("my name is {}", user->name());

debug_to()

template<typename... Args>

void fastly::log::debug_to	(	std::string_view	dest,
		std::format_string< Args... >	fmt,
		Args &&...	args )

Send a Debug-level message to a specified configured endpoint. Supports C++20 format strings.

Logging must be initialized in order for this to do anything. See init_simple() and LoggerBuilder for more information.

Example

fastly::log::LoggerBuilder()
    .default_endpoint("my_default_logs")
    .endpoint("my_other_endpoint")
    .init();
fastly::log::debug("Whoops");
fastly::log::debug_to("my_other_endpoint", "my name is {}", user->name());

error()

template<typename... Args>

void fastly::log::error	(	std::format_string< Args... >	fmt,
		Args &&...	args )

Send an Error-level message to the configured default endpoint. Supports C++20 format strings.

Logging must be initialized in order for this to do anything. See init_simple() and LoggerBuilder for more information.

Example

fastly::log::init_simple("my_log_endpoint");
fastly::log::error("my name is {}", user->name());

Examples

esi.cpp.

error_to()

template<typename... Args>

void fastly::log::error_to	(	std::string_view	dest,
		std::format_string< Args... >	fmt,
		Args &&...	args )

Send an Error-level message to a specified configured endpoint. Supports C++20 format strings.

Logging must be initialized in order for this to do anything. See init_simple() and LoggerBuilder for more information.

Example

fastly::log::LoggerBuilder()
    .default_endpoint("my_default_logs")
    .endpoint("my_other_endpoint")
    .init();
fastly::log::error("Whoops");
fastly::log::error_to("my_other_endpoint", "my name is {}", user->name());

info()

template<typename... Args>

void fastly::log::info	(	std::format_string< Args... >	fmt,
		Args &&...	args )

Send an Info-level message to the configured default endpoint. Supports C++20 format strings.

Logging must be initialized in order for this to do anything. See init_simple() and LoggerBuilder for more information.

Example

fastly::log::init_simple("my_log_endpoint");
fastly::log::info("my name is {}", user->name());

Examples

async_reqs.cpp, and echo.cpp.

info_to()

template<typename... Args>

void fastly::log::info_to	(	std::string_view	dest,
		std::format_string< Args... >	fmt,
		Args &&...	args )

Send an Info-level message to a specified configured endpoint. Supports C++20 format strings.

Logging must be initialized in order for this to do anything. See init_simple() and LoggerBuilder for more information.

Example

fastly::log::LoggerBuilder()
    .default_endpoint("my_default_logs")
    .endpoint("my_other_endpoint")
    .init();
fastly::log::info("Whoops");
fastly::log::info_to("my_other_endpoint", "my name is {}", user->name());

init_simple() [1/4]

void fastly::log::init_simple

(

Endpoint

endpoint

)

init_simple() [2/4]

void fastly::log::init_simple	(	Endpoint	endpoint,
		LogLevelFilter	level )

Initialize logging with a single endpoint filtered by log level.

For advanced configuration, see the LoggerBuilder class, and the module-level documentation.

fastly::log::init_simple("my_endpoint", fastly::log::LogLevelFilter::Warn);
fastly::log::warn("This will be written to my_endpoint...");
fastly::log::info("...but this won't");

Examples

async_reqs.cpp, config_store.cpp, echo.cpp, esi.cpp, and ngwaf_inspect.cpp.

init_simple() [3/4]

void fastly::log::init_simple

(

std::string_view

endpoint

)

init_simple() [4/4]

void fastly::log::init_simple	(	std::string_view	endpoint,
		LogLevelFilter	level )

max_level()

LogLevelFilter fastly::log::max_level

(

)

Returns the current maximum log level.

The maximum log level is set by the set_max_level() function.

set_max_level()

void fastly::log::set_max_level

(

LogLevelFilter

level

)

Set the global maximum log level.

trace()

template<typename... Args>

void fastly::log::trace	(	std::format_string< Args... >	fmt,
		Args &&...	args )

Send a Trace-level message to the configured default endpoint. Supports C++20 format strings.

Logging must be initialized in order for this to do anything. See init_simple() and LoggerBuilder for more information.

Example

fastly::log::init_simple("my_log_endpoint");
fastly::log::trace("my name is {}", user->name());

trace_to()

template<typename... Args>

void fastly::log::trace_to	(	std::string_view	dest,
		std::format_string< Args... >	fmt,
		Args &&...	args )

Send a Trace-level message to a specified configured endpoint. Supports C++20 format strings.

Logging must be initialized in order for this to do anything. See init_simple() and LoggerBuilder for more information.

Example

fastly::log::LoggerBuilder()
    .default_endpoint("my_default_logs")
    .endpoint("my_other_endpoint")
    .init();
fastly::log::trace("Whoops");
fastly::log::trace_to("my_other_endpoint", "my name is {}", user->name());

warn()

template<typename... Args>

void fastly::log::warn	(	std::format_string< Args... >	fmt,
		Args &&...	args )

Send a Warn-level message to the configured default endpoint. Supports C++20 format strings.

Logging must be initialized in order for this to do anything. See init_simple() and LoggerBuilder for more information.

Example

fastly::log::init_simple("my_log_endpoint");
fastly::log::warn("my name is {}", user->name());

warn_to()

template<typename... Args>

void fastly::log::warn_to	(	std::string_view	dest,
		std::format_string< Args... >	fmt,
		Args &&...	args )

Send a Warn-level message to a specified configured endpoint. Supports C++20 format strings.

Logging must be initialized in order for this to do anything. See init_simple() and LoggerBuilder for more information.

Example

fastly::log::LoggerBuilder()
    .default_endpoint("my_default_logs")
    .endpoint("my_other_endpoint")
    .init();
fastly::log::warn("Whoops");
fastly::log::warn_to("my_other_endpoint", "my name is {}", user->name());