syslog-rs

A syslog client Rust crate which supports most commonly used RFC message formatters, Local and Remote server connections and both sync and async interfaces.

Attention! V5.0.0 was rejected, and in V6.0.0 the API is stabilized.

Dual licensed crate.

• This crate i.e code is NOT an Open Source software. This is a FREE software and follows the principle of Sources Available/Disclosed software which must be fairly used.
• It is published under FSF/OSI approved licenses however author does not follow/share/respect OSI and FSF principles and phylosophy.
• License is subject to be changed in further versions without warning.
• If you are using code in non-free (in terms of gratis) software you MUST NEVER demand a development of any features which are missing and needed for your business if you are not sponsoring/contributing those changes.
• Access to the code can be limited by author/platform to specific entities due to the local laws (not my bad or fault)(despite what is said in the license).

• AI generated sloppy code is prohibited. AI generates slop "a priori" (anyway).
• Licenses (thank you OSS sectarians ) do not anyhow limit AI training, but f^ck you all - ChatGPT, CockPilot, especially Claude and rest unidentified cr@p.
• It is strongly discouraged from using the AI based tools to write or enhance the code. AI slope would 100% violate the license by introducing the 3rd party licensed code.

The pull requests are now supported because the repository was moved to Codeberg. The alternative way is to send patches over the email to patch[at]4neko.org.

In case if you would like to contribute the code, please use pull request. Your pull request should include:

• Description of changes and why it is needed.

• Test the pull request.

  In case of you prefer email and patch files please consider the following:

• For each feature or fix, please send patches separatly.

• Please write what your patch is implementing or fixing.

• I can read the code and I am able to understand it, so don't write a poem or essay in the description to the patches.

• Please test your patch.

• Can I use the MPL-2.0 licensed code (crate) in larger project licensed with more permissive license like BSD or MIT.

I want to distribute (outside my organization) executable programs or libraries that I have compiled from someone else's unchanged MPL-licensed source code, either standalone or part of a larger work. What do I have to do?

You must inform the recipients where they can get the source for the MPLed code in the executable program or library you are distributing (i.e., you must comply with Section 3.2). You may distribute any executables you create under a license of your choosing, as long as that license does not interfere with the recipients' rights to the source under the terms of the MPL.

MPL2.0 FAQ

Yes, MPL- and Apache-licensed code can be used with an MIT codebase (so in that sense, they are "compatible"). However, the MPL- / Apache-licensed code remains under its original license. (So although compatible, you cannot relicense someone else's MPL or Apache code into the MIT license.) This means that your final codebase will contain a mix of MPL, Apache, and MIT licensed code. As an example, MPL has weak copyleft, so if you modified an MPL file, that file (including your changes) must remain under the MPL license.

Answer1

You should use this license if you are located in the EU which gives you more advantages over GPL because in case of any disputes, the license allows you to defend your rights in a European Union country, in this case it will be Spain. It has also been translated into all languages of the EU member states.

Matrix of EUPL compatible open source licences

EUPL-1.2 is incompatiable with GPL according to GNU ORG

This is a free software license. By itself, it has a copyleft comparable to the GPL's, and incompatible with it.

Version

v 6.2.0

Attention! Previous version 5.0.0 was rejected. In version v6.0.0 the crate's API is stabilized and should not change.

• License updated. By default a MPL-2.0 is selected. If it is required to use another type, specify it somewhere i.e in the cargo.toml using comments.
• Updated crate bitfields to version 2.

• The instance-copy-on-write crate was updated. The CoW is selected to use the RwLock, because the atomic based locks are still under testing.
• Added new tests.
• Added new error codes.

• Added more comments.
• Improved syslog_5424.rs sequence number assign and added conditional comilation to fallback to mutex if Atomics are not available.
• Fixed the SyslogFormatted structure and trait SyslogFormatter. CoW is no longer used. vsyslog1_format is now borrowing the progname and pid.

• The syslog.rs was removed due to redundancy.
• Now the SyslogShared (v4.0.0) is SyncSyslog.
• Now the SyslogQueue (v4.0.0) is QueuedSyslog.
• Now the SyslogThreadLocal (v5.0.0) is SingleSyslog.
• The StreamableSyslog is now SyStream and StreamableSyslogApi is now SyStreamApi.

• The syslog (sync) API was updated once again. Now the main SYSLOG instance is Syslog<>.
• The SyslogSync (previously SyslogShared) is no logner using mutex, but experimental CoW crate which should allow to perfrom the log sending without blocking mutex.
• The SyslogQueueThread (previously SyslogQueue) changed, but nothing has changed dramatically.
• Added thread local syslog in syslog_threadlocal.rs, structure SyslogThreadLocal.
• get_max_msg_size() in the SyslogTap is no longer requires self.
• The formatters trait SyslogFormatter function vsyslog1_format no longer provides the tap data.

License:

Sources are available under: MPL-2.0 OR EUPL-1.2

Issues tracker:

The project has moved to Codeberg.

Description

An implementation of the syslog from glibc/libc like it was designed in in both system libraries. The API is almost compatible with what is in libc/glibc. Supports both sync and async and custom formatters.

• GNU/Linux RFC3164 (UTF-8 by default)
• *BSD and OSX RFC5424 (BOM UTF-8 by default) (including msgid and parametes).
• Tokio async
• Smol async
• TLS over TCP syslog server connection
• TCP/UDP syslog server connection
• Local file writer

Available features:

• feature = use_sync enables the sync syslog SyncSyslog and all sync functionality.
• feature = build_with_thread_local enables the lockless syslog client SingleSyslog for single threaded or thread_local instances.
• feature = build_async_tokio or build_async_smol for asynchronious execution. Enables AsyncSyslog. Cannot be used together.
• feature = build_async_interface an experimental feature which allowes to implement async for some unsupported executor. See /docs/ for info. Can not be used together with build_async_tokio or build_async_smol.
• feature = build_with_queue autmaticallly enables use_sync as dependancy. It also enables the QueuedSyslog. When used in combination with one of the build_async_tokio or build_async_smol, can be used to write to syslog server from both sync and async code using single connection to syslog server.
• feature = build_with_net enables the TCP/UDP
• feature = build_ext_tls enables the TLS over TCP support.
• feature = build_ext_file enables the local logging to file (without syslog server).

The use_sync is acting like the libc's/glibc's functions syslog(), openlog()...

There are two types of syslog client:

• SyncSyslog - a single syslog instance which is shared between the threads. A CoW is used for simultanious access control.
• QueuedSyslog - a signle syslog instance which is shared between the threads using MPSC channels. A worker thread is allocated to receive messages from other threads and forward mwssages to syslog server.
• SingleSyslog - a single thread syslog which is not Send and not Sync. Can be used with thread_local.

The use_sync_queue has the same API as libc/glibc but it is different in some ways. It spawns a worker thread which forwards messages from the queue (channel) to syslog server. If used with async can act as a sync/async interfacing by providing the interface to attach the async syslog instance to the sync queue and use a signle channel to syslog server.

┌───────────────────────────────────────────────────────────────────┐
│build_with_queue                                                   │
│                                                                   │
│       build_sync                                                  │
│       ┌────────────┐    ┌───────────┐                             │
│       │ SYNC_QUEUE ┼────► CROSSBEAM ┼────────────────┐            │
│       └────────────┘    │  adapter  │                │            │
│                         └───────────┘                │            │
│                                                      │            │
│       build_async_tokio                  ┌───────────▼───────────┐│
│       ┌────────────┐   ┌────────────┐    │                       ││
│  ┌────► SYNC_QUEUE ┼───► TOKIO MPSC ┼────►  SYSLOG_WORKER THREAD ││
│  │    └────────────┘   │   adapter  │    │                       ││
│  │                     └────────────┘    └───────────▲────▲──────┘│
│  │                                                   │    │       │
│  │    build_async_smol ┌────────────┐                │    │       │
│  │    ┌────────────┐   │ SMOL MPSC  │                │    │       │
│  ├────► SYNC_QUEUE ┼───►   adapter  ┼────────────────┘    │       │
│  │    └────────────┘   └────────────┘                     │       │
│  │                                                        │       │
│  │                                                        │       │
│  │    build_async_interface                               │       │
│  │    ┌────────────┐   ┌────────────┐                     │       │
│  ┼────► SYNC_QUEUE ┼───► EXT MPSC   ┼─────────────────────┘       │
│  │    └────────────┘   │  adapter   │                             │
│  │                     └────────────┘                             │
│  │  ┌──────────────────────┐                                      │
│  └──┼  AsyncSyslogQueueApi │                                      │
│     │       trait          │                                      │
│     └──────────────────────┘                                      │
└───────────────────────────────────────────────────────────────────┘                                           

A AsyncSyslog is the only client option which is available. But, the sync QueuedSyslog supports the async API if use_async_* is enabled.

Available tunables:

• feature = udp_truncate_1024_bytes
• feature = udp_truncate_1440_bytes DEFAULT

The above is for RFC5424 which controls the syslog message length for forwarding via UDP protocol.

• feature = tcp_truncate_1024_bytes

• feature = tcp_truncate_2048_bytes DEFAULT

• feature = tcp_truncate_4096_bytes

• feature = tcp_truncate_max_bytes

• feature = truncate_default - a shortcut for udp_truncate_1440_bytes and tcp_truncate_2048_bytes

The above is for RFC5424 which controls the syslog message length for forwarding via TCP protocol.

• feature = dgram_sysctl_failure_panic

The above is for *BSD systems only and controls the behaviour of the sysctl error handling. If this is enabled, the crate will panic is access to sysctl fails. Not enabled by default.

Usage:

For default syslog-rs = "6.1"

For customization: syslog-rs = {version = "6.1", default-features = false, features = ["use_sync", "truncate_default"]}

Contributors

Ordered by Relkom s.r.o (c) 2021

Developed by: Aleksandr Morozov

Examples

See ./examples/ in the repository.

use std::{sync::LazyLock, thread};
use std::time::Duration;

use syslog_rs::formatters::DefaultSyslogFormatter;
use syslog_rs::{SyslogApi, SyncSyslog};
use syslog_rs::{LogFacility, LogStat, Priority, SyslogLocal};

pub static SYSLOG: LazyLock<SyncSyslog> = LazyLock::new(|| 
    {
        SyncSyslog::openlog(
            Some("example"), 
            LogStat::LOG_CONS | LogStat::LOG_PID, 
            LogFacility::LOG_DAEMON, SyslogLocal::new()
        )
        .unwrap()
    }
);

pub static SYSLOG2: LazyLock<SyncSyslog<DefaultSyslogFormatter, SyslogLocal>> = LazyLock::new(|| 
    {
        SyncSyslog
            ::<_, _>
            ::openlog_with(
            None, 
            LogStat::LOG_CONS | LogStat::LOG_NDELAY | LogStat::LOG_PID, 
            LogFacility::LOG_DAEMON, SyslogLocal::new()
        )
        .unwrap()
    }
);

pub static SYSLOG3: LazyLock<SyncSyslog<DefaultSyslogFormatter, SyslogLocal>> = LazyLock::new(|| 
    {
        SyncSyslog
            ::<_, _>
            ::openlog_with(
                None, 
                LogStat::LOG_CONS | LogStat::LOG_NDELAY | LogStat::LOG_PID, 
                LogFacility::LOG_DAEMON, SyslogLocal::new()
            )
            .unwrap()
    }
);

macro_rules! logdebug 
{
    ($($arg:tt)*) => (
        SYSLOG.syslog(Priority::LOG_DEBUG, format!($($arg)*).into())
    )
}

macro_rules! logdebug2 
{
    ($($arg:tt)*) => (
        SYSLOG2.syslog(Priority::LOG_DEBUG, format!($($arg)*).into())
    )
}

pub fn main()
{
    logdebug2!("test program name!");

    
    logdebug!("test message1!");

    SYSLOG.change_identity(Some("example2")).unwrap();

    logdebug!("test message from new ident");

    let new_syslog = 
        SyncSyslog
            ::<DefaultSyslogFormatter, SyslogLocal>
            ::openlog_with(
                None, 
                LogStat::LOG_CONS | LogStat::LOG_NDELAY | LogStat::LOG_PID, 
                LogFacility::LOG_DAEMON, SyslogLocal::new()
            )
            .unwrap();

    let c_new_syslog = new_syslog.clone();
    let thread_hndl = 
        std::thread::spawn(move || 
            {
                logdebug!("message from thread 1");
                std::thread::sleep(Duration::from_nanos(1000));
                logdebug!("message from thread 2");
                std::thread::sleep(Duration::from_nanos(1000));
                logdebug!("message from thread 3");
                std::thread::sleep(Duration::from_nanos(1000));
                logdebug!("message from thread 4");

                c_new_syslog.syslog(Priority::LOG_DEBUG, "test".into());
            }
        );

    let _ = thread_hndl.join();

    logdebug!("joined");
    thread::sleep(Duration::from_micros(10));

    return;
}

use syslog_rs::sy_async::AsyncSyslog;
use tokio::sync::OnceCell;
use tokio::time::{sleep, Duration};

use syslog_rs::{LogFacility, LogStat, Priority, SyslogLocal};


pub static SYSLOG: OnceCell<AsyncSyslog> = OnceCell::const_new();

macro_rules! logdebug 
{
    ($($arg:tt)*) => (
        SYSLOG.get().unwrap().syslog(Priority::LOG_DEBUG, format!($($arg)*)).await
    )
}

#[tokio::main]
async fn main()
{
    let syslog =
        AsyncSyslog::openlog(
                Some("example_async"), 
                LogStat::LOG_CONS | LogStat::LOG_NDELAY | LogStat::LOG_PID, 
                LogFacility::LOG_DAEMON,
                SyslogLocal::new()
            )
            .await
            .unwrap();


    SYSLOG.get_or_init(|| async { syslog }).await;


    logdebug!("test message async start!");
    
    SYSLOG.get().unwrap().vsyslog(Priority::LOG_DEBUG, "test 21").await;

    sleep(Duration::from_micros(10)).await;

    SYSLOG.get().unwrap().change_identity("new_identity").await;

    logdebug!("test message new identity!");

    sleep(Duration::from_micros(10)).await;

    logdebug!("test 123!");
    logdebug!("test 123123! end ");

    return;
}

This exampel requires the feature build_with_thread_local to be enabled.

use std::{cell::RefCell, thread, time::Duration};

use syslog_rs::{formatters::DefaultSyslogFormatter, LogFacility, LogStat, Priority, SyslogApi, SyslogLocal, SingleSyslog};

thread_local! 
{
    // Could add pub to make it public to whatever Foo already is public to.
    static SYSLOG: RefCell<SingleSyslog<DefaultSyslogFormatter, SyslogLocal>> = 
        RefCell::new(
            SingleSyslog
                ::<_, _>
                ::openlog_with(Some("test"), LogStat::LOG_PID, LogFacility::LOG_DAEMON, SyslogLocal::new())
                    .unwrap()
        );
}

pub fn main()
{
  
    SYSLOG
        .with_borrow(|b| 
            b.syslog(Priority::LOG_DEBUG, "start".into())
        );

    let thread_hndl = 
        std::thread::spawn(move || 
            {
                SYSLOG
                    .with_borrow(|b| 
                        b.syslog(Priority::LOG_DEBUG, "start thread".into())
                    );

                SYSLOG
                    .with_borrow(|b| 
                        b.change_identity(Some("thread1"))
                    )
                    .unwrap();

                SYSLOG
                    .with_borrow(|b| 
                        b.syslog(Priority::LOG_DEBUG, "end thread new identity".into())
                    );
            }
        );

    let _ = thread_hndl.join();

    SYSLOG
        .with_borrow(|b| 
            b.syslog(Priority::LOG_DEBUG, "end".into())
        );

    thread::sleep(Duration::from_micros(10));

    return;
}

use std::sync::OnceLock;
use std::thread;
use std::time::Duration;

use chrono::{Local, SecondsFormat};

use syslog_rs::{SyncSyslog, SyslogApi};
use syslog_rs::{SyslogFile, NEXTLINE, WSPACE};
use syslog_rs::{common, formatters::{SyslogFormatted, SyslogFormatter}};

use syslog_rs::{LogStat, LogFacility, Priority};

pub static SYNC_SYSLOG: OnceLock<SyncSyslog<MyFormatter, SyslogFile>> = OnceLock::new();

macro_rules! logdebug 
{
    ($($arg:tt)*) => (
        SYNC_SYSLOG.get().unwrap().syslog(Priority::LOG_DEBUG, format!($($arg)*).into());
    )
}

#[derive(Debug, Clone)]
pub struct MyFormatter(String);

unsafe impl Send for MyFormatter {}

impl From<String> for MyFormatter
{
    fn from(value: String) -> MyFormatter 
    {
        return Self(value);
    }
}

impl From<&'static str> for MyFormatter
{
    fn from(value: &'static str) -> MyFormatter
    {
        return Self(value.to_string());
    }
}

impl SyslogFormatter for MyFormatter
{
    fn vsyslog1_format(&self, _max_msg_size: usize, pri: Priority, progname: &str, pid: &str) -> SyslogFormatted
    {
        let timedate = Local::now().to_rfc3339_opts(SecondsFormat::Secs, false);

        let msg_payload_final = 
            if self.0.ends_with("\n") == true
            {
                common::truncate(&self.0)
            }
            else
            {
                &self.0
            };

        let msg_header = 
            pri.to_string();
           
        let msg_pkt = 
            [
                WSPACE, "MYFORMATTER",
                WSPACE, timedate.as_str(), 
                WSPACE, progname,
                WSPACE, pid,
                WSPACE, msg_payload_final, NEXTLINE
            ]
            .concat();


        return 
            SyslogFormatted::new( Some(msg_header),  msg_pkt );
    }
}

pub fn main()
{
    let syslog = 
        SyncSyslog
            ::<MyFormatter, SyslogFile>
            ::openlog_with(
            Some("example"), 
            LogStat::LOG_CONS | LogStat::LOG_NDELAY | LogStat::LOG_PID, 
            LogFacility::LOG_DAEMON,
            SyslogFile::new("/tmp/myformatter.log")
        ).unwrap();

    SYNC_SYSLOG.get_or_init(|| syslog);

    logdebug!("test message!");

    SYNC_SYSLOG.get().unwrap().change_identity(Some("another")).unwrap();

    logdebug!("test message new!");

    thread::sleep(Duration::from_micros(10));

    return;
}

use std::sync::OnceLock;
use std::thread;
use std::time::Duration;

use syslog_rs::{SyncSyslog, SyslogApi};

#[cfg(target_os = "linux")]
use syslog_rs::{formatters::FormatRfc3146, SyslogLocal};

#[cfg(not(target_os = "linux"))]
use syslog_rs::{formatters::{FormatRfc5424}, SyslogLocal};

use syslog_rs::{LogStat, LogFacility, Priority};

#[cfg(target_os = "linux")]
pub static SYNC_SYSLOG: OnceLock<SyncSyslog<FormatRfc3146, SyslogLocal>> = OnceLock::new();
#[cfg(not(target_os = "linux"))]
pub static SYNC_SYSLOG: OnceLock<SyncSyslog<FormatRfc5424, SyslogLocal>> = OnceLock::new();

macro_rules! logdebug 
{
    ($($arg:tt)*) => (
        SYNC_SYSLOG.get().unwrap().syslog(Priority::LOG_DEBUG, format!($($arg)*).into());
    )
}

pub fn main()
{
    let syslog = 
        SyncSyslog
            ::<_, _>
            ::openlog_with(
                Some("formatter_sel"), 
                LogStat::LOG_CONS | LogStat::LOG_NDELAY | LogStat::LOG_PID, 
                LogFacility::LOG_DAEMON,
                SyslogLocal::new()
            ).unwrap();

    SYNC_SYSLOG.get_or_init(|| syslog);

    logdebug!("test message!");

    thread::sleep(Duration::from_micros(10));

    return;
}

Either build_async_tokio or build_async_smol and build_with_queue should be enabled. Example below requires also feature build_ext_file to be enabled.

use std::sync::OnceLock;
use std::thread;
use std::time::Duration;


use syslog_rs::formatters::{DefaultSyslogFormatterFile};
use syslog_rs::{SyslogApi, QueuedSyslog};
use syslog_rs::sync::DefaultQueueAdapter;
use syslog_rs::{LogFacility, LogStat, Priority, SyslogFile};
use syslog_rs::AsyncSyslogQueueApi;
use tokio::sync::{mpsc};
use tokio::{runtime, task};

pub static SYSLOG: OnceLock<QueuedSyslog<DefaultQueueAdapter, DefaultSyslogFormatterFile, SyslogFile>> = OnceLock::new();


macro_rules! logdebug 
{
    ($($arg:tt)*) => (
        SYSLOG.get().as_ref().unwrap().syslog(Priority::LOG_DEBUG, format!($($arg)*).into())
    )
}

macro_rules! alogdebug 
{
    ($($arg:tt)*) => (
        SYSLOG.get().as_ref().unwrap().a_syslog(Priority::LOG_DEBUG, format!($($arg)*).into()).await
    )
}


pub fn main()
{
    SYSLOG.get_or_init(move || {
        QueuedSyslog
            ::<_, DefaultSyslogFormatterFile, SyslogFile>
            ::openlog_with(
                Some("example_logtofile"), 
                LogStat::LOG_CONS | LogStat::LOG_NDELAY | LogStat::LOG_PID, 
                LogFacility::LOG_DAEMON,
                SyslogFile::new("/tmp/example_logtofile.txt")
            )
            .unwrap()
    });
    

    logdebug!("test message logtofile!");

    thread::sleep(Duration::from_micros(10));

    let runtime = 
        runtime::Builder::new_multi_thread()
            .enable_all()
            .build()
            .unwrap();

    runtime.block_on(async 
        {
            let s =
                task::spawn_blocking(move || 
                    {
                        for i in 0..10
                        {
                            logdebug!("blocking thread 1 message no: '{}'", i);
                        
                            thread::sleep(Duration::from_micros(300));
                        }

                        return;
                    }
                );

            for i in 0..10
            {
                alogdebug!("async thread message no: '{}'", i);

                tokio::time::sleep(Duration::from_micros(304)).await;
            }

            s.await.unwrap();

            let (tx, mut rx) = mpsc::channel::<u64>(1);

            task::spawn_blocking(move || 
                {
                    SYSLOG.get().unwrap().update_tap_data(SyslogFile::new("/tmp/example_logtofile2.txt")).unwrap();

                    tx.blocking_send(0).unwrap();

                    for i in 0..10
                    {
                        logdebug!("blocking NEW thread message no: '{}'", i);
                    
                        thread::sleep(Duration::from_micros(300));
                    }
                    return;
                }
            );

            rx.recv().await;

            for i in 0..10
            {
                alogdebug!("async NEW thread message no: '{}'", i);

                tokio::time::sleep(Duration::from_micros(304)).await;
            }
        }
    );

    logdebug!("test message logtofile!");

    return;
}

This example requires the feature build_ext_net to be enabled.

use std::{sync::LazyLock, thread};
use std::time::Duration;



use syslog_rs::formatters::DefaultSyslogFormatter;
use syslog_rs::{SyncSyslog, SyslogApi};
use syslog_rs::{LogFacility, LogStat, Priority, SyslogNetUdp};

pub static SYSLOG: LazyLock<SyncSyslog<DefaultSyslogFormatter, SyslogNetUdp>> = LazyLock::new(|| 
    {
        SyncSyslog
            ::<DefaultSyslogFormatter, SyslogNetUdp>
            ::openlog_with(
                Some("example"), 
                LogStat::LOG_CONS | LogStat::LOG_NDELAY | LogStat::LOG_PID, 
                LogFacility::LOG_DAEMON,
                SyslogNetUdp::new("127.0.0.1:7777", None).unwrap()            
            )
            .unwrap()
    }
);

/*
pub static SYSLOG2: LazyLock<Syslog<DefaultSyslogFormatter, syslog_rs::SyslogNetTcp>> = LazyLock::new(|| 
    {
        Syslog
            ::<DefaultSyslogFormatter, syslog_rs::SyslogNetTcp>
            ::openlog_with(
                Some("example"), 
                LogStat::LOG_CONS | LogStat::LOG_PID, 
                LogFacility::LOG_DAEMON,
                syslog_rs::SyslogNetTcp::new("127.0.0.1:7778", None, None).unwrap()            
            )
            .unwrap()
    }
);
*/

macro_rules! logdebug 
{
    ($($arg:tt)*) => (
        SYSLOG.syslog(Priority::LOG_DEBUG, format!($($arg)*).into())
    )
}

pub fn main()
{
    // netcat -ul 7777
    logdebug!("test message!");

    thread::sleep(Duration::from_micros(10));

    return;
}

This exampel requires the feature build_ext_tls to be enabled.

use std::{sync::LazyLock, thread};
use std::time::Duration;

use syslog_rs::formatters::DefaultSyslogFormatter;
use syslog_rs::{SyncSyslog, SyslogApi};
use syslog_rs::{LogFacility, LogStat, Priority, SyslogTls};

pub const  CERT_INLINE: &'static [u8] = b"cert...";

pub static SYSLOG: LazyLock<SyncSyslog<DefaultSyslogFormatter, SyslogTls>> = LazyLock::new(|| 
    {
        SyncSyslog
            ::<_, SyslogTls>
            ::openlog_with(
                Some("example"), 
                LogStat::LOG_CONS | LogStat::LOG_NDELAY | LogStat::LOG_PID, 
                LogFacility::LOG_DAEMON,
                SyslogTls::new("127.0.0.1:514", None, "domain.tld", CERT_INLINE.to_vec(), None).unwrap()
            )
            .unwrap()
    }
);

macro_rules! logdebug 
{
    ($($arg:tt)*) => (
        SYSLOG.syslog(Priority::LOG_DEBUG, format!($($arg)*).into())
    )
}

pub fn main()
{
    logdebug!("test message!");

    thread::sleep(Duration::from_micros(10));

    return;
}

This exampel requires the feature build_async_smol to be enabled.

use std::time::Duration;

use smol::{io, Timer};
use smol::lock::OnceCell;
use syslog_rs::sy_async::AsyncSyslog;
use syslog_rs::{LogFacility, LogStat, Priority, SyslogLocal};


pub static SYSLOG: OnceCell<AsyncSyslog> = OnceCell::new();

macro_rules! logdebug 
{
    ($($arg:tt)*) => (
        SYSLOG.get().unwrap().syslog(Priority::LOG_DEBUG, format!($($arg)*)).await
    )
}

fn main() -> io::Result<()> 
{
    smol::block_on(
        async 
        {
            let syslog =
                AsyncSyslog::openlog(
                        Some("smol_example"), 
                        LogStat::LOG_CONS | LogStat::LOG_NDELAY | LogStat::LOG_PID, 
                        LogFacility::LOG_DAEMON,
                        SyslogLocal::new()
                    )
                    .await
                    .unwrap();


            SYSLOG.get_or_init(|| async { syslog }).await;


            logdebug!("SMOL test message async start!");
            
            SYSLOG.get().unwrap().vsyslog(Priority::LOG_DEBUG, "SMOL test 2").await;

            Timer::after(Duration::from_micros(10)).await;

            SYSLOG.get().unwrap().change_identity("SMOL_new_identity").await;

            logdebug!("SMOL test message new identity!");

            Timer::after(Duration::from_micros(10)).await;

            logdebug!("SMOL test 123!");
            logdebug!("SMOL test 123123! end ");

            Ok(())
        }
    )
}

From the crate version 3, the crate can be provided with custom implementation of the async props like sockets or other things. In order to achieve this some traits should be implemented in the program which uses this crate and enables the build_async_interface. The build-in async exec like tokio or smol can not be enabled together.

See example file.

extern crate syslog_rs; 

use std::fmt;
use std::io::ErrorKind;
use std::net::Shutdown;
use std::time::Duration;
use std::{borrow::Cow, io::IoSlice};

use syslog_rs::a_sync::AsyncMutexGuard;
use syslog_rs::formatters::DefaultSyslogFormatter;
use syslog_rs::nix::errno::Errno;
use syslog_rs::nix::libc;

use syslog_rs::error::SyslogError;
use syslog_rs::{common, throw_error_errno, throw_error_os, AsyncSyslog, AsyncSyslogTap, AsyncTap, LogFacility, LogStat, Priority, SyslogDestMsg, SyslogLocal, TapType, PATH_CONSOLE, PATH_LOG, PATH_LOG_PRIV, PATH_OLDLOG, PATH_OSX};
use syslog_rs::{AsyncSyslogInternal, AsyncSyslogInternalIO, AsyncMutex, error::SyRes, formatters::SyslogFormatter, map_error_os, AsyncSyslogDestination};
use tokio::fs::File;
use tokio::io::AsyncWriteExt;
use tokio::net::UnixDatagram;
use tokio::sync::MutexGuard;
use tokio::time::sleep;
use tokio::{io::AsyncWrite, sync::Mutex};

/// Implemeting the custom IO and thread control things which is needed by the crate.
#[derive(Debug)]
pub struct OurAsyncSyslogIO;

impl OurAsyncSyslogIO
{
    /// Sends to the FD i.e file of stderr, stdout or any which 
    /// implements [Write] `write_vectored` in async manner
    ///
    /// # Arguments
    /// 
    /// * `file_fd` - mutable consume of the container FD.
    ///
    /// * `msg` - a reference on array of data
    ///
    /// * `newline` - a new line string ref i.e "\n" or "\r\n"
    pub(crate) async 
    fn async_send_to_fd<W>(mut file_fd: W, msg: &str, newline: &str) -> SyRes<usize>
    where W: AsyncWrite + Unpin
    {
        return 
            file_fd
                .write_vectored(&[IoSlice::new(msg.as_bytes()), IoSlice::new(newline.as_bytes())])
                .await
                .map_err(|e|
                    map_error_os!(e, "async_send_to_fd() writev() failed")
                );
    } 
}

impl AsyncSyslogInternalIO for OurAsyncSyslogIO
{
    #[inline]
    async 
    fn send_to_stderr(logstat: LogStat, msg: &str)
    {
        if logstat.intersects(LogStat::LOG_PERROR) == true
        {
            let stderr_lock = tokio::io::stderr();

            let newline = "\n";
            let _ = Self::async_send_to_fd(stderr_lock, msg, newline).await;
        }
    }

    #[inline]
    async 
    fn send_to_syscons(logstat: LogStat, msg_payload: &str)
    {
        if logstat.intersects(LogStat::LOG_CONS)
        {
            let syscons = 
                File
                    ::options()
                        .create(false)
                        .read(false)
                        .write(true)
                        .custom_flags(libc::O_NONBLOCK | libc::O_CLOEXEC)
                        .open(*PATH_CONSOLE)
                        .await;

            if let Ok(file) = syscons
            {
                let newline = "\n";
                let _ = Self::async_send_to_fd(file, msg_payload, newline);
            }
        }
    }
    
    async 
    fn sleep_micro(us: u64) 
    {
        sleep(Duration::from_micros(us)).await;
    }

}

/// Implementing the mutex realization for out executor.
#[derive(Debug)]
struct MutexOveride<T: Sized>(Mutex<T>);

/// Also the mutex guard.
#[derive(Debug)]
struct MutexGuardNative<'a, T>(MutexGuard<'a, T>);

impl<'a, T>  MutexGuardNative<'a, T>
{ 
    fn new(g:  MutexGuard<'a, T>) -> Self
    {
        return Self(g);
    }
}

impl<F: SyslogFormatter + Send, D: AsyncSyslogDestination> AsyncMutex<F, D, AsyncSyslogInternal<F, D, OurAsyncSyslogIO>> 
for MutexOveride<AsyncSyslogInternal<F, D, OurAsyncSyslogIO>>
{
    type MutxGuard<'mux> = MutexGuardNative<'mux, AsyncSyslogInternal<F, D, OurAsyncSyslogIO>>;

    fn a_new(v: AsyncSyslogInternal<F, D, OurAsyncSyslogIO>) -> Self 
    {
        return Self(Mutex::new(v));
    }
    
    async 
    fn a_lock<'mux>(&'mux self) -> Self::MutxGuard<'mux>
    {
        return MutexGuardNative::new(self.0.lock().await);
    }
}

impl<'mux, F: SyslogFormatter + Send, D: AsyncSyslogDestination> AsyncMutexGuard<'mux, F, D, AsyncSyslogInternal<F, D, OurAsyncSyslogIO>>
for MutexGuardNative<'mux, AsyncSyslogInternal<F, D, OurAsyncSyslogIO>>
{
    fn guard(&self) -> &AsyncSyslogInternal<F, D, OurAsyncSyslogIO>
    {
        return &self.0;
    }

    fn guard_mut(&mut self) -> &mut AsyncSyslogInternal<F, D, OurAsyncSyslogIO>
    {
        return &mut self.0;
    }
}

/// Implementing the sylog provider (in this example a SyslogLocal will be wrapped into our struct
/// because it is not possible to implement foreign traits for foreign structs.
#[derive(Debug, Clone)]
struct NativeSyslogLocal(SyslogLocal);

impl NativeSyslogLocal
{
    fn new(s: SyslogLocal) -> Self
    {
        return Self(s);
    }
}

impl fmt::Display for NativeSyslogLocal
{
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result 
    {
        write!(f, "{}", self.0)
    }
}

/// A async destination where the type of the tap i.e socket is declared.
impl AsyncSyslogDestination for NativeSyslogLocal
{
    type SocketTap = AsyncTap::<tokio::net::UnixDatagram, Self>;

}

/// A maximum message size.
impl SyslogDestMsg for NativeSyslogLocal
{
    fn get_max_msg_len() -> usize 
    {
        if *common::RFC5424_MAX_DGRAM >= common::MAXLINE
        {
            return common::MAXLINE;
        }
        else
        {
            return *common::RFC5424_MAX_DGRAM;
        };
    }
}

/// Implementing a [AsyncSyslogTap] for the previously created [NativeSyslogLocal] for the
/// [AsyncTap] - socket.
impl AsyncSyslogTap<NativeSyslogLocal> for AsyncTap<UnixDatagram, NativeSyslogLocal>
{
    fn new(req_tap: NativeSyslogLocal) -> SyRes<Self>
    {
        return Self::new(req_tap);
    }


    async 
    fn connectlog(&mut self) -> SyRes<()> 
    {
        let sock = 
            UnixDatagram
                ::unbound()
                    .map_err(|e|
                        map_error_os!(e, "unbounded unix datagram initialization failure: {}", e)
                    )?;

        let tap_type = 
            if self.get_tap_data().0.get_use_alternative() == false && self.get_tap_data().0.get_custom_remote_path().is_some() == true 
            {
                if let Err(e) = sock.connect(self.get_tap_data().0.get_custom_remote_path().as_ref().unwrap())
                {
                    throw_error_os!(e, "failed to open connection to syslog server at '{}'", 
                        self.get_tap_data().0.get_custom_remote_path().as_ref().unwrap().display());
                }
                else 
                {
                    TapType::CustomLog
                }
            }
            else if self.get_tap_data().0.get_custom_remote_path().is_some() == true &&
                sock.connect(self.get_tap_data().0.get_custom_remote_path().as_ref().unwrap()).is_ok() == true
            {
                TapType::CustomLog
            }
            else if let Ok(_) = sock.connect(PATH_LOG_PRIV)
            {
                TapType::Priv
            }
            else if let Ok(_) = sock.connect(PATH_LOG)
            {
                TapType::UnPriv
            }
            else if let Ok(_) = sock.connect(PATH_OLDLOG)
            {
                TapType::OldLog
            }
            else if let Ok(_) = sock.connect(PATH_OSX)
            {
                TapType::Priv
            }
            else
            {
                // failed to open socket
                throw_error_errno!(Errno::last(), "failed to open connection to syslog server");
            };

        self.set_sock(sock);
        self.set_cur_tap_type(tap_type);

        return Ok(());
    }

    async 
    fn send(&mut self, msg: &[u8]) -> std::io::Result<usize> 
    {
        let sock = 
            self
                .get_sock_mut()
                .ok_or_else(||
                    std::io::Error::new(ErrorKind::NotConnected, "no connection")
                )?;

        return sock.send(msg).await;
    }

    async 
    fn disconnectlog(&mut self) -> std::io::Result<()>
    {
        match self.take_sock()
        {
            Some(s) => 
            {
                self.set_cur_tap_type(TapType::None);

                s.shutdown(Shutdown::Both)
            },
            None =>
            {
                self.set_cur_tap_type(TapType::None);

                Ok(())
            }
        }
    }

    fn is_connected(&self) -> bool
    {
        return self.get_sock().is_some();
    }

    fn get_type(&self) -> TapType 
    {
        return self.get_tap_type();
    }

    fn get_max_msg_size() -> usize
    {
        return NativeSyslogLocal::get_max_msg_len();
    }

    fn update_tap_data(&mut self, tap_data: NativeSyslogLocal)
    {
        self.update_tap_data(tap_data); 
    }
}

#[tokio::main]
async
fn main() 
{
    // provide everything which was created to the AsyncSyslog.
    let syslog =
        AsyncSyslog
            ::<NativeSyslogLocal, DefaultSyslogFormatter, OurAsyncSyslogIO, MutexOveride<_>>
            ::openlog_with(
                Some("example_cust"), 
                LogStat::LOG_CONS | LogStat::LOG_NDELAY | LogStat::LOG_PID, 
                LogFacility::LOG_DAEMON,
                NativeSyslogLocal::new(SyslogLocal::new())
            )
            .await
            .unwrap();

    syslog.vsyslog(Priority::LOG_DEBUG, "test custom async exec in example").await;

    println!("Hello, world!");
}