{"id":22830778,"url":"https://github.com/mguinness/syslog-framework-logging","last_synced_at":"2025-04-23T19:13:40.967Z","repository":{"id":144143092,"uuid":"47709188","full_name":"mguinness/syslog-framework-logging","owner":"mguinness","description":"Syslog provider for Microsoft.Extensions.Logging","archived":false,"fork":false,"pushed_at":"2019-01-02T23:22:43.000Z","size":28,"stargazers_count":25,"open_issues_count":0,"forks_count":11,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-04-23T19:13:29.824Z","etag":null,"topics":["netstandard","syslog"],"latest_commit_sha":null,"homepage":null,"language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mguinness.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-12-09T18:00:05.000Z","updated_at":"2024-06-04T17:15:02.000Z","dependencies_parsed_at":null,"dependency_job_id":"d49e199a-716a-4a7e-a6f0-cf8b9716b817","html_url":"https://github.com/mguinness/syslog-framework-logging","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mguinness%2Fsyslog-framework-logging","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mguinness%2Fsyslog-framework-logging/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mguinness%2Fsyslog-framework-logging/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mguinness%2Fsyslog-framework-logging/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mguinness","download_url":"https://codeload.github.com/mguinness/syslog-framework-logging/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250496991,"owners_count":21440231,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["netstandard","syslog"],"created_at":"2024-12-12T20:14:45.286Z","updated_at":"2025-04-23T19:13:40.947Z","avatar_url":"https://github.com/mguinness.png","language":"C#","readme":"# Syslog.Framework.Logging\nSyslog provider for [Microsoft.Extensions.Logging](https://www.nuget.org/packages/Microsoft.Extensions.Logging), the logging subsystem used by ASP.NET Core.\n\nThis package routes ASP.NET log messages through Syslog, so you can capture these in any Syslog server like [Syslog Server](https://github.com/mguinness/syslogserver).\n\nThe Syslog implementation supports the following features:\n\n - RFC 3164\n - RFC 5424 (v1)\n - Structured data (RFC 5424 only)\n - UTC or local time stamps\n - UDP and Unix sockets as message transport protocols,\n - Can be extended with custom message transport procotol,\n - Custom facility types\n\n### Instructions\n\nInstall the Syslog.Framework.Logging [NuGet package](https://www.nuget.org/packages/Syslog.Framework.Logging).\n\nNext in appsettings.json add the following and modify where necessary:\n\n    {\n      \"SyslogSettings\": {\n        \"MessageTransportProtocol\": \"Udp\",\n        \"ServerHost\": \"127.0.0.1\",\n        \"ServerPort\": 514,\n        \"HeaderType\": \"Rfc5424v1\",\n        \"FacilityType\": \"Local0\",\n        \"UseUtc\": true,\n        \"StructuredData\": [ \n          {\n            \"Id\": \"mydata\",\n            \"Elements\": [\n              { \"Name\": \"tag\", \"Value\": \"MyTag\" }\n            ]\n          }\n        ]\n      }\n    }\n\nThen in your web application's `Main` method, configure Syslog:\n\n```csharp\npublic class Program\n{\n  public static void Main(string[] args)\n  {\n    CreateWebHostBuilder(args)\n      .ConfigureLogging((ctx, logging) =\u003e\n      {\n        var slConfig = ctx.Configuration.GetSection(\"SyslogSettings\");\n        if (slConfig != null)\n        {\n          var settings = new SyslogLoggerSettings();\n          slConfig.Bind(settings);\n          // Configure structured data here if desired.\n          logging.AddSyslog(settings);\n        }\n      }\n  }\n}\n```\n\nIf you have a console app, you can use the logging provider directly. This is what Microsoft uses to instantiate `ILogger` instances. It is possible to setup Microsoft dependency injection, but that is outside the scope of this article.\n\n```csharp\nusing Microsoft.Extensions.Logging;\nusing Syslog.Framework.Logging;\nusing System;\n\nnamespace MySyslogConsoleApp\n{\n  class Program\n  {\n    public readonly static SyslogLoggerProvider mLoggingProvider;\n    public readonly static ILogger mLogger;\n\n    static Program()\n    {\n      var settings = new SyslogLoggerSettings();\n      // Set the Syslog setting here.\n      mLoggingProvider = new SyslogLoggerProvider(settings, Environment.MachineName, Microsoft.Extensions.Logging.LogLevel.Debug);\n      mLogger = mLoggingProvider.CreateLogger\u003cProgram\u003e();\n    }\n\n    static void Main(string[] args)\n    {\n      mLogger.LogInformation(\"Hello World\");\n      var awe = new MyAwesomeClass();\n      awe.DoSomethingAmazing();\n      Console.WriteLine(\"Hello World!\");\n    }\n  }\n\n  public class MyAwesomeClass\n  {\n    private static readonly ILogger mLogger = Program.mLoggingProvider.CreateLogger\u003cMyAwesomeClass\u003e();\n    \n    public void DoSomethingAmazing()\n    {\n      mLogger.LogCritical(\"I just did something awe inspiring!\");\n    }\n  }\n}\n```\n### Message transport protocols\nA message transport protocol defines means by which the message is delivered to a syslog server.\nThis library currently has the following built-in transport protocols:\n#### UDP\nA fast but unreliable protocol. When using UDP be aware that messages can be lost or they can be delivered out of order. Allows sending of messages directly to a remote server.\n\nTo use this transport protocol configure your syslog server to accept UDP messages and change your config to include the following lines (change the server host and port according to your server configuration):\n```\n\"SyslogSettings\": {\n    \"MessageTransportProtocol\": \"Udp\",\n    \"ServerHost\": \"127.0.0.1\",\n    \"ServerPort\": 514\n}\n```\n#### Unix domain sockets\nA fast and reliable protocol for sending messages to a local syslog server on Unix systems. Does NOT support sending of messages to a remote server (but note that most syslog server implementations can be configured to forward the messages to a centralized server, also with advanced features such as queueing the messages if the server is unavailable). \n\nNote that by default most syslog servers (at least rsyslog is) are configured to expect special message format for default `/dev/log` socket. This message format is inflexible and is not supported by this library. If you want to use this transport protocol you have to configure the server to listen to additional socket in standard format or reconfigure the default socket. \n\nIn rsyslog you can reconfigure the /dev/log socket to use the same format as for messages sent by Udp or Tcp by replacing the following entry in `/etc/rsyslog.conf`:\n\n`module(load=\"imuxsock\") # provides support for local system logging`\n\nwith\n\n`module(load=\"imuxsock\" SysSock.UseSpecialParser=\"off\") # provides support for local system logging`\n\nNote that during testing we did not encounter any side effects when disabling special message format for `/dev/log` but there is a possibility that logs coming from some applications using that format can be malformed so depending on your requirements the usage of an additional socket in different path can be better solution.\n\nTo use this transport protocol change your config to include the following lines (change the socket path if it is different than /dev/log):\n```\n\"SyslogSettings\": {\n    \"MessageTransportProtocol\": \"UnixSocket\",\n    \"UnixSocketPath\": \"/dev/log\"\n}\n```\n#### Adding custom protocol\nIf built-in protocols aren't enough you can add support for any protocol by implementing just 1 simple interface - `IMessageSender`.\n\nFor example, to use Tcp protocol you could write this simple class (note - this is just an example designed for simplicity, NOT a production ready implementation):\n```\npublic class TcpMessageSender : IMessageSender\n{\n   public void SendMessageToServer(byte[] messageData)\n   {\n      using (var tcp = new TcpClient())\n      {\n         tcp.Connect(\"127.0.0.1\", 514);\n\t\t\t\t\n         using (var stream = tcp.GetStream())\n         {\n            stream.Write(messageData, 0, messageData.Length);\n            stream.WriteByte((byte)'\\n');\n         }\n      }\n   }\n}\n```\nAnd then tell the library to use this protocol implementation by assigning an object of this class to a `CustomMessageSender` property of `SyslogLoggerSettings`:\n```\n    CreateWebHostBuilder(args)\n    .ConfigureLogging((ctx, logging) =\u003e\n    {\n        var slConfig = ctx.Configuration.GetSection(\"SyslogSettings\");\n        \n        logging.AddSyslog(slConfig, x =\u003e\n        {\n            x.CustomMessageSender = new TcpMessageSender();\n        });\n    }\n```\nIf you have written a generic implementation of protocol not currently supported by the library and you think it can be useful to more people you are encouraged to contribute the implementation to the project.\n\n### Release notes\n#### 2.1.2\nMade changes to a RFC 5424 message sent by the library to fix some deviations from the RFC 5424 standard:\n* If any message header has no value a NILVALUE (-) is now written as the header value instead of just skipping the header. This fixes a bug where a part of message could be interpreted as structured data and the message malformed when it started with square braces followed by a colon and the message had no structured data assigned.\n* The timestamp is now written with 6 digits in a second fraction part as is mandated by the standard. Previously 7 digits have been written causing some syslog server implementations (such as rsyslog) to incorrectly display that part.\n* If we fail to retrieve the process id a NILVALUE is sent instead of 0.\n\nAside from fixing the aforementioned bugs the changes should be transparent to any RFC 5424 compliant syslog server implementation.\n\n#### 2.2.0\n* Support for sending messages by UNIX domain sockets.\n* Support for custom transport procotol implementations.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmguinness%2Fsyslog-framework-logging","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmguinness%2Fsyslog-framework-logging","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmguinness%2Fsyslog-framework-logging/lists"}