How to re-use existing external Fmt formatters?

[espakm]

Hello Quillers,
I would like to migrate from Boost logging to Quill. I have a "TRACE_FMT" macro that takes a format string and args and passes them down to Boost logging, and there are template specialisations for many custom types, like:

namespace fmt {
template <>
struct formatter<MyCustomType> : ostream_formatter {};
}

that is just like what Quill needs, apart from the namespace, that is "fmt" and not "fmtquill".

It would be tedious to write a new template specialisation for every such class just because of the namespace change, so I tried this:

template <typename T>
struct fmtquill::formatter<T>: fmt::formatter<T>{};

But it does not work.
As I see, it is also not supported to use an external fmt library anymore.
Any suggestion would be welcome, how to solve this.
Thank you

[odygrd]

Hey!

Unfortunately, you need to define the specializations explicitly. As far as I know, C++ doesn't allow defining a generic specialization since the primary template isn't accessible.

You can derive from fmt::formatter, but you'll need to template both parse and format so they work with different Context types. However, if you're deriving from ostream_formatter, this approach won't work since parse isn't templated.

I've put together an example showcasing a few different possibilities. Hope it helps

https://godbolt.org/z/5Wsf5WY6P

[rmanaloto-tastytrade]

I'm kind of in the same boat here.
I just started playing around with this library and it would be a huge win if my existing fmt::formatters just worked out of the box.
I haven't dug too deep into the the quill code yet, but shouldn't there be a way to check if an existing fmt::formatter specialization exists already for my user defined types and use that (with precedence lower than the quil user defined types/codecs)?

Or, what is different in the quill formatters/codecs that makes them incompatible with existing fmt::formatters?

thanks in advance.
-ray

[espakm]

Thank you, @odygrd, hi Ray!

I do not care much about the libfmt version, but having two copies in different namespaces seems redundant and makes the migration cumbersome.
So, since it is not possible to let Quill use an external Fmt any more, I tried to do the opposite, making our current code use the Fmt bundled with Quill.

TLDR; it did not go smoothly, either.

I made a few wrapper headers for fmt, e.g. "fmt/format.h" looks like this:

#pragma once
#include <quill/bundled/fmt/format.h>
#define FMT_STRING FMTQUILL_STRING
namespace fmt = fmtquill;

Unfortunately, because of the namespace declaration, I could not define the formatters in the fmt namespace any more, but rather I had to put the namespace qualifiers everywhere.
E.g.:

namespace fmt {
template <>
struct formatter<MyCustomType> : ostream_formatter {};
}

became:

template <>
struct fmt::formatter<MyCustomType> : fmt::ostream_formatter {};

And also had to define a Codec or wrap the argument into a fmt::format("{}", arg) call.

IMO, a fallback to the "slow path" formatting of custom types and allowing either using an external Fmt (does not need to be backward compatible with ancient versions of Fmt) or if not, at least exposing the internal Fmt (by a macro and having headers in the usual place), would help people migrating to Quill.

[odygrd]

Thanks for the suggestions and ideas! I’ll give it some thought, though it’s not a straightforward change.

The main issue is that the fallback to an external libfmt would need to happen inside libfmt itself, not in the logging library. Heavily modifying the bundled fmt would make future updates more difficult.

We did support external fmt in older versions, but one challenge was that fmt's internal API changes between versions, requiring #ifdef flags to handle different versions. Even if we ignored that and only supported the exact same version as the bundled one, it still wouldn’t be feasible right now. The bundled fmt has minor changes for better backend logging throughput and also requires protected class members in fmt::buffer instead of private.

Even if all of that were addressed, there wouldn’t be much actual benefit—you’d still need to provide the Codec. As mentioned earlier, there’s no need to duplicate the formatter code since you can derive from it, though I understand that’s not the most convenient approach. It’s just an extra two lines near the Codec definition, which you’d need anyway. The best way to think about it is that the logger has its own formatting system rather than being an extension of libfmt.

[espakm]

Thanks for giving an insight into the complexity of all this!

I saw it was supported before 4.0. Maybe the best would be to get some of the required changes into the upstream, e.g. the protected member issue looks simple, I'm sure PR would be welcome, even if it is not re-using fmt as a dependency, at least the codebases converge.

There are too many custom types that I would need to write codecs for, most of which are non-trivially copiable, so I could not make a macro for it. So, I passed fmt::to_string(my_object). (Slightly shorter version of "fmt::format("{}", my_object)" :-) .)

This is what I finally came up with:

template <typename T>
struct ToStringCodec
{
    static size_t compute_encoded_size(quill::detail::SizeCacheVector& conditional_arg_size_cache, T const& arg) noexcept
    {
        return quill::Codec<std::string>::compute_encoded_size(conditional_arg_size_cache, fmt::to_string(arg));
    }

    static void encode(std::byte*& buffer, quill::detail::SizeCacheVector const& conditional_arg_size_cache,
                       uint32_t& conditional_arg_size_cache_index, T const& arg) noexcept
    {
        quill::Codec<std::string>::encode(buffer, conditional_arg_size_cache, conditional_arg_size_cache_index, fmt::to_string(arg));
    }

    static T decode_arg(std::byte*& buffer)
    {
        T arg;
        quill::Codec<std::string>::decode_arg(buffer);
        return arg;
    }

    static void decode_and_store_arg(std::byte*& buffer, quill::DynamicFormatArgStore* args_store)
    {
        quill::Codec<std::string>::decode_and_store_arg(buffer, args_store);
    }
};

With this, I can now make the template specialisations for my custom types:

template <>
struct quill::Codec<MyCustomType> : ToStringCodec<MyCustomType>
{
};

Clearly, this is not as efficient as a "hot path" codec would be, but it compiles and it is functional.

I think that Quill should fall back to a codec like this if fmt is able to convert the object to a string (e.g. the stream operator is defined).

[odygrd]

A bit of history to provide context. Until version v3, the library operated very similarly to what you describe. It supported an external libfmt and did not require a Codec, it would just copy the type via the it's copy constructor.

However, these changes were introduced as improvements, and I believe the additional boilerplate introduced is worth it.

The library performs asynchronous formatting and uses a buffered SPSC queue. When a custom type is passed to be logged, it has to create a binary copy in the SPSC queue pre-allocated buffer. However, C++ lacks introspection, and this introduces potential issues. For example, consider a type like this:

class CustomType {
   std::shared_ptr<A> a; 
};

If we take a binary copy of this object, it’s possible that the a member is modified before the backend can format the value. As a result, an invalid or incorrect value would be logged. To address this, we initially implemented very complex type traits to determine which types were safe to copy or required the user to explicitly tag their type as COPY_LOGGABLE. However, this approach increased compile times, as every single type had to be checked, making it less practical and not worth the cost in the end.

The original implementation used the copy constructor to copy user-defined types to our pre-allocated queue, relying on fmt::formatter without a Codec. However, this introduced another hidden performance cost. Consider this example:

class Vector {
  size_t size;
  size_t capacity;
  int8_t* buffer;
};

Copying this object would copy the three members into the pre-allocated queue, but it would also require allocating heap memory to deep copy the buffer member separately, outside of the pre-allocated queue. This difference in performance is visible here: Logging Complex Types like std::vector. Notably, other libraries like fmtlog do not optimize for this scenario.

To address these issues—primarily the second one—we introduced the concept of a Codec to allow the library to serialize custom types directly into the pre-allocated buffer without any additional heap allocation. Many codecs are already implemented for standard STL types here:
Standard Codecs

With this approach, the second problem, heap allocation for members was resolved, as the Codec allows serialization directly into the pre-allocated buffer. Additionally, it also partially addresses the first problem. Since the user provides the Codec and defines how their custom type is serialized, the need for extra tagging (e.g., COPY_LOGGABLE) is eliminated.

As for the removal of external fmt, this was done to further improve both compile times and throughput. I ended up re-implementing parts of fmtlib to achieve this, but with fewer include dependencies and members. For instance DynamicFormatArgStore in quill and fmtlib/args.h

As you correctly noted, an alternative would be to convert custom types to strings before encoding. Adding a Codec for this, as you suggested, is indeed the right idea.

Previously, I provided a similar Codec in another request. You can find it here:
Example Codec on Godbolt

This example uses fmtquill::format_to_n to directly encode/format in the SPSC queue buffer.

I’m considering including this StringcConvertibleCodec in the master branch so that users don’t need to implement it themselves. I can’t recall why it wasn’t included initially, but I’ll investigate further. While I’m not sure yet if it should be enabled as a fallback, I believe allowing users to explicitly enable it would be a good compromise.

[espakm]

Thanks for the detailed explanation and the code!

I replaced my codec with your one. I think it would help others if it was part of the project. Whether there is a fallback to it or not, is secondary. (((I think, it helps at the first encountering with the library when things work out of the box, writing a custom codec is an important optimisation, but not making it should not break the build. But up to you, of course. :-) )))

There is also a std::convertible_to<From, To> concept in C++20, maybe there could be a codec for types that match this concept.

https://en.cppreference.com/w/cpp/concepts/convertible_to

So, there could be two types, StringConvertibleCodec and OstreamConvertibleCodec.

I have the very same problem at a different part of the project, not logging, but collecting data into a file, and the data needs to be converted before writing. This now happens in the producer thread, and when I tried to move it to the consumer thread, it crashed because enqueued data has been destructed in the meantime. Taking a binary copy is one way of dealing with this, but what I thought instead, would be to flush the data queue before the life of the enqueued data is over. That would be even faster, as the data would not need to be copied at all. In my very specific scenario this should work, but maybe a generic solution in Quill would do too many flushes. I thought to mention it, though.

My other thought is reflection, that will come with C++26, but most compilers support much of it already, just it needs to be enabled by a flag.

[odygrd]

Hey,

Support for logging user-defined types has been improved—thanks for the motivation!

You can check out v8.2.0 here:
CHANGELOG.md#v820

I decided not to offer operator<< codec support. While we likely wouldn’t face the same issues as fmtlib/fmt#2357, I didn’t want to take the risk. It’s also slower than fmt::formatter, and users have the flexibility to provide their own codec with it if needed.

That said, operator<< can still be enabled explicitly:

template <>
struct fmtquill::formatter<UserType> : fmtquill::ostream_formatter {};

I’m not sure when the next release will be, but main branch is always ready to use.