---
title: Events Overlays in Logs Explorer
description: "Overlay feature gate rollout history or raw JSON events onto Logs Explorer time-series charts to connect log and event trends to the changes behind them."
product: general
token_estimate: 954
---
# Events Overlays in Logs Explorer

> For AI agents: a documentation index is available at [/llms.txt](/llms.txt). Append `.md` to any page URL for markdown, or send `Accept: text/markdown`.

Events Overlays add a marker layer to time-series charts in Logs Explorer, so you can line up log and event trends with the changes that drove them. Overlay a feature gate's rollout history to see exactly when a change shipped, or map raw JSON events onto the chart for ad hoc annotations. On-call responders and engineers use overlays to connect a spike or regression to the config change behind it.

> **Info:**
>
> The feature gate overlay source is in early access, gated behind `logs_overlay_gate_source`. Statsig opts employees in by default.

---

## How overlays work

The **Overlay events** control lives in the chart toolbar as a popover. Open it, pick an overlay source, configure which decorations render, and Logs Explorer draws the overlay on top of your query results.

Overlays render only on marker-capable time-series charts: **Line**, **stacked line**, and **timeseries bar**. Other visualizations show an unsupported message and skip the overlay fetch entirely.

Logs Explorer quantizes the chart window to the minute, so a live 15-second refresh doesn't re-run the gate snapshot walk on every tick.

{% callout type="note+ %} The default time window in Logs Explorer is only 2 hours. Typically, gate changes take place over a week. Be sure to check your time window to ensure that the Logs Explorer time window and your window for gate changes overlap.

> **Note:**
>
>

---

## Overlay sources

Select a source from the **Overlay events** popover. Logs Explorer offers two sources.

### Feature gate

The feature gate source walks a selected gate's config-change and snapshot history, then renders three decorations you can toggle independently:

- **Changes**: markers at each point where the gate's configuration changed.
- **Rollout %**: a dashed step line that tracks the gate's rollout percentage over time.
- **Shade when off**: shaded regions across intervals where the gate was disabled.

A follow-rule selector lets you track a specific rule instead of the gate as a whole.

### Raw JSON

Paste your events, then map their fields in the field-mapping grid. A live parse preview shows how Statsig reads each field, so you can confirm the mapping before you apply it.

---

## Add an overlay

1. Open Logs Explorer and run a query that renders as a **Line**, **stacked line**, or **timeseries bar** chart.
2. In the chart toolbar, click **Overlay events**.
3. Select a source: **Feature gate** or **Raw JSON**.
4. For a feature gate, choose the gate, toggle the **Changes**, **Rollout %**, and **Shade when off** decorations you want, and set a follow rule if you need one.
5. For raw JSON, map the event fields in the grid and confirm the parse preview.
6. Apply the overlay to draw it on the chart.

Logs Explorer saves your overlay configuration to local storage per project and surface, so it persists when you return to the same chart.

---

## Share an overlay

Click **Copy link** to share an overlay. Statsig encodes the overlay configuration into an `overlay` URL parameter, which hydrates the overlay once on open and then strips the parameter from the address bar.

You can use **Copy link** (or copy/paste the URL from the address bar) only when the encoded overlay fits within URL size limits. For a large field mapping, rebuild the overlay from the source configuration instead.

---

## Limitations

> **Note:**
>
> Overlays render only on marker-capable time-series charts (**Line**, **stacked line**, and **timeseries bar**). The feature gate source is in early access behind `logs_overlay_gate_source`. **Copy link** works only when the overlay payload fits URL size limits.