---
title: "Use TensorBoard on an instance"
description: "Run TensorBoard on a TIR Instance with the TensorBoard add-on and open its charts in your browser at the web address TIR gives the add-on."
content_type: "how-to"
product: "tir-instance"
platform: "TIR"
url: "/tir/tir-instance/how-to/use-tensorboard-on-an-instance/"
topic: ["guides"]
---

# Use TensorBoard on an instance

<!-- cspell:ignore logdir linspace keras -->

Run TensorBoard in your instance and open it in a browser tab. It shows how the loss of a training
run changes from epoch to epoch. You reach TensorBoard through the **Tensorboard** add-on, which
gives the app on port 6006 a web address of its own. The example here trains a small Keras model
and logs its loss. Once it works, point TensorBoard at your own training logs.

TensorBoard reaches your browser only when both parts are in place: the add-on is turned on, and
TensorBoard is running on port 6006 in the instance. Turning on an add-on is free.

## Before you begin

- A **Running** instance whose image includes JupyterLab, such as a TIR pre-built image. Add-ons
  work only on images with JupyterLab. See [Create an instance](/tir/tir-instance/how-to/create-an-instance/).
- A role in the project that lets you update instances, if you turn the add-on on for an existing
  instance.
- For the example, TensorFlow 2 on the image. To add it, run
  `!pip3 install tensorflow` in a notebook cell.

## Turn on the TensorBoard add-on

You can choose the add-on when you create the instance: under **Advanced Settings** > **Add-Ons**,
pick **Tensorboard**. See [Create an instance](/tir/tir-instance/how-to/create-an-instance/).

To turn it on for an instance you already have:

1. Open the instance and go to **Overview** > **Add-ons**.
2. Select **Configure Add-ons**, pick **Tensorboard**, and select **Save changes**.

The instance keeps running while you add or remove an add-on. The add-on then shows **Active** with
port 6006, an **Open** link, and the commands that install and start TensorBoard in a notebook cell.
Until its address is ready, it shows **Starting...** in place of **Open**.

## Install TensorBoard

The PyTorch, TensorFlow, and Transformers pre-built images already include TensorBoard. On other
images, such as the Jupyter image, open JupyterLab and run this in a notebook cell:

```bash
!pip3 install tensorboard
```

A package you install this way is kept only until the instance restarts, because everything outside
the workspace at `/home/jovyan` returns to the image's contents. Install it again after a restart,
or install it from a start script so it is there after every start. See
[Run start scripts on an instance](/tir/tir-instance/how-to/run-start-scripts-on-an-instance/).

## Log a training run

TensorBoard shows what your training code writes to a log folder. The example below fits a straight
line with Keras and writes the loss of every epoch under `logs/scalars`. Each run gets its own folder
there, named after the date and time of the run, so you can tell runs apart when you train again.

The log folder is created next to the notebook. Keep the notebook in `/home/jovyan`, so that the
logs are kept when the instance restarts.

1. Import the libraries and check that TensorFlow is version 2 or later:

   ```python
   import os
   from datetime import datetime
   from packaging import version

   import tensorflow as tf
   from tensorflow import keras
   from keras import backend as K

   import numpy as np

   print("TensorFlow version: ", tf.__version__)
   assert version.parse(tf.__version__).release[0] >= 2, \
       "This requires TensorFlow 2.0 or above."
   ```

2. Make 1,000 data points that lie roughly on the line y = 0.5x + 2, and split them into a training
   set and a test set:

   ```python
   data_size = 1000
   # 80% of the data is for training.
   train_pct = 0.8

   train_size = int(data_size * train_pct)

   # Create some input data between -1 and 1 and randomize it.
   x = np.linspace(-1, 1, data_size)
   np.random.shuffle(x)

   # Generate the output data.
   # y = 0.5x + 2 + noise
   y = 0.5 * x + 2 + np.random.normal(0, 0.05, (data_size, ))

   # Split into test and train pairs.
   x_train, y_train = x[:train_size], y[:train_size]
   x_test, y_test = x[train_size:], y[train_size:]
   ```

3. Train the model with the Keras TensorBoard callback, which writes the training and test loss to
   the log folder after every epoch:

   ```python
   logdir = "logs/scalars/" + datetime.now().strftime("%Y%m%d-%H%M%S")
   tensorboard_callback = keras.callbacks.TensorBoard(log_dir=logdir)

   model = keras.models.Sequential([
       keras.layers.Dense(16, input_dim=1),
       keras.layers.Dense(1),
   ])

   model.compile(
       loss='mse', # keras.losses.mean_squared_error
       optimizer=keras.optimizers.SGD(learning_rate=0.2),
   )

   print("Training ... With default parameters, this takes less than 10 seconds.")
   training_history = model.fit(
       x_train, # input
       y_train, # output
       batch_size=train_size,
       verbose=0, # Suppress chatty output; use TensorBoard instead
       epochs=100,
       validation_data=(x_test, y_test),
       callbacks=[tensorboard_callback],
   )

   print("Average test loss: ", np.average(training_history.history['loss']))
   ```

   The cell prints the average loss when training ends. Keras 3 also prints a warning about the
   input shape argument of the first layer. The model still trains.

## Start TensorBoard and open it

Start TensorBoard on the root log folder of the example, then print the add-on's address:

```python
%load_ext tensorboard
%tensorboard --logdir logs/scalars --bind_all --port 6006

os.getenv("TENSORBOARD_URL")
```

In the command:

- `--logdir` is the folder TensorBoard reads. For your own training, use the folder your code writes
  its logs to.
- The bind-all option makes TensorBoard listen on all addresses, which the add-on needs to reach
  it.
- `--port 6006` keeps TensorBoard on the add-on's port. If another TensorBoard already uses that
  port, the command stops with an error rather than moving to another port, since the add-on reaches only 6006.

Leave out TensorBoard's path prefix option: the add-on removes the address prefix before each
request reaches TensorBoard.

TensorBoard opens in its own browser tab, outside the notebook. Wait a few seconds for it to
start, then open the address the last line prints in a new browser tab. The same address opens from
**Open** under **Overview** > **Add-ons**. You need to be signed in to TIR to open it. If you are signed out, it redirects you to the sign-in page.

## Read the loss charts

TensorBoard opens on **Time Series**. Under **epoch_loss**, one line shows the training run and one
the validation run. Both fall steeply in the first 10 to 20 epochs, to near zero, and then stay flat
until epoch 100: the model has found the line.

![TensorBoard Time Series page. On the left, two runs are ticked: one ending in /train and one ending in /validation. The epoch_loss chart shows both loss lines starting above 0.02, falling to about 0.0025 within the first 20 steps, and staying flat to step 100. A second chart, evaluation_loss_vs_iterations, begins below it. The Settings panel on the right shows Smoothing at 0.6.](/images/tir/tir-instance/tensorboard-loss-charts.png)

Each time you train again, a new run appears in the list on the left, and its lines join the same
charts for comparison.

The **Gradio** add-on builds a web page where people can try your model. See
[Use Gradio on an instance](/tir/tir-instance/how-to/use-gradio-on-an-instance/). If a restart
clears TensorBoard or your packages, see
[Troubleshooting TIR Instances](/tir/tir-instance/troubleshooting/tir-instance/#my-files-or-installed-packages-are-gone-after-a-restart).
If the add-on address shows an error because nothing is listening on its port, see
[Troubleshooting TIR Instances](/tir/tir-instance/troubleshooting/tir-instance/#upstream-connect-error-or-disconnectreset-before-headers).