Process snapshot

Extensions 1.0 end of life

OneAgent and ActiveGate version 1.299 are the last versions supporting OneAgent and ActiveGate Extensions 1.0 framework. You can continue using Extensions 1.0 if you stay at OneAgent or ActiveGate version 1.299. Note that this means you'll be using an unsupported Python version 3.8. We strongly recommend migrating your extensions to the latest Extensions 2.0 framework.

For more information, see General guidance and how to migrate.

The embedded_api module is available only in the Python interpreter embedded in OneAgent. It exposes a few data structures that can be useful when developing extensions, particularly the process snapshot.

Note that there are other methods available for processing the snapshot.

class embedded_api.ProcessSnapshot

Contains information about the current state of processes on the system, as perceived by OneAgent. The main purpose of this class is to provide information so that entities and their associated IDs can be used when reporting plugin measurements

host_id

The ID of the host - int.

entries

Process groups detected on the host. An iterable of ProcessSnapshotEntry instances.

entries

Containers information detected on the host. An iterable of ContainerInfo instances.

class embedded_api.ProcessSnapshotEntry

Contains information about a single process group. It contains the entity of the group that should be used to report measurements associated with processes in the group.

group_id

Group ID of the snapshot entry. A “process group” is a set of processes that perform the same function across multiple hosts. For example, you might have a cluster of servers with each server running the same process in support of multiple hosts.

node_id

Node of the process snapshot entry. This is a value used to differentiate between multiple process group instances running on the same host. It's calculated based on a set of process-type specific parameters, though often the value is 0.

group_instance_id

Process group instance is the ID of a group of processes that perform the same task on a given host. Process group instance ID is a unique identifier in your environment, and thus should be used to report associated data.

process_type

Process group type (int). Please refer to Plugin.json reference for the full list of available process types.

group_name

Name of the process group. This is assigned in a manner specific to each process type.

processes

Processes assigned to this process group. An iterable of ProcessInfo instances.

properties

Additional information on the process in the form of a dictionary. Possible keys include:

  • mssql_instance_name - instance name of MSSQL, assigned only to process groups of type MSSQL.

class embedded_api.ProcessInfo

Contains information about a single process.

pid

Pid of the process

process_name

Name of the process

properties

Additional information on the process in the form of a dictionary. Possible keys include:

  • WorkDir - working directory of the process
  • CmdLine - command line of the process
  • PortBindings - TCP port binding data. Use snapshot.parse_port_bindings() to receive parsed data. The parsed data is list of 2 element tuple. The first field is a binded IP address (string) and the second field is a port (integer). 0.0.0.0 bind address is converted to local host address 127.0.0.1.
  • ListeningPorts - ports on which the process is listening in the form of a space-separated string. This is deprecated, so please use PortBindings.