Skip to main content

Registration

Before an agent can send metrics to the platform, it must register itself with the PMP4PG backend. Registration is a one-time process that:

  1. Creates a Server and Agent record in the platform repository
  2. Assigns a unique agent_id (UUID) to this agent
  3. Generates a unique api_key for secure communication

Prerequisites​

Before registering the agent:

  • The PMP4PG platform (backend) must be running and reachable from the agent host
  • A registration token must have been generated by a platform administrator
  • The agent binary must be installed and config.yml must be configured

Step 1 — Obtain a Registration Token​

A platform administrator generates a one-time registration token from the PMP4PG web interface:

{screenshot: generate-registration-token}

Navigate to Server Management → Add New Server and generate a registration token. Copy this token — it will be used in the next step.

warning

Registration tokens are single-use. Once an agent registers successfully, the token is invalidated. Generate a new token for each agent you register.

Step 2 — Set the Token in config.yml​

Edit the agent's config.yml and paste the registration token:

registration:
  token: "your-one-time-registration-token-here"

agent:
  id: ""        # Leave empty — will be assigned by the platform

central:
  api_url: "http://pmp-backend.example.com:8080/pmp"
  api_key: ""   # Leave empty — will be assigned by the platform

Also make sure the server section is correctly filled:

server:
  hostname: "pg-prod-01"     # How this server will appear in the dashboard
  environment: RUN           # RUN or BUILD
  datacenter: "eu-west-1"
  tags:
    - postgresql-16
    - app-backend

Step 3 — Run the Registration​

Execute the agent in registration mode:

cd /opt/pmp4pg-agent
./pmp4pg-agent --config config.yml --register

The agent will:

  1. Detect that agent.id is empty
  2. Collect server information (hostname, OS, PostgreSQL version)
  3. Send a POST /api/v1/register request to the backend with the registration token
  4. Display the assigned agent_id and api_key

Expected output:

================================================================================
PMP4PG Agent — Registration
================================================================================
Collecting server information...
  Hostname    : pg-prod-01
  OS          : linux/amd64
  PostgreSQL  : 16.2
  Environment : RUN

Sending registration request to http://pmp-backend.example.com:8080/pmp ...

Registration successful!

  Agent ID  : a3f1c2d4-8b5e-4f2a-9c1d-0e7f3b2a6d8c
  API Key   : 4a8f2c1d9e3b7f5a2c4d6e8f0a1b3c5d

ACTION REQUIRED:
  Copy the above values into your config.yml:

    agent:
      id: "a3f1c2d4-8b5e-4f2a-9c1d-0e7f3b2a6d8c"

    central:
      api_key: "4a8f2c1d9e3b7f5a2c4d6e8f0a1b3c5d"

  Then clear the registration token:
    registration:
      token: ""

  Then restart the agent in normal mode.
================================================================================

Step 4 — Update config.yml​

Copy the agent_id and api_key from the registration output into config.yml:

agent:
  id: "a3f1c2d4-8b5e-4f2a-9c1d-0e7f3b2a6d8c"   # ← paste here

central:
  api_url: "http://pmp-backend.example.com:8080/pmp"
  api_key: "4a8f2c1d9e3b7f5a2c4d6e8f0a1b3c5d"   # ← paste here

registration:
  token: ""   # ← clear the token

Step 5 — Verify in the Platform​

The registered server should now appear in the PMP4PG dashboard:

{screenshot: new-server-registered-dashboard}

Navigate to the Global Dashboard — the new server will appear with status INACTIVE (no heartbeat yet). It will switch to ACTIVE once the agent is started in normal mode.

Next Steps​