> For the complete documentation index, see [llms.txt](https://docs.digitalapi.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.digitalapi.ai/api-gateway/observability/building-custom-widgets.md).

# Building custom widgets

A **custom widget** is a saved metric tile that renders live gateway data. Pick a metric (request count, error rate, p50/p95/p99 latency), a chart type (KPI number, line, or bar), filters, and a title. The widget appears on the Custom Widgets surface and re-runs against current traffic every time you open it.

### Reading the custom widgets surface

#### Open the custom widgets page

To open:

1. From the left sidebar, choose **Observability** → **Custom Widgets** (`/observability/widgets`).
2. Read the page heading **Custom Widgets** and the subtitle *Build and manage custom analytics widgets*.
3. The table renders the existing widgets; on a fresh organisation it shows the empty-state message *No custom widgets yet. Create a widget to start tracking custom metrics.*

![Figure 8-1. The Custom Widgets surface.](/files/h6F72tZXyPKs100byO7p)

Table 8-A. Columns on the Custom Widgets list.

| Column      | What it shows                                                                      |
| ----------- | ---------------------------------------------------------------------------------- |
| **Title**   | Widget label set at creation.                                                      |
| **METRIC**  | The metric the widget tracks (request count, error rate, or a latency percentile). |
| **TYPE**    | The chart type (KPI single number, line, or bar).                                  |
| **Created** | Timestamp of widget creation.                                                      |

**Verify**

1. The URL is `<your-helix-portal-domain>/observability/widgets`.
2. **Create widget** is visible at the top right.
3. Existing widgets render in the table; the empty state shows the prompt to create one.

{% hint style="success" %}
**Result:** You see every custom widget in the organisation, ready to open or extend.
{% endhint %}

Related tasks:

* [Create a custom widget](#create-a-custom-widget): author a new widget.

### Creating a custom widget

#### Create a custom widget

**Before you start**

* The metric the widget will track. Common choices are request count, error rate (4xx, 5xx), p50/p95/p99 latency, and request size.
* The chart type: **Single Number (KPI)** for the *one big number* tile you glance at during a release, or **line** or **bar** for trends and category comparisons.
* Filters: environment, service, route, status class, and time window.
* A title that survives skimming. *Production 5xx (last 1h)* beats *5xx*.

To create a widget:

1. From the left sidebar, choose **Observability** → **Custom Widgets** → **Create widget**. The portal navigates to `/observability/widgets/new`.
2. Enter a widget title in the field placeheld with `e.g. Daily Request Volume`.
3. Add a short note in **What does this widget help you track?** so other operators know what it answers.
4. Pick a chart type: **Single Number (KPI)** for one-value tiles, **line** for trends over time, or **bar** for category comparisons.
5. Pick the metric and dimensions, then adjust the time window.
6. Save.

![Figure 8-2. The Create Widget form.](/files/2BrEx3PUA25BaxcjkBlP)

The numbered callouts in Figure 8-2 are:

1. **Widget title.** Shown on the widget tile. Required. Placeholder reads `e.g. Daily Request Volume`.
2. **What does this widget help you track?** Operator-facing description that surfaces on hover.
3. **Chart type: Single Number (KPI).** Renders one big number, suited to *today's request count* or *current 5xx rate*.
4. **Chart type: line or bar.** Trend over time or category leaderboard.

**Verify**

1. The new widget appears at the top of the **Custom Widgets** list.
2. Opening the widget renders the chart with the chosen metric and filters.
3. Filter changes inside the widget update the chart immediately.

{% hint style="success" %}
**Result:** A saved metric tile lives in the portal and reruns on demand.
{% endhint %}

{% hint style="success" %}
**Tip:** Build one KPI widget per metric you watch every day (production 5xx rate, p95 latency, request volume) and one drilldown widget per environment. On release day, open the KPI widgets in one tab and the trace timeline in another; that pair covers most regression-detection workflows.
{% endhint %}

{% hint style="info" %}
**Note:** Widgets are organisation-scoped. Other operators with the right permissions see and open them; widgets do not carry per-user state.
{% endhint %}

{% hint style="danger" %}
**Caution:** A widget with no filters scopes to *all* traffic across *all* environments. For incident-driven widgets, set the environment filter explicitly; otherwise staging noise contaminates the production signal.
{% endhint %}

Related tasks:

* [Investigating with request traces](/api-gateway/observability/investigating-with-request-traces.md#investigating-with-request-traces): drill from a widget data point into the trace that produced it.
* [Building custom reports](/api-gateway/observability/building-custom-reports.md#building-custom-reports): filtered table-style views rather than chart tiles.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.digitalapi.ai/api-gateway/observability/building-custom-widgets.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.