DocumentaciónHelp

APM agents

Install the APM agent on a Linux or Windows server, instrument its applications (including Windows services and IIS), update it without reinstalling, check its status, and revoke or remove it.

On this page

An APM agent receives telemetry from the applications on a server and sends it to ARGUNIS with that agent's own certificate. In Settings → APM → APM agents you create the command that installs it, see the steps to instrument each application, update it when a new version is out, check whether it's connected, and revoke or remove it.

Before you start

  • Your plan must include the APM module and APM must be active. See Enable APM.

  • To see the list you need Operate on the APM module. To create tokens, update, revoke or remove you need Administer.

  • A Linux server with systemd (x64 or arm64) with someone who can use sudo, or a Windows Server 2016 or later (x64) with someone who can open PowerShell as Administrator.

If the page shows a notice above the list (for example, that APM isn't active), you can't create tokens until it's resolved.

ARGUNIS doesn't install, instrument or restart anything on your servers on its own. The server administrator runs the commands on this page when they decide to.

Create the install command

  1. Go to Settings → APM → APM agents.

  2. Click New APM agent.

  3. Enter a Name that identifies the server or system (for example, the server name and its environment). It can't repeat another agent's name.

  4. Click Create.

  5. Copy the command with Copy install command and keep it somewhere safe: it includes the agent token. Below it, the Agent connection appears: the address where it enrolls, where it will send, and the authority fingerprint. Then click Done.

The command is shown only once, its token installs a single agent, and it expires after 24 hours. If it's lost or expires, create a new one (below).

Install the agent on the server

  1. Log in to the Linux server where the applications run, with a user who can use sudo.

  2. Paste and run the command you copied. It looks like this:

curl -fsSL 'https://<tu ARGUNIS>/apm-agent/v1/install.sh' | sudo sh -s -- --token 'jaa_…'
  1. Wait for the message APM agent … installed and running.

The installer verifies the agent's signature before installing anything, creates a dedicated system user for the agent, enrolls it with the token (the certificate key is generated on your server and never leaves it), and sets it up as a service that starts automatically. Within a few minutes the agent shows as connected in the list.

On a ARGUNIS installed on your network with its own certificate, the command shown on screen is already built for that: it downloads the installer, verifies its fingerprint, and passes it your authority's certificate (--server-ca). Use it as is.

Instrument an application

Each application you want to see in APM is instrumented once, with its systemd service. In Settings → APM → API key and SDK, section Instrument an application with the APM agent, choose the language (Java, .NET, Node.js or Python) to see its exact steps.

  1. If the language requires it, prepare the application:

    • Node.js: in the application folder, npm install @opentelemetry/api @opentelemetry/auto-instrumentations-node.

    • Python: in the application's environment, pip install opentelemetry-distro opentelemetry-exporter-otlp && opentelemetry-bootstrap -a install.

    • Java and .NET: nothing; the agent downloads and verifies what's needed.

  2. On the server, run the command with the service name, its environment and its version:

sudo argunis-apm-agent --instrumentar facturacion.service --lenguaje java --env produccion --version 1.4.2
  1. Python only: add opentelemetry-instrument in front of the service's start command.

  2. Restart the service when it suits you (for example, during a maintenance window):

sudo systemctl restart facturacion.service

The command leaves the configuration ready but doesn't restart the application: it starts sending after you restart it.

To stop instrumenting it, run sudo argunis-apm-agent --desinstrumentar facturacion.service and restart the service.

Observe an application without instrumenting it (eBPF)

If an application on a Linux server can't be instrumented (a program without source code, an old binary, or a language with no agent), the agent can observe it from the operating system with eBPF, using OpenTelemetry eBPF Instrumentation (OBI). It sees its HTTP and gRPC requests and its database queries (MySQL, PostgreSQL, SQL Server, Redis, MongoDB), Kafka and others, without touching or restarting the application. It's off by default: the server administrator turns it on.

You need a Linux server with kernel 5.8 or later (or Red Hat Enterprise Linux 8 and its derivatives) that exposes BTF, like current distributions (Ubuntu 20.10+, Debian 11+, RHEL 8.2+), and the APM agent already installed. If the server doesn't qualify, the command says so and turns nothing on.

  1. Choose what to observe: the programs listening on certain ports or an executable by name.

  2. On the server, run one of these commands:

sudo argunis-apm-agent --ebpf activar --puertos 80,443,8080 --env produccion
sudo argunis-apm-agent --ebpf activar --proceso facturador --env produccion
  1. Wait for the message eBPF enabled. Within a few minutes the application appears in APM → Services with the name of its executable.

To check it, run sudo argunis-apm-agent --ebpf estado; to change what it observes, run --ebpf activar again with other ports or process; to turn it off, sudo argunis-apm-agent --ebpf desactivar.

With eBPF you see the rate, errors and latency of each request and its calls, but not what happens inside the code (functions, exceptions with their details) or HTTPS requests encrypted by the Java application itself. If the application can be instrumented with its language (above), that's the best option. Applications that are already instrumented aren't duplicated: eBPF skips them.

What each instrumentation method covers, by language and version: What you can monitor with APM.

Install the agent on Windows

  1. In the agent install dialog, choose the Windows tab.

  2. On the Windows server, open PowerShell as Administrator.

  3. Copy the command from Step 1 and paste it into PowerShell (it's a single line). It downloads the installer, verifies its fingerprint (SHA-256), and only then runs it.

  4. When it asks for the key, copy the one from Step 2, paste it and press Enter. Nothing shows on screen when you paste it: that's normal.

  5. Wait for the message APM agent … installed and running.

The installer verifies the agent's signature, sets up the ArgunisApmAgent Windows service (it starts with the host), and enrolls the agent: its certificate key is generated on the server, in C:\ProgramData\ArgunisApmAgent, which only the system and administrators can read. The agent's logs are in C:\ProgramData\ArgunisApmAgent\logs.

On a ARGUNIS installed on your network with its own certificate, the command on the Windows tab already includes your authority's certificate (-ServerCa). Use it as is.

Instrument a Windows service or IIS

On Windows you can instrument .NET applications (.NET Framework 4.6.2 or later and .NET 6 or later) and Java applications (8 or later) that run as a Windows service, and .NET sites on IIS by their application pool (app pool). The agent downloads and verifies what's needed; you don't have to change the application. All commands go in PowerShell as Administrator.

Windows service (use the service name, the one Get-Service shows, not the display name):

& 'C:\Program Files\ArgunisApmAgent\bin\argunis-apm-agent.ps1' -Instrumentar Facturacion -Lenguaje dotnet -Env produccion -Version 1.4.2

With Java, change -Lenguaje dotnet to -Lenguaje java. Then, when it suits you, restart the service:

Restart-Service -Name 'Facturacion'

IIS (.NET only), with the app pool name:

& 'C:\Program Files\ArgunisApmAgent\bin\argunis-apm-agent.ps1' -AppPool Ventas -Lenguaje dotnet -Env produccion

Then recycle the app pool when it suits you:

Restart-WebAppPool -Name 'Ventas'

The command sets the instrumentation variables on the service or app pool but doesn't restart the application: it starts sending after you restart or recycle it. IIS may recycle the app pool on its own when its configuration changes, if it's set up that way.

Variables the service or app pool already had are kept. To stop instrumenting, run argunis-apm-agent.ps1 -Desinstrumentar Facturacion (service) or argunis-apm-agent.ps1 -Desinstrumentar -AppPool Ventas (IIS), and restart or recycle: the agent's variables are removed and the previous ones come back. To see the agent's status: argunis-apm-agent.ps1 -Status.

Uninstall the Windows agent

  1. First remove the instrumentation from each application (above) and restart it: the uninstaller won't proceed if any is still instrumented.

  2. In PowerShell as Administrator, run the installer with -Desinstalar (download it from the URL shown in the dialog):

& "$env:TEMP\argunis-apm-agent-install.ps1" -Desinstalar
  1. Also remove the agent in ARGUNIS (below, Remove an agent).

What you get

  • The application appears in APM → Services with the name, environment and version you set, along with its traces, rate, errors and latencies. See View services.

  • The agent sends over an encrypted channel with its own certificate, which it renews automatically before it expires.

  • If ARGUNIS is unavailable for a while, what was sent waits on the server's disk and is delivered when it's back, without being lost.

Check the status

Each agent shows:

Column

What it means

Status (dot and text under the name)

waiting for installation (not installed yet; if it says token expired, create a new one), connected (sent in the last few minutes), offline, installed · not connected yet or revoked

Server

Host name and operating system reported by the agent

Version

Version of the installed agent. → 1.3.1 (yellow) means a new version is available; updating to … means the order was sent; … failed, rolled back to … (red) means the new version didn't start and the agent kept the previous one (hover to see the reason)

Last connection

How long ago it last connected or sent (hover to see the exact date)

Certificate expires

How long its certificate is valid. The agent renews it automatically before that date

Update an agent

When a new version of the APM agent is out, the Version column says so and the Update button (arrows icon) appears in the row. You don't need to reinstall or create a token: the agent keeps its identity, its certificate, whatever is waiting on disk, the instrumented applications and eBPF.

  1. In the agent's row, click Update (or Update all to … above the list for all agents on an older version).

  2. Confirm with Update.

  3. Within a minute at most, the agent picks up the order: it downloads the new version, verifies its signature, and restarts only the APM agent (your applications keep running). When it's done, the Version column shows the new one.

If the new version doesn't start, the agent rolls back to the previous one on its own within a few minutes and the row shows it in red. Data isn't lost: it waits on the server's disk while the agent restarts.

The server administrator can also update it:

sudo argunis-apm-agent --actualizar
& 'C:\Program Files\ArgunisApmAgent\bin\argunis-apm-agent.ps1' -Actualizar

Agents on a version earlier than 1.3.0 can't be updated from the web (the new version notice appears, but without a button): reinstall them once with a new token (below).

Create a new token for an agent

Use this if the token expired before installing or if you need to reinstall the agent.

  1. In the agent's row, click the key icon (New install token).

  2. Confirm with Create token.

  3. Copy the new install command and click Done.

  4. Run it on the server as in Install the agent on the server or Install the agent on Windows. Applications that are already instrumented aren't touched.

If the agent was already installed, its certificate stops being valid immediately and you'll have to reinstall it with the new token. If it wasn't, the previous unused tokens stop working.

Revoke an agent

  1. In the agent's row, click the stop icon (Revoke).

  2. Confirm with Revoke.

Its certificate stops being valid immediately and ARGUNIS cuts its connection. The agent stays in the list as revoked; to use that server again, remove it and create a new agent.

Remove an agent

  1. In the agent's row, click the trash icon (Remove).

  2. Confirm with Remove.

If the agent was active, its certificate stops being valid immediately and ARGUNIS cuts its connection. Afterwards, uninstall it from the server.

Data the agent already sent stays in APM until it expires under the retention period.

Related

Search Argunis Monitoring

Type at least 2 characters to search Argunis Monitoring.

↑↓ to navigate · Enter to open · Esc to close