{"id":28501864,"url":"https://github.com/fluent/fluent-logger-forward-node","last_synced_at":"2025-07-05T02:32:03.261Z","repository":{"id":38348840,"uuid":"379283984","full_name":"fluent/fluent-logger-forward-node","owner":"fluent","description":"A fluent forward protocol implementation for Node.js","archived":false,"fork":false,"pushed_at":"2023-05-09T15:32:56.000Z","size":560,"stargazers_count":12,"open_issues_count":7,"forks_count":9,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-06-25T21:40:52.119Z","etag":null,"topics":["fluent","fluent-bit","fluentd","forward","logger","node"],"latest_commit_sha":null,"homepage":"https://fluent.github.io/fluent-logger-forward-node/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fluent.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","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":"2021-06-22T13:43:19.000Z","updated_at":"2025-05-14T07:28:05.000Z","dependencies_parsed_at":"2024-06-18T18:37:42.952Z","dependency_job_id":null,"html_url":"https://github.com/fluent/fluent-logger-forward-node","commit_stats":{"total_commits":52,"total_committers":5,"mean_commits":10.4,"dds":0.07692307692307687,"last_synced_commit":"937ad65703067cad762570c2e60fad4c6262255c"},"previous_names":["jamiees2/fluentd-node"],"tags_count":27,"template":false,"template_full_name":null,"purl":"pkg:github/fluent/fluent-logger-forward-node","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fluent%2Ffluent-logger-forward-node","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fluent%2Ffluent-logger-forward-node/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fluent%2Ffluent-logger-forward-node/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fluent%2Ffluent-logger-forward-node/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fluent","download_url":"https://codeload.github.com/fluent/fluent-logger-forward-node/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fluent%2Ffluent-logger-forward-node/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263671746,"owners_count":23494027,"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":["fluent","fluent-bit","fluentd","forward","logger","node"],"created_at":"2025-06-08T16:08:12.065Z","updated_at":"2025-07-05T02:32:03.256Z","avatar_url":"https://github.com/fluent.png","language":"TypeScript","readme":"# @fluent-org/logger\n[![Build Status](https://github.com/fluent/fluent-logger-forward-node/actions/workflows/main.yml/badge.svg)](https://github.com/fluent/fluent-logger-forward-node/actions)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![Docs](https://img.shields.io/badge/Docs-latest-informational)](https://fluent.github.io/fluent-logger-forward-node/)\n\n[Fluent Forward Protocol](https://github.com/fluent/fluentd/wiki/Forward-Protocol-Specification-v1) implementation for Node.js. \nBuilt upon [fluent-logger-node](https://github.com/fluent/fluent-logger-node).\n\n[![NPM](https://nodeico.herokuapp.com/@fluent-org/logger.svg)](https://npmjs.com/package/@fluent-org/logger)\n\n## Install\n\n    $ npm install @fluent-org/logger\n\n## Client\n`@fluent-org/logger` provides a fully functional client that implements the Forward protocol. It supports reconnection, acknowledgements, timeouts, event retries, and more, and exposes its functionality via a simple typed Promise interface.\n\nFor a full list of the client options and methods, see the [FluentClient docs](https://fluent.github.io/fluent-logger-forward-node/classes/FluentClient.html)\n\n### Prerequisites\nThe fluent daemon should be listening in forward mode.\n\nA simple starting configuration for Fluentd is the following:\n```aconf\n\u003csource\u003e\n  @type forward\n  port 24224\n\u003c/source\u003e\n\n\u003cmatch **.*\u003e\n  @type stdout\n\u003c/match\u003e\n```\n\nSee the [FluentD docs](https://docs.fluentd.org/input/forward) for more info.\n\nA similar starting configuration for Fluent Bit is the following:\n```ini\n[INPUT]\n    Name              forward\n    Listen            0.0.0.0\n    Port              24224\n    Buffer_Chunk_Size 1M\n    Buffer_Max_Size   6M\n\n[OUTPUT]\n    Name   stdout\n    Match  *\n```\n\nSee the [Fluent Bit docs](https://docs.fluentbit.io/manual/pipeline/inputs/forward) for more info.\n\n### Sending an event record to an upstream Fluent server\n\n```js\nconst FluentClient = require(\"@fluent-org/logger\").FluentClient;\nconst logger = new FluentClient(\"tag_prefix\", {\n  socket: {\n    host: \"localhost\",\n    port: 24224,\n    timeout: 3000, // 3 seconds\n  }\n});\n```\n\nThe emit method has following signature\n\n```typescript\nemit(data: Record\u003cstring, any\u003e): Promise\u003cvoid\u003e;\nemit(data: Record\u003cstring, any\u003e, timestamp: number | Date | EventTime): Promise\u003cvoid\u003e;\nemit(label: string, data: Record\u003cstring, any\u003e): Promise\u003cvoid\u003e;\nemit(label: string, data: Record\u003cstring, any\u003e, timestamp: number | Date | EventTime): Promise\u003cvoid\u003e;\n```\n\nThe returned Promise is resolved once the event is written to the socket, or rejected if an error occurs.\n\n### Acknowledgements\nThe [Fluent forward protocol](https://github.com/fluent/fluentd/wiki/Forward-Protocol-Specification-v1) provides explicit support for acknowledgements, which allow the client to be sure that the event reached its destination.\n\nEnabling acknowledgements means that the promise returned by `emit` will be resolved once the client receives an explicit acknowledgement from the server.\n```js\nconst FluentClient = require(\"@fluent-org/logger\").FluentClient;\nconst logger = new FluentClient(\"tag_prefix\", {\n  ack: {}\n});\n```\n\n### Event modes\nThe [Fluent forward protocol](https://github.com/fluent/fluentd/wiki/Forward-Protocol-Specification-v1) provides multiple message modes, `Message`, `Forward`, `PackedForward`(default), `CompressedPackedForward`. The Fluent client supports all of them.\n\n\n```js\nconst FluentClient = require(\"@fluent-org/logger\").FluentClient;\nconst logger = new FluentClient(\"tag_prefix\", {\n  eventMode: \"Message\" | \"Forward\" | \"PackedForward\" | \"CompressedPackedForward\"\n});\n```\n\n\n### Disable automatic reconnect \n```js\nconst logger = new FluentClient(\"tag_prefix\", {\n  socket: {\n    host: \"localhost\",\n    port: 24224,\n    timeout: 3000, // 3 seconds\n    disableReconnect: true\n  }\n});\n// If you disable reconnections, the socket has to be manually connected, \n// connect() returns a promise, which rejects on connection errors.\nlogger.connect();\n```\n\n### Shared key authentication\n\nLogger configuration:\n\n```js\nconst logger = new FluentClient(\"tag_prefix\", {\n  socket: {\n    host: \"localhost\",\n    port: 24224,\n    timeout: 3000, // 3 seconds\n  },\n  security: {\n    clientHostname: \"client.localdomain\",\n    sharedKey: \"secure_communication_is_awesome\"\n  }\n});\n```\n\nFluentd configuration:\n\n```aconf\n\u003csource\u003e\n  @type forward\n  port 24224\n  \u003csecurity\u003e\n    self_hostname input.testing.local\n    shared_key secure_communication_is_awesome\n  \u003c/security\u003e\n\u003c/source\u003e\n\n\u003cmatch dummy.*\u003e\n  @type stdout\n\u003c/match\u003e\n```\n\nSee also the [Fluentd](https://github.com/fluent/fluentd) examples.\n\n### TLS/SSL encryption\n\nLogger configuration:\n\n```js\nconst logger = new FluentClient(\"tag_prefix\", {\n  socket: {\n    host: \"localhost\",\n    port: 24224,\n    timeout: 3000, // 3 seconds\n    tls: {\n      ca: fs.readFileSync(\"/path/to/ca_cert.pem\")\n    },\n  },\n  security: {\n    clientHostname: \"client.localdomain\",\n    sharedKey: \"secure_communication_is_awesome\"\n  },\n});\n```\n\nFluentd configuration:\n\n```aconf\n\u003csource\u003e\n  @type forward\n  port 24224\n  \u003ctransport tls\u003e\n    ca_cert_path /path/to/ca_cert.pem\n    ca_private_key_path /path/to/ca_key.pem\n    ca_private_key_passphrase very_secret_passphrase\n  \u003c/transport\u003e\n  \u003csecurity\u003e\n    self_hostname input.testing.local\n    shared_key secure_communication_is_awesome\n  \u003c/security\u003e\n\u003c/source\u003e\n\n\u003cmatch dummy.*\u003e\n  @type stdout\n\u003c/match\u003e\n```\n\nFYI: You can generate certificates using the `fluent-ca-generate` command since Fluentd 1.1.0.\n\nSee also [How to enable TLS/SSL encryption](https://docs.fluentd.org/input/forward#how-to-enable-tls-encryption).\n\n### Mutual TLS Authentication\n\nLogger configuration:\n\n```js\nconst logger = new FluentClient(\"tag_prefix\", {\n  socket: {\n    host: \"localhost\",\n    port: 24224,\n    timeout: 3000, // 3 seconds\n    tls: {\n      ca: fs.readFileSync(\"/path/to/ca_cert.pem\"),\n      cert: fs.readFileSync(\"/path/to/client-cert.pem\"),\n      key: fs.readFileSync(\"/path/to/client-key.pem\"),\n      passphrase: \"very-secret\"\n    },\n  },\n  security: {\n    clientHostname: \"client.localdomain\",\n    sharedKey: \"secure_communication_is_awesome\"\n  }\n});\n```\n\nFluentd configuration:\n\n```aconf\n\u003csource\u003e\n  @type forward\n  port 24224\n  \u003ctransport tls\u003e\n    ca_path /path/to/ca-cert.pem\n    cert_path /path/to/server-cert.pem\n    private_key_path /path/to/server-key.pem\n    private_key_passphrase very_secret_passphrase\n    client_cert_auth true\n  \u003c/transport\u003e\n  \u003csecurity\u003e\n    self_hostname input.testing.local\n    shared_key secure_communication_is_awesome\n  \u003c/security\u003e\n\u003c/source\u003e\n\n\u003cmatch dummy.*\u003e\n  @type stdout\n\u003c/match\u003e\n```\n\n### EventTime support\n\nWe can also specify an [EventTime](https://github.com/fluent/fluentd/wiki/Forward-Protocol-Specification-v1#eventtime-ext-format) as a timestamp. See the [EventTime docs](https://fluent.github.io/fluent-logger-forward-node/classes/eventtime.html)\n\n```js\nconst FluentClient = require(\"@fluent-org/logger\").FluentClient;\nconst EventTime = require(\"@fluent-org/logger\").EventTime;\nconst eventTime = new EventTime(1489547207, 745003500); // 2017-03-15 12:06:47 +0900\nconst logger = new FluentClient(\"tag_prefix\", {\n  socket: {\n    host: \"localhost\",\n    port: 24224,\n    timeout: 3000, // 3 seconds\n  }\n});\nlogger.emit(\"tag\", { message: \"This is a message\" }, eventTime);\n```\n\n### Handling errors\nThe Fluent client will manage errors internally, and reject promises on errors. If you\"d like to access the non-user facing internal errors, you can do so by passing `errorHandler`\n\n```js\nconst FluentClient = require(\"@fluent-org/logger\").FluentClient;\nconst logger = new FluentClient(\"tag_prefix\", {\n  onSocketError: (err: Error) =\u003e {\n    console.error(\"error!\", err)\n  }\n});\n```\n\n### Retrying events\nSometimes it makes sense to resubmit events if their initial submission failed. You can do this by specifying `eventRetry`.\n```js\nconst FluentClient = require(\"@fluent-org/logger\").FluentClient;\nconst logger = new FluentClient(\"tag_prefix\", {\n  eventRetry: {}\n});\n```\n\n## Server\n`@fluent-org/logger` includes a fully functional forward server which can be used as a downstream Fluent sink. \n\n```js\nconst FluentServer = require(\"@fluent-org/logger\").FluentServer;\n\nconst server = new FluentServer({ listenOptions: { port: 24224 }});\n\nawait server.listen();\n```\n\nFluentd config:\n```aconf\n\u003cmatch pattern\u003e\n  @type forward\n  send_timeout 60s\n  recover_wait 10s\n  hard_timeout 60s\n\n  \u003cserver\u003e\n    name fluent_node \n    host 127.0.0.1\n    port 24224\n    weight 60\n  \u003c/server\u003e\n\n  \u003csecondary\u003e\n    @type file\n    path /var/log/fluent/forward-failed\n  \u003c/secondary\u003e\n\u003c/match\u003e\n```\n\nSee the [FluentD docs](https://docs.fluentd.org/output/forward) for more info.\n\nAlternatively, see the [Fluent Bit docs](https://docs.fluentbit.io/manual/pipeline/outputs/forward) for info on setting up Fluent Bit.\n\nFor a full list of the server options and methods, see the [FluentServer docs](https://fluent.github.io/fluent-logger-forward-node/classes/fluentserver.html)\n\n\n## License\n\nApache License, Version 2.0.\n\n[fluent-logger-python]: https://github.com/fluent/fluent-logger-python\n[fluent-logger-node]: https://github.com/fluent/fluent-logger-node\n\n\n## About NodeJS versions\n\nThis package is compatible with NodeJS versions \u003e= 12.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffluent%2Ffluent-logger-forward-node","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffluent%2Ffluent-logger-forward-node","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffluent%2Ffluent-logger-forward-node/lists"}