Agent properties and selectors

This page lists the properties and selectors available for querying and finding NXLog Agent instances within NXLog Platform. You can build search expressions by combining the supported operators and one or more agent properties to find matching NXLog Agent instances. For example, when viewing agents, setting up auto-enrollment rules, and assigning configurations.

Agent properties

Each NXLog Agent instance has several properties containing information about the agent’s operating environment. To those, NXLog Platform adds agent-management properties.

Table 1. Properties associated with a connected NXLog Agent instance
Property name	Description
`added-time`	Timestamp of the moment the agent first connected to NXLog Platform. Example: `2025-03-27 17:15:26.139781467 UTC`.
`address`	Host IP address and port number used by the agent to connect to NXLog Platform or null when the agent is offline. Example: `10.10.22.21:55076`.
`arch`	CPU architecture of the agent’s host. Possible values: `x86_64`, `arm`.
`cached-logs`	Most recent log entries sent by this agent to NXLog Platform.
`certificate`	Information about the stored certificate, including the start and expiration time.
`comment`	Optional description associated with the agent.
`config`	Either the actual content of the agent `managed.conf` file, or the expected content when it has been changed from NXLog Platform but not yet updated on the agent. Example: `config REGEX "(?s:.)AllowUntrusted(\s)(?i)true(?-i)(?s:.)*"`
`config-synced-with-template`	Synchronization status of the agent configuration and the corresponding configuration in NXLog Platform. `true` if the agent configuration is identical to the most recent version of the configuration assigned to the agent. `false` if the agent configuration is not identical to the most recent version of the configuration assigned to the agent. `null` if the agent configuration is not related to any configuration.
`configured`	Configuration status: `true` if the agent has at least one input or output module configured, `false` otherwise.
`connected-time`	Timestamp of the moment the agent last connected to NXLog Platform. Example: `2025-03-27 17:15:26.139781467 UTC`.
`cpu-load`	Average CPU load of the agent process, measured since the process started.
`cpu-usage-time`	CPU usage time of the agent process, measured in milliseconds since the process started.
`enrolled`	Enrollment status of the agent: `true` if the enrollment process completed successfully, and `false` otherwise.
`enrolled-time`	Timestamp of the moment the agent was most recently enrolled in NXLog Platform. Example: `2025-03-27 17:15:26.139781467 UTC`.
`eps`	Same as `events-per-second`.
`errors`	Information on any error related to the agent, for example if an invalid configuration was deployed on the agent.
`events-per-second`	Log processing rate of the agent, in events per second (EPS).
`fd-count`	Number of file descriptors currently in use by the agent.
`file-acls`	Directories that can be used with the GetFile and PutFile web service requests. The name of the ACL is used in these requests together with the filename. ACLs are configured through the xm_admin module.
`file-names`	Name of the files associated with the agent, namely the certificate files and the configuration file.
`files`	Content of the files associated with the agent, namely the certificate files and the configuration file.
`files-sync`	Synchronization information for the files associated with the agent, namely the certificate files and the configuration file.
`files-synced`	Synchronization status of the agent files: `true` if the certificate and configuration files of the agent are synchronized with NXLog Platform, `false` otherwise.
`host`	Same as `hostname`.
`hostname`	The hostname of the machine where the agent is running, as reported by the agent.
`id`	The UUID of the agent in UUID Version 1 format. The agent typically reports its ID, but NXLog Platform can generate or overwrite it, for example, to avoid duplication when you create a second agent instance by cloning a VM.
`label-names`	Names of all labels configured in the agent. Labels are configured through the xm_admin module.
`labels`	Custom key-value pairs defined with supplementary details about the agent, such as the display name, local contact information, and so on. Labels are configured through the xm_admin module.
`last-processed-event-time`	Timestamp of the last event processed by the agent. Example: `2025-03-27 17:15:26.139781467 UTC`.
`manager-address`	The NXLog Platform IP address and port number to which the agent is connected or `null` when the agent is offline. Example: `10.10.22.254:5515`
`memory-used`	Amount of RAM used by the agent in bytes.
`module-names`	Names of the modules included in the agent configuration.
`modules`	Information about the modules included in the agent configuration.
`name`	Same as `hostname`.
`online`	Connection status of the agent: `true` if the connection between NXLog Platform and the agent is established, `false` otherwise.
`os`	Type of operating system where the agent is running. Possible values: `Android`, `Linux`, `Windows`, `AIX`, `FreeBSD` (for FreeBSD, NetBSD), `OpenBSD`, `BSD`, `HP-UX`, `Irix`, `macOS`, `Solaris`, `Unix`, `Unknown`.
`os-release`	Operating system type and version. Example: `Fedora Linux 39 (Workstation Edition)`
`persisted`	`true` if the agent is set to use persistent message queues to store logs on disk instead of in memory , `false` otherwise.
`persisted-time`	Timestamp of the moment the agent was set to use a persistent log queue, `null` if the agent is not set to use a persistent log queue. Example: `2025-03-27 17:15:26.139781467 UTC`.
`pid`	Process identifier of the agent instance. Example: `9188`
`polled-time`	Timestamp of the latest NXLog Platform data request from the agent. NXLog Platform polls agents once every 60 seconds. Example: `2025-03-27 17:15:26.139781467 UTC`.
`route-names`	Names of the routes included in the agent configuration.
`routes`	Information about the routes included in the agent configuration.
`started-time`	Timestamp of the most recent agent start or restart. Example: `2025-03-27 17:15:26.139781467 UTC`.
`status`	The agent’s management status: `ok`, `warning` (or `warn`), `error` (or `err`). The `errors` property contains a list of the detailed error types and messages.
`synced`	Overall synchronization status of the agent files with NXLog Platform, determined by the `files-synced` and `config-synced-with-template` fields. `true` if all agent files are synchronized and the agent is either not assigned to a configuration, or the local agent configuration is identical to the most recent version of the configuration assigned to the agent on NXLog Platform. `false` if either the agent files are not synchronized, or the agent is assigned to a configuration but the local configuration is not identical to the most recent version of that configuration on NXLog Platform.
`template-id`	UUID of the configuration assigned to the agent or `null` when a configuration is not assigned.
`template-name`	Name of the configuration assigned to the agent or `null` when a configuration is not assigned.
`thread-count`	Number of threads the agent is using.
`version`	Version of the agent. Example: `6.2.9212`.
`warnings`	Information on any warnings related to the agent, for example if the agent files are not synchronized with NXLog Platform.

Agent selector operators

You can use the following operators to write selectors for querying and finding agents.

Comparison operators

Comparison operators are binary operators that take the following form:

{expression 1} {operator} {expression 2}

Table 2. Comparison operators
Operator	Alternative spellings	Description
`==`	`=`, `EQ`, `eq`	Tests if the property value is equal to the provided value.
`!=`	`NE`, `ne`	Tests if the property value is not equal to the provided value.
`<=`	`LE`, `le`	Tests if the property value is less than or equal to the provided value.
`<`	`LT`, `lt`	Tests if the property value is less than the provided value.
`>=`	`GE`, `ge`	Tests if the property value is greater than or equal to the provided value.
`>`	`GT`, `gt`	Tests if the property value is greater than the provided value.
`LIKE`	`like`	Tests if the property value matches a wildcard expression.
`REGEX`	`regex`	Tests if the property value matches a Rust-style regular expression.

Logical operators

Logical operators can be unary or binary.

Table 3. Logical operators
Operator	Alternative spellings	Description
`NOT`		Inverts (negates) the operators or expressions. Examples: `NOT property = value` which is equal to `property != value` or `NOT (property = value)` `property NOT LIKE value`
`AND`	`&&`, `&`	Pairs of sub-expressions connected using this operator must both evaluate to true for the full expression to be true.
`OR`	`\|\|`, `\|`	At least one of the sub-expressions connected using this operator must evaluate to true for the full expression to be true.
`IN`		The expression is true if the property is equal to one of a list of values. Example: `hostname IN rhel01, rhel02, rhel03` or `hostname IN (rhel01, rhel02, rhel03)`
`IS`		Checks the property for existence or presence of value: `EMPTY` If the property is empty. `NONE` True if the property doesn’t exist. You can use existence checks only for optional properties. `NULL` Alternative spelling for `NONE`. `SOME` True if the property exists. You can use existence checks only for optional properties. Examples: `enroll-time IS NONE` `enroll-time IS SOME`
`HAS`		True if the property exists. Example: `HAS enroll-time`. Equivalent to `enroll-time IS SOME` or `NOT (enroll-time is NONE)`

Agent properties and selectors