{"id":24107466,"url":"https://github.com/syniol/go-logger","last_synced_at":"2026-02-13T02:21:12.649Z","repository":{"id":205519699,"uuid":"714437625","full_name":"syniol/go-logger","owner":"syniol","description":"Golang Ultra-Light Cloud Native Logger Library","archived":false,"fork":false,"pushed_at":"2023-11-04T21:59:03.000Z","size":7,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-28T09:06:04.033Z","etag":null,"topics":["go","golang","logger","logging","logging-library"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/syniol.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}},"created_at":"2023-11-04T21:42:18.000Z","updated_at":"2023-11-04T22:03:41.000Z","dependencies_parsed_at":null,"dependency_job_id":"646ab9ab-495e-4831-89be-b022a14b2503","html_url":"https://github.com/syniol/go-logger","commit_stats":null,"previous_names":["syniol/sylog"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/syniol/go-logger","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syniol%2Fgo-logger","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syniol%2Fgo-logger/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syniol%2Fgo-logger/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syniol%2Fgo-logger/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/syniol","download_url":"https://codeload.github.com/syniol/go-logger/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syniol%2Fgo-logger/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264613783,"owners_count":23637435,"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":["go","golang","logger","logging","logging-library"],"created_at":"2025-01-10T22:30:25.161Z","updated_at":"2026-02-13T02:21:12.641Z","avatar_url":"https://github.com/syniol.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SyLog: Structured, Facility-Aware Logging for Go\n![workflow](https://github.com/syniol/go-logger/actions/workflows/ci.yml/badge.svg)  \n\n\u003cp align='center'\u003e\n\t\u003cimg style='max-width: 100%; width: 320px;' src='https://github.com/user-attachments/assets/865f2acc-30e0-4c5b-8ce6-069b3204b740' /\u003e\n\u003c/p\u003e\n\nSyLog brings the battle-tested Facility and Severity methodology of Unix Syslog \nto modern Go applications. It provides a structured, JSON-first logging interface \ndesigned to give distributed systems the same level of granular categorisation \nthat system administrators have relied on for decades.\n\n\n## Why SyLog?\nIn the world of microservices, a simple string message is rarely enough. By implementing \nthe facility concept, this package allows you to categorise logs not just by what happened, but by where it originated within your architecture (e.g., auth-service, payment-gateway, kernel).\n\n * **Contextual Tracing:** Automatically captures file locations and line numbers to pinpoint failures.\n * **RFC-Inspired Severities:** Moves beyond simple \"Info/Error\" levels to include Alert, Critical, and Emergency states.\n * **Structured Output:** Native JSON formatting out of the box, ready for ingestion by ELK, Splunk, or Grafana Loki.\n * **Developer-Centric API:** A clean, variadic interface that feels natural to Go developers.\n\n\n## Quick Start\nFirst you need to add and download SyLog dependency in your Go project.\n```shell\ngo get github.com/syniol/go-logger\n```\n\n**Example code:**\n```go\npackage main\n\nimport \"github.com/syniol/go-logger\"\n\nfunc main() {\n\tsylog.LogAlert(\"pay microservice\", \"mock message for alert log\")\n}\n```\n\n**Resulting Output:**\n```json\n{\n  \"level\": \"alert\",\n  \"facility\": \"pay microservice\",\n  \"message\": \"mock message for alert log\",\n  \"trace\": [\n    \"location: '/Users/hadi/dev/golang/logger/logger.go' on line: 100\"\n  ],\n  \"timestamp\": \"2023-11-04T21:36:33Z\"\n}\n```\n\n\n## Log Schema Definition\nEvery log entry is emitted as a structured JSON object. This consistent schema ensures \nthat your logs are machine-readable and ready for high-performance indexing in modern \nobservability stacks.\n\n| Field       | Type     | Description                                                                                                                                                                                                            |\n|-------------|----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `level`     | `string` | The severity level mapped from the invoked method (e.g., `alert`, `warn`, `info` ). Derived from **RFC 5424** standards.                                                                                               |\n| `facility`  | `string` | The logical component or service name. Used as the primary partition for log filtering in distributed environments.                                                                                                    |\n| `message`   | `string` | The primary log descriptor. This is captured from the first argument provided to the logging method.                                                                                                                   |\n| `trace`     | `array`  | A collection of contextual metadata. The first element is automatically injected with the file path and line number of the caller. Subsequent elements contain any additional variadic arguments passed to the method. |\n| `timestamp` | `string` | The UTC time of event generation, formatted according to the **ISO 8601 / RFC 3339** standard for universal compatibility.                                                                                             |\n\n### A Design Note on the `trace` Array\nThe trace field is designed for **maximum forensic utility**. By capturing the exact \nline number where the log was triggered, it eliminates the guesswork during incident \nresponse. Because it is an array, it keeps your top-level JSON namespace clean while \nallowing you to pass as much supplemental context as needed.\n\n\n## Severity Levels: The 8-Tier Standard\nThis package implements the full spectrum of Unix Syslog severity levels. Rather than passing a level\nas a variable, SyLog provides dedicated methods for each. This ensures type safety and clear intent at\nthe call site.\n\n### Which Method to Use?\nChoosing the right level is critical for effective alerting and noise reduction in your monitoring dashboards.\n\n| Method           | Level             | Syslog Code | Use Case                                                                        |\n|------------------|-------------------|-------------|---------------------------------------------------------------------------------|\n| `LogEmergency()` | **Emergency**     | 0           | **System is unusable.** Total failure. Everyone gets paged.                     |\n| `LogAlert()`     | **Alert**         | 1           | **Immediate action required.** e.g., Primary database down.                     |                           \n| `LogCritical()`  | **Critical**      | 2           | **Critical conditions.** e.g., Hard device errors or loss of primary functions. |\n| `LogError()`     | **Error**         | 3           | **Error conditions.** Something failed, but the app is still running.           |                \n| `LogWarning()`   | **Warning**       | 4           | **Warning conditions.** Potential issues that should be investigated.           |               \n| `LogNotice()`    | **Notice**        | 5           | **Normal but significant.** Non-error events that deserve tracking.             |                   \n| `LogInfo()`      | **Informational** | 6           | **Standard operational logs.** General \"\"heartbeat\"\" of the app.                |              \n| `LogDebug()`     | **Debug**         | 7           | **Developer verbosity.** Detailed info for troubleshooting.                     |                             \n\n\n### Implementation Mapping\nIn your JSON output, these methods automatically map to the `level` key. This allows your log aggregator\n(Datadog, Grafana, etc.) to apply color-coding and trigger automated alerts based on the numerical priority.\n```go\n// Severity 1: Trigger SRE page\nsylog.LogAlert(\"vault-service\", \"Credential rotation failed - Unauthorised access detected\")\n\n// Severity 6: Standard audit trail\nsylog.LogInfo(\"user-service\", \"User ID 505 logged in successfully\")\n```\n\u003e**Architect's Tip:** In a production environment, you should typically set your log sink to ignore `LogDebug` and\n`LogInfo` to save on storage costs, while ensuring `LogWarning` and above are always captured.\n\n### The Unopinionated Philosophy\nSyLog is designed to be a transparent sidecar to your application logic. Unlike other logging libraries that may\nforce a `panic()` or `os.Exit()` when a high-severity log is triggered, this package is entirely non-intrusive.\n\n#### Execution Control\nWhether you call `LogInfo()` or `LogEmergency()`, the package will:\n1. Capture the trace and timestamp.\n2. Format the JSON payload.\n3. Emit the log to the configured output.\n4. Return control to your application.\n\n#### Why this matters\n* **Testing:** Your unit tests won't unexpectedly terminate when testing error-handling paths.\n* **Graceful Shutdowns:** You can log a Critical failure and still allow your application to close database connections or finish inflight requests before exiting.\n* **Separation of Concerns:** We believe a logger’s job is to report, not to decide the lifecycle of your software.\n\n#### Example: Handling an Emergency\n```go\nif err != nil {\n    // The logger records the disaster...\n    sylog.LogEmergency(\"kernel\", \"Memory limit reached, unable to continue\")\n    \n    // ...but YOU decide how to crash.\n    panic(\"System Unstable\") \n}\n```\n\n\n## Core Concepts: The Power of \"Facility\"\nIn systems architecture, clarity is the antidote to complexity. When adapting the Syslog\nFacility concept for modern microservices, we are essentially moving from \"What happened?\"\nto \"Who is responsible?\"\n\nIn traditional Unix, facilities were predefined (like `auth`, `cron`, or `kern`). \nIn SyLog package, the Facility becomes a dynamic tag representing the Service Identity.\nUnlike traditional loggers that only categorise by severity (Level), SyLog introduces \nthe Facility parameter as a first-class citizen.\n\n### What is a Facility?\nIn this package, a Facility represents the Identity of the Component. While the level \ntells you the urgency of the message, the `facility` tells you exactly which microservice \nor sub-system generated it.\n\n### Why this matters for Observability\nBy explicitly tagging logs with a facility, you provide high-cardinality metadata that \nmodern observability tools (CloudWatch, Prometheus, Datadog) use for indexing and filtering.\n\n| Advantage              | Benefit                                                                                                                  |\n|------------------------|--------------------------------------------------------------------------------------------------------------------------|\n| **Granular Filtering** | Instantly isolate all logs from the `billing-engine` without parsing complex message strings.                            |\n| **Routing Logic**      | Route logs from the `auth` facility to a high-security storage bucket while sending `frontend` logs to standard storage. |\n| **Alerting Accuracy**  | Set up monitors that trigger only when `alert` level logs appear specifically within the `database-proxy` facility.      |\n\n### How to choose a Facility name\nFor the best results in distributed environments, we recommend following a consistent naming \nconvention for your facilities:\n\n * **Service Name:** e.g., payment-microservice\n * **Sub-system:** e.g., worker-pool or cache-layer\n * **Environment (Optional):** e.g., prod-api-gateway\n\n### Implementation Example\nInstead of generic logging:\n```go\n// Vague: Where did this happen?\nsylog.LogError(\"Database connection timed out\")\n```\n\nUse the **Facility-first** approach:\n```go\n// Precise: The 'order-processor' is the culprit.\nsylog.LogError(\"order-processor\", \"Database connection timed out\")\n```\nWhen this reaches **CloudWatch** or **Datadog**, you can simply run a query like facility: \n\"order-processor\" to see the entire lifecycle of that specific service's behavior.\n\n\n#### Credits\nAuthor: [Hadi Tajallaei](mailto:hadi@syniol.com)\n\nCopyright \u0026copy; 2023-2026 Syniol Limited. All rights Reserved.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsyniol%2Fgo-logger","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsyniol%2Fgo-logger","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsyniol%2Fgo-logger/lists"}