{"id":18256859,"url":"https://github.com/kkamkou/node-gelf-pro","last_synced_at":"2025-04-06T13:11:11.779Z","repository":{"id":17537293,"uuid":"20339948","full_name":"kkamkou/node-gelf-pro","owner":"kkamkou","description":"Graylog2 client library for Node.js","archived":false,"fork":false,"pushed_at":"2024-03-27T17:40:32.000Z","size":281,"stargazers_count":68,"open_issues_count":3,"forks_count":29,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-04-15T07:27:21.899Z","etag":null,"topics":["gelf","graylog","node-js","ssl","tcp","tls","udp"],"latest_commit_sha":null,"homepage":"https://docs.graylog.org/docs/gelf","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/kkamkou.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":"2014-05-30T19:26:14.000Z","updated_at":"2024-06-27T14:40:08.374Z","dependencies_parsed_at":"2023-01-14T13:00:41.014Z","dependency_job_id":"5e1130d4-ff15-4fbe-8d67-22a42284b9cb","html_url":"https://github.com/kkamkou/node-gelf-pro","commit_stats":{"total_commits":205,"total_committers":12,"mean_commits":"17.083333333333332","dds":0.3853658536585366,"last_synced_commit":"81050011e5e133a2446a2aca29701af9d37ccdaf"},"previous_names":[],"tags_count":38,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kkamkou%2Fnode-gelf-pro","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kkamkou%2Fnode-gelf-pro/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kkamkou%2Fnode-gelf-pro/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kkamkou%2Fnode-gelf-pro/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kkamkou","download_url":"https://codeload.github.com/kkamkou/node-gelf-pro/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247485287,"owners_count":20946398,"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":["gelf","graylog","node-js","ssl","tcp","tls","udp"],"created_at":"2024-11-05T10:23:56.123Z","updated_at":"2025-04-06T13:11:11.758Z","avatar_url":"https://github.com/kkamkou.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"gelf pro\n=============\n`gelf-pro` - Graylog2 client library for Node.js.  \nSends logs to Graylog2 server in GELF (Graylog Extended Log Format) format.\n\n**Features:**\n- JS object marshalling\n- UDP/TCP/TLS support\n- Filtering, Transforming, Broadcasting.\n\n![Build Status](https://github.com/kkamkou/node-gelf-pro/actions/workflows/node.js.yml/badge.svg?branch=master)\n![Coverage Status](https://coveralls.io/repos/github/kkamkou/node-gelf-pro/badge.svg?branch=master)\n\n## Installation\n```\n\"dependencies\": {\n  \"gelf-pro\": \"~1.4\" // see the \"releases\" section\n}\n```\n\n`npm install gelf-pro` (**ALL** node.js versions are supported [0.x to 2x.x] :)\n\nLibrary only depends on: `lodash#~4.17`\n\n## Initialization\n```javascript\nvar log = require('gelf-pro');\n```\n\n### Adapters\n\n\u003e [!WARNING]\n\u003e To ensure consistent behavior, **none of the existing adapters re-use the socket connection**. Re-using socket connections can lead to resource leakage, complexity in state management, concurrency issues, security risks, and may not always provide significant performance benefits.\n\u003e It's often simpler and safer to establish new connections as needed rather than re-using existing ones, ensuring better resource utilization and reducing potential complications in network communication.\n\u003e\n\u003e There are multiple ([1](https://github.com/kkamkou/node-gelf-pro/pull/68), [2](https://github.com/fdelayen/node-gelf-pro/commit/b52b4b6b1ff26772314b8673dd6fd724c0937caa)) variants available for you to borrow from and create a new adapter. [See related section](#third-party-adapters).\n\n- UDP (with deflation and chunking)\n  - Input: `GELF UDP`\n- TCP\n  - Input: `GELF TCP` (with `Null frame delimiter`)\n- TCP via TLS(SSL)\n  - Input: `GELF TCP` (with `Null frame delimiter` and `Enable TLS`)\n\n\n\u003e [!NOTE]\n\u003e Within a more or less stable network (which is most likely), I would recommend using the `udp` adapter.\n\u003e I would also recommend it for an average to high-loaded project.\n\u003e For sensitive information, the `tcp-tls` adapter is recommended.\n\n### Configuration\n```javascript\n// simple\nlog.setConfig({adapterOptions: {host: 'my.glog-server.net'}});\n\n// advanced\nlog.setConfig({\n  fields: {facility: \"example\", owner: \"Tom (a cat)\"}, // optional; default fields for all messages\n  filter: [], // optional; filters to discard a message\n  transform: [], // optional; transformers for a message\n  broadcast: [], // optional; listeners of a message\n  levels: {}, // optional; default: see the levels section below\n  aliases: {}, // optional; default: see the aliases section below\n  adapterName: 'udp', // optional; currently supported \"udp\", \"tcp\" and \"tcp-tls\"; default: udp\n  adapterOptions: { // this object is passed to the adapter.connect() method\n    // common\n    host: '127.0.0.1', // optional; default: 127.0.0.1\n    port: 12201, // optional; default: 12201\n    // ... and so on\n    \n    // tcp adapter example\n    family: 4, // tcp only; optional; version of IP stack; default: 4\n    timeout: 1000, // tcp only; optional; default: 10000 (10 sec)\n    \n    // udp adapter example\n    protocol: 'udp4', // udp only; optional; udp adapter: udp4, udp6; default: udp4\n    \n    // tcp-tls adapter example\n    key: fs.readFileSync('client-key.pem'), // tcp-tls only; optional; only if using the client certificate authentication\n    cert: fs.readFileSync('client-cert.pem'), // tcp-tls only; optional; only if using the client certificate authentication\n    ca: [fs.readFileSync('server-cert.pem')] // tcp-tls only; optional; only for the self-signed certificate\n  }\n});\n```\n\u003e `log.setConfig` merges the data. Therefore, you can call it multiple times.\n\n### Basic functionality\n```javascript\nvar extra = {tom: 'cat', jerry: 'mouse', others: {spike: 1, tyke: 1}};\n\nlog.info(\"Hello world\", extra, function (err, bytesSent) {});\nlog.info(\"Hello world\", function (err, bytesSent) {});\nlog.info(\"Hello world\", extra);\nlog.info(\"Hello world\");\n\nlog.error('Oooops.', new Error('An error message'));\n// ^-- extra becomes: {short_message: 'Oooops.', _error_message: 'An error message', _error_stack: Error's stack}\n\nlog.error(new Error('An error message'));\n// ^-- extra becomes: {short_message: 'An error message', full_message: Error's stack}\n\nlog.message(new Error('An error message'), 3); // same as previous\n```\n\n##### Extra\nIn case `extra` [is a plain object](https://lodash.com/docs#isPlainObject),\nthe library converts it to a readable format. Other values [are converted to string](https://lodash.com/docs#toString).\nThe acceptable format of a key is: `^[\\w-]$`\n```javascript\nlog.info(\n  'a new msg goes here',\n  {me: {fname: 'k', lname: 'k', bdate: new Date(2000, 01, 01)}}\n);\n// ^-- extra becomes: {_me_fname: 'k', _me_lname: 'k', _me_bdate: 'Tue Feb 01 2000 00:00:00 GMT+0100 (CET)'}\n```\n\n##### Filtering\nSometimes we have to discard a message which is not suitable for the current environment. It is `NOT` possible to modify the data.\n```javascript\nlog.setConfig({\n  filter: [\n    function (message) { // rejects a \"debug\" message\n      return (message.level \u003c 7);\n    }\n  ]\n});\n```\n\n##### Transforming\n`transforming` happens after `filtering`. It is possible to modify the data.\n\n```javascript\nlog.setConfig({\n  transform: [\n    function (message) { // unwind an error\n      if (_.isError(message.error)) {\n        message.error = {message: message.error.message, stack: message.error.stack};\n      }\n      return message;\n    }\n  ]\n});\n```\n\n##### Broadcasting\n`broadcasting` happens after `transforming`. It is `NOT` possible to modify the data.\n\n```javascript\nlog.setConfig({\n  broadcast: [\n    function (message) { // broadcasting to console\n      console[message.level \u003e 3 ? 'log' : 'error'](message.short_message, message);\n    }\n  ]\n});\n```\n\n### Levels ([1](https://httpd.apache.org/docs/current/mod/core.html#loglevel), [2](https://logging.apache.org/log4j/2.0/log4j-api/apidocs/org/apache/logging/log4j/Level.html), [3](http://stackoverflow.com/questions/2031163/when-to-use-the-different-log-levels))\n\nDefault:  \n`{emergency: 0, alert: 1, critical: 2, error: 3, warning: 4, notice: 5, info: 6, debug: 7}`  \nExample: `log.emergency(...)`, `log.critical(...)`, etc.  \nCustom example: `{alert: 0, notice: 1, ...}`\n\n### Third party adapters\nYou can force using custom adapter by setting the `adapter` right after initialisation.  The [signature](lib/adapter/abstract.js) might be found here. \n```javascript\n  var log = require('gelf-pro');\n  var myFancyAdapter = require('...');\n  log.adapter = myFancyAdapter;\n  // (!) adapterName and adapterOptions will be ignored\n```\n\n### Aliases\n\nDefault: `{log: 'debug', warn: 'warning'}`  \nExample: `log.log(...) -\u003e log.debug(...)`, `log.warn(...) -\u003e log.warning(...)`, etc.  \nCustom example: `{red: 'alert', yellow: 'notice', ...}`\n\n### Tests\n#### Cli\n```bash\nnpm install\nnpm test\n```\n\n#### Docker\n```bash\n[sudo] docker build --no-cache -t node-gelf-pro .\n[sudo] docker run -ti --rm -v \"${PWD}:/opt/app\" -w \"/opt/app\" node-gelf-pro\n```\n\n#### Contributors\n\n- [corbinu](https://github.com/corbinu)\n- [joelharkes](https://github.com/joelharkes)\n- [mkalam-alami](https://github.com/mkalam-alami)\n\n#### License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkkamkou%2Fnode-gelf-pro","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkkamkou%2Fnode-gelf-pro","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkkamkou%2Fnode-gelf-pro/lists"}