> For the complete documentation index, see [llms.txt](https://boxlang.ortusbooks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://boxlang.ortusbooks.com/boxlang-framework/observability.md).

# Observability

How to see what your BoxLang applications, servers and AI agents are doing, with BxLens, BxMCP, logging and the debugger.

Observability answers one question: **what is my application doing right now, and why?** BoxLang gives you several tools for it. Some are built into the runtime, and some are modules you add. This section helps you pick the right one and shows how to get started.

{% embed url="<https://www.youtube.com/watch?v=m0MAC_JetTk>" %}

## 🧭 Pick your tool

| I want to...                                                          | Use                                                                                                                 | Cost                                        |
| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
| See what one request did, step by step                                | [BxLens](https://boxlang.ortusbooks.com/boxlang-framework/observability/bxlens.md) debug bar                        | Free                                        |
| Find slow queries, repeated queries and slow outgoing calls           | [BxLens](https://boxlang.ortusbooks.com/boxlang-framework/observability/bxlens.md) bar and console                  | Free, with limits                           |
| Work failures as issues: group, resolve, ignore, add notes            | [BxLens](https://boxlang.ortusbooks.com/boxlang-framework/observability/bxlens.md) Errors page                      | Free in memory, saved to disk with BoxLang+ |
| Watch the JVM, threads, disks, caches and scheduled tasks of a server | [BxLens](https://boxlang.ortusbooks.com/boxlang-framework/observability/bxlens.md) console                          | Free for one server                         |
| Be alerted by email, Slack, Teams or Telegram                         | [BxLens](https://boxlang.ortusbooks.com/boxlang-framework/observability/bxlens.md) alerts and reports               | BoxLang+                                    |
| Watch many servers from one place                                     | [BxLens](https://boxlang.ortusbooks.com/boxlang-framework/observability/bxlens.md) fleet view                       | BoxLang+                                    |
| See what your AI agents do and what they cost                         | [AI and MCP observability](https://boxlang.ortusbooks.com/boxlang-framework/observability/ai-and-mcp.md)            | BoxLang+                                    |
| Keep an audit trail of an agent you build                             | [BoxLang AI governance](https://boxlang.ortusbooks.com/boxlang-ai/boxlang-ai/governance-and-security.md) middleware | Included with BoxLang AI                    |
| Let an AI assistant inspect and operate a live runtime                | [BxMCP](https://boxlang.ortusbooks.com/boxlang-ai/bx-mcp.md)                                                        | Free, needs `bx-ai`                         |
| Write application and runtime logs                                    | [Logging](https://boxlang.ortusbooks.com/boxlang-framework/logging.md)                                              | Core                                        |
| Step through code                                                     | [BoxLang Debugger](https://boxlang.ortusbooks.com/getting-started/ide-tooling/boxlang-debugger.md)                  | Core                                        |
| Time a block of code                                                  | [Timer component](https://boxlang.ortusbooks.com/boxlang-language/reference/components/debug/timer.md)              | Core                                        |

## 🔭 What you can observe

{% columns %}
{% column %}

### Your application

* Every request, with a waterfall of templates, queries and HTTP calls
* Errors grouped into issues that you can work through
* Slow and repeated queries, including ORM SQL
* Outgoing HTTP calls by host and endpoint
* Mail your application builds and sends
* ColdBox events, views, modules and schedulers
  {% endcolumn %}

{% column %}

### Your servers and agents

* The JVM: heap, garbage collection, threads and deadlocks
* Executors, scheduled tasks, datasources and caches
* Disks, CPU and memory, with the share that belongs to BoxLang
* Every server that shares a store folder
* AI agent runs, model calls, tool calls and MCP servers, with cost
  {% endcolumn %}
  {% endcolumns %}

## 🚀 Get started

{% stepper %}
{% step %}

### Install BxLens

```bash
# BoxLang binary
bx-module install bx-lens

# CommandBox
box install bx-lens
```

{% endstep %}

{% step %}

### Turn on the bar and the console

BxLens ships with everything off. Enable each surface in `boxlang.json`. The [BxLens page](https://boxlang.ortusbooks.com/boxlang-framework/observability/bxlens.md) shows the settings.
{% endstep %}

{% step %}

### Open your app

Load a page from the same machine to see the bar. Open `/~bxlens/index.bxm` for the console.
{% endstep %}

{% step %}

### Add the agents

If you build with BoxLang AI, turn on the AI page of the console. If you want an AI assistant to inspect the runtime, install [BxMCP](https://boxlang.ortusbooks.com/boxlang-ai/bx-mcp.md). See [AI and MCP observability](https://boxlang.ortusbooks.com/boxlang-framework/observability/ai-and-mcp.md).
{% endstep %}
{% endstepper %}

## 📚 In this section

{% content-ref url="/pages/EzEcU6oifVQJccVAX4AM" %}
[BxLens](https://boxlang.ortusbooks.com/boxlang-framework/observability/bxlens.md)
{% endcontent-ref %}

{% content-ref url="/pages/sUkT14JcLG3FdFndaaja" %}
[AI and MCP Observability](https://boxlang.ortusbooks.com/boxlang-framework/observability/ai-and-mcp.md)
{% endcontent-ref %}

{% content-ref url="/pages/J1PXlIwB56Ax1VPcaLqa" %}
[Gallery and Videos](https://boxlang.ortusbooks.com/boxlang-framework/observability/gallery.md)
{% endcontent-ref %}

## 🔗 Related

{% content-ref url="/pages/uxLeDfcz3tUZw9F6X5r5" %}
[Logging](https://boxlang.ortusbooks.com/boxlang-framework/logging.md)
{% endcontent-ref %}

{% content-ref url="/pages/zXzxkBeHADkATzbyFTAr" %}
[BxMCP](https://boxlang.ortusbooks.com/boxlang-ai/bx-mcp.md)
{% endcontent-ref %}


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://boxlang.ortusbooks.com/boxlang-framework/observability.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
