Skip to content

style: apply /style-guide pass to models/runs #2724

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
johndmulhausen wants to merge 5 commits into
base: main
Choose a base branch
from
Open

style: apply /style-guide pass to models/runs #2724

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
1df3e6e
style: apply /style-guide pass to models/runs
johndmulhausen Jun 4, 2026
73bba3f
fix: address Copilot review feedback in models/runs
johndmulhausen Jun 5, 2026
e6fd29f
fix: correct broken run-identifiers anchors on runs landing page
johndmulhausen Jun 5, 2026
f764512
Merge origin/main into style-guide/models-runs-20260604-113608
johndmulhausen Jun 10, 2026
32ce07b
style: remove auto-added keywords frontmatter from models/runs
johndmulhausen Jun 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 29 additions & 26 deletions models/runs/alert.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,56 +1,58 @@
---
description: Send alerts, triggered from your Python code, to your Slack or email
title: Send an alert
keywords: ["run.alert()", "Slack alerts", "Scriptable run alerts", "AlertLevel"]
---
import { ColabLink } from '/snippets/_includes/colab-link.mdx';

<ColabLink url="https://wandb.me/alerts-colab" />

Create alerts with Slack or email if your run crashes or with a custom trigger. For example, you can create an alert if the gradient of your training loop starts to blow up (reports NaN) or a step in your ML pipeline completes. Alerts apply to all projects where you initialize runs, including both personal and team projects.
Create alerts with Slack or email if your run crashes or with a custom trigger. For example, you can create an alert if the gradient of your training loop reports `NaN`. You can also create an alert when a step in your ML pipeline completes. Alerts let you respond to training issues without continually watching the dashboard. Alerts apply to all projects where you initialize runs, including personal and team projects.


And then see W&B Alerts messages in Slack (or your email):
After you configure alerts, W&B Alerts messages appear in Slack or your email:

<Frame>
<img src="/images/track/send_alerts_slack.png" alt="Slack alert setup" />
</Frame>

<Note>
W&B Alerts require you to add `run.alert()` to your code. Without modifying your code, [Automations](/models/automations/) provide another way to notify Slack based on an event in W&B, such as when an [artifact](/models/artifacts/) artifact version is created or when a [run metric](/models/runs/) meets or changes by a threshold.
W&B Alerts require you to add `run.alert()` to your code. Without modifying your code, [Automations](/models/automations/) provide another way to notify Slack based on an event in W&B, such as when W&B creates an [artifact](/models/artifacts/) version or when a [run metric](/models/runs/) meets or changes by a threshold.

For example, an automation can notify a Slack channel when a new version is created, run an automated testing webhook when the `production` alias is added to an artifact, or start a validation job only when a run's `loss` is within acceptable bounds.
For example, an automation can notify a Slack channel when W&B creates a new version. It can run an automated testing webhook when you add the `production` alias to an artifact. It can also start a validation job only when a run's `loss` is within acceptable bounds.

Read the [Automations overview](/models/automations/) or [create an automation](/models/automations/create-automations/).
To create an automation, see [Create an automation](/models/automations/create-automations/).
</Note>
<Note>
The following guide only applies to alerts in Multi-tenant Cloud.

If you're using [W&B Server](/platform/hosting/) in your Private Cloud or on W&B Dedicated Cloud, refer to [Configure Slack alerts in W&B Server](/platform/hosting/monitoring-usage/slack-alerts) to set up Slack alerts.
</Note>
To set up an alert, take these steps, which are detailed in the following sections:
The following sections describe how to set up an alert:

1. Turn on Alerts in your W&B [User Settings](https://wandb.ai/settings).
1. Turn on **Alerts** in your W&B [User Settings](https://wandb.ai/settings).
2. Add `run.alert()` to your code.
3. Test the configuration.

### 1. Turn on alerts in your W&B User Settings
## Turn on alerts in your W&B user settings

In your [User Settings](https://wandb.ai/settings):
This step enables the alert delivery channels (Slack or email) that `run.alert()` calls use. You only have to do this the first time you set up W&B Alerts, or when you want to modify how you receive alerts.

* Scroll to the **Alerts** section
* Turn on **Scriptable run alerts** to receive alerts from `run.alert()`
* Use **Connect Slack** to pick a Slack channel to post alerts. We recommend the **Slackbot** channel because it keeps the alerts private.
* **Email** will go to the email address you used when you signed up for W&B. We recommend setting up a filter in your email so all these alerts go into a folder and don't fill up your inbox.
In your [User Settings](https://wandb.ai/settings), configure the following:

You will only have to do this the first time you set up W&B Alerts, or when you'd like to modify how you receive alerts.
* Scroll to the **Alerts** section.
* Turn on **Scriptable run alerts** to receive alerts from `run.alert()`.
* Use **Connect Slack** to pick a Slack channel to post alerts. W&B recommends the **Slackbot** channel because it keeps alerts private.
* **Email** goes to the email address you used when you signed up for W&B. W&B recommends setting up a filter in your email so that all these alerts go into a folder and don't fill your inbox.

<Frame>
<img src="/images/track/demo_connect_slack.png" alt="Alerts settings in W&B User Settings" />
</Frame>

### 2. Add `run.alert()` to your code
After you complete these settings, W&B can deliver alerts to your chosen channels whenever your code calls `run.alert()`.

## Add `run.alert()` to your code

Add `run.alert()` to your code (either in a Notebook or Python script) wherever you'd like it to be triggered
This step defines when alerts fire and what they contain. Each `run.alert()` call defines the condition that triggers a notification and the content of the message you receive. Add `run.alert()` to your code (either in a Notebook or Python script) wherever you want to trigger it.

```python
import wandb
Expand All @@ -59,13 +61,15 @@ with wandb.init() as run:
run.alert(title="High Loss", text="Loss is increasing rapidly")
```

### 3. Test the configuration
## Test the configuration

Check your Slack or emails for the alert message. If you didn't receive any, make sure you've got emails or Slack turned on for **Scriptable Alerts** in your [User Settings](https://wandb.ai/settings)
Confirm that alerts reach you before you rely on them in production runs. Run your code to trigger the alert, then check your Slack or emails for the alert message. If you don't receive any, make sure you have emails or Slack turned on for **Scriptable run alerts** in your [User Settings](https://wandb.ai/settings).

## Example
After you complete these steps, your runs can notify you through Slack or email whenever the conditions you specify in `run.alert()` are met.

This simple alert sends a warning when accuracy falls below a threshold. In this example, it only sends alerts at least 5 minutes apart.
## Example alert

The following example shows a typical `run.alert()` pattern: it monitors a metric and sends a warning when accuracy falls below a threshold. It sends alerts no more than once every 5 minutes.

```python
import wandb
Expand All @@ -82,21 +86,20 @@ with wandb.init() as run:
)
```


## Tag or mention users

Use the at sign `@` followed by the Slack user ID to tag yourself or your colleagues in either the title or the text of the alert. You can find a Slack user ID from their Slack profile page.
Tag users to direct alerts to the right person and trigger Slack's standard mention notifications. To tag yourself or a colleague, use the at sign `@` followed by the Slack user ID in the alert title or text. You can find a Slack user ID from their Slack profile page.

```python
run.alert(title="Loss is NaN", text=f"Hey <@U1234ABCD> loss has gone to NaN")
```

## Configure team alerts

Team admins can set up alerts for the team on the team settings page: `wandb.ai/teams/your-team`.
Besides individual alerts, team admins can configure alerts that apply to everyone on the team. Team admins can set up team alerts on the team settings page: `wandb.ai/teams/[YOUR-TEAM]`.

Team alerts apply to everyone on your team. W&B recommends using the **Slackbot** channel because it keeps alerts private.

## Change Slack channel to send alerts to
## Change the Slack channel for alerts

To change what channel alerts are sent to, click **Disconnect Slack** and then reconnect. After you reconnect, pick a different Slack channel.
To redirect alerts to a different Slack channel, click **Disconnect Slack** and then reconnect. After you reconnect, pick a different Slack channel.
75 changes: 40 additions & 35 deletions models/runs/color-code-runs.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,50 +1,55 @@
---
description: "Color-code W&B runs based on metrics or config parameters to create visually meaningful chart legends."
title: Semantic run plot legends
keywords: ["key-based colors", "run colors", "buckets", "hyperparameter coloring"]
---

Create visually meaningful line plots and plot legends by color-coding your W&B runs based on metrics or configuration parameters. Identify patterns and trends across experiments by coloring runs according to their performance metrics (highest, lowest, or latest values). W&B automatically groups your runs into color-coded buckets based on the values of your selected parameter.

To use metric or configuration-based colors for your runs, you need to configure two settings:
To use metric- or configuration-based colors for your runs, turn on key-based colors and then choose the metric or configuration key and Y value that determine each run's color.

### Turn on key-based colors
The following sections describe how to enable key-based colors, choose a metric or configuration key, set a Y value, and customize the buckets W&B uses to assign colors.

## Turn on key-based colors

Enable key-based colors so W&B can assign run colors based on a metric or configuration key instead of the default per-run colors.

1. Navigate to your W&B project.
2. Select the **Workspace** tab from the project sidebar.
3. Click on the **Settings** icon in the top right corner.
3. Click the **Settings** icon in the top right corner.
4. From the drawer, select **Runs**.
5. In the **Run colors** section, select **Key-based colors**.
6. Configure the following options:
- From the **Key** dropdown, select the metric you want to use for assigning colors to runs.
- From the **Y value** dropdown, select the y value you want to use for assigning colors to runs.
- From the **Y value** dropdown, select the Y value you want to use for assigning colors to runs.
- Set the number of buckets to a value from 2 to 8.

<Note>
When you use key-based colors, the option to [customize run colors](/models/runs/run-colors) is not available.
When you use key-based colors, the option to [customize run colors](/models/runs/run-colors) isn't available.
</Note>

The following sections describe how to set the metric and y value and as how to customize the buckets used for assigning colors to runs.
After you turn on key-based colors, W&B colors each run based on the key and Y value you selected. The following sections describe how to set the metric and Y value and how to customize the buckets that W&B uses to assign colors to runs.

## Example: key-based colors with a loss metric

### Example: Key-based coloring with loss metric
In this example plot, W&B colors runs with a gradient where darker colors represent higher loss values and lighter colors represent lower loss values. The Y value is set to **Latest** to use the most recent loss value for each run.

In this example plot, runs are colored with a gradient where darker colors represent higher loss values and lighter colors represent lower loss values. The Y value is set to `latest` to use the most recent loss value for each run.

<Image src="/images/app_ui/run-colors-key-based.png" alt="W&B workspace showing runs colored based on their loss values using key-based coloring." />

## Set a metric

The metric options in your **Key** dropdown are derived from the key-value pairs [you log to W&B](/models/runs/color-code-runs/#custom-metrics) and [default metrics](/models/runs/color-code-runs/#default-metrics) defined by W&B.
Choose a metric to base your run colors on. The metric options in your **Key** dropdown come from the [custom metrics](/models/runs/color-code-runs/#custom-metrics) you log to W&B and the [default metrics](/models/runs/color-code-runs/#default-metrics) that W&B defines.

### Default metrics

* `Relative Time (Process)`: The relative time of the run, measured in seconds since the start of the run.
* `Relative Time (Wall)`: The relative time of the run, measured in seconds since the start of the run, adjusted for wall clock time.
* `Wall Time`: The wall clock time of the run, measured in seconds since the epoch.
* `Step`: The step number of the run, which is typically used to track the progress of training or evaluation.
- `Relative Time (Process)`: The relative time of the run, measured in seconds since the start of the run.
- `Relative Time (Wall)`: The relative time of the run, measured in seconds since the start of the run, adjusted for wall clock time.
- `Wall Time`: The wall clock time of the run, measured in seconds since the epoch.
- `Step`: The step number of the run, which is typically used to track the progress of training or evaluation.

### Custom metrics

Color runs and create meaningful plot legends based on custom metrics logged by your training or evaluation scripts. Custom metrics are logged as key-value pairs, where the key is the name of the metric and the value is the metric value.
Color runs and create meaningful plot legends based on custom metrics that your training or evaluation scripts log. You log custom metrics as key-value pairs, where the key is the name of the metric and the value is the metric value.

For example, the following code snippet logs accuracy (`"acc"` key) and loss (`"loss"` key) during a training loop:

Expand All @@ -69,7 +74,7 @@ Within the **Key** dropdown, both `"acc"` and `"loss"` are available options.

## Set a configuration key

The configuration options in your **Key** dropdown are derived from the key-value pairs you pass to the `config` parameter when you initialize a W&B run. Configuration keys are typically used to log hyperparameters or other settings used in your training or evaluation scripts.
As an alternative to using a metric, you can color runs based on a configuration key such as a hyperparameter. The configuration options in your **Key** dropdown come from the key-value pairs you pass to the `config` parameter when you initialize a W&B run. Use configuration keys to log hyperparameters or other settings used in your training or evaluation scripts.

```python
import wandb
Expand All @@ -87,40 +92,40 @@ with wandb.init(project="basic-intro", config=config) as run:

Within the **Key** dropdown, `"learning_rate"`, `"batch_size"`, and `"optimizer"` are available options.

## Set a y value
## Set a Y value

You can choose from the following options:
After you select a key, set a Y value to control which value of the selected metric drives the color assignment. The Y value determines which value of the selected metric W&B uses to assign a color to each run. You can choose from the following options:

- **Latest**: Determine color based on Y value at last logged step for each line.
- **Max**: Color based on highest Y value logged against the metric.
- **Min**: Color based on lowest Y value logged against the metric.
- **Latest**: Determines color based on Y value at the last logged step for each line.
- **Max**: Determines color based on the highest Y value logged against the metric.
- **Min**: Determines color based on the lowest Y value logged against the metric.

## Customize buckets

Buckets are ranges of values that W&B uses to categorize runs based on the metric or configuration key you select. Buckets are evenly distributed across the range of values for the specified metric or configuration key and each bucket is assigned a unique color. Runs that fall within that bucket's range are displayed in that color.
Adjust the number of buckets to control how finely W&B groups your runs by value. Buckets are ranges of values that W&B uses to categorize runs based on the metric or configuration key you select. W&B distributes buckets evenly across the range of values for the specified metric or configuration key and assigns each bucket a unique color. W&B displays runs that fall within a bucket's range in that color.

Consider the following:
Consider the following example:

<Frame>
<img src="/images/track/color-coding-runs.png" alt="Color coded runs" />
<img src="/images/track/color-coding-runs.png" alt="Run colors settings with Key set to acc and Y value set to Max, showing six buckets across the accuracy range." />
</Frame>

- **Key** is set to `"Accuracy"` (abbreviated as `"acc"`).
- **Y value** is set to `"Max"`
- **Y value** is set to **Max**.

With this configuration, W&B colors each run based on their accuracy values. The colors vary from a light yellow color to a deep color. Lighter colors represent lower accuracy values, while deeper colors represent higher accuracy values.
With this configuration, W&B colors each run based on its accuracy value. The colors vary from light yellow to deep purple. Lighter colors represent lower accuracy values, while deeper colors represent higher accuracy values.

Six buckets are defined for the metric, with each bucket representing a range of accuracy values. Within the **Buckets** section, the following range of buckets are defined:
W&B defines six buckets for the metric, with each bucket representing a range of accuracy values. The **Buckets** section defines the following range of buckets:

- Bucket 1: (Min - 0.7629)
- Bucket 2: (0.7629 - 0.7824)
- Bucket 3: (0.7824 - 0.8019)
- Bucket 4: (0.8019 - 0.8214)
- Bucket 5: (0.8214 - 0.8409)
- Bucket 6: (0.8409 - Max)
- Bucket 1: (Min to 0.7629)
- Bucket 2: (0.7629 to 0.7824)
- Bucket 3: (0.7824 to 0.8019)
- Bucket 4: (0.8019 to 0.8214)
- Bucket 5: (0.8214 to 0.8409)
- Bucket 6: (0.8409 to Max)

In the line plot below, the run with the highest accuracy (0.8232) is colored in a deep purple (Bucket 5), while the run with the lowest accuracy (0.7684) is colored in a light orange (Bucket 2). The other runs are colored based on their accuracy values, with the color gradient indicating their relative performance.
In the following line plot, the run with the highest accuracy (0.8232) appears in a deep purple (Bucket 5), while the run with the lowest accuracy (0.7684) appears in a light orange (Bucket 2). W&B colors the other runs based on their accuracy values, with the color gradient indicating their relative performance.

<Frame>
<img src="/images/track/color-code-runs-plot.png" alt="Color coded runs plot" />
<img src="/images/track/color-code-runs-plot.png" alt="Line plot with runs colored by accuracy, from light orange for lower values to deep purple for higher values." />
</Frame>
Loading
Loading