Collect process metrics with the procstat plugin - Amazon CloudWatch
Configuring the CloudWatch agent for procstatMetrics collected by procstatViewing process metrics imported by the CloudWatch agent

Collect process metrics with the procstat plugin

The procstat plugin enables you to collect metrics from individual processes. It is supported on Linux servers and on servers running supported version of Windows Server.

Configuring the CloudWatch agent for procstat

To use the procstat plugin, add a procstat section in the metrics_collected section of the CloudWatch agent configuration file. There are three ways to specify the processes to monitor. You can use only one of these methods, but you can use that method to specify one or more processes to monitor.

  • pid_file: Selects processes by the names of the process identification number (PID) files they create.

  • exe: Selects the processes that have process names that match the string that you specify, using regular expression matching rules. The match is a "contains" match, meaning that if you specify agent as the term to match, processes with names like cloudwatchagent match the term. For more information, see Syntax.

  • pattern: Selects processes by the command lines used to start the processes. All processes are selected that have command lines matching the specified string using regular expression matching rules. The entire command line is checked, including parameters and options used with the command.

    The match is a "contains" match, meaning that if you specify -c as the term to match, processes with parameters like -config match the term.

  • drop_original_metrics – Optional. If you are using the aggregation_dimensions field in the metrics section to roll up metrics into aggregated results, then by default the agent sends both the aggregated metrics and the original metrics that are separated for each value of the dimension. If you don't want the original metrics to be sent to CloudWatch, you can specify this parameter with a list of metrics. The metrics specified along with this parameter don't have their metrics by dimension reported to CloudWatch. Instead, only the aggregated metrics are reported. This reduces the number of metrics that the agent collects, reducing your costs.

The CloudWatch agent uses only one of these methods, even if you include more than one of the above sections. If you specify more than one section, the CloudWatch agent uses the pid_file section if it is present. If not, it uses the exe section.

On Linux servers, the strings that you specify in an exe or pattern section are evaluated as regular expressions. On servers running Windows Server, these strings are evaluated as WMI queries. An example would be pattern: "%apache%". For more information, see LIKE Operator.

Whichever method you use, you can include an optional metrics_collection_interval parameter, which specifies how often in seconds to collect those metrics. If you omit this parameter, the default value of 60 seconds is used.

In the examples in the following sections, the procstat section is the only section included in the metrics_collected section of the agent configuration file. Actual configuration files can also include other sections in metrics_collected. For more information, see Manually create or edit the CloudWatch agent configuration file.

Configuring with pid_file

The following example procstat section monitors the processes that create the PID files example1.pid and example2.pid. Different metrics are collected from each process. Metrics collected from the process that creates example2.pid are collected every 10 seconds, and the metrics collected from the example1.pid process are collected every 60 seconds, the default value. 

{
    "metrics": {
        "metrics_collected": {
            "procstat": [
                {
                    "pid_file": "/var/run/example1.pid",
                    "measurement": [
                        "cpu_usage",
                        "memory_rss"
                    ]
                },
                {
                    "pid_file": "/var/run/example2.pid",
                    "measurement": [
                        "read_bytes",
                        "read_count",
                        "write_bytes"
                    ],
                    "metrics_collection_interval": 10
                }
            ]
        }
    }
}

Configuring with exe

The following example procstat section monitors all processes with names that match the strings agent or plugin. The same metrics are collected from each process. 

{
    "metrics": {
        "metrics_collected": {
            "procstat": [
                {
                    "exe": "agent",
                    "measurement": [
                        "cpu_time",
                        "cpu_time_system",
                        "cpu_time_user"
                    ]
                },
                {
                    "exe": "plugin",
                    "measurement": [
                        "cpu_time",
                        "cpu_time_system",
                        "cpu_time_user"
                    ]
                }
            ]
        }
    }
}

Configuring with pattern

The following example procstat section monitors all processes with command lines that match the strings config or -c. The same metrics are collected from each process. 

{
    "metrics": {
        "metrics_collected": {
            "procstat": [
                {
                    "pattern": "config",
                    "measurement": [
                        "rlimit_memory_data_hard",
                        "rlimit_memory_data_soft",
                        "rlimit_memory_stack_hard",
                        "rlimit_memory_stack_soft"
                    ]
                },
                {
                    "pattern": "-c",
                    "measurement": [
                        "rlimit_memory_data_hard",
                        "rlimit_memory_data_soft",
                        "rlimit_memory_stack_hard",
                        "rlimit_memory_stack_soft"
                    ]
                }
            ]
        }
    }
}

Metrics collected by procstat

The following table lists the metrics that you can collect with the procstat plugin.

The CloudWatch agent adds procstat to the beginning of the following metric names. There is a different syntax depending on whether it was collected from a Linux server or a server running Windows Server. For example, the cpu_time metric appears as procstat_cpu_time when collected from Linux and as procstat cpu_time when collected from Windows Server.

Metric name Available on Description

cpu_time

Linux

The amount of time that the process uses the CPU. This metric is measured in hundredths of a second.

Unit: Count

cpu_time_guest

Linux

The amount of time that the process is in guest mode. This metric is measured in hundredths of a second.

Type: Float

Unit: None

cpu_time_guest_nice

Linux

The amount of time that the process is running in a niced guest. This metric is measured in hundredths of a second.

Type: Float

Unit: None

cpu_time_idle

Linux

The amount of time that the process is in idle mode. This metric is measured in hundredths of a second.

Type: Float

Unit: None

cpu_time_iowait

Linux

The amount of time that the process is waiting for I/O operations to complete. This metric is measured in hundredths of a second.

Type: Float

Unit: None

cpu_time_irq

Linux

The amount of time that the process is servicing interrupts. This metric is measured in hundredths of a second.

Type: Float

Unit: None

cpu_time_nice

Linux

The amount of time that the process is in nice mode. This metric is measured in hundredths of a second.

Type: Float

Unit: None

cpu_time_soft_irq

Linux

The amount of time that the process is servicing software interrupts. This metric is measured in hundredths of a second.

Type: Float

Unit: None

cpu_time_steal

Linux

The amount of time spent running in other operating systems when running in a virtualized environment. This metric is measured in hundredths of a second.

Type: Float

Unit: None

cpu_time_stolen

Linux, Windows Server

The amount of time that the process is in stolen time, which is time spent in other operating systems in a virtualized environment. This metric is measured in hundredths of a second.

Type: Float

Unit: None

cpu_time_system

Linux, Windows Server, macOS

The amount of time that the process is in system mode. This metric is measured in hundredths of a second.

Type: Float

Unit: Count

cpu_time_user

Linux, Windows Server, macOS

The amount of time that the process is in user mode. This metric is measured in hundredths of a second.

Unit: Count

cpu_usage

Linux, Windows Server, macOS

The percentage of time that the process is active in any capacity.

Unit: Percent

memory_data

Linux, macOS

The amount of memory that the process uses for data.

Unit: Bytes

memory_locked

Linux, macOS

The amount of memory that the process has locked.

Unit: Bytes

memory_rss

Linux, Windows Server, macOS

The amount of real memory (resident set) that the process is using.

Unit: Bytes

memory_stack

Linux, macOS

The amount of stack memory that the process is using.

Unit: Bytes

memory_swap

Linux, macOS

The amount of swap memory that the process is using.

Unit: Bytes

memory_vms

Linux, Windows Server, macOS

The amount of virtual memory that the process is using.

Unit: Bytes

num_fds

Linux

The number of file descriptors that this process has open.

Unit: None

num_threads

Linux, Windows, macOS

The number of threads in this process.

Unit: None

pid

Linux, Windows Server, macOS

Process identifier (ID).

Unit: None

pid_count

Linux, Windows Server. macOS

The number of process IDs associated with the process.

On Linux servers and macOS computers the full name of this metric is procstat_lookup_pid_count and on Windows Server it is procstat_lookup pid_count.

Unit: None

read_bytes

Linux, Windows Server

The number of bytes that the process has read from disks.

Unit: Bytes

write_bytes

Linux, Windows Server

The number of bytes that the process has written to disks.

Unit: Bytes

read_count

Linux, Windows Server

The number of disk read operations that the process has executed.

Unit: None

rlimit_realtime_priority_hard

Linux

The hard limit on the real-time priority that can be set for this process.

Unit: None

rlimit_realtime_priority_soft

Linux

The soft limit on the real-time priority that can be set for this process.

Unit: None

rlimit_signals_pending_hard

Linux

The hard limit on maximum number of signals that can be queued by this process.

Unit: None

rlimit_signals_pending_soft

Linux

The soft limit on maximum number of signals that can be queued by this process.

Unit: None

rlimit_nice_priority_hard

Linux

The hard limit on the maximum nice priority that can be set by this process.

Unit: None

rlimit_nice_priority_soft

Linux

The soft limit on the maximum nice priority that can be set by this process.

Unit: None

rlimit_num_fds_hard

Linux

The hard limit on the maximum number of file descriptors that this process can have open.

Unit: None

rlimit_num_fds_soft

Linux

The soft limit on the maximum number of file descriptors that this process can have open.

Unit: None

write_count

Linux, Windows Server

The number of disk write operations that the process has executed.

Unit: None

involuntary_context_switches

Linux

The number of times that the process was involuntarily context-switched.

Unit: None

voluntary_context_switches

Linux

The number of times that the process was context-switched voluntarily.

Unit: None

realtime_priority

Linux

The current usage of real-time priority for the process.

Unit: None

nice_priority

Linux

The current usage of nice priority for the process.

Unit: None

signals_pending

Linux

The number of signals pending to be handled by the process.

Unit: None

rlimit_cpu_time_hard

Linux

The hard CPU time resource limit for the process.

Unit: None

rlimit_cpu_time_soft

Linux

The soft CPU time resource limit for the process.

Unit: None

rlimit_file_locks_hard

Linux

The hard file locks resource limit for the process.

Unit: None

rlimit_file_locks_soft

Linux

The soft file locks resource limit for the process.

Unit: None

rlimit_memory_data_hard

Linux

The hard resource limit on the process for memory used for data.

Unit: Bytes

rlimit_memory_data_soft

Linux

The soft resource limit on the process for memory used for data.

Unit: Bytes

rlimit_memory_locked_hard

Linux

The hard resource limit on the process for locked memory.

Unit: Bytes

rlimit_memory_locked_soft

Linux

The soft resource limit on the process for locked memory.

Unit: Bytes

rlimit_memory_rss_hard

Linux

The hard resource limit on the process for physical memory.

Unit: Bytes

rlimit_memory_rss_soft

Linux

The soft resource limit on the process for physical memory.

Unit: Bytes

rlimit_memory_stack_hard

Linux

The hard resource limit on the process stack.

Unit: Bytes

rlimit_memory_stack_soft

Linux

The soft resource limit on the process stack.

Unit: Bytes

rlimit_memory_vms_hard

Linux

The hard resource limit on the process for virtual memory.

Unit: Bytes

rlimit_memory_vms_soft

Linux

The soft resource limit on the process for virtual memory.

Unit: Bytes

Viewing process metrics imported by the CloudWatch agent

After importing process metrics into CloudWatch, you can view these metrics as time series graphs, and create alarms that can watch these metrics and notify you if they breach a threshold that you specify. The following procedure shows how to view process metrics as a time series graph. For more information about setting alarms, see Using Amazon CloudWatch alarms.

To view process metrics in the CloudWatch console

  1. Open the CloudWatch console at https://console.aws.amazon.com/cloudwatch/.

  2. In the navigation pane, choose Metrics.

  3. Choose the namespace for the metrics collected by the agent. By default, this is CWAgent, but you may have specified a different namespace in the CloudWatch agent configuration file.

  4. Choose a metric dimension (for example, Per-Instance Metrics).

  5. The All metrics tab displays all metrics for that dimension in the namespace. You can do the following:

    1. To graph a metric, select the check box next to the metric. To select all metrics, select the check box in the heading row of the table.

    2. To sort the table, use the column heading.

    3. To filter by resource, choose the resource ID and then choose Add to search.

    4. To filter by metric, choose the metric name and then choose Add to search.

  6. (Optional) To add this graph to a CloudWatch dashboard, choose Actions, Add to dashboard.