# Introduction



Flare can collect and display structured log messages from your JavaScript application, separate from error reports. This gives you insight into what your application is doing, beyond just the errors it throws.

Logs are buffered in the browser and shipped to Flare in batches as their own entity. They show up in your project's [logs view](/docs/flare/logs/working-with-logs), independent of any error report.

> Logging is available in `@flareapp/js` (version 2.3.0 and up). The React, Vue and Svelte packages re-export the same client, so the API described here works there too.

## Enabling log collection

Log collection is **disabled by default**, so no log traffic is sent until you switch it on. Enable it with the `enableLogs` option, after calling `flare.light()`:

```js
import { flare } from '@flareapp/js';

flare.light('YOUR PROJECT KEY');

flare.configure({
    enableLogs: true,
});
```

While `enableLogs` is `false`, every `flare.logger.*` call is a no-op. Turning it back off again clears any buffered logs that haven't been shipped yet.

## Recording logs

Once enabled, record a log through `flare.logger`. There is a method for each [severity level](/docs/javascript/logs/levels):

```js
flare.logger.info('User signed in');
flare.logger.warning('Slow response from the API');
flare.logger.error('Checkout failed');
```

Each method takes a message and an optional [attributes](/docs/javascript/logs/attributes) object with structured data for that single log entry:

```js
flare.logger.info('User signed in', { userId: 42, plan: 'pro' });
```

The full set of methods is `debug`, `info`, `notice`, `warning`, `error`, `critical`, `alert`, and `emergency`. See [Levels](/docs/javascript/logs/levels) for what each one means and how to filter them.

## How logs are shipped

Logs are not sent one by one. The client buffers them and flushes a batch to Flare when any of these happens:

- the buffer reaches `maxLogBufferSize` records (default `100`),
- the buffered payload reaches `logFlushMaxBytes` (default ~`800 KB`),
- the `logFlushIntervalMs` timer fires (default `5000` ms after the first buffered log), or
- the browser tab is hidden (`visibilitychange` → `hidden`), e.g. on navigation or closing the tab.

The unload flush uses `fetch` with `keepalive` so the request survives the page going away. Browsers cap keepalive request bodies, so on that path the client ships the most recent records that fit within `keepaliveMaxBytes` (default ~`60 KB`) and drops older overflow.

A log can only be shipped once a project key is set. If you record logs before `flare.light()` runs, they stay buffered and are sent on the next flush after the key is available.

### Flushing manually

`flare.flush()` forces the buffered logs to be sent immediately. This matters when the page is about to do something that bypasses the normal unload flush, or in environments where the tab-hidden trigger doesn't fire:

```js
await flare.flush();
```

## Configuration options

Logging behaviour is tuned through `flare.configure()`:

| Option | Default | Description |
|--------|---------|-------------|
| `enableLogs` | `false` | Master switch. No logs are recorded or sent while this is `false`. |
| `minimumLogLevel` | _(none)_ | Drop logs below this [severity](/docs/javascript/logs/levels). When unset, all levels are sent. |
| `serviceName` | _(none)_ | Service name attached to log records (sent as `service.name`). |
| `maxLogBufferSize` | `100` | Maximum number of buffered records before a flush is triggered. |
| `logFlushIntervalMs` | `5000` | Milliseconds after the first buffered log before the batch is flushed. |
| `logFlushMaxBytes` | `800000` | Approximate buffered payload size that triggers a flush. |
| `keepaliveMaxBytes` | `60000` | Byte budget for the unload (`keepalive`) flush. Records that don't fit are dropped. |
| `logsIngestUrl` | `https://ingress.flareapp.io/v1/logs` | Custom endpoint for log batches. |

These options live alongside the error-reporting options on the [configuration reference](/docs/javascript/reference/configuration).

## Disabling log collection

Set `enableLogs` back to `false` to stop collecting. Any logs still in the buffer are discarded:

```js
flare.configure({ enableLogs: false });
```