Customizing Platform Log Forwarding

Page last updated:

Warning: Pivotal Cloud Foundry (PCF) v2.3 is no longer supported because it has reached the End of General Support (EOGS) phase as defined by the Support Lifecycle Policy. To stay up to date with the latest software and security updates, upgrade to a supported version.

Page last updated:

You can configure Pivotal Application Service (PAS) to forward logs to remote endpoints using the Syslog protocol defined in RFC 5424. For more information, see Enable Syslog Forwarding in Configuring Logging in PAS.

PAS annotates forwarded messages with structured data. This structured data identifies the originating BOSH Director, deployment, instance group, availability zone, and instance ID. All logs forwarded from BOSH jobs have their PRI set to 14, representing Facility: user-level messages and Warning: warning conditions, as defined in RFC 5424 Section 6.2.1. This PRI value may not reflect the originally intended PRI of the log.

Logs forwarded from other sources, such as kernel logs, retain their original PRI value.

The following table describes the log line Structured Data:

Structured Data Description
ENTERPRISE_NUMBER Cloud Foundry’s private enterprise number, 47450, as defined in RFC 5424 Section 7.2.2.
DIRECTOR The name of the BOSH Director managing the deployment.
DEPLOYMENT The name of the BOSH deployment.
INSTANCE_GROUP The name of the BOSH instance_group.
AVAILABILITY_ZONE The name of the BOSH availability zone.

Log lines use the format below:

    [instance@ENTERPRISE_NUMBER director="$DIRECTOR" deployment="$DEPLOYMENT" 

Example log messages:

<14>1 2017-01-25T13:25:03.18377Z etcd - - [instance@47450 
    director="test-env" deployment="cf" group="diego_database" az="us-west1-a" 
    id="83bd66e5-3fdf-44b7-bdd6-508deae7c786"] [INFO] the leader is 
<14>1 2017-01-25T13:25:03.184491Z bbs - - [instance@47450 
    director="test-env" deployment="cf" group="diego_database" az="us-west1-a" 

Modify Which Logs PAS Forwards

When you enable log forwarding, PAS forwards all log lines written to the /var/vcap/sys/log directories on all Cloud Foundry virtual machines (VMs) to your configured External Syslog Aggregator endpoint by default.

You can configure PAS to forward a subset of logs instead of forwarding all logs as follows.

  1. In the PAS tile, select System Logging.
  2. In the Custom rsyslog Configuration textbox, enter a custom syslog rule. See the example custom syslog rules below.
  3. Click Save.

For more information about enabling and configuring syslog forwarding, see Configuring Logging in PAS.

The custom rsyslog rules shown below are written in RainerScript. The custom rules are inserted before the rule that forwards logs. The stop command, stop, prevents logs from reaching the forwarding rule. This filters out these logs.

Logs filtered out before forwarding remain on the local disk, where the BOSH job originally wrote them. These logs remain on the local disk only until BOSH Director recreates the VMs. You can access these logs from Ops Manager or through SSH.

Note: PAS requires a valid custom rule to forward logs. If your custom rule contains syntax errors, PAS forwards no logs.

Forward Only Logs From a Certain Job

This rule filters out logs unless they originate from the uaa job:

if ($app-name != "uaa") then stop

Exclude Logs With Certain Content

This rule filters out logs that contain “DEBUG” in the body.

if ($msg contains "DEBUG") then stop

Note: The above example contains “DEBUG” in the message body. Not all logs intended for debugging purposes contain the string “DEBUG” in the message body.