---
title: Using Notecard Trace Mode
description: Learn how to utilize Notecard trace mode for debugging
source_url: https://dev.blues.io/support/using-notecard-trace-mode/
canonical_url: https://dev.blues.io/support/using-notecard-trace-mode/
markdown_url: https://dev.blues.io/support/using-notecard-trace-mode.md
---

# Using Notecard Trace Mode

All Notecards can be placed into trace mode. When enabled, a Notecard's trace mode generates a stream of messages that can help with debugging or understanding Notecard behavior.

You can utilize trace mode using:

1. [In-Browser Terminal](#in-browser-terminal)
2. [Serial Terminal Apps](#serial-terminal-apps)
3. [\_log Environment Variable](#log-environment-variable)

> **Note:**
>
> Trace output is emitted only over a **serial** connection—either the USB serial port or the Notecard's `AUX` `RX`/`TX` serial port. It is **not** sent over the I2C bus, so `{"req":"card.trace","mode":"on"}` will enable trace mode but a host communicating with the Notecard over I2C cannot read the trace stream on that bus. If your host uses I2C, connect a serial terminal to the `AUX` `RX`/`TX` pins (115200 8N1) to view live trace output, or use the [`_log` environment variable](#log-environment-variable) to capture (less verbose) logs to the `_log.qo` Notefile on Notehub.

> **Warning:**
>
> Notecard's trace mode is available for debugging purposes only. The format of the output is not standardized and is subject to change at any time. If you need help interpreting a Notecard's trace output to debug an issue, reach out in our [community forum](https://discuss.blues.com) or [contact Blues support](mailto:support@blues.com).

## In-Browser Terminal

Complete the following steps to use trace mode via the In-Browser Terminal.

1. Visit the [In-Browser Terminal](https://dev.blues.io/terminal/).

2. [Connect your Notecard to the terminal](https://dev.blues.io/quickstart/notecard-quickstart/notecard-and-notecarrier-f.md).

3. Enable trace mode with the following request:

   ```json
   {"req":"card.trace","mode":"on"}
   ```

4. Perform actions that you want to debug. For example, to debug network connectivity issues you may wish to run a `hub.sync` request.

   ```json
   {"req":"hub.sync"}
   ```

5. Disable trace mode with the following request:

   ```json
   {"req":"card.trace","mode":"off"}
   ```

6. (Optional) Download the trace log using the **Save History** button in the top-left corner of the Terminal. This will download the contents of the Terminal history to a `.log` file. ![Saving history via Notecard In-Browser Terminal](https://dev.blues.io/images/guides/notecard-guides/trace-mode/terminal-save-history.png?v=ffb59de4)

## Serial Terminal Apps

Complete the following steps to use trace mode via a serial terminal app.

1. Connect a Notecard to your serial terminal app using one of the following serial port configurations.

   | Connection | Serial Configuration                            | Abbreviated |
   | ---------- | ----------------------------------------------- | ----------- |
   | USB        | Baud Rate: 9600, 8 bit, no parity, 1 stop bit   | 9600 8N1    |
   | AUX RX/TX  | Baud Rate: 115200, 8 bit, no parity, 1 stop bit | 115200 8N1  |

   > **Note:**
   >
   > Refer to our guides on using Tera Term and CoolTerm for more specific instructions on connecting to Notecard via those applications:
   >
   > - [Configuring Tera Term to communicate with Notecard](https://discuss.blues.com/t/how-do-i-configure-tera-term-to-communicate-with-notecard/150)
   > - [Configuring CoolTerm to communicate with Notecard](https://discuss.blues.com/t/how-do-i-configure-coolterm-to-communicate-with-notecard/151)

2. Enable trace mode with the following request:

   ```json
   {"req":"card.trace","mode":"on"}
   ```

3. Perform actions that you want to debug. For example, to debug network connectivity issues you may wish to run a `hub.sync` request.

   ```json
   {"req":"hub.sync"}
   ```

4. Disable trace mode with the following request:

   ```json
   {"req":"card.trace","mode":"off"}
   ```

## \_log Environment Variable

You can remotely enable diagnostic logging at the device, fleet, or project level using the `_log` [reserved environment variable](https://dev.blues.io/guides-and-tutorials/notecard-guides/understanding-environment-variables.md#reserved-environment-variables). When enabled, this will save trace logs to the `_log.qo` Notefile on Notehub. Please note that the trace logs saved to Notehub using this method are far less verbose than the logs you can generate using the other methods outlined above.

> **Warning:**
>
> Saving and syncing logging data with Notehub will impact your cellular data allocation. To avoid unnecessary usage, enable this feature only when required and disable it immediately afterward.

1. Set the `_log` environment variable using either the [env.default API](https://dev.blues.io/api-reference/notecard-api/env-requests/latest.md#env-default) or [the Notehub UI](https://dev.blues.io/guides-and-tutorials/notecard-guides/understanding-environment-variables.md#setting-a-notehub-device-variable).

2. When setting the variable, use one of the following values to specify the scope of the logging data to save:

   - `gps` (to save high-level GPS status information)
   - `gpsmax` (to save more verbose GPS logging)
   - `power` (to save power-usage snapshots from a connected [Mojo](https://dev.blues.io/datasheets/mojo-datasheet.md))
   - `modem` (to save modem lifecycle and network state transitions)
   - `accel` (to save accelerometer/motion-detection activity)
   - `all` (to save more broad diagnostic data)

   To capture more than one scope at a time, separate the values with a comma or semicolon (for example, `gps,modem`).

3. Note that `_log.qo` Notes are **generated only when a new Notehub session begins**. If your Notecard is running in `continuous` mode, either set the `_session_mins` environment variable or set a `duration` value in your `hub.set` request. This allows you to define session length (in minutes) and ensure logs are created as expected.

4. When finished gathering trace log data, be sure to **delete these environment variables** to silence logging and avoid unnecessary data usage.