@mcesystems/logging-g4

1. Description

What it does: Node-only logging client that sends events to the MCE logging service. Events are queued and sent in batches on a cron-style schedule (e.g. every 10 minutes at fixed clock boundaries). Failed sends (401, network errors) are persisted to disk and retried on the next run. If the service stays offline longer than MAX_OFFLINE_TIME, the client throws.

When it's used: Use this package when your application needs to send structured log events to the MCE logging service with batching, persistence, and offline handling—for example device management tools or services that must not lose logs when the API is temporarily unavailable.

2. Install

pnpm add @mcesystems/logging-g4

Requirements: Node.js 18+. This package uses Node APIs (fs, os, path) and is not compatible with browsers or other non-Node runtimes.

3. Resources

No binary resources are required. You need a credentials file (see Setup) and network access to the auth and logging APIs.

4. Examples

Single event

pnpm exec tsx src/example/sendLog.ts

Uses CREDENTIALS_PATH, LOGGING_API_URL, AUTH_API_URL from .env or environment. Sends one event; returns "delayed" (event queued for next scheduled send).

Batch after 1 minute (with 15s gap between events)

pnpm exec tsx src/example/sendBatchAfterOneMinute.ts

Queues three events with a 15-second gap between each; shows the time when the batch is sent at the next 1-minute boundary. Sets TIME_BETWEEN_LOG=60000 and CACHED_EVENTS_PATH to a temp file if not set.

For step-by-step explanations and scenarios, see Example.md.

5. API

LogClient

Constructor

• Input: none
• Output: new LogClient instance. Call logEvent() after creation; init() runs on first logEvent() if needed.

logEvent(event)

• Input: event — object with event_severity, event_type, event_info, context (and optional fields). Omit event_id, event_time, framework_id, event_source; they are set by the client.
• Output: Promise<LogSendResult> — always "delayed" (event queued for next scheduled send). No immediate send. The outcomes "success" and "MAX_OFFLINE_TIME passed" occur inside the cron job: when MAX_OFFLINE_TIME is exceeded, sendBatch() throws so the process receives the exception.

LogSendResult

Type: "success" | "MAX_OFFLINE_TIME passed" | "delayed". Exported for typing; logEvent() returns "delayed" only.

6. Flow

Example flow: create client, queue several events, let the cron send the batch at the next boundary.

import { LogSeverity } from "@mcesystems/logging-interfaces/lib/sdk";
import { LogClient } from "@mcesystems/logging-g4";

const logClient = new LogClient();

await logClient.logEvent({
	event_severity: LogSeverity.Info,
	event_type: "device_connected",
	event_info: {
		message: "Device connected",
		source: "device-manager",
		timestamp: new Date().toISOString(),
	},
	context: { deviceId: "abc123" },
});
// result is "delayed" — batch will be sent at next TIME_BETWEEN_LOG boundary

await logClient.logEvent({
	event_severity: LogSeverity.Info,
	event_type: "device_disconnected",
	event_info: { message: "Device disconnected", timestamp: new Date().toISOString() },
	context: { deviceId: "abc123" },
});
// both events are queued; cron sends the batch at the next boundary

7. Setup

Environment variables

• TIME_BETWEEN_LOG (ms): Interval between batch send attempts. Sends run at fixed clock boundaries (e.g. 10 min → 13:50, 14:00, 14:10). Default: 10 minutes.
• MAX_OFFLINE_TIME (ms): After this many ms since the first send failure, the client throws. If the batch was successfully persisted and still within this window, no throw. Default: 1 hour.
• CACHED_EVENTS_PATH: Path to a single JSON file for pending (delayed) events. Required. Delayed batches are written here on send failure and loaded on the next run; file is deleted after a successful send.
• CREDENTIALS_PATH: Path to credentials file used by @mcesystems/auth-g4. Required for auth.
• LOGGING_API_URL: Logging API base URL. Required.
• AUTH_API_URL: Auth API URL for token. Required.

Resources location: None. Credentials file path is given by CREDENTIALS_PATH. Pending events file path is given by CACHED_EVENTS_PATH.

8. TODO

• [ ] Optional: Expand Example.md with more scenarios (e.g. offline handling, MAX_OFFLINE_TIME).
• [ ] Optional: Token refresh on 401 before persisting and retrying.