Capsule8 Docs
Capsule8 Docs

Configuring Alerts

Capsule8 was designed to let users decide which data they need to best serve their workflows. As such, we support custom formatting of Alerts through Alert Templates.

Default Alert Formatting

By default, Alerts are UTF-8 encoded JSON strings that are newline-delimited. Alerts will arrive one at a time no matter what type of output destination (stdout, webhook, etc.).

Default limits

It is important to note that some log ingestion systems like Splunk, ELK, and syslog have default limits on the number of bytes that a single log entry can contain. In some cases, this can lead to Alerts appearing on multiple lines or not parsing correctly as valid JSON if they are truncated.

To work around these limits, it is possible to ingest a smaller Alert by turning off certain Alert information or to ingest only a portion of the Alert. This can be achieved by setting the configuration of features like process lineage or cloud metadata to “off,” by the post-processing of Alerts written to a blob storage bucket with a cloud function, or by the use of Alert Templates to alert the Alert format from within the Capsule8 Sensor itself.


Alerts contain a metadata field with information about the node the sensor was running on such as the hostname and OS.

In AWS or GCP cloud environments, this field can be optionally enriched with instance metadata from the instance’s local metadata service. These services are local HTTP servers that return information about the running instnace. For more information about these services see the AWS and GCP documentation.

To configure the cloud metadata feature either run the sensor with the CLOUD_META environment variable or set the cloud_meta key in the capsule8-sensor.yaml config file. The possible values are aws, gcp, or auto to instruct the sensor to auto-detect the metadata service. Keep in mind that, depending on the instance’s configuration, this could add to the alert size considerably.

Process Lineage

Alerts contain a lineage field with the full process lineage of the process that triggered the Alert going back to the process that launched that process.

In many cases the process lineage will terminate with an init process or system like systemd or dockerd. This can be useful for creating fine-grained white and black lists.

While process lineage details provide useful context, they can considerably increase the size of an Alert. To disable it set the CAPSULE8_PROCESS_LINEAGE_IN_ALERT environment variable to false or add process_lineage_in_alert: false to the capsule8-analytics.yaml config file. For more information about process lineage see the Capsule8 Strategy guide.

Removing Process Lineage

While process lineage details provide useful context, they can considerably increase the size of an Alert. If process lineage is not wanted in standard JSON Alerts, it can be disabled by setting the CAPSULE8_PROCESS_LINEAGE_IN_ALERT environment variable to false, nor by adding process_lineage_in_alert: false to your analytics config file.