{"id":18143385,"url":"https://github.com/tristanls/telemetry","last_synced_at":"2025-07-10T06:07:50.472Z","repository":{"id":57526483,"uuid":"82419237","full_name":"tristanls/telemetry","owner":"tristanls","description":"Telemetry is a helper for creating and emitting structured telemetry events like logs, metrics, or usage.","archived":false,"fork":false,"pushed_at":"2017-02-26T20:14:37.000Z","size":21,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-06T19:35:22.782Z","etag":null,"topics":["go","golang","logging","metrics","telemetry","usage"],"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/tristanls.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}},"created_at":"2017-02-18T22:10:44.000Z","updated_at":"2023-07-11T09:43:24.000Z","dependencies_parsed_at":"2022-09-07T02:50:43.120Z","dependency_job_id":null,"html_url":"https://github.com/tristanls/telemetry","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/tristanls/telemetry","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tristanls%2Ftelemetry","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tristanls%2Ftelemetry/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tristanls%2Ftelemetry/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tristanls%2Ftelemetry/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tristanls","download_url":"https://codeload.github.com/tristanls/telemetry/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tristanls%2Ftelemetry/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264538137,"owners_count":23624426,"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","logging","metrics","telemetry","usage"],"created_at":"2024-11-01T19:07:12.201Z","updated_at":"2025-07-10T06:07:50.448Z","avatar_url":"https://github.com/tristanls.png","language":"Go","readme":"# Telemetry\n\n_Stability: 1 - [Experimental](https://github.com/tristanls/stability-index#stability-1---experimental)_\n\nTelemetry is a helper for creating and emitting structured telemetry events like logs, metrics, or usage.\n\n## Contributors\n\n[@tristanls](https://github.com/tristanls)\n\n## Contents\n\n* [Usage](#usage)\n    * [Logger](#logger)\n    * [Metrics](#metrics)\n* [Documentation](#documentation)\n* [Releases](#releases)\n\n## Usage\n\nTo run the below example run: `$ go run examples/json_to_stdout.go`.\n\n```go\npackage main\n\nimport (\n\t\"github.com/tristanls/telemetry\"\n)\n\nvar emitter = telemetry.NewEmitter()\nvar writer = telemetry.NewWriter()\n\nfunc main() {\n\n\temitter.AddListener(func(event *telemetry.Event) {\n\t\twriter.Write(event.Marshal())\n\t})\n\n\tevent := telemetry.New().WithProvenance(telemetry.Fields{\n\t\t\"import\":  \"github.com/tristanls/telemetry\",\n\t\t\"version\": \"0.0.0\",\n\t})\n\n\temitter.Emit(event.WithFields(telemetry.Fields{\n\t\t\"type\":    \"log\",\n\t\t\"level\":   \"info\",\n\t\t\"message\": \"hello o/\",\n\t}))\n\n\tdetailedProvenance := event.WithProvenance(telemetry.Fields{\n\t\t\"file\": \"json_to_stdout.go\",\n\t})\n\n\temitter.Emit(detailedProvenance.WithFields(telemetry.Fields{\n\t\t\"type\":        \"metric\",\n\t\t\"name\":        \"web requests\",\n\t\t\"target_type\": \"counter\",\n\t\t\"unit\":        \"Req\",\n\t\t\"value\":       1,\n\t}))\n\n\temitter.Emit(detailedProvenance.WithFields(telemetry.Fields{\n\t\t\"type\":     \"usage\",\n\t\t\"tenantId\": \"tristan1234\",\n\t\t\"usage\": telemetry.Fields{\n\t\t\t\"storage\": telemetry.Fields{\n\t\t\t\t\"request\": telemetry.Fields{\n\t\t\t\t\t\"unit\":  \"Req\",\n\t\t\t\t\t\"value\": 2,\n\t\t\t\t},\n\t\t\t},\n\t\t},\n\t}))\n}\n```\n\nWhich should result in something like:\n\n```json\n{\"level\":\"info\",\"message\":\"hello o/\",\"provenance\":[{\"import\":\"github.com/tristanls/telemetry\",\"version\":\"0.0.0\"}],\"timestamp\":\"2017-02-18T22:02:35.452Z\",\"type\":\"log\"}\n{\"name\":\"web requests\",\"provenance\":[{\"import\":\"github.com/tristanls/telemetry\",\"version\":\"0.0.0\"},{\"file\":\"json_to_stdout.go\"}],\"target_type\":\"counter\",\"timestamp\":\"2017-02-18T22:02:35.452Z\",\"type\":\"metric\",\"unit\":\"Req\",\"value\":1}\n{\"provenance\":[{\"import\":\"github.com/tristanls/telemetry\",\"version\":\"0.0.0\"},{\"file\":\"json_to_stdout.go\"}],\"tenantId\":\"tristan1234\",\"timestamp\":\"2017-02-18T22:02:35.452Z\",\"type\":\"usage\",\"usage\":{\"storage\":{\"request\":{\"unit\":\"Req\",\"value\":2}}}}\n```\n\n### Logger\n\nLogger is a helper for emitting log events using Telemetry.\n\nTo run the example below run: `$ go run examples/logger.go`.\n\n```go\npackage main\n\nimport (\n\t\"github.com/tristanls/telemetry\"\n\t\"github.com/tristanls/telemetry/logger\"\n)\n\nfunc main() {\n\n\t_telemetry := telemetry.New()\n\temitter := telemetry.NewEmitter()\n\twriter := telemetry.NewWriter()\n\n\temitter.AddListener(func(event *telemetry.Event) {\n\t\twriter.Write(event.WithProvenance(telemetry.Fields{\n\t\t\t\"example\": \"github.com/tristanls/telemetry/logger/logger.go\",\n\t\t}).Marshal())\n\t})\n\n\tlog := logger.NewLogger(_telemetry, emitter)\n\n\tlog.Log(logger.Info, \"hello\")\n\tlog.Logf(logger.Debug, \"hello %v\", \"o/\")\n\tlog.Debug(\"debugging\")\n\tlog.Debugf(\"formatted %s\", \"debugging\")\n\tlog.Info(\"informational\")\n\tlog.Infof(\"informational with %s\", \"format\")\n\tlog.Warn(\"warning\")\n\tlog.Warnf(\"warning with %s\", \"format\")\n\tlog.Error(\"error happened\")\n\tlog.Errorf(\"error happened with %s\", \"format\")\n\tlog.Fatal(\"fatally oh, noes\")\n\tlog.Fatalf(\"fatal, but it is not a logger's job to %s\", \"stop the process :/\")\n\n\tevent := _telemetry.WithFields(telemetry.Fields{\n\t\t\"these\":    \"will be\",\n\t\t\"included\": \"in all events extend this one\",\n\t})\n\n\tlog.Loge(logger.Warn, event, \"hello\")\n\tlog.Logef(logger.Error, event, \"formatted with %v\", \"provided format\")\n\tlog.Debuge(event, \"debugged\")\n\tlog.Debugef(event, \"formatted %s\", \"debugging\")\n\tlog.Infoe(event, \"informational\")\n\tlog.Infoef(event, \"informational with %s\", \"format\")\n\tlog.Warne(event, \"warning\")\n\tlog.Warnef(event, \"warning with %s\", \"format\")\n\tlog.Errore(event, \"error happened\")\n\tlog.Erroref(event, \"error happened with %s\", \"format\")\n\tlog.Fatale(event, \"fatally oh, noes\")\n\tlog.Fatalef(event, \"fatal, but it is not a logger's job to %s\", \"stop the process :/\")\n}\n```\n\n### Metrics\n\nMetrics is a helper for emitting metric events using Telemetry.\n\nTo run the example below run: `$ go run examples/metrics.go`.\n\n```go\npackage main\n\nimport (\n\t\"github.com/tristanls/telemetry\"\n\t\"github.com/tristanls/telemetry/metrics\"\n)\n\nfunc main() {\n\n\t_telemetry := telemetry.New()\n\temitter := telemetry.NewEmitter()\n\twriter := telemetry.NewWriter()\n\n\temitter.AddListener(func(event *telemetry.Event) {\n\t\twriter.Write(event.WithProvenance(telemetry.Fields{\n\t\t\t\"example\": \"github.com/tristanls/telemetry/examples/metrics.go\",\n\t\t}).Marshal())\n\t})\n\n\tm := metrics.NewMetrics(_telemetry, emitter)\n\n\tm.Metric(_telemetry.WithFields(telemetry.Fields{\n\t\t\"name\":        \"my.gauge\",\n\t\t\"target_type\": \"gauge\",\n\t\t\"unit\":        \"ms\",\n\t\t\"value\":       133,\n\t}))\n\tm.Counter(\"my.counter\", _telemetry.WithFields(telemetry.Fields{\n\t\t\"unit\":  \"Req\",\n\t\t\"value\": 123,\n\t}))\n\tm.Gauge(\"my.gauge\", _telemetry.WithFields(telemetry.Fields{\n\t\t\"unit\":  \"ms\",\n\t\t\"value\": 133,\n\t}))\n\tm.Histogram(\"search.results.returned\", _telemetry.WithFields(telemetry.Fields{\n\t\t\"value\": telemetry.Fields{\n\t\t\t\"measureUnit\":       \"request\",\n\t\t\t\"sampleSizeUnit\":    \"Req\",\n\t\t\t\"updateCount\":       2,\n\t\t\t\"max\":               7122,\n\t\t\t\"mean\":              4174.5,\n\t\t\t\"median\":            7122,\n\t\t\t\"min\":               1227,\n\t\t\t\"percentile75\":      7122,\n\t\t\t\"percentile95\":      7122,\n\t\t\t\"percentile98\":      7122,\n\t\t\t\"percentile99\":      7122,\n\t\t\t\"percentile999\":     7122,\n\t\t\t\"standardDeviation\": 2947.5,\n\t\t\t\"sampleSize\":        2,\n\t\t},\n\t}))\n\tm.Meter(\"requests\", _telemetry.WithFields(telemetry.Fields{\n\t\t\"value\": telemetry.Fields{\n\t\t\t\"rateUnit\":          \"Req/s\",\n\t\t\t\"updateCount\":       11,\n\t\t\t\"updateCountUnit\":   \"Req\",\n\t\t\t\"meanRate\":          692.3612402089173,\n\t\t\t\"oneMinuteRate\":     0,\n\t\t\t\"fiveMinuteRate\":    0,\n\t\t\t\"fifteenMinuteRate\": 0,\n\t\t},\n\t}))\n\tm.Timer(\"request.latency\", _telemetry.WithFields(telemetry.Fields{\n\t\t\"value\": telemetry.Fields{\n\t\t\t\"measureUnit\":       \"ms\",\n\t\t\t\"rateUnit\":          \"Req/s\",\n\t\t\t\"sampleSizeUnit\":    \"Req\",\n\t\t\t\"updateCount\":       2,\n\t\t\t\"meanRate\":          125.82722724393419,\n\t\t\t\"oneMinuteRate\":     0,\n\t\t\t\"fiveMinuteRate\":    0,\n\t\t\t\"fifteenMinuteRate\": 0,\n\t\t\t\"max\":               178,\n\t\t\t\"mean\":              89.01773188379212,\n\t\t\t\"median\":            178,\n\t\t\t\"min\":               0.03412902355194092,\n\t\t\t\"percentile75\":      178,\n\t\t\t\"percentile95\":      178,\n\t\t\t\"percentile98\":      178,\n\t\t\t\"percentile99\":      178,\n\t\t\t\"percentile999\":     178,\n\t\t\t\"standardDeviation\": 88.98293548572138,\n\t\t\t\"sampleSize\":        2,\n\t\t},\n\t}))\n}\n```\n\n## Documentation\n\nPlease refer to [generated Go documentation](https://godoc.org/github.com/tristanls/telemetry)\n\n## Releases\n\nWe follow semantic versioning policy ([semver.org](http://semver.org/)) with a caveat:\n\n\u003e Given a version number MAJOR.MINOR.PATCH, increment the:\n\u003e\n\u003eMAJOR version when you make incompatible API changes,\u003cbr/\u003e\n\u003eMINOR version when you add functionality in a backwards-compatible manner, and\u003cbr/\u003e\n\u003ePATCH version when you make backwards-compatible bug fixes.\n\n**caveat**: Major version zero is a special case indicating development version that may make incompatible API changes without incrementing MAJOR version.","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftristanls%2Ftelemetry","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftristanls%2Ftelemetry","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftristanls%2Ftelemetry/lists"}