Collect process metrics with the procstat plugin
The procstat plugin enables you to collect metrics from individual processes. The plugin is supported on Linux servers and on servers running supported version of Windows Server. This section describes how to configure the CloudWatch agent for procstat and view metrics the CloudWatch agent imports. It also lists the metrics that procstat collects.
Note
The procstat
plugin is not supported for the Fargate launch type in Amazon ECS environments.
Topics
Configure 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 specifyagent
as the term to match, processes with names likecloudwatchagent
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 theaggregation_dimensions
field in themetrics
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.
Configure 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 |
---|---|---|
|
Linux |
The amount of time that the process uses the CPU. This metric is measured in hundredths of a second. Unit: Count |
|
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 |
|
Linux |
The amount of time that the process is running in a nice guest. This metric is measured in hundredths of a second. Type: Float Unit: None |
|
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 |
|
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 |
|
Linux |
The amount of time that the process is servicing interrupts. This metric is measured in hundredths of a second. Type: Float Unit: None |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
Linux, Windows Server, macOS |
The percentage of time that the process is active in any capacity. Unit: Percent |
|
Linux, macOS |
The amount of memory that the process uses for data. Unit: Bytes |
|
Linux, macOS |
The amount of memory that the process has locked. Unit: Bytes |
|
Linux, Windows Server, macOS |
The amount of real memory (resident set) that the process is using. Unit: Bytes |
|
Linux, macOS |
The amount of stack memory that the process is using. Unit: Bytes |
|
Linux, macOS |
The amount of swap memory that the process is using. Unit: Bytes |
|
Linux, Windows Server, macOS |
The amount of virtual memory that the process is using. Unit: Bytes |
|
Linux |
The number of file descriptors that this process has open. Unit: None |
|
Linux, Windows, macOS |
The number of threads in this process. Unit: None |
|
Linux, Windows Server, macOS |
Process identifier (ID). Unit: None |
|
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 Unit: None |
|
Linux, Windows Server |
The number of bytes that the process has read from disks. Unit: Bytes |
|
Linux, Windows Server |
The number of bytes that the process has written to disks. Unit: Bytes |
|
Linux, Windows Server |
The number of disk read operations that the process has executed. Unit: None |
|
Linux |
The hard limit on the real-time priority that can be set for this process. Unit: None |
|
Linux |
The soft limit on the real-time priority that can be set for this process. Unit: None |
|
Linux |
The hard limit on maximum number of signals that can be queued by this process. Unit: None |
|
Linux |
The soft limit on maximum number of signals that can be queued by this process. Unit: None |
|
Linux |
The hard limit on the maximum nice priority that can be set by this process. Unit: None |
|
Linux |
The soft limit on the maximum nice priority that can be set by this process. Unit: None |
|
Linux |
The hard limit on the maximum number of file descriptors that this process can have open. Unit: None |
|
Linux |
The soft limit on the maximum number of file descriptors that this process can have open. Unit: None |
|
Linux, Windows Server |
The number of disk write operations that the process has executed. Unit: None |
|
Linux |
The number of times that the process was involuntarily context-switched. Unit: None |
|
Linux |
The number of times that the process was context-switched voluntarily. Unit: None |
|
Linux |
The current usage of real-time priority for the process. Unit: None |
|
Linux |
The current usage of nice priority for the process. Unit: None |
|
Linux |
The number of signals pending to be handled by the process. Unit: None |
|
Linux |
The hard CPU time resource limit for the process. Unit: None |
|
Linux |
The soft CPU time resource limit for the process. Unit: None |
|
Linux |
The hard file locks resource limit for the process. Unit: None |
|
Linux |
The soft file locks resource limit for the process. Unit: None |
|
Linux |
The hard resource limit on the process for memory used for data. Unit: Bytes |
|
Linux |
The soft resource limit on the process for memory used for data. Unit: Bytes |
|
Linux |
The hard resource limit on the process for locked memory. Unit: Bytes |
|
Linux |
The soft resource limit on the process for locked memory. Unit: Bytes |
|
Linux |
The hard resource limit on the process for physical memory. Unit: Bytes |
|
Linux |
The soft resource limit on the process for physical memory. Unit: Bytes |
|
Linux |
The hard resource limit on the process stack. Unit: Bytes |
|
Linux |
The soft resource limit on the process stack. Unit: Bytes |
|
Linux |
The hard resource limit on the process for virtual memory. Unit: Bytes |
|
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
-
Open the CloudWatch console at https://console.aws.amazon.com/cloudwatch/
. -
In the navigation pane, choose Metrics.
-
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.
-
Choose a metric dimension (for example, Per-Instance Metrics).
-
The All metrics tab displays all metrics for that dimension in the namespace. You can do the following:
-
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.
-
To sort the table, use the column heading.
-
To filter by resource, choose the resource ID and then choose Add to search.
-
To filter by metric, choose the metric name and then choose Add to search.
-
(Optional) To add this graph to a CloudWatch dashboard, choose Actions, Add to dashboard.