@theotherwillembotha/node-red-loki 0.0.55

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026, Willem Botha
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,72 @@
+# @theotherwillembotha/node-red-loki
+
+Grafana Loki logger config node for Node-RED. Extends the logging infrastructure provided by [@theotherwillembotha/node-red-plugincore](https://github.com/theotherwillembotha/nodered_plugincore) with a Loki transport, so any node built with the `@Logger` decorator can ship structured log entries directly to a Loki instance.
+
+---
+
+## Usage in Node-RED
+
+### Installation
+
+Either use the **Manage Palette** option in the Node-RED editor, or run the following command in your Node-RED user directory (typically `~/.node-red`):
+
+```bash
+npm install @theotherwillembotha/node-red-loki
+```
+
+> [!IMPORTANT]
+> **This plugin requires [`@theotherwillembotha/node-red-plugincore`](https://github.com/theotherwillembotha/nodered_plugincore) to be installed.**
+>
+> `node-red-plugincore` is declared as a dependency and npm will install it automatically alongside this package. However, due to a [known Node-RED limitation](https://github.com/node-red/node-red/issues/3529), packages that arrive as transitive npm dependencies are only discovered by the Node-RED runtime on the **next startup**.
+>
+> **You have two options:**
+> - Install [`@theotherwillembotha/node-red-plugincore`](https://flows.nodered.org/node/@theotherwillembotha/node-red-plugincore) via the palette manager or `npm install` **first**, then install this plugin — both will be available immediately without a restart.
+> - Install this plugin directly — `node-red-plugincore` will be installed automatically alongside it. **Restart Node-RED** once and both packages will be fully loaded.
+
+### Config node
+
+This package adds a single config node: **Loki Logger**.
+
+The Loki Logger config node appears in the logger selector of any node that uses the `@Logger` decorator (e.g. the Logger Node from [node-red-telemetry](https://github.com/theotherwillembotha/nodered_telemetry), or any custom node built on this framework).
+
+#### Configuration fields
+
+| Field | Description |
+|-------|-------------|
+| **Name** | Optional label for this config node |
+| **Host** | Hostname or IP address of your Loki instance (e.g. `loki` or `192.168.1.10`) |
+| **Port** | Loki HTTP port (default: `3100`) |
+| **Tenant ID** | Optional. Set the `X-Scope-OrgID` header for multi-tenant Loki deployments. Leave blank for single-tenant mode. |
+| **Level** | Minimum log level to ship: Debug, Info, Warning, or Error |
+| **Template** | Handlebars template that shapes each log entry. The default `message:{{msg}}` passes the raw message through. Customise to include only the fields you need (e.g. `{{msg.topic}}: {{msg.payload}}`). |
+
+#### Example
+
+A typical setup for a single-tenant Loki instance running on the same Docker network:
+
+- **Host:** `loki`
+- **Port:** `3100`
+- **Tenant ID:** _(blank)_
+- **Level:** `Info`
+- **Template:** `message:{{msg}}`
+
+For multi-tenant deployments, set the **Tenant ID** to match your Loki organisation ID. The value is sent as the `X-Scope-OrgID` HTTP header on every push request.
+
+---
+
+## Prerequisites
+
+- Node.js 18+
+- Node-RED 3+
+- A running [Grafana Loki](https://grafana.com/oss/loki/) instance reachable from your Node-RED host
+
+---
+
+## Repository
+
+- Source: [github.com/theotherwillembotha/nodered_loki](https://github.com/theotherwillembotha/nodered_loki)
+- Issues: [github.com/theotherwillembotha/nodered_loki/issues](https://github.com/theotherwillembotha/nodered_loki/issues)
+
+## License
+
+[ISC](LICENSE)

package/build/GenerateNodes.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_red_plugincore_1 = require("@theotherwillembotha/node-red-plugincore");
+const LokiLoggerConfigNode_1 = require("./loki/node/LokiLoggerConfigNode");
+new node_red_plugincore_1.NodeGenerator("./src/loki/")
+    .registerNode(LokiLoggerConfigNode_1.LokiLoggerConfigNode)
+    .generate("./build/Nodes", "./build/Plugins");
+process.exit(0);

package/build/Nodes.html

@@ -0,0 +1,153 @@
+
+<!--
+
+    This file was automatically generated using the NODERED Core utility.
+    Any modifications to his file will be overwritten the next time the code is regenerated.
+        
+    You have been warned.
+    
+-->
+
+<script type="text/javascript">
+    RED.nodes.registerType('LokiLoggerConfigNode', {
+      category: 'config',
+      label: function() {
+        return this.name
+      },
+      paletteLabel: 'Loki Logger Config Node',
+      defaults: {
+        name: {
+          value: 'Logger Example',
+          required: true
+        },
+        template: {
+          value: 'message:{{msg}}',
+          required: true
+        },
+        level: {
+          value: 'info',
+          required: true
+        },
+        loki_host: {},
+        loki_tenantid: {},
+        loki_userid: {},
+        loki_authtoken: {},
+      },
+      oneditprepare: function() {
+        // **** LokiLoggerConfigNode **** //
+        {
+          let node = this;
+          let levelSelection = $("#node-config-input-level");
+          levelSelection.typedInput({
+            type: "level",
+            types: [{
+              value: "level",
+              options: [{
+                value: "DEBUG",
+                label: "debug"
+              }, {
+                value: "INFO",
+                label: "info"
+              }, {
+                value: "WARNING",
+                label: "warning"
+              }, {
+                value: "ERROR",
+                label: "error"
+              }, ]
+            }]
+          });
+          this.editor = RED.editor.createEditor({
+            id: 'node-config-input-templateEditor',
+            mode: 'ace/mode/handlebars',
+            value: this.template
+          });
+        }
+      },
+      oneditsave: function() {
+        // **** LokiLoggerConfigNode **** //
+        {
+          let node = this;
+          this.template = this.editor.getValue();
+          this.editor.destroy();
+          delete this.editor;
+        }
+      },
+      oneditcancel: function() {},
+      oneditdelete: function() {},
+    });
+
+</script>
+
+
+<script type="text/html" data-template-name='LokiLoggerConfigNode'>
+    <div id='section_LokiLoggerConfigNode'>
+        <div id="LoggerConfig">
+            <div class="form-row">
+                <label class="towb_editorlabel" for="node-config-input-name"><i class="fa fa-font"></i> Name</label>
+                <input type="text" id="node-config-input-name" />
+            </div>
+
+            <div class="form-row">
+                <label class="towb_editorlabel" for="node-config-input-level"><i class="fa fa-signal"></i> Level</label>
+                <input type="text" id="node-config-input-level" />
+            </div>
+
+            <div class="form-row">
+                <label class="towb_editorlabel" for="node-config-input-loki_host"><i class="fa fa-server"></i> Host</label>
+                <input class="required" type="text" id="node-config-input-loki_host" />
+            </div>
+            <div class="form-row">
+                <label class="towb_editorlabel" for="node-config-input-loki_tenantid"><i class="fa fa-building-o"></i> Tenant ID</label>
+                <input class="" type="text" id="node-config-input-loki_tenantid" />
+            </div>
+            <div class="form-row">
+                <label class="towb_editorlabel" for="node-config-input-loki_userid"><i class="fa fa-user"></i> Username</label>
+                <input class="" type="text" id="node-config-input-loki_userid" />
+            </div>
+            <div class="form-row">
+                <label class="towb_editorlabel" for="node-config-input-loki_authtoken"><i class="fa fa-key"></i> Auth Token</label>
+                <input class="" type="password" id="node-config-input-loki_authtoken" />
+            </div>
+
+            <div class="form-row">
+                <label class="towb_editorlabel" for="node-config-input-templateEditor"><i class="fa fa-code"></i> Template</label>
+                <div style="height: 250px; min-height:150px;" class="node-text-editor" id="node-config-input-templateEditor"></div>
+            </div>
+        </div>
+
+    </div>
+</script>
+
+<script type="text/markdown" data-help-name='LokiLoggerConfigNode'>
+Pushes log messages to a Grafana Loki instance using the Loki HTTP API.
+
+### Properties
+: *name*        (string)    : A descriptive name for this logger configuration.
+: *level*       (level)     : The minimum log level. Messages below this threshold are suppressed. Options: DEBUG, INFO, WARNING, ERROR.
+: *host*        (string)    : The base URL of the Loki instance, including port (e.g. `http://localhost:3100`).
+: *tenant ID*   (string)    : The tenant identifier for multi-tenant Loki deployments (`X-Scope-OrgID` header). Leave blank for single-tenant deployments.
+: *username*    (string)    : Username for Loki authentication.
+: *auth token*  (string)    : Authentication token or password for Loki.
+: *template*    (mustache)  : A Mustache/Handlebars template that formats the log message body.
+
+### Mustache Templating
+Mustache/Handlebars templates build the message string pushed to Loki.
+
+#### Provided Properties
+: *msg*         (object)    : The Node-RED message object passed through the node.
+: *currentTime* (string)    : The current time in ISO 8601 format.
+
+#### Helpers
+: *json*        (helper)    : Serialises an object to a JSON string using `JSON.stringify`.
+
+#### Examples
+- `{{{json msg}}}` — serialises the full message object as JSON.
+
+#### References
+- [Grafana Loki — HTTP API](https://grafana.com/docs/loki/latest/reference/loki-http-api/)
+- [Mustache — Wikipedia](https://en.wikipedia.org/wiki/Mustache_(template_system))
+- [Mustache — Playground](https://jgonggrijp.gitlab.io/wontache/playground.html)
+</script>
+
+        

package/build/Nodes.js

@@ -0,0 +1,18 @@
+
+/*
+
+    This file was automatically generated using the NODERED Core utility.
+    Any modifications to his file will be overwritten the next time the code is regenerated.
+        
+    You have been warned.
+    
+*/
+"use strict";
+const NodeManager = require("@theotherwillembotha/node-red-plugincore").NodeManager;
+const LokiLoggerConfigNode = require("@theotherwillembotha/node-red-loki").LokiLoggerConfigNode;
+module.exports = (RED) => {
+let manager = new NodeManager(RED);
+    manager.registerNodeType("LokiLoggerConfigNode", LokiLoggerConfigNode);
+}        
+        
+        

package/build/Plugins.js

@@ -0,0 +1,70 @@
+
+/*
+
+    This file was automatically generated using the NODERED Core utility.
+    Any modifications to his file will be overwritten the next time the code is regenerated.
+        
+    You have been warned.
+    
+*/
+"use strict";
+const runtime = require("node-red").runtime;
+
+
+module.exports = function (RED) {
+
+    // 1. make a list of all the plugins that need to be installed.
+    let pluginList =  []
+        .map(service => service.getServiceDescriptor())
+        .filter(plugin => !RED.plugins.get(plugin.id()));
+
+    // 2. register a listener if there are any plugins in the pluginList.
+    if(pluginList.length > 0){
+        RED.events.on('registry:plugin-added', async pluginID => {
+
+            let addedPlugin = pluginList.find(plugin => plugin.id() === pluginID);
+            let plugin = RED.plugins.get(pluginID);
+
+            if(addedPlugin && plugin.instantiate && !plugin.instance){
+                console.log("Deploying instance of: " + plugin.id);
+                plugin.instance = new plugin.class();
+                
+                // instantiate the plugin.
+                await plugin.instance.init(RED);
+
+                // publish an event that it has ben deployed.
+                RED.events.emit("plugin.instantiated", pluginID);
+                                
+                pluginList.splice(pluginList.findIndex(current => current.id() === addedPlugin.id()), 1);
+
+                // register a flow deployment listener.
+                let startupDeployment = true;
+                RED.events.on('runtime-event', async (event) => {
+                    // startup deployment.
+                    if ("runtime-deploy" === event?.id && startupDeployment) {
+                        //console.log("STARTUP DEPLOYMENT");
+                        startupDeployment = false;
+                        const flows = await runtime.flows.getFlows({});
+                        await plugin.instance.onDeploy(flows);
+                    }
+                    
+                    // stopping flows on redeployment.
+                    if ("runtime-state" === event?.id && event?.payload?.state === "stop" && event?.payload?.deploy) {
+                        //console.log("REDEPLOY!");
+                        const flows = await runtime.flows.getFlows({});
+                        await plugin.instance.onDeploy(flows);
+                    }
+                });
+            }
+        });
+    }
+
+    // 3. register the plugins.
+    [...pluginList].forEach(plugin => {
+        RED.plugins.registerPlugin(plugin.id(), {
+            type: plugin.type(),
+            instantiate:true,
+            class: plugin.clazz()
+        });
+    })
+};

package/build/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./loki/node/LokiLoggerConfigNode"), exports);

package/build/loki/node/LokiLoggerConfigNode.js

@@ -0,0 +1,100 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LokiLoggerConfigNode = void 0;
+const node_red_plugincore_1 = require("@theotherwillembotha/node-red-plugincore");
+const node_red_plugincore_2 = require("@theotherwillembotha/node-red-plugincore");
+const winston_1 = require("winston");
+const winston_loki_1 = __importDefault(require("winston-loki"));
+let LokiLoggerConfigNode = class LokiLoggerConfigNode extends node_red_plugincore_1.LoggerConfigNode {
+    constructor(node, config) {
+        super(node, config);
+        const loggerConfig = {
+            id: this.id(),
+            type: "LOKI",
+            template: config.template,
+            level: config.level,
+            host: config.loki_host,
+            userid: config.loki_userid,
+            authtoken: config.loki_authtoken,
+            tenantid: config.loki_tenantid,
+        };
+        this._logger = new LokiLogger(loggerConfig);
+    }
+    logger() {
+        return this._logger;
+    }
+};
+exports.LokiLoggerConfigNode = LokiLoggerConfigNode;
+exports.LokiLoggerConfigNode = LokiLoggerConfigNode = __decorate([
+    (0, node_red_plugincore_1.NodeDescription)({
+        id: "LokiLoggerConfigNode",
+        name: "Loki Logger",
+        group: "config",
+        sourceFile: node_red_plugincore_2.SourceUtility.getSourcePath("/build/", "/src/") + "LokiLoggerConfigNode.html",
+        package: "@theotherwillembotha/node-red-loki",
+        dependencies: [node_red_plugincore_1.LoggerService],
+        tags: ["LoggerType"]
+    }),
+    __metadata("design:paramtypes", [Object, Object])
+], LokiLoggerConfigNode);
+function toWinstonLevel(level) {
+    const l = level.toLowerCase();
+    return l === 'warning' ? 'warn' : l;
+}
+class LokiLogger extends node_red_plugincore_1.AbstractLogger {
+    constructor(config) {
+        super(config);
+        this.winstonLevel = toWinstonLevel(config.level);
+        const transportConfig = {
+            headers: {},
+            host: config.host,
+            json: true,
+            format: winston_1.format.json(),
+            replaceTimestamp: true,
+            onConnectionError: (err) => console.error(`[LokiLogger] connection error (host: ${config.host}):`, err),
+            basicAuth: (config.userid && config.authtoken)
+                ? `${config.userid}:${config.authtoken}`
+                : undefined
+        };
+        if (config.tenantid) {
+            transportConfig.headers["X-Scope-OrgID"] = config.tenantid;
+        }
+        this.winston = (0, winston_1.createLogger)({
+            level: this.winstonLevel,
+            format: winston_1.format.json(),
+            defaultMeta: {},
+            transports: [
+                new winston_loki_1.default(transportConfig),
+            ],
+        });
+    }
+    createLogger(config) {
+        return new LokiAppender(config, this.winston, this.winstonLevel);
+    }
+}
+class LokiAppender extends node_red_plugincore_1.Log {
+    constructor(config, winston, level) {
+        super(config);
+        this.winston = winston;
+        this.level = level;
+    }
+    writeToLog(_level, message, tags) {
+        this.winston.log({
+            level: this.level.toLowerCase(),
+            message: message,
+            labels: tags
+        });
+    }
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@theotherwillembotha/node-red-loki",
+  "version": "0.0.55",
+  "description": "Grafana Loki logger config node for Node-RED. Built on @theotherwillembotha/node-red-plugincore.",
+  "main": "./build/index.js",
+  "exports": "./build/index.js",
+  "author": "Willem Botha (@theotherwillembotha)",
+  "license": "ISC",
+  "keywords": [
+    "node-red",
+    "loki",
+    "logging",
+    "grafana",
+    "observability"
+  ],
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "build": "npm run clean && tsc && npm run generate-nodes",
+    "clean": "rm -rf ./build",
+    "generate-nodes": "node build/GenerateNodes.js"
+  },
+  "files": [
+    "build/",
+    "LICENSE",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/theotherwillembotha/nodered_loki.git"
+  },
+  "bugs": {
+    "url": "https://github.com/theotherwillembotha/nodered_loki/issues"
+  },
+  "homepage": "https://github.com/theotherwillembotha/nodered_loki#readme",
+  "engines": {
+    "node": ">=18",
+    "nodered": ">=4.0.0"
+  },
+  "dependencies": {
+    "@theotherwillembotha/node-red-plugincore": "^0.0.55",
+    "winston": "^3.17.0",
+    "winston-loki": "^6.1.3"
+  },
+  "devDependencies": {
+    "@theotherwillembotha/node-red-plugincore": "../nodered_plugincore",
+    "@types/node": "^22.15.29",
+    "@types/node-red": "~1.3.5"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "node-red": {
+    "version": ">=4.0.0",
+    "nodes": {
+      "loki": "./build/Nodes.js"
+    },
+    "plugins": {
+      "loki": "./build/Plugins.js"
+    }
+  }
+}