> For the complete documentation index, see [llms.txt](https://docs.flopsar.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flopsar.com/user-guide/setting-up-monitoring/agents.md).

# Agents

Connected JVMs appear under **Home → Instances**. Each agent reports an **application** name (`app=` on the command line) and an **instance** name (editable in the Workstation). Click an instance to open its details.

Instance telemetry (JVM, agent counters) is refreshed about every five seconds and is not persisted — it is available only while the agent stays connected.

<figure><img src="https://1957839935-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQzShZISPoFZ9zIHUdjNB%2Fuploads%2Fgit-blob-1eae2799532f976f5d60229e3b4502beffb8de86%2Finstances_list.png?alt=media" alt="Home → Instances with the Online, Licensed, Total Methods, With Errors and Data Sent cards, and the Connected Instances table with one konakart instance"><figcaption><p>One connected instance of konakart.</p></figcaption></figure>

## Instances list

Summary cards:

* **Online** — agents with an open session
* **Licensed** — instances that currently hold a license seat
* **Total Methods** — instrumented methods across online agents
* **With Errors** — instances that reported detected JVM errors
* **Data Sent** — outbound volume from agents

The table has the following columns:

* **Instance** — opens the instance details. A red dot marks an instance with detected JVM errors.
* **Application**
* **Profile** — the active profile; opens the profile.
* **Host** — the host name; hover it to see the address.
* **Tech** — the monitored technology.
* **Version** — the agent version; a check mark means the instance holds a license seat.
* **Methods** — instrumented methods; a spinning cog means instrumentation is in progress.
* **CPU** — the host CPU usage.
* **Errors** — internal errors of the agent (see [Diagnostics](#diagnostics)), not JVM errors.
* **Sent** — data the agent has sent.

Filter by instance, application, host, technology, version, or profile; sort any column. An empty list means no agent has completed a handshake (check [agent tokens](https://docs.flopsar.com/administrator-guide/agent/agent-tokens.md) and `server=`).

The **⋮** menu at the end of a row runs some of the [instance queries](#details) without opening the details:

* **Options** — Command line, JVM properties, Packages
* **Diagnostics** — Classloaders, Plugins, Active profile, Class bytes

**Active profile** shows the profile as the agent currently applies it. It is available only from this menu.

Attaching the library is an administrator task — see [Installation → Agent](https://docs.flopsar.com/administrator-guide/installation/agent.md).

## Instance details

The details page has four tabs: **Details**, **Memory**, **Threads**, and **Diagnostics**.

<figure><img src="https://1957839935-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQzShZISPoFZ9zIHUdjNB%2Fuploads%2Fgit-blob-975fc925f111098c3879b1bcaa636ffe9f32a97e%2Finstance_details.png?alt=media" alt="The details of a konakart instance: the Details, Memory, Threads and Diagnostics tabs, the CPU usage, System memory, Errors, Instr. methods and Data rate charts, and the Details, Settings, Capabilities, System and JVM cards"><figcaption><p>The Details tab. When the agent detects JVM errors, a <strong>Detected errors</strong> banner appears above the cards.</p></figcaption></figure>

### Details

Charts at the top show the recent CPU usage, system memory, agent errors, instrumented methods, and data rate. Below them are the cards:

* **Details** — instance name, application, PID, agent version, start and connect times. Click the name to rename the instance.
* **Settings** — profile, number of loaded plugins, and whether CPU time, memory, and threads monitoring are enabled.
* **Capabilities** — JVM features the agent can use: class retransform, CPU time, Java errors, virtual threads, and memory sampling.
* **System** — host name, operating system, CPU model and number of cores, installed memory.
* **JVM** — version, name, and vendor.

**Options** (requires **Query agents**) runs live queries against that JVM:

* Command line
* JVM properties
* Threads dump. **Add to case** in its header keeps a new thread dump of the instance as evidence of an [investigation](https://docs.flopsar.com/user-guide/observing-and-diagnosing/investigation.md); see [Adding Evidence](https://docs.flopsar.com/user-guide/observing-and-diagnosing/investigation/adding-evidence.md#a-thread-dump). *Available since Flopsar 7.2.*
* Packages
* Class bytes
* Classloaders

**Agent Diagnostics** in the same menu:

* Telemetry — see [Agent telemetry](#agent-telemetry)
* Plugins

### Agent telemetry

**Options → Telemetry** shows the agent's own runtime counters. They are read from the agent when the dialog opens; **Refresh** in the dialog header reads them again. Nothing is stored on the server, and the counters cover the time since the agent started.

<figure><img src="https://1957839935-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQzShZISPoFZ9zIHUdjNB%2Fuploads%2Fgit-blob-f91e93407d6d50273e7bd50a4058d83fabe56e1e%2Fagent_telemetry.png?alt=media" alt="The Agent Telemetry dialog with the General, Symbols and Invocations groups: Bytes sent, Memory usage, Threads, Classes, Methods, Keys, Invocations outbound queue size, Invocations outbound enqueued and Invocations outbound dropped"><figcaption><p>Agent telemetry of a konakart instance.</p></figcaption></figure>

| Group       | Counter                         | Meaning                                                                                                |
| ----------- | ------------------------------- | ------------------------------------------------------------------------------------------------------ |
| General     | Bytes sent                      | Data the agent has sent to the server                                                                  |
| Symbols     | Memory usage                    | Memory the agent uses for its symbol tables                                                            |
| Symbols     | Threads, Classes, Methods, Keys | Names in the agent's symbol tables: thread names, class names, method names, and key-value metric keys |
| Invocations | Invocations outbound queue size | Collected invocations waiting in the agent to be sent                                                  |
| Invocations | Invocations outbound enqueued   | Invocations the agent has queued for sending                                                           |
| Invocations | Invocations outbound dropped    | Invocations the agent discarded because they could not be queued                                       |

The agent sends each name to the server once and then refers to it by an identifier. The symbol counts are therefore not the number of instrumented methods on the Details tab.

**Pull symbols from the agent** (the arrow next to Threads, Classes, Methods, or Keys) asks the agent to send all names of that kind to the server again. Use it when the server is missing names that the agent has already reported. The button is disabled for five seconds after each use.

A non-zero **Invocations outbound dropped** means data was lost; see [Dropped data](#dropped-data). A queue size that keeps growing means the agent produces data faster than it can send it.

### Detected errors

The agent reports a subset of `java.lang.Error` types. When one is detected, a **Detected errors** banner lists the types and counts. Click a type to inspect occurrences. **Clear** (requires **Query agents**) resets the agent's error registry.

Reported types include `VerifyError`, `NoClassDefFoundError`, `ClassFormatError`, `StackOverflowError`, `OutOfMemoryError`, `UnsupportedClassVersionError`, `VirtualMachineError`, `ClassCircularityError`, `UnsatisfiedLinkError`, `NoSuchMethodError`, and `NoSuchFieldError`. If `VerifyError` or `ClassFormatError` is caused by instrumentation, exclude the offending class from the profile.

{% hint style="info" %}
The agent can report errors that never appear in the application's own logs. They are often not fatal.
{% endhint %}

### Dropped data

If the agent cannot send all collected data, a **Dropped data** warning shows how many invocations were dropped. Reduce the monitoring scope or check throughput between the agent and the server.

### Memory

A heap-usage chart for the connected instance. **Get heap dump** (requires **Switch agent's features** and **Query agents**) walks the heap and fills the **Heap Objects** table: the classes that take the most memory, with the number of instances and their total size. The size is the sum of the objects' own sizes, without the objects they reference. Walking the heap can slow the application down — use it briefly.

### Threads

Two charts: the number of live threads and the number of threads created per second.

### Diagnostics

The agent's own log. The agent does not write log files on disk; it keeps its most recent 512 log lines in memory, so the log is lost when the JVM restarts. Without **Query agents** the tab is empty.

**Fetch logs** reads the log from the agent. The view does not update by itself; **Refresh** reads it again. Each line has a timestamp, a level, and a message:

* `E` — an error, shown in red, for example a failed instrumentation, class retransformation, or query
* `W` — a warning, shown in amber
* `I` — information, for example profile decoding and class retransformation

Messages longer than about 120 characters are cut off.

The **Lines**, **Errors**, and **Warns** counters cover everything the agent has logged since the JVM started, including lines no longer kept in memory. The same error count appears in the **Errors** column of the [instances list](#instances-list) and in the **Errors** chart on the Details tab.

Messages from the agent startup (command-line options, configuration errors, the agent key) and detailed errors from parsing and rewriting the bytecode of a class are not in this log. The agent prints them to the standard error output of the JVM, so look for lines starting with `[FLOPSAR]` in the application's console output or its log — especially when the agent does not connect at all.

Each **Fetch logs** and **Refresh** is recorded in the audit log.
