Monitor your first machine.

1. Choose your machine

For host monitoring, install the native agent on the machine you want to observe. A container sees its own namespaces and mounted files; it does not automatically see the entire host.

2. Prepare your Logship instance

1. If you do not have an instance, complete Single Node Deployment. Open the frontend and finish initial setup.
2. Select the account that should receive these records. Under Settings → Account, copy its account ID.
3. Find the backend API base URL that the agent can reach. In a local installation, the browser usually opens http://localhost:8000, while the backend is http://localhost:5000. On a remote machine, use the server’s reachable hostname instead of localhost.
4. You need account permissions to manage agents and create dashboards and alerts. This guide uses manual approval rather than placing an administrator credential in the agent configuration.

These values only fill the configuration example below. They are not sent or saved by this page.

3. Install the agent

These commands are for a Linux x64 host with curl and unzip installed. For ARM64 or a musl-based distribution, choose the matching archive from agent releases instead.

curl -fL https://github.com/logship-io/logship-agent/releases/latest/download/LogshipAgent-linux-x64.zip -o logship-agent.zip
sudo mkdir -p /opt/logship-agent /var/lib/logship-agent
sudo unzip -o logship-agent.zip -d /opt/logship-agent
sudo chmod +x /opt/logship-agent/Logship.Agent.ConsoleHost

Checkpoint: the agent binary is extracted, or the container image is available. You have not started collection yet.

4. Configure and start collection

Fill in your backend URL and account ID in step 2. Save the generated JSON as /opt/logship-agent/appsettings.json. The example starts host, CPU, storage, network, and process collection.

{
  "Output": {
    "endpoint": "http://localhost:5000",
    "account": "YOUR-ACCOUNT-UUID",
    "interval": "00:00:05",
    "dataPath": "/var/lib/logship-agent"
  },
  "Sources": {
    "SystemInformation": {
      "enabled": true,
      "interval": "00:00:30"
    },
    "System.CPU": {
      "enabled": true,
      "interval": "00:00:10"
    },
    "DiskInformation": {
      "enabled": true,
      "interval": "00:00:30"
    },
    "NetworkInformation": {
      "enabled": true,
      "interval": "00:00:30"
    },
    "ProcessInformation": {
      "enabled": true,
      "interval": "00:01:00"
    }
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information"
    }
  }
}

Keep the configured data directory when upgrading or restarting. It stores the agent’s refresh credential; losing it can require another registration and approval.

Install a systemd service with an explicit working directory, then check its logs:

sudo tee /etc/systemd/system/logship-agent.service > /dev/null <<'SERVICE'
[Unit]
Description=Logship collection agent
Wants=network-online.target
After=network-online.target
[Service]
WorkingDirectory=/opt/logship-agent
ExecStart=/opt/logship-agent/Logship.Agent.ConsoleHost
Restart=on-failure
[Install]
WantedBy=multi-user.target
SERVICE
sudo systemctl daemon-reload
sudo systemctl enable --now logship-agent
sudo journalctl -u logship-agent -n 30 --no-pager

Checkpoint: the process is running and attempting registration. Waiting for approval is expected on a new manually registered agent.

5. Approve the connection

1. In the receiving account, open Settings → Account → Agents.
2. Find your host under Pending Approvals. Match its hostname and device verification details to the agent’s logs.
3. Choose Approve and confirm the matching registration. The agent detects approval and begins uploading.

For fleet automation, use Create Registration Token on that page and follow the registration-token instructions. A registration token is different from an ingestion token for a custom integration.

6. Verify incoming records

Open Query in the same receiving account and choose Execute after pasting this query. Allow at least one 30-second storage interval after approval.

System.Storage
| where timestamp > ago(10m)
| project timestamp, machine, Name, TotalSizeBytes, AvailableFreespaceBytes
| order by timestamp desc
| take 20

Checkpoint: recent rows show your machine name, volume name, total size, and available bytes. With multiple agents, add a machine filter before continuing.

If there are no records, use the troubleshooting tree below. An unknown-table error can mean that the source has not uploaded its first record yet.

7. Build your first dashboard

1. First run the chart query below in Query. Open Render in the result pane to inspect free space over the last hour.
2. Open Dashboards → Create Dashboard and name the dashboard My machines.
3. In dashboard edit mode, choose Add Chart. In the chart editor, set Tile type to Kusto and paste the query.
4. Save the chart, then choose Save on the dashboard. If opening an existing dashboard, choose Edit first.

System.Storage
| where timestamp > ago(1h)
| where TotalSizeBytes > 0
| extend freePercent = 100.0 * AvailableFreespaceBytes / TotalSizeBytes
| summarize freePercent = min(freePercent) by timestamp = bin(timestamp, 1m), machine, Name
| order by timestamp asc
| render timechart

Checkpoint: the saved dashboard shows a line for each machine and volume that has data. Reopen it from the dashboard list to verify it was saved.

The built-in administration dashboards monitor Logship’s own services. This dashboard uses the records from your newly connected host.

8. Alert when a disk is low

This example returns one row per machine and volume whose observed free space was below 10% in the last five minutes. It does not report a silent or disconnected agent.

System.Storage
| where timestamp > ago(5m)
| where TotalSizeBytes > 0
| extend freePercent = 100.0 * AvailableFreespaceBytes / TotalSizeBytes
| summarize freePercent = min(freePercent) by machine, Name
| where freePercent < 10

1. Open Alerts → Create Alert. Name it Low disk space and paste the query.
2. Set Interval to one minute. The query itself filters for low-space rows. Keep its output fields available to the alert editor.
3. Use machine and Name as unique fields so separate volumes can be handled separately.
4. Choose the incident action, a valid owner, and severity. Enable automatic resolution if you want the incident to resolve when the query stops matching.
5. Save the enabled alert. To test without filling a disk, temporarily use a threshold that matches a known volume, verify the result and action, then restore 10%.

For the full incident walkthrough and notification setup, see Work through a test incident. Email delivery also needs a configured messenger.

9. Add the sources you need

• Files and service logs

  Choose file paths or platform sources such as journald and Windows ETW.

• Linux authentication and SSH

  Enable the authentication source and inspect its schema before adding alerts.

• Prometheus and OpenTelemetry

  Configure scrape targets or the agent’s OTLP gRPC receiver for instrumented applications.

• Wireless activity

  Use a dedicated monitor-capable Linux adapter for supported management-frame observations.

• Plex and OpenWrt projects

  Continue with a service or router you already run.

Troubleshooting