alogfmt

Implements an encoder for logfmt using serde.

To use, add the following the [dependencies] table in your Cargo.toml.

alogfmt = "^0.1.0"

Usage

The primary interface of this package consists of the to_string, to_bytes, and to_writer functions. These functions can be used to serialize logfmt-encoded structures to a String, Vec<u8>, and an io::Write respectively.

use alogfmt::{to_string, to_bytes, to_writer};
use anyhow::Result;
use serde::Serialize;

#[derive(Serialize)]
struct MyStruct {
    pub ts: u64,
    pub message: String,
}

fn main() -> Result<()> {
    let s = MyStruct{
        ts: 1690232215,
        message: String::from("Hello World!"),
    };

    let lf = to_string(&s)?;

    assert_eq!(
        lf,
        r#"ts=1690232215 message="Hello World!""#
    );

    Ok(())
}

The Serializer implementation is also exported. It wraps an io::Write and can be used in a similar manner to to_writer. The Serializer is not particularly expensive to construct, so calling to_writer should be fine normally. If you'd like to re-use the Serializer, you must call serializer.reset() or serializer.next() to reset the serializer's internal state such that it is ready for the next document.

use alogfmt::Serializer;
use anyhow::Result;
use serde::Serialize;

#[derive(Serialize)]
struct MyStruct {
    pub ts: u64,
    pub message: String,
}

fn main() -> Result<()> {
    let s = MyStruct{
        ts: 1690232215,
        message: String::from("Hello World!"),
    };

    let mut serializer = Serializer::new(Vec::new());

    for i in 0..3 {
        s.serialize(&mut serializer)?;
        serializer.next()?;
    }

    // take back the io::Write so we can check the results
    let result = unsafe {
        // The serializer should only ever produce valid utf8, so
        // we can use from_utf8_unchecked to avoid the overhead of
        // checking if the vector is UTF-8 encoded, though the safe
        // from_utf8 would work just as well.
        String::from_utf8_unchecked(serializer.writer())
    };

    assert_eq!(
        result,
        "ts=1690232215 message=\"Hello World!\"\nts=1690232215 message=\"Hello World!\"\nts=1690232215 message=\"Hello World!\"\n"
    );

    Ok(())
}

License

    Copyright (C) 2023 Aurora McGinnis

    This Source Code Form is subject to the terms of the Mozilla Public
    License, v. 2.0. If a copy of the MPL was not distributed with this
    file, You can obtain one at http://mozilla.org/MPL/2.0/.