{"id":18915185,"url":"https://github.com/uber-common/larch","last_synced_at":"2025-04-15T08:31:42.290Z","repository":{"id":57384375,"uuid":"44686881","full_name":"uber-common/larch","owner":"uber-common","description":"A reservoir sampling logging framework","archived":false,"fork":false,"pushed_at":"2019-10-19T21:07:22.000Z","size":77,"stargazers_count":6,"open_issues_count":2,"forks_count":2,"subscribers_count":2547,"default_branch":"master","last_synced_at":"2025-03-23T15:17:05.566Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://www.uber.com","language":"JavaScript","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/uber-common.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":"2015-10-21T15:44:04.000Z","updated_at":"2022-09-22T08:56:04.000Z","dependencies_parsed_at":"2022-09-14T00:52:33.177Z","dependency_job_id":null,"html_url":"https://github.com/uber-common/larch","commit_stats":null,"previous_names":["uber/larch"],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uber-common%2Flarch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uber-common%2Flarch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uber-common%2Flarch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uber-common%2Flarch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/uber-common","download_url":"https://codeload.github.com/uber-common/larch/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249035604,"owners_count":21202121,"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":[],"created_at":"2024-11-08T10:14:45.337Z","updated_at":"2025-04-15T08:31:42.063Z","avatar_url":"https://github.com/uber-common.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Larch\n\nIt's a logging framework. Currently it's main use is to reservoir sample logs\nand forward them to [Logtron](http://github.com/uber/logtron). In the long\nterm, it may replace Logtron. It can be used like this:\n\n```javascript\nvar Logtron = require('logtron');\n\nvar Larch = require('larch');\nvar LogtronBackend = require('larch/logtron-backend');\nvar ReservoirBackend = require('larch/reservoir-backend');\n\nvar clients = ...\nvar logtronLogger = Logtron({...});\n\nvar logger = Larch({\n    backends: [ReservoirBackend({\n        backend: LogtronBackend(logtronLogger),\n        statsd: clients.statsd,\n        clusterStatsd: clients.clusterStatsd,\n        size: 100,\n        flushInterval: 50\n    })]\n});\nlogger.bootstrap();\n\nlogger.warn('warn string', {meta: 'object'});\n```\n\n## Docs\n\n## `Larch({ backends: Array })`\n\n`Larch` is a constructor that takes a list of backends.\n\nGenerally you want to use the `ReservoirBackend`\n\n### `larch.bootstrap()`\n\nRemember to call `bootstrap()` on larch to start the reservoir.\n\n## `ReservoirBackend(opts)`\n\n`ReservoirBackend` takes a set of options including:\n\n - `backend`; what to write to if we sample the log call\n - `statsd`; where to emit stats.\n - `clusterStatsd`; where to emit cluster-wide latency stats.\n - `size`; The amount of records that can be logged per interval\n - `flushInterval`; How often we should flush the reservoir\n\nThe reservoir will log (1000 / `flushInterval`) * `size` records per second.\n\nThis means by default it will log `2000` records per second.\n\n## Using `willSample($level, $msg)`\n\nThe top level Larch object, as well as each backend, has a method `willSample`.\nThis method returns `true` if any backend after this backend in the object tree\nis interested in taking a log with level `$level`. This can be used to avoid\nallocating space for large meta objects, like so:\n\n```javascript\nif (larch.willSample('warn', 'thing failed!')) {\n    larch.swarn('thing failed!', {\n        count: this.count,\n        length: this.length,\n        largeArrayOfThings: this.bigArray,\n        hugeAmountOfUsefulDebuggingInfo: this.stuff\n    });\n}\n```\n\nThis way, we can do less work when we have a lot of logs because we don't have\nto allocate the large meta object.\n\nRegular log methods (`.log`, `.error`, etc) will first compute a sampling\ndecision. Log methods prefixed with an `s` (`.slog`, `.serror`, etc) will use\na previously computed sampling decision. Calling an `s` method without first\ncalling `.willSample($level, $msg)` will throw.\n\n# Contributors\n\n* [Russ Frank](http://github.com/rf)\n* [Mark Yen](http://github.com/markyen)\n\n# License\n\nMIT.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuber-common%2Flarch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fuber-common%2Flarch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuber-common%2Flarch/lists"}