> For the complete documentation index, see [llms.txt](https://docs.datasentinel.io/manual/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.datasentinel.io/manual/implementation/agent-usage.md).

# Agent Usage

How to operate a Datasentinel agent once it is installed: its command line, its API, what it collects, and its configuration and log files.

This section covers the daily operation of an agent. To install one, see [Agent installation](https://docs.datasentinel.io/manual/getting-started/installation/agent.md). To update one, see [Agent upgrade](https://docs.datasentinel.io/manual/implementation/upgrade/agent.md).

| Page                                                                                                   | What it covers                                                                           |
| ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
| [Release Notes](https://docs.datasentinel.io/manual/implementation/agent-usage/release-notes.md)       | The changes of each agent version. Releases are cumulative: install the most recent one. |
| [CLI](https://docs.datasentinel.io/manual/implementation/agent-usage/cli.md)                           | Every command of the `datasentinel` command line                                         |
| [API Reference](https://docs.datasentinel.io/manual/implementation/agent-usage/api-reference.md)       | The same operations through the API of the agent                                         |
| [Collection Level](https://docs.datasentinel.io/manual/implementation/agent-usage/collection-level.md) | What the agent collects for each connection, and how to adjust it                        |
| [Internals](https://docs.datasentinel.io/manual/implementation/agent-usage/internals.md)               | Configuration files, log file and internal limits                                        |

## Two ways to drive the agent

The command line and the API do the same things. Use the command line on the server, and the API from a script or a remote tool.

|               | CLI                                                                          | API                                                                                              |
| ------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| **Used from** | A terminal on the agent server                                               | Any host that can reach the agent                                                                |
| **Address**   | The `datasentinel` command                                                   | `https://<<host_name>>:8282` by default                                                          |
| **Reference** | [CLI](https://docs.datasentinel.io/manual/implementation/agent-usage/cli.md) | [API Reference](https://docs.datasentinel.io/manual/implementation/agent-usage/api-reference.md) |

## What you manage

| Area                 | What you do                                                          | CLI examples                                                             |
| -------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| **Agent**            | Start, stop and check the agent, change its port and its limits      | `datasentinel status agent`                                              |
| **Upload server**    | Set and test the platform the agent sends its metrics to             | `datasentinel show server`, `datasentinel test server`                   |
| **Token**            | Set and check the license token                                      | `datasentinel show token`                                                |
| **Proxy**            | Route the agent through a proxy server                               | `datasentinel show proxy`                                                |
| **Connections**      | Add, show, update, enable, disable and delete PostgreSQL connections | `datasentinel show connections`                                          |
| **Collection level** | Choose what is collected for a connection                            | `datasentinel update connection <<connection_name>> lock-monitoring off` |
| **Internals**        | Display the internal metrics of the agent                            | `datasentinel show metrics`                                              |

## What the agent collects

Each connection has its own collection settings. The defaults suit most instances.

| Setting                   | Default                    | What it controls                                         |
| ------------------------- | -------------------------- | -------------------------------------------------------- |
| Query monitoring          | on                         | The statistics of the queries, from `pg_stat_statements` |
| Query monitoring filters  | 2 calls or 1 second        | Which queries are collected                              |
| Query monitoring optimize | on                         | The grouping of similar queries                          |
| Table monitoring          | on                         | The statistics of tables and indexes, every hour         |
| Lock monitoring           | on, with a 30-second delay | The detection of blocking scenarios                      |
| Query samples             | off                        | Samples of queries with their literal values             |

Two limits are set for the whole agent: the number of tables per instance, and the number of distinct queries per day (30000 by default). Above a limit, the matching collection is deactivated.

See [Collection Level](https://docs.datasentinel.io/manual/implementation/agent-usage/collection-level.md).

{% hint style="info" %}
With the [agentless](https://docs.datasentinel.io/manual/features/other-features/agentless-monitoring.md) method, the same settings exist. They are set once for all the agentless instances, in the [backend configuration](https://docs.datasentinel.io/manual/implementation/platform-usage/configuration/backend.md#agentless-agents).
{% endhint %}

## Files and limits

| Item              | Where                                                                                            |
| ----------------- | ------------------------------------------------------------------------------------------------ |
| **Configuration** | The hidden `.datasentinel` directory of the user's home: `agent.yml` and `connections.yml`       |
| **Log**           | `datasentinel.log`, in the `log` subdirectory of the agent                                       |
| **Memory limit**  | 2 GB by default. The agent checks its memory every 15 minutes and stops if it exceeds the limit. |

See [Internals](https://docs.datasentinel.io/manual/implementation/agent-usage/internals.md).

## Pages

{% content-ref url="/pages/MAP2YFfUJ0hfgplw8cAI" %}
[Release Notes](https://docs.datasentinel.io/manual/implementation/agent-usage/release-notes.md)
{% endcontent-ref %}

{% content-ref url="/pages/xmYSWfE9TA99dsgsW4mn" %}
[CLI](https://docs.datasentinel.io/manual/implementation/agent-usage/cli.md)
{% endcontent-ref %}

{% content-ref url="/pages/J9dSGVENOsIzGxqxpoKG" %}
[API Reference](https://docs.datasentinel.io/manual/implementation/agent-usage/api-reference.md)
{% endcontent-ref %}

{% content-ref url="/pages/PU7809BSrcyBDPOEXxXT" %}
[Collection Level](https://docs.datasentinel.io/manual/implementation/agent-usage/collection-level.md)
{% endcontent-ref %}

{% content-ref url="/pages/hUrX1ho94QetFEPZo44R" %}
[Internals](https://docs.datasentinel.io/manual/implementation/agent-usage/internals.md)
{% endcontent-ref %}

## See also

* [Agent FAQ](https://docs.datasentinel.io/manual/getting-started/faqs/agent-faq.md)
* [Unexpected Agent Termination](https://docs.datasentinel.io/manual/implementation/troubleshooting/unexpected-agent-termination.md)
* [Platform Usage](https://docs.datasentinel.io/manual/implementation/platform-usage.md)


---

# 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://docs.datasentinel.io/manual/implementation/agent-usage.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.
