idoc-logs-react

Log client for the IDOC.Logs centralizing server: batched HTTPS shipping, global error capture, breadcrumbs, and React bindings.

The browser counterpart of IDOC.Logs.Nlog (the C#/NLog client). Entries are sent to the server's POST /api/logs/client endpoint, authenticated by a per-application API key.

Installation

npm install idoc-logs-react

Quick start

// main.tsx — once, at startup
import { initIdocLogs } from "idoc-logs-react";

initIdocLogs({
  url: "https://logs.example.com:5001",
  apiKey: "<clé API générée dans l'admin du serveur>",
  version: "1.4.0",
});

That's it — unhandled errors (window.onerror) and unhandled promise rejections are now reported automatically, with breadcrumbs.

Logging manually

import { idocLogs } from "idoc-logs-react";

idocLogs.info("Panier", "Commande validée");
idocLogs.error("Panier", "Échec du paiement", err);

React error boundary

import { IdocLogsErrorBoundary } from "idoc-logs-react/react";

<IdocLogsErrorBoundary fallback={(err, reset) => <ErreurPage onRetry={reset} />}>
  <App />
</IdocLogsErrorBoundary>

Render errors are reported as Fatal with the React component stack.

import { useIdocLogger } from "idoc-logs-react/react";

const logs = useIdocLogger();
logs.warn("Profil", "Avatar introuvable, fallback utilisé");

Options

| Option | Default | Description | |--------|---------|-------------| | url | — | Base URL of the log server (e.g. https://logs.example.com:5001) | | apiKey | — | Per-application API key (generated in the server admin) | | version | null | Application version attached to each entry | | niveauEnvoi | "Info" | Minimum level actually sent (local default). Lower levels only feed breadcrumbs. The server may override this per application at startup — see Server-driven emission level. | | captureGlobale | true | Hook window.onerror / unhandledrejection | | breadcrumbsMax | 30 | Breadcrumb circular buffer size | | flushIntervalleMs | 5000 | Batch flush interval | | flushMaxEntrees | 20 | Batch size triggering an immediate flush |

Behaviour

• Batching — entries are queued and flushed every 5 s or every 20 entries (50 max per request, the server limit).
• Page close — pending entries are flushed with fetch(keepalive: true) on pagehide/visibilitychange, which unlike sendBeacon supports the X-Api-Key header.
• Failure — if the server is unreachable or rejects the batch, entries are re-queued (bounded at 200) and a 30-second backoff applies. Logging never blocks nor throws — same philosophy as the NLog target.
• Breadcrumbs & context — every log call (any level) feeds a circular buffer. Error/Fatal entries carry a Contexte JSON with the breadcrumbs, current URL, screen size and language. The server adds the source IP and User-Agent.
• Levels — NLog names: Trace, Debug, Info, Warn, Error, Fatal.

Server-driven emission level

Since 1.1.0, initIdocLogs fetches GET /api/logs/niveau once at startup (with the X-Api-Key header). If the server has an emission-level override configured for this application, it overrides niveauEnvoi for the session — letting an operator temporarily lower an app to Trace for a diagnostic window, then restore it centrally, without redeploying. There is no polling: the level is read only at init. No override, an expired override, an unreachable server or an older server all leave the local niveauEnvoi in force. Configure the override and its optional expiry per application in the log server admin.

Server-side setup

1. Generate an API key for your application in the log server admin (Applications page).
2. Add your web app's origin to "CORS origines autorisées" in the server's Resources/configuration.json.

License

MIT