{"id":30141046,"url":"https://github.com/hmlendea/nucilog.core","last_synced_at":"2026-04-19T19:08:19.488Z","repository":{"id":297474178,"uuid":"996891997","full_name":"hmlendea/nucilog.core","owner":"hmlendea","description":"Lightweight abstraction package for structured .NET logging.","archived":false,"fork":false,"pushed_at":"2026-03-23T11:59:15.000Z","size":108,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-03-24T08:39:47.282Z","etag":null,"topics":["csharp","dotnet","logging","nuget","nuget-package"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hmlendea.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":null,"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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":null,"patreon":"hmlendea","open_collective":null,"ko_fi":"hmlendea","tidelift":null,"community_bridge":null,"liberapay":"HMlendea","issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":null,"thanks_dev":null,"custom":"https://hmlendea.go.ro/fund.html"}},"created_at":"2025-06-05T16:11:43.000Z","updated_at":"2026-03-23T11:57:49.000Z","dependencies_parsed_at":"2025-06-05T17:32:32.679Z","dependency_job_id":"89fca1ba-cac4-4ba2-ad8d-14a43d937197","html_url":"https://github.com/hmlendea/nucilog.core","commit_stats":null,"previous_names":["hmlendea/nucilog.core"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/hmlendea/nucilog.core","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hmlendea%2Fnucilog.core","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hmlendea%2Fnucilog.core/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hmlendea%2Fnucilog.core/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hmlendea%2Fnucilog.core/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hmlendea","download_url":"https://codeload.github.com/hmlendea/nucilog.core/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hmlendea%2Fnucilog.core/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32018820,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T20:23:30.271Z","status":"online","status_checked_at":"2026-04-19T02:00:07.110Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["csharp","dotnet","logging","nuget","nuget-package"],"created_at":"2025-08-11T04:22:49.909Z","updated_at":"2026-04-19T19:08:19.467Z","avatar_url":"https://github.com/hmlendea.png","language":"C#","funding_links":["https://patreon.com/hmlendea","https://ko-fi.com/hmlendea","https://liberapay.com/HMlendea","https://hmlendea.go.ro/fund.html"],"categories":[],"sub_categories":[],"readme":"[![Donate](https://img.shields.io/badge/-%E2%99%A5%20Donate-%23ff69b4)](https://hmlendea.go.ro/fund.html) [![Build Status](https://github.com/hmlendea/nucilog.core/actions/workflows/dotnet.yml/badge.svg)](https://github.com/hmlendea/nucilog.core/actions/workflows/dotnet.yml) [![Latest GitHub release](https://img.shields.io/github/v/release/hmlendea/nucilog.core)](https://github.com/hmlendea/nucilog.core/releases/latest)\n\n# NuciLog.Core\n\nNuciLog.Core is a lightweight logging abstraction for .NET applications that want predictable, structured log messages without coupling application code directly to a specific logging backend.\n\nThe library focuses on three things:\n\n- a consistent set of log levels\n- operation-aware logging\n- structured `key=value` log output\n\nIt is designed to be extended by implementing a custom logger sink, while the base `Logger` class handles overload normalization and message construction.\n\n# Features\n\n- `Verbose`, `Debug`, `Info`, `Warn`, `Error`, and `Fatal` log levels\n- operation and operation status tracking\n- structured log details through `LogInfo`\n- exception enrichment with exception type, message, and stack trace\n- predictable output formatting for downstream processing\n- no-op `NullLogger` implementation for disabled logging scenarios\n\n# Target Framework\n\nThe package currently targets `.NET 10.0`.\n\n# Installation\n\n[![Get it from NuGet](https://raw.githubusercontent.com/hmlendea/readme-assets/master/badges/stores/nuget.png)](https://nuget.org/packages/NuciLog.Core)\n\n**.NET CLI**:\n```bash\ndotnet add package NuciLog.Core\n```\n\n**Package Manager**:\n```powershell\nInstall-Package NuciLog.Core\n```\n\n# Quick Start\n\n`Logger` is an abstract base class. To use the library, create a concrete implementation and write the final log line to your preferred destination.\n\n```csharp\nusing System;\nusing NuciLog.Core;\n\npublic sealed class ConsoleLogger : Logger\n{\n\tprotected override void WriteLog(LogLevel level, Func\u003cstring\u003e logMessage)\n\t{\n\t\tConsole.WriteLine($\"[{level}] {logMessage()}\");\n\t}\n}\n\npublic sealed class AppLogKey(string name) : LogInfoKey(name)\n{\n\tpublic static LogInfoKey UserId =\u003e new AppLogKey(nameof(UserId));\n\tpublic static LogInfoKey CorrelationId =\u003e new AppLogKey(nameof(CorrelationId));\n}\n```\n\nExample usage:\n\n```csharp\nusing NuciLog.Core;\n\nILogger logger = new ConsoleLogger();\nlogger.SetSourceContext\u003cProgram\u003e();\n\nlogger.Info(\n\tOperation.StartUp,\n\tOperationStatus.Started,\n\t\"Initialising service\",\n\tnew LogInfo(AppLogKey.CorrelationId, \"req-42\"));\n\nlogger.Info(\n\tOperation.StartUp,\n\tOperationStatus.Success,\n\tnew LogInfo(AppLogKey.UserId, 1234));\n\ntry\n{\n\tthrow new InvalidOperationException(\"Configuration file is invalid\");\n}\ncatch (Exception ex)\n{\n\tlogger.Error(\n\t\tOperation.StartUp,\n\t\tOperationStatus.Failure,\n\t\t\"Service failed to start\",\n\t\tex,\n\t\tnew LogInfo(AppLogKey.CorrelationId, \"req-42\"));\n}\n```\n\nPossible output:\n\n```text\n2026-03-23T11:22:33.1090023+02:00||INFO|Operation=StartUp,OperationStatus=STARTED,Message=Initialising service,CorrelationId=req-42\n2026-03-23T11:22:33.1090123+02:00||INFO|Operation=StartUp,OperationStatus=SUCCESS,UserId=1234\n2026-03-23T11:22:33.1090223+02:00||INFO|Operation=StartUp,OperationStatus=FAILURE,Message=Service failed to start,CorrelationId=req-42,Exception=System.InvalidOperationException,ExceptionMessage=Configuration file is invalid\n```\n\n# Concepts\n\n## Logger\n\n`Logger` provides the implementation for the large set of convenience overloads exposed by `ILogger`. All overloads eventually resolve to:\n\n```csharp\nprotected abstract void WriteLog(LogLevel level, Func\u003cstring\u003e logMessage)\n```\n\nThis keeps application code simple while leaving the final output destination under your control.\n\n## Log Levels\n\nThe available log levels are:\n\n- `Verbose`\n- `Debug`\n- `Info`\n- `Warn`\n- `Error`\n- `Fatal`\n\n## Operations and Statuses\n\nOperations provide semantic context for application lifecycle or business actions.\n\nBuilt-in operations:\n\n- `Unknown`\n- `StartUp`\n- `ShutDown`\n\nBuilt-in operation statuses:\n\n- `Unknown`\n- `Started`\n- `Success`\n- `Failure`\n- `InProgress`\n\nYou can introduce your own domain-specific operations or statuses by deriving from `Operation` or `OperationStatus`.\n\n## Structured Details\n\nStructured fields are added through `LogInfo` instances:\n\n```csharp\nlogger.Info(\n\t\"User authenticated\",\n\tnew LogInfo(AppLogKey.UserId, 1234),\n\tnew LogInfo(AppLogKey.CorrelationId, \"req-42\"));\n```\n\nEach `LogInfo` contains:\n\n- a `LogInfoKey`\n- a stringified value\n\nValues can be created from:\n\n- `string`\n- `object`\n- `DateTime` with a custom format\n\nTo define custom keys, derive from `LogInfoKey` and expose strongly named static members, as shown in the quick start example.\n\n# Output Format\n\nGenerated log lines use comma-separated `key=value` pairs.\n\nThe output order is:\n\n1. `Operation`\n2. `OperationStatus`\n3. message and custom structured fields\n4. exception-related fields\n\nExample:\n\n```text\nOperation=StartUp,OperationStatus=SUCCESS,Message=Ready,UserId=1234\n```\n\nImportant formatting rules:\n\n- empty or whitespace values are omitted\n- duplicate keys are collapsed so the last value wins\n- if the final value of a duplicate key is empty, that key is removed\n- line breaks inside values are converted to `\\n`\n- commas inside values are replaced with `͵` (unicode look-alike character) to preserve parsing\n- when logging an exception without a message, `Message=An exception has occurred.` is added automatically\n\n# API Overview\n\nThe most commonly used members are:\n\n- `ILogger` for the logging contract\n- `Logger` for the base implementation\n- `NullLogger` for a no-op logger\n- `LogInfo` for structured details\n- `LogInfoKey` for defining structured field names\n- `Operation` and `OperationStatus` for contextual logging\n\nCommon overload patterns are available for each log level:\n\n- message only\n- operation only\n- operation with status\n- message with exception\n- operation with message\n- operation with status and message\n- any of the above with `params LogInfo[]`\n- any of the above with `IEnumerable\u003cLogInfo\u003e`\n\nExamples:\n\n```csharp\nlogger.Debug(\"Cache warmup started\");\nlogger.Info(Operation.StartUp, OperationStatus.Started);\nlogger.Warn(Operation.ShutDown, \"Shutdown taking longer than expected\");\nlogger.Error(\"Request failed\", ex);\nlogger.Fatal(Operation.ShutDown, OperationStatus.Failure, \"Host terminated\", ex);\n```\n\n# Source Context\n\nThe logger exposes source context through:\n\n```csharp\nlogger.SetSourceContext\u003cProgram\u003e();\nlogger.SetSourceContext(typeof(Program));\n```\n\nThis sets the `SourceContext` property on the logger instance. At the moment, source context is stored on the logger but is not automatically emitted as part of the generated log message.\n\n# Null Logger\n\nUse `NullLogger` when you need an `ILogger` implementation that safely ignores all log calls:\n\n```csharp\nILogger logger = new NullLogger();\n```\n\nThis is useful for tests, optional integrations, or disabled logging pipelines.\n\n# Development\n\nBuild the solution:\n\n```bash\ndotnet build NuciLog.sln\n```\n\nRun the tests:\n\n```bash\ndotnet test NuciLog.sln\n```\n\nThe test suite covers:\n\n- log level dispatch for all severity levels\n- structured message building\n- exception formatting\n- duplicate key handling\n- sanitisation of commas and new lines\n\n# License\n\nLicensed under GNU GPL v3. See `LICENSE` for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhmlendea%2Fnucilog.core","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhmlendea%2Fnucilog.core","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhmlendea%2Fnucilog.core/lists"}