🔀 Merge remote-tracking branch 'origin/fix-49' into develop

CHANGELOG.md

@@ -7,6 +7,7 @@
 — 🔊 — Add a warning messages in the logs if there is no tasks in database. (fix #41)
 - ✨ — Add command to generate example configuration (fix #38)
 - 📝 — Improve documentation
+- ✨ — Add command to warn if it’s been long since last viewing an agent (fix #49)
 
 ## 0.1.1
 

argos/commands.py

@@ -2,6 +2,7 @@ import asyncio
 import os
 from functools import wraps
 from pathlib import Path
+from sys import exit as sysexit
 from uuid import uuid4
 
 import click
@@ -177,6 +178,41 @@ async def cleandb(max_results, max_lock_seconds, config):
     click.echo(f"{updated} locks released")
 
 
+@server.command()
+@click.option(
+    "--time-without-agent",
+    default=5,
+    help="Time without seeing an agent after which a warning will be issued, in minutes. "
+    "Default is 5 minutes.",
+    callback=validate_max_results,
+)
+@click.option(
+    "--config",
+    default="config.yaml",
+    help="Path of the configuration file. "
+    "If ARGOS_YAML_FILE environment variable is set, its value will be used instead.",
+    envvar="ARGOS_YAML_FILE",
+    callback=validate_config_access,
+)
+@coroutine
+async def watch_agents(time_without_agent, config):
+    """Watch agents (to run routinely)
+
+    Issues a warning if no agent has been seen by the server for a given time.
+    """
+    # It’s mandatory to do it before the imports
+    os.environ["ARGOS_YAML_FILE"] = config
+
+    # The imports are made here otherwise the agent will need server configuration files.
+    from argos.server import queries
+
+    db = await get_db()
+    agents = await queries.get_recent_agents_count(db, time_without_agent)
+    if agents == 0:
+        click.echo(f"No agent has been seen in the last {time_without_agent} minutes.")
+        sysexit(1)
+
+
 @server.command(short_help="Load or reload tasks’ configuration")
 @click.option(
     "--config",

argos/server/queries.py

@@ -241,3 +241,11 @@ async def release_old_locks(db: Session, max_lock_seconds: int):
     )
     db.commit()
     return updated
+
+
+async def get_recent_agents_count(db: Session, minutes: int):
+    """Get agents seen less than <minutes> ago"""
+    max_time = datetime.now() - timedelta(minutes=minutes)
+
+    agents = db.query(Result.agent_id).filter(Result.submitted_at > max_time).distinct()
+    return agents.count()

docs/cli.md

@@ -83,6 +83,7 @@ Commands:
   migrate          Run database migrations
   reload-config    Load or reload tasks’ configuration
   start            Starts the server (use only for testing or development!)
+  watch-agents     Watch agents (to run routinely)
 ```
 
 <!--[[[end]]]
@@ -164,6 +165,35 @@ Options:
 <!--[[[end]]]
 -->
 
+### Server watch-agents
+
+<!--
+.. [[[cog
+    help(["server", "cleandb", "--help"])
+.. ]]] -->
+
+```man
+Usage: argos server cleandb [OPTIONS]
+
+  Clean the database (to run routinely)
+
+  - Removes old results from the database.
+  - Removes locks from tasks that have been locked for too long.
+
+Options:
+  --max-results INTEGER       Number of results per task to keep
+  --max-lock-seconds INTEGER  The number of seconds after which a lock is
+                              considered stale, must be higher than 60 (the
+                              checks have a timeout value of 60 seconds)
+  --config TEXT               Path of the configuration file. If ARGOS_YAML_FILE
+                              environment variable is set, its value will be
+                              used instead.
+  --help                      Show this message and exit.
+```
+
+<!--[[[end]]]
+-->
+
 ### Server reload-config
 
 <!--

docs/installation/getting-started.md

@@ -158,3 +158,15 @@ Here is a crontab example, which will clean the db each hour:
 # Keeps 10 results per task, and remove tasks’ locks older than 1 hour
 7 * * * * argos server cleandb --max-results 10 --max-lock-seconds 3600
 ```
+
+## Watch the agents
+
+In order to be sure that agents are up and communicate with the server, you can run periodically the `argos server watch-agents` command.
+
+Here is a crontab example, which will check the agents every 5 minutes:
+
+```bash
+*/5 * * * * argos server watch-agents --time-without-agent 10
+```
+
+Check the documentation of the command with `argos server watch-agents --help`

docs/installation/tl-dr.md

@@ -147,10 +147,10 @@ systemctl enable --now argos-server.service argos-agent.service
 systemctl status argos-server.service argos-agent.service
 ```
 
-If all works well, you have to put a cron task in `argos` crontab:
+If all works well, you have to put some cron tasks in `argos` crontab:
 
 ```bash
-echo "*/10 * * * * . /etc/default/argos-server && export ARGOS_DATABASE_URL && export ARGOS_YAML_FILE && cd /opt/argos/ && /opt/argos/venv/bin/argos server cleandb --max-lock-seconds 120 --max-results 1200" | crontab -u argos -
+echo -e "*/10 * * * * . /etc/default/argos-server && export ARGOS_DATABASE_URL && export ARGOS_YAML_FILE && cd /opt/argos/ && /opt/argos/venv/bin/argos server cleandb --max-lock-seconds 120 --max-results 1200\n*/10 * * * * . /etc/default/argos-server && export ARGOS_DATABASE_URL && export ARGOS_YAML_FILE && cd /opt/argos/ && /opt/argos/venv/bin/argos server watch-agents --time-without-agent 10" | crontab -u argos -
 ```
 
 See the [this page](../deployment/nginx.md) for using Nginx as reverse proxy.