Page last updated:
Audit events help Cloud Foundry operators monitor actions taken against resources (such as applications) via user or system actions.
Differences from Other Types of Events
Despite being similar in name, audit events are different from Cloud Foundry Usage Events. Unlike usage events, audit events are not suitable for application and service billing.
Another tool to help administrators monitor user actions on Cloud Foundry is Security Event Logging. Unlike Security Event Logs, audit events do not cover all API endpoints, but provide more details about a user’s actions.
The easiest way to view events for an application is to use the Cloud Foundry CLI:
cf events APP_NAME
This results in the following output:
time event actor description 2018-09-04T17:03:49.00-0700 audit.app.droplet.create admin 2018-09-04T17:03:28.00-0700 audit.app.update admin state: STARTED 2018-09-04T17:03:27.00-0700 audit.app.build.create admin 2018-09-04T17:03:24.00-0700 audit.app.upload-bits admin 2018-09-04T17:03:24.00-0700 audit.app.map-route admin 2018-09-04T17:03:24.00-0700 audit.app.create admin instances: 1, state: STOPPED, environment_json: [PRIVATE DATA HIDDEN]
This command shows the 50 most recent events for that application. To see more events, or events that are not attributed to an application, use the following Cloud Foundry API endpoint:
For documentation about using this endpoint, see the API documentation.
Events are currently only viewable via the v2 api, but user actions in the Cloud Foundry v3 API will still result in audit event creation.
Using Audit Events
The following describes some of the intended use cases of audit events.
Usage events allow users, administrators, and operators a view a resource’s history. For example, by looking at usage events for an application, an operator will see information such as when it was last updated, if it has crashed recently, etc.
Querying For Events
A user is able to query the events endpoint with various filters. For example, a user could query for all events of a given type, or all events associated with a resource since a given timestamp.
Allowed filters are enumerated on the API documentation.
External Auditing Warehouse
For auditing and compliance reasons, some operators may wish to keep a record of all audit events that have occured. Because audit events expire and may be purged during a deploy, these operators must maintain an external data warehouse. This way they can store and access events across expiration events and conform to their own compliance requirements.
Types of Audit Events
App Lifecycle (audit.app.*)
Organization Lifecycle (audit.organization.*)
Route Lifecycle (audit.route.*)
Service Lifecycle (audit.service.*)
Service Binding Lifecycle (audit.service_binding.*)
Service Broker Lifecycle (audit.service_broker.*)
Service Dashboard Client Lifecycle (audit.service_dashboard_client.*)
Service Instance Lifecycle (audit.service_instance.*)
Service Key Lifecycle (audit.service_key.*)
Service Plan Visibility Lifecycle (audit.service_plan_visibility.*)
Space Lifecycle (audit.space.*)
User Lifecycle (audit.user.*)
User-Provided Service Instance Lifecycle (audit.user_provided_service_instance.*)
When are events created?
Most events are created when a user acts upon a resource.
For example, a user issuing a
cf stop APP_NAME command causes an
audit.app.stop event to be created and associated with that user.
Service events (
audit.service*) are created after the service broker has approved an interaction.
Crash events (
audit.app.crash) are created when Diego marks an application instance as crashed.
Blob events (
blob.remove_orphan) are created by a daily clean up job and do not represent user action.
Audit events can be created at any point during the execution of the action they describe. This means the action associated with the event is not guaranteed to have succeeded.
The audit events table can grow to be very large. So, for performance considerations, certain database migrations may result in the truncation of this table. In other words, this means that a deployment with such a migration will result in a loss of events.
These migrations are exceedingly rare and any release of capi-release that includes one will note this behavior prominently in its release notes.
The order of audit events returned from the API may not match the sequence of events that occurred in the system.
Do not rely on timestamps to sequence events; they may come from different Cloud Controller instances whose times could be slightly mismatched.
Audit events expire after 31 days by default. This is configurable using the capi-release manifest property