{"id":30048388,"url":"https://github.com/segmentio/events","last_synced_at":"2025-10-16T06:48:00.272Z","repository":{"id":15415736,"uuid":"78068625","full_name":"segmentio/events","owner":"segmentio","description":"Go package for routing, formatting and publishing events produced by a program.","archived":false,"fork":false,"pushed_at":"2024-09-18T22:46:37.000Z","size":183,"stargazers_count":71,"open_issues_count":4,"forks_count":16,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-08-14T15:34:37.877Z","etag":null,"topics":["events","go","golang","logging","segment","signals"],"latest_commit_sha":null,"homepage":null,"language":"Go","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/segmentio.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":"2017-01-05T01:46:09.000Z","updated_at":"2024-09-18T21:31:43.000Z","dependencies_parsed_at":"2023-10-14T16:38:39.007Z","dependency_job_id":"82076861-d74a-49fd-b340-1bbe0e337f48","html_url":"https://github.com/segmentio/events","commit_stats":null,"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/segmentio/events","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/segmentio%2Fevents","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/segmentio%2Fevents/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/segmentio%2Fevents/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/segmentio%2Fevents/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/segmentio","download_url":"https://codeload.github.com/segmentio/events/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/segmentio%2Fevents/sbom","scorecard":{"id":809909,"data":{"date":"2025-08-11","repo":{"name":"github.com/segmentio/events","commit":"75cb1a9358b3809533ad134916c845efe8d57b4b"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":4.3,"checks":[{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Maintained","score":0,"reason":"0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Code-Review","score":5,"reason":"Found 11/19 approved changesets -- score normalized to 5","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Token-Permissions","score":0,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Warn: no topLevel permission defined: .github/workflows/ci.yml:1","Info: no jobLevel write permissions found"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Pinned-Dependencies","score":0,"reason":"dependency not pinned by hash detected -- score normalized to 0","details":["Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:19: update your workflow using https://app.stepsecurity.io/secureworkflow/segmentio/events/ci.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:22: update your workflow using https://app.stepsecurity.io/secureworkflow/segmentio/events/ci.yml/master?enable=pin","Info:   0 out of   2 GitHub-owned GitHubAction dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: MIT License: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":4,"reason":"branch protection is not maximal on development and all release branches","details":["Info: 'allow deletion' disabled on branch 'master'","Info: 'force pushes' disabled on branch 'master'","Warn: 'branch protection settings apply to administrators' is disabled on branch 'master'","Info: 'stale review dismissal' is required to merge on branch 'master'","Warn: required approving review count is 1 on branch 'master'","Warn: codeowners review is required - but no codeowners file found in repo","Warn: 'last push approval' is disabled on branch 'master'","Warn: 'up-to-date branches' is disabled on branch 'master'","Info: status check found to merge onto on branch 'master'","Info: PRs are required in order to make changes on branch 'master'"],"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"Vulnerabilities","score":10,"reason":"0 existing vulnerabilities detected","details":null,"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 25 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}}]},"last_synced_at":"2025-08-23T12:50:13.373Z","repository_id":15415736,"created_at":"2025-08-23T12:50:13.373Z","updated_at":"2025-08-23T12:50:13.373Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279163652,"owners_count":26117502,"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","status":"online","status_checked_at":"2025-10-16T02:00:06.019Z","response_time":53,"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":["events","go","golang","logging","segment","signals"],"created_at":"2025-08-07T10:11:11.041Z","updated_at":"2025-10-16T06:48:00.267Z","avatar_url":"https://github.com/segmentio.png","language":"Go","readme":"# events [![CircleCI](https://circleci.com/gh/segmentio/events.svg?style=shield)](https://circleci.com/gh/segmentio/events) [![Go Report Card](https://goreportcard.com/badge/github.com/segmentio/events)](https://goreportcard.com/report/github.com/segmentio/events) [![GoDoc](https://godoc.org/github.com/segmentio/events?status.svg)](https://godoc.org/github.com/segmentio/events)\nGo package for routing, formatting and publishing events produced by a program.\n\n## Motivations\n\n**Most new code should use the new standard library log/slog package\nfor logging. While this package won't go away, it may not see many new\ncontributions.**\n\nThe events package attempts to address these problems by providing high level\nabstractions with highly efficient implementations. But it also goes further,\noffering a new way to think about what logging is in a program, starting with\nthe package name, `events`, which expresses what this problem is about.\nDuring its execution, a program produces events, and these events need to be\ncaptured, routed, formatted and published to a persitence system in order to\nbe later analyzed.\n\nThe package was inspired by [this post](https://dave.cheney.net/2015/11/05/lets-talk-about-logging)\nfrom Dave Cheney. It borrowed a lot of the ideas but tried to find the sweet\nspot between Dave's idealistic view of what logging is supposed to be, and\nproduction constraints that we have here at Segment.\n\n## Events\n\nAt the core of the package is the `Event` type. Instances of this type carry\nthe context in which the event was generated and the information related to\nthe event.\n\nEvents are passed from the sources that trigger them to handlers, which are\ntypes implementing the `Handler` interface:\n```go\ntype Handler interface {\n    HandleEvent(*Event)\n}\n```\nThe sub-packages provide implementations of handlers that publish events to\nvarious formats and locations.\n\n## Logging\n\nThe `Logger` type is a source of events, the program uses loggers to generate\nevents with an API that helps the developer express its intent. Unlike a lot of\nlogging libraries, the logger doesn't support levels of messages, instead it\nexposes a `Log` and `Debug` methods. Events generated by the `Log` method are\nalways produced by the logger, while those generated by `Debug` may be turned\non or off if necessary.\n\nThe package also exposes a default logger via top-level functions which cover\nthe needs of most programs. The `Log` and `Debug` functions support fmt-style\nformatting but augment the syntax with features that make it simpler to generate\nmeaningful events. Refer to the package's documentation to learn more about it.\n\n### Log message formatting\n\nThe `events` package supports a superset of the `fmt` formatting language. The\npercent-base notation for placeholders is enhanced to automatically generated\nevent arguments from values passed to the call to `Log` or `Debug` functions.\nThis works by inserting an argument name wrapped in braces (`{}`) between the\n`%` sign and the verb of the format.\n\nFor example, this piece of code generates an event that has an argument named\n\"name\" and a value named \"Luke\":\n```go\npackage main\n\nimport (\n    \"github.com/segmentio/events/v2\"\n)\n\nfunc main() {\n    events.Log(\"Hello %{name}s!\", \"Luke\")\n}\n```\n\nNote that using the extended syntax is optional and the regular `fmt` format\nis supported as well.\n\n### Compatibility with the standard library\n\nThe standard `log` package doesn't give much flexibility when it comes to its\nlogger type. It is a concrete type and there is no `Logger` interface which\nwould make it easy to plugin different implementations in packages that need to\nlog events. Unfortunately many of these packages have hard dependencies on the\nstandard logger, making it hard to capture their events and produce them in\ndifferent formats.\nHowever, the `events/log` package is a shim between the standard `log` package,\nand a stream of events. It exposes an API compatible with the standard library,\nand automatically configures the `log` package to reroute the messages it emits\nas events to the default logger.\n\n## Handlers\n\nEvent handlers are the abstraction layer that allows to connect event sources to\narbitrary processing pipelines.\nThe sub-packages provides pre-defiend implementations of handlers.\n\n### text\n\nThe `events/text` package provides the implementation of an event handler which\nformats the event it receives in a human-readable format.\n\n### ecs-logs\n\nThe `events/ecslogs` package provides the implementation of an event handler\nwhich formats the events it receives in a format that is understood by ecs-logs.\n\nWe said the logger doesn't support log levels, however these levels have proven\nuseful to get a signal on a program misbehaving when it starts emitting tons of\n*ERROR* level messages.\nHowever, the program doesn't have to express what the severity level is in order\nto get the right behavior. The `events/ecslogs` package analyzes the events it\nreceives and guess what the level should be, here are the rules:\n- By default events are set to the *INFO* level.\n- If an event was generated from a `Debug` call then handler sets the event\nlevel to *DEBUG*.\n- If the event's arguments contains at least one value that satisfies the\n`error` interface then the level is set to *ERROR*.\nThese rules allow for the best of both worlds, giving the program a small and\nexpressive API to produce events while maintaining compatibility with our\nexisting tools.\n\n#### DEBUG/INFO/ERROR\n\nThe events package has two main log levels (`events.Log` and `events.Debug`),\nbut the `ecslogs` subpackage will automatically extract error values in the\nevent arguments, generate _ERROR_ level messages, and put the error and stack\ntrace (if any is available) into the event data.\n\nFor example, this code will output a structured log message with _ERROR_ level.\n```go\npackage main\n\nimport (\n    \"errors\"\n    \"os\"\n\n    \"github.com/segmentio/events/v2\"\n    \"github.com/segmentio/events/v2/ecslogs\"\n)\n\nfunc main() {\n    events.DefaultHandler = ecslogs.NewHandler(os.Stdout)\n    events.Log(\"something went wrong: %{error}v\", errors.New(\"oops!\"))\n}\n```\n\nOtherwise, events generated by a call to `Log` will be shown as _INFO_ messages\nand events generated by a call to `Debug` will be shown as _DEBUG_ messages.\n\n### Automatic Configuration\n\nThe sub-packages have side-effects when they are imported:\n\nBoth `events/text` and `events/ecslogs` override the default logger's handler\nwhen you import them. If the program's output is a terminal, `events/text` will\nset a handler, while `events/ecslogs` will set a handler if the output is _not_\na terminal.\n\nThis approach mimics what we've achieved in many parts of our software stack and\nhas proven to be a good default, doing the right thing whether the program is\ndealing with a production or development environment.\n\nHere's a code example that is commonly used to configure the events package:\n\n```go\npackage main\n\nimport (\n    \"github.com/segmentio/events/v2\"\n    _ \"github.com/segmentio/events/v2/ecslogs\"\n    _ \"github.com/segmentio/events/v2/text\"\n)\n\nfunc main() {\n    events.Log(\"enjoy!\")\n}\n```\n\n### Errata\n\nThis package only officially supports the latest two Go versions.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsegmentio%2Fevents","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsegmentio%2Fevents","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsegmentio%2Fevents/lists"}