​Audit ​Logs

How to use Audit Logs to govern activities in your Kestra instance.

What are Audit Logs

Audit Logs record all activities performed in your Kestra instance by users and service accounts. By reviewing Audit Logs, system administrators can track user activity, and security teams can investigate incidents and ensure compliance with regulatory requirements.

Why are Audit Logs important

The audit log table in Kestra serves as a historical record that developers and system administrators can use to track changes, monitor system usage, and verify system activity. It's a transparency tool that helps in understanding the sequence of activities, ensuring accountability for actions taken, and providing data for troubleshooting and analysis. Given that Audit Logs are immutable, they can also be used to detect and investigate security incidents. If you leverage Kestra edition with Elasticsearch backend, you can also use Kibana to search and visualize your logs.

How to access Audit Logs

You can access Audit Logs from the Administration section in the UI. That UI page provides a detailed table of recorded events, capturing the actions taken within the system:

Each row in the table represents a distinct event with several columns providing specific details:

• Resource Type column categorizes the resource that the event is associated with, such as editing a flow (FLOW) or executing it (EXECUTION).
• Changes indicates whether a given resource has been created, updated, or deleted.
• Actor identifies who performed the action. The user can be a human, system or a service account.
• Details section offers an in-depth description of the event, including identifiers such as the id, namespace, flowId, executionId, revision, etc. — those fields depend on the type of resource the event is associated with.
• Date represents the timestamp of when the event occurred.

How to see a full diff of a specific event

To see a full diff of a specific event, click on the icon at the end of each row to expand the details. The expanded view will show the full diff of the event side-by-side, including the before and after states of a given resource:

Below is an example where we manually change the Execution state from FAILED to SUCCESS and the diff shows the exact change made to the Execution:

How to use the Details filter to search for specific Audit Log events

The Details filter allows you to flexibly search for any Audit Log event using the key:value format. It's a tag-based system which works the same way as Execution Labels.

For example, you can filter for all events related to a specific namespace by typing namespace:your_namespace:

To further filter for a specific event, you can simply click on the relevant tag in the Details column:

How to filter for tenant-specific events

Let's say you want to find out when a specific tenant was created. Simply type "Tenant" in the search bar to filter for events related to when the tenant was created, updated, or deleted.

Alternatively, you can explicitly type in the Details filter id:your_tenant_id to filter for events related to that tenant:

How to Purge Audit Logs

The Enterprise Edition of Kestra generates an audit log for every action taken on the platform. While these logs are essential for tracking changes and ensuring compliance, they can accumulate over time and take up significant amount of space in the database.

The PurgeAuditLogs task, available in Kestra v0.19.0 and higher, will remove old audit logs that are no longer needed. You can set a date range for the logs you want to delete, choose a specific namespace, and even filter by permissions or actions (CREATE, READ, UPDATE, DELETE).

Here is the recommended way to implement the Audit Logs retention policy that will purge audit logs older than one month:

id: audit_log_cleanup
namespace: system
tasks:
  - id: purge_audit_logs
    type: io.kestra.plugin.ee.core.log.PurgeAuditLogs
    description: Purge audit logs older than 1 month
    endDate: "{{ now() | dateAdd(-1, 'MONTHS') }}"

Note how the above flow is added to the system namespace, which is the default namespace for System Flows. This ensures that this maintenance flow and its executions are hidden from the main UI, making them only visible within the system namespace that can be managed by platform administrators.

Combining the System Flows functionality with the PurgeAuditLogs task provides a simple way to manage your audit logs as code and from the UI, ensuring you keep them as long as you need to stay compliant while keeping your database clean and performant.