---
url: "https://vueda.dev/v3/reference/api/py/vueda.core.audit.md"
title: "core.audit"
---

# core.audit

## Overview

An explicit action context for audited writes that happen outside a request.

## `action_is_open` {#action_is_open}

Return whether an action is open, so a write made now joins it.

An operation that names its own action only when nothing else has opened one checks this first.
Inside an open action it runs unchanged and keeps that action's name.

### Signature {#action_is_open-signature}

`action_is_open()`

### Source {#action_is_open-source}

`server/vueda/core/audit.py:59`

## `audited_action` {#audited_action}

Group every audited write inside this block under one action.

Request traffic takes its context from history middleware. A management command, a background
task, or a nested service operation has no request, so it names its own action here. Writes
outside any context still record events; they just carry no identity associating them with the
other writes of the same operation.

``kind`` says what sort of source the action came from. The middleware records ``request``,
VDQ tasks record ``task``, and a management command should pass ``command``. A block that names
no kind keeps the kind of the action it runs inside, so a service operation called from a request
stays a request action; at the top level it defaults to ``system``. The history API publishes the
kind, so a project that adds one should expect clients to render it as an unrecognized value.

Nesting follows pghistory: an inner block adds its metadata to the outer action, and the outer
action keeps that metadata until it exits. Only the outermost block clears the action when it
ends, because an inner one leaving must not take the action its caller is still writing under.

### Signature {#audited_action-signature}

`audited_action(action, kind, metadata)`

#### Parameters {#audited_action-parameters}

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| <span id="audited_action-param-action">action</span> |  | yes |  |  |
| <span id="audited_action-param-kind">kind</span> |  | no | `None` |  |
| <span id="audited_action-param-metadata">metadata</span> |  | no |  |  |

### Source {#audited_action-source}

`server/vueda/core/audit.py:17`

## `current_action_metadata` {#current_action_metadata}

Return the metadata of the action currently open, or an empty mapping outside one.

History middleware records the acting user on a request's action, so this is where code holding
no user of its own can find who is acting.

### Signature {#current_action_metadata-signature}

`current_action_metadata()`

### Source {#current_action_metadata-source}

`server/vueda/core/audit.py:68`

## Source

`server/vueda/core/audit.py`