{"id":15013425,"url":"https://github.com/fgm/filog","last_synced_at":"2025-04-12T04:44:11.722Z","repository":{"id":47947772,"uuid":"71136400","full_name":"fgm/filog","owner":"fgm","description":"A fine logger package for Meteor.JS applications (client + server)","archived":false,"fork":false,"pushed_at":"2021-08-11T15:25:38.000Z","size":5171,"stargazers_count":18,"open_issues_count":15,"forks_count":6,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-03-26T00:13:01.071Z","etag":null,"topics":["log","logger","logging","meteor","meteorjs","mongodb","psr-3","syslog","typescript"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fgm.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null}},"created_at":"2016-10-17T12:31:39.000Z","updated_at":"2021-01-12T12:43:57.000Z","dependencies_parsed_at":"2022-08-12T14:51:26.330Z","dependency_job_id":null,"html_url":"https://github.com/fgm/filog","commit_stats":null,"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fgm%2Ffilog","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fgm%2Ffilog/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fgm%2Ffilog/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fgm%2Ffilog/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fgm","download_url":"https://codeload.github.com/fgm/filog/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248182080,"owners_count":21060893,"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":["log","logger","logging","meteor","meteorjs","mongodb","psr-3","syslog","typescript"],"created_at":"2024-09-24T19:44:16.020Z","updated_at":"2025-04-12T04:44:11.700Z","avatar_url":"https://github.com/fgm.png","language":"TypeScript","readme":"FiLog: a Meteor 1.9 logging package\n===================================\n\n[![Build Status](https://travis-ci.org/fgm/filog.svg?branch=master)](https://travis-ci.org/fgm/filog)\n[![CodeCov Test Coverage](https://codecov.io/gh/fgm/filog/branch/master/graph/badge.svg)](https://codecov.io/gh/fgm/filog)\n[![codebeat badge](https://codebeat.co/badges/b1379317-2bc2-4059-b640-c393f3ad20ea)](https://codebeat.co/projects/github-com-fgm-filog-63ts-source_processor)\n[![Known Vulnerabilities](https://snyk.io/test/github/fgm/filog/badge.svg?targetFile=package.json)](https://snyk.io/test/github/fgm/filog?targetFile=package.json)\n[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Ffgm%2Ffilog.svg?type=shield)](https://app.fossa.io/projects/git%2Bgithub.com%2Ffgm%2Ffilog?ref=badge_shield)\n\nFiLog is a highly configurable isomorphic logger for Meteor applications,\nsupporting configurable logging strategies and custom processing and log sending\ndestinations.\n\nOut of the box, it can log to the console (browser, server), the Meteor database,\nany Syslog server, and includes a \"tee\" logger to send to multiple destinations.\nOn the browser, it can log to its own Meteor server over DDP, or to a\ncentralized FiLog log aggregation server over HTTP.\n\nFiLog is based upon low-level NPM packages::\n\n* Stack capture and standardization: https://www.npmjs.com/package/tracekit\n* Meteor user capture in call stack: https://www.npmjs.com/package/callsite\n\nRead the [Documentation](https://fgm.github.io/filog).\n\n\nConfiguration and usage\n-----------------------\n\n#### Main ideas:\n\n* A logged event is a `(level, message, context)` triplet, in which\n    * `level` is an RFC5424 number (0..7)\n    * `message` is a plain string or can be converted to one automatically\n    * `context` is a plain Object\n* the package has no configuration of its own, it is entirely\n  configured by its users, the client- and server-side Meteor parts of the\n  application.\n* Both client and server applications may capture exception stack traces and log\n  them for plain errors (`window.onerror` handling) and exception reporting.\n  This is triggered by the `logger.arm()` method, and can be disabled by the\n  `logger.disarm()` method.\n\n#### Typical use case:\n\n- `client/main.js`:\n  - instantiates any number of \"processors\": instances of classes derived from\n    `ProcessorBase`. These are able to add information to a message on its way\n    to the logging destination. Current concrete processors are:\n    - `BrowserProcessor`: adds browser-related information, such as user\n      agent, platform, operating system, client memory\n    - `MeteorUserProcessor`: adds user-related information if any is\n      available. Assumes the application is configured with some Meteor\n      accounts package, like `fgm:accounts-drupal`.\n    - `RoutingProcessor`: adds request-related information, such as the\n      path being served.\n  - instantiates any number of \"senders\": instances of classes derived from\n    `SenderBase`. These are able to receive a `(level, message, context)`\n    triplet (\"event\") and forward it somwhere else. Current concrete senders\n    are:\n    - `ConsoleSender`: output the message using `console.log`\n    - `MeteorClientHttpSender`: HTTP POST the message to the Meteor server\n      present at the URL defined by the Meteor-standard `ROOT_URL`\n      environment variable.\n    - `MongodbSender`: store the event in a collection in the Meteor MongoDB\n      database instance (or the minimongo on the client).\n    - `NullSender`: ignore the message.\n    - `SyslogSender`: send the event to syslog, on server only: including it on\n      client will fail.\n    - `TeeSender`: send the event to all sender instances passed to its \n      constructor as an array. Useful to send logs to multiple destinations.\n  - instantiate a sending \"strategy\": instance of a class derived from\n    `StrategyBase`. There are able to decide, based on an event, where it\n    should be sent by available senders. They may also modify the logger\n    instance at the last step of its construction, Two concrete strategies are\n    currently available:\n    - `LeveledStrategy`: based on the level of the message, it defines three\n      severity levels: low, medium, and high, as well as the breakpoints\n      between them in terms of RFC5424 levels, and associates a sender\n      instance with each of these levels\n    - `TrivialStrategy` uses a single sender for all messages. Especially useful \n      for early work client-side, where you want everything to be stored to \n      collect as much information as possible from a limited number of clients.\n      May also be useful for tests, to simplify test setup.\n  - constructs a `ClientLogger` instance, passing it the strategy instance, like:\n\n          let logger = new ClientLogger(new LeveledStrategy(\n            new NullSender(),\n            new ConsoleSender(),\n            new MeteorClientHttpSender(Meteor.absoluteUrl('logger'))\n          ));\n\n  - adds processor instances to the logger instance, like:\n\n          logger.processors.push(\n            new BrowserProcessor(),\n            new RoutingProcessor(),\n            new MeteorUserProcessor(Meteor)\n          );\n\n  - is now able to log events, like:\n\n          logger.warn(\"Some warning condition\", { foo: \"bar\" });\n\n  - with this configuration:\n    - logger applies processors to add browser, user, and routing information\n      to the message context\n    - since warnings are considered worthy of storage (default configuration\n      of the `LeveledStrategy` constructor), the logger passes the now-rich\n      message to the Meteor server thanks to the `MeteorClientHttpSender`\n      sender\n    - message arrives server-side.\n- `server/main.js`\n  - is configured in much the same way as the client, so it has its own `logger`,\n    typically configured with just a `MongodbSender` instance for all levels.\n\n        let sender = new MongodbSender(Mongo, 'logger');\n        let logger = new ServerLogger(\n          new LeveledStrategy(sender, sender, sender),\n          WebApp);\n        logger.processors.push(new MeteorUserProcessor());\n\n  - in the example above, it receives the POSTed event, and proceed to log it\n    - because it has already been processed client-side, it is logged \"raw\",\n      without applying additional processors to it\n    - the MongoDb sender instance stores the event.\n  - the server may also initiate a logging action, for example in a publish\n    function or Meteor method. It can use the same API:\n\n        logger.error(\"Some server condition\", { baz: \"quux\" }\n\n    - since the message is server-originated, the server processors will be\n      applied, to add the Meteor user information to the event\n    - the MongoDb sender instance stores the event.\n\n\nFormat note\n-----------\n\n- Whatever the enabled processors, the `Logger.log()` method adds a\n  millisecond-level timestamp to each context, under the `timestamp.log` key.\n- Senders designed to exit the system, like the MongoDB sender, or a syslog or\n  logstash Beats forwarder, are expected to add another millisecond-level \n  timestamp, under the `timestamp.store` key.\n\nThese two timestamps are here to alleviate any issue resulting from a clock\ndifference between clients and servers.\n\nAny sender can add extra keys to the context, under the `timestamp` main key,\nto enable timing diagnostics.\n\n\nRunning tests\n-------------\n\nThe module contains tests. Some of them are unit tests and need nothing special\nto run, while others are currently implemented as integration tests and assume\nyou have a working harness project using Filog, exposed on \n`http://localhost:3000`.\n\nStart by compiling the package:\n\n* `meteor yarn run ts-compile`\n\nThen you can run :\n\n* just unit tests with `meteor yarn run test-unit` \n* just integration tests with `meteor yarn run test-integration`\n* both tests with `meteor yarn run test`\n* both tests including coverage generation with `meteor yarn run cover`\n \nTo run integration tests, you need to run the provided test_harness project in\none terminal, and the tests in another one. Alternatively, you could also roll\nyour own bespoke test harness, which will need to have Filog configured.\n\n\n#### Example server-side code in the test_harness/ directory\n\nThis file is needed to allow Filog to operate on the `/logger` URL: otherwise, \nMeteor will handle it natively and return a 200 with the default application \npage, failing the integration tests.\n\n\n#### Terminal 1\n\n```bash\ncd (filog_dir)/test_harness\nmeteor yarn\nmeteor run --port 3100\n```\n\nThis example uses port 3100 to avoid conflicting with existing applications on\nthe default Meteor port (3000). To use another port, be sure to change it in \n`__tests__/integration/harness.ts` too.\n\n\n#### Terminal 2\n\n```bash\ncd (filog_dir)\nmeteor yarn\nmeteor yarn run compile\nmeteor yarn run test\nmeteor yarn run cover\n```\n\n**TIP** Reading the `.travis.yml` file can be useful too.\n\n\n## License\n[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Ffgm%2Ffilog.svg?type=large)](https://app.fossa.io/projects/git%2Bgithub.com%2Ffgm%2Ffilog?ref=badge_large)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffgm%2Ffilog","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffgm%2Ffilog","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffgm%2Ffilog/lists"}