Registry / devops / loki-grpc-client

loki-grpc-client

library2.2.0jsnpmunverified

A TypeScript-native gRPC client for sending log entries to Grafana Loki. Version 2.2.0 is the latest stable release, actively maintained by Balena with a moderate release cadence. It wraps Loki's Protobuf API (logproto) for efficient binary transport, supports TLS and connection pooling, and provides a simple streaming interface. Differentiates from HTTP-based clients (e.g., winston-loki, loki-transport-winston) by using gRPC for lower latency and higher throughput, and ships with full TypeScript definitions.

devops analytics

npm install loki-grpc-client

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · LOKI-GRPC-CLIENT

loki-grpc-client

devopsjavascriptv2.2.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

LokiClient

✓ import { LokiClient } from 'loki-grpc-client'

✗ const LokiClient = require('loki-grpc-client').LokiClient

ESM-only; CommonJS require can be used with destructuring.

Create a Loki client, push single log entries via stream, and send batch pushes with labels.

import { LokiClient } from 'loki-grpc-client'; const client = new LokiClient({ url: process.env.LOKI_URL ?? 'localhost:9095', tls: false, maxStreamBuffer: 100, streamName: 'my-app', labels: { app: 'my-app', env: 'production' } }); const stream = client.createStream(); stream.write({ timestamp: Date.now(), line: 'Hello, Loki!' }); // or send a batch const entries = [ { timestamp: Date.now(), line: 'Log entry 1' }, { timestamp: Date.now(), line: 'Log entry 2' } ]; client.push(entries, { 'app': 'my-app' }); process.on('SIGTERM', () => { stream.end(); client.close(); });

Debug

Known issues

breakingv2.0.0 renamed `pushStream` to `createStream` and changed return type from Writable to a custom stream object.

fix

Use `createStream` and call `write`/`end` on the returned stream. See migration guide.

affects: >=2.0.0 <2.0.0

breakingv2.0.0 removed CommonJS support; package is now ESM-only.

fix

Switch your project to ESM or use dynamic import if necessary.

affects: >=2.0.0

breakingv1.x used `grpc` (grpc package); v2.x uses `@grpc/grpc-js`. Incompatible.

fix

Install `@grpc/grpc-js` and update client options (no more `credentials` needed).

affects: >=2.0.0

deprecatedThe `pushStream` method in v1.x is deprecated in v2.0.0 and removed in later versions.

fix

Migrate to `createStream` in v2.x.

affects: >=1.0.0 <2.0.0

gotchaIf using TLS, ensure your root CA is configured via `GRPC_DEFAULT_SSL_ROOTS_FILE_PATH` environment variable or by passing `tls: true` with proper credentials; otherwise connection fails silently.

fix

Set `GRPC_DEFAULT_SSL_ROOTS_FILE_PATH` or provide custom `channelCredentials` in client options.

affects: >=2.0.0

gotchaThe `maxStreamBuffer` option controls the number of entries buffered before forcing a flush. Setting it too low may cause dropped logs under high load.

fix

Increase `maxStreamBuffer` or implement backpressure handling.

affects: >=2.0.0

Errors

Common errors & fixes

TypeError: LokiClient is not a constructor

CommonJS require without default import in ESM-only package.

fix

Use `import { LokiClient } from 'loki-grpc-client'` instead of `require`.

Error: 14 UNAVAILABLE: failed to connect to all addresses

Loki server unreachable or TLS mismatch.

fix

Check the URL and port. If using TLS, set `tls: false` for plaintext or configure proper certificates.

TypeError: stream.write is not a function

Using v1.x API `pushStream` which returned a different object.

fix

Update to v2.x and use `createStream` which returns a Writable-like stream.

Upgrade

Version history

2.2.0latest on npm

Audit

Dependencies

grpc-jsrequiredCore gRPC transport implementation

protobufjsrequiredProtobuf message serialization/deserialization

Agent activity

19 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/balena-io-modules/node-loki-grpc-client ↗

packageloki-grpc-client ↗

homepagehttps://github.com/balena-io-modules/node-loki-grpc-client#readme ↗