Skip to content
📌 OpenRun 1.0 is released, read the announcement
Audit Events

Audit Events

OpenRun automatically creates audit events for all operations. See demo for a demo of events viewing.

Introduction

All operations against the OpenRun server are automatically logged in a database. The default location for this database is $OPENRUN_HOME/metadata/clace_audit.db. This can be configured by setting the property

openrun.toml
[metadata]
audit_db_connection = "sqlite:$OPENRUN_HOME/metadata/clace_audit.db"

The events which are logged are

  • All HTTP requests except GET, HEAD and OPTIONS
  • System events, like app updates and any metadata changes (webhook calls included)
  • Action invocations (execute, validate and suggest, prefixed with api_, cli_ or mcp_ when not run from the form UI) and async action run completions (run_finish); the ops tools use case shows the rows a confirmed, declined and refused destructive run leave
  • Job runs: every finished job run writes a job event with the run id and status
  • MCP calls: every JSON-RPC request to the management, an app’s or the aggregate MCP endpoint is an mcp event, see MCP apps
  • Custom events, as defined in app code

Configuration

The configurable options related to audit events are:

  • app_config.audit.redact_url: Set to true to redact the API path for HTTP events. By default, the API path, except for query string, is logged
  • app_config.audit.skip_http_events: Set to true to skip HTTP event logging

The app config options can be set globally in the openrun.toml. It can also be set individually for an app by setting the app metadata. For example,

openrun app update conf --promote 'audit.redact_url=true' /myapp

The retention for audit events is configurable globally. The config settings in openrun.toml are:

  • system.http_event_retention_days : Number of days to retain http events, default 90
  • system.non_http_event_retention_days : Number of days to retain non-http events, default 180

Custom Events

HTTP, System and Action events are generated automatically. Apps can also define custom events. To add a custom event, in a handler function, add a call to ace.audit. The parameters for ace.audit are:

PropertyOptionalTypeDefaultNotes
operationfalsestringThe operation type to log
targetfalsestringThe target the operation is being done on
detailtruestringDetailed info about the event

For example, the dictionary app does:

ace.audit("word_lookup", args.word)

This will enable searching the audit events (using the Viewer app) for all operations of type “word_lookup”.

Only the last call to ace.audit from a handler function is logged.

Event Viewer

Events can be viewed by admin using the Event Viewer app code: demo. To install the app on your instance, run

openrun app create --approve --auth system github.com/openrundev/apps/openrun/audit_viewer /events

The event viewer shows events for all apps. This app can be installed with access by admins only.

Access Log

Separately from the audit database, every HTTP request (GET included) is written to the access log $OPENRUN_HOME/logs/access.log when logging.access_logging is true (the default). Each entry is a JSON line with method, host, url, proto, remote, status, bytes, duration, request_id, user_id and app_id. The request_id is the same id recorded on the audit events of that request, so the two can be correlated; user_id and app_id are empty for unauthenticated and non-app requests. Rotation follows logging.max_size_mb and logging.max_backups.