Skip to main content

Monitoring Agents

Maintaining Agents

Maintaining Agents - configuration

Viewing Logs

Logs can be found on the Logs tab for each Agent and Connection, and filtered by both log severity and date. For Agents v4.9+, user-defined log messages can be added by referencing the corresponding agent_sdk method for logging.

Descriptions of log messages can be found on the Agent Logs page.

Agent logs

Monitoring Agent Connections

Connection status updates and logs can be accessed in the Ganymede web app UI.

Connection cards

 

Connection data can be viewed by clicking on the appropriate connection card in the Connections tab.

Connection Detail UI

 

This opens up a page displaying parameters associated with the Connection:

Field NameDescription
StatusCurrent running status of the installed Connection
AgentAgent associated with the Connection
Connection VersionThe version of the Connection configuration currently running, updated when the Connection configuration is modified
Agent VersionThe version of the Agent configuration from which the Connection is running, updated when the Agent configuration or processor code changes
Core VersionThe version of the core Agent infrastructure from which the Connection is running; requires a reinstall to update
Started AtUTC Time when the Connection was first registered in Ganymede
Last Status PingTime when last status ping was received from the Connection by Ganymede
PC NameHostname of the machine hosting the connection
MAC AddressMAC address of the machine hosting the connection
Machine IPIP address that Ganymede sees from the machine hosting the connection
Install PathDirectory path on the hosting machine where the executable was installed on
Service NameWindows service name for the Connection on the hosting machine
Agent TagsTags applied to all file captured by any Connection running from the Agent, configured in the Agent UI

Connection Status

Agents send a heartbeat message to Ganymede Cloud every 30 seconds to inform their status. The status of an Agent can be one of the following:

  • Live: The Agent is currently running and communicating with Ganymede Cloud
  • Disconnected: Ganymede Cloud has not received a status update from the Agent in the last 65 seconds
  • Shutdown: The Agent was intentionally shut down, possibly due to a user shutting down the computer, manually stopping the Agent service, or encountering a known exception.
  • Deprecated: The Agent has been disabled in Ganymede UI as described in the Updating Agents section.

Custom Logging

You can create custom logs that will be displayed in the Ganymede UI and local log files by using the logger keyword argument in your user-defined processor code. For example:

def execute(**kwargs) -> Optional[TriggerFlowParams]:  # type: ignore
# if there is not logger, the default logger is print
logger = kwargs.get("logger", print)
logger(f"Local files: {os.listdir('./')}")

Updating Agents

To modify Agent settings after creation, select the desired Agent in the Ganymede web app UI to update the Agent. Upon clicking

Update
, the Agent will be built and then made available for download.

Agent update configuration

 

Agents can also be archived or disabled.

Archived Agents cannot be updated, but the Agent's connections can still communicate with Ganymede Cloud. All associated connections for these Agents will continue to run, but the Agent can no longer be modified. Archived agents can be restored to an active state by selecting the desired Agent and clicking on the Restore Agent link.

Disabled Agents cannot be updated and its connections can no longer communicate with Ganymede Cloud.

Updating Connections

To update a Connection, select the desired Connection in the Connections tab and click the

Edit Connections
button. You can update the following fields on a connection from the Ganymede UI:

Connection Detail UI
  • Name: Display name for the Connection
  • Image: An image to associate with the Connection in the Ganymede UI.
  • Tags: File tags to apply to files uploaded by the Connection
  • Variables: Key-value pairs that can be referenced in user-defined code
  • Labels: Strings that can be used to group Connections in the Ganymede UI

Remote Update of Live Connections

Every time the Connection contacts Ganymede with a health check-in, Ganymede responds with any changes that the Connection needs to incorporate. There are three level of changes that can occur.

  • Core Version Update: The core version corresponds to the underlying Agent code developed by Ganymede. These changes are new features or patches applied across all Agents, but each Agent manages which core version it is pinned to.
  • Agent Configuration Update: Updated through the Agent page or the Agent's processor notebook. This configuration applies to all Connections for that Agent. For example, if an Agent that runs flow upon file capture is updated to run a new flow, then all compatible Connections will begin to run the new flow.
  • Connection Configuration Update: Updates made to the Connection's configuration will only update a single Connection, rather than the Agent that it was generated from. Different Connection-level variables and labels can be configured for Connections associated with the same Agent.

There are two types of remote updates that occur based on the type of update - full update or runtime update.

Full Update

Compatibility

  • Agents installed with core v4.8.0 or later.
  • The core version of the installed connection must align with the major version of the core version of the agent Ganymede's UI. Otherwise, a breaking change requires reinstallation.
  • Auto-update is enabled for the agent.
How full updates are initiated

A full update is only triggered for a "Core Version Update." The remote update is not initiated without user intervention.

note

In the Ganymede UI, an Agent's core version is listed on the right side of the page in a section called "Core Agent Infrastructure." If the agent is not up to date to the latest available core version, an "Upgrade" button will appear. The text will inform users what version is available and what version the agent is currently pinned to.

Agent build history

Once a user clicks to Upgrade an agent, all connections will be told of the new version on their next status ping.

Update Process

A full update requires reinstalling the executable, but Ganymede now handles this installation seamlessly. When a Connection receives a command to perform a full update, it continues to operate normally while attempting to start the new version in parallel after verifying the validity of the command and the executable. Once the new version registers with Ganymede as operational, the old Connection stops. The new executable also cleans up the artifacts of the old executable and its dependencies.

There may be a disruption to any ongoing processing on the Agent during the update, so it is safest to request it when no activity occurs on the instruments where the Agent Connections are running.

If the new Connection fails to start, the old Connection will resume, and the system will not attempt a full update again on that version to avoid putting the Connection in a precarious state.

Runtime Update

Compatibility
  • Agents installed with core v1.0.0 or later
  • The core version of the installed connection must match the core version of the agent Ganymede's UI
  • Auto-update is enabled for the agent
How runtime updates are initiated

Changes in the Agent configuration, including the Agent user-defined code, or Connection configuration, will be sent to the Connection on its next status ping as soon as they are saved.

Update Process

A runtime update does not require any process restart or executable reinstallation. As a result, the Connection can accept changes to configuration while continuing normal operations. The update is validated for integrity and the information is stored locally for access if the Connection restarts for any reason.

Viewing Build History

Each iteration of Agent build can be viewed in the History tab of the Agent. This view provides context for each change, either as a log of the configuration change or through a custom commit message from the Agent notebook.

Agent build history

 

Configuration differences between two Agent builds can be viewed for audit or debugging purposes by clicking

button.

Agent build history detail

Uninstalling Agent Connections

Windows

The Agent can be uninstalled and the associated service removed through the “Add or Remove Programs” panel from the Control Panel.

Agent uninstall

 

After uninstalling the Agent, the Ganymede folder will remain in the Program Files directory.

warning

By default, the directory that the Agent Connection is installed to is retained, so that logs associated with Connection are kept on the instrument PC. Removing the Ganymede folder will also remove these logs.

Linux

To uninstall the Agent, stop the systemd service associated with the Agent and remove the service file from /etc/systemd/system/.

# to stop the Agent Connection service
sudo systemctl stop ganymede_example_agent.service

# remove the service file
sudo rm /etc/systemd/system/ganymede_example_agent.service