> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/maiagent-user-guide/en/build/hook/execution-logs.md).

# Hook Execution Logs

Review every Hook interception or modification, trace the inspection source for attachments and tool responses, control whether original message content is logged, and trace Hook execution details for

Every interception, modification, or pass performed by Hook is recorded. For regulated industries such as finance, healthcare, and government, **traceability is itself a compliance requirement**—when a problem occurs, you must be able to determine which message was processed by which rule, what action was taken, and when it happened.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-1916bf98af5cadc70d005bb90a69fc1a26c2438a%2Fhook-audit-customization.png?alt=media" alt="Hook execution logs and customization capabilities"><figcaption><p>The Audit Log records every action in full, including the matched rule, action taken, processing result, and timestamp. It supports keyword searches, filtering by assistant, and report exports.</p></figcaption></figure>

## <mark style="color:blue;">1. View Execution Logs</mark> <a href="#view-logs" id="view-logs"></a>

From the left menu, go to <mark style="color:blue;">AgentOps</mark> → <mark style="color:blue;">Hook Execution Logs</mark>. For each execution, you can see:

* **AI assistant**—The AI assistant that triggered it
* **Hook name and Hook type**—The Hook that processed it
* **Trigger point**—When the Hook intervened (when receiving a user message / after an AI response was generated)
* **Hook action and result**—What it did (mask and modify / intercept and block / pass) and the processing result
* **Message content and creation time**—Which message was processed and when it occurred

You can filter by **assistant, rule, type, action, action result, trigger point, date range, or keyword**, and you can also **export reports** for further audit analysis. The top of the page also displays statistics for the **total number of executions, number of matches, and match rate**.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-02d08b2bf82b538bc633e02667bfb7502dc43830%2Fhook-logs-list.png?alt=media" alt="Hook execution log list"><figcaption><p>Execution log list: Each entry shows the AI assistant, Hook name, trigger point, action, and result. You can see actual actions such as Personal Data Masking replacing a phone number with [REDACTED_PHONE], or sensitive keywords and prompt injections being blocked.</p></figcaption></figure>

### View Details for an Individual Entry <a href="#log-detail" id="log-detail"></a>

Open any entry to view the full context of the action: **basic information (Hook name, type, trigger point, action, and result), related information, message content, and Metadata**. This lets you clearly understand what the system did.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-d7de07c825554da9e4acc3f69c726b4f76233e07%2Fhook-log-detail.png?alt=media" alt="Details for an individual Hook execution log"><figcaption><p>Entry details: In this Personal Data Masking example, the action is modify and the message content has been masked as [REDACTED_PHONE].</p></figcaption></figure>

### Trace Checks on Attachments, Knowledge Bases, and Tool Responses <a href="#input-context-source" id="input-context-source"></a>

Hooks that run before content reaches the AI inspect more than user-entered text. Attachment content, passages retrieved from the knowledge base, and tool responses in Agent mode all pass through the same set of Hooks (see [Four Sources](/maiagent-user-guide/en/build/hook.md#four-sources)). These checks also create execution log entries, with the trigger point shown as “When receiving a user message.” Open an entry and look in the **Metadata** section to see:

* `path`: `input_context`, indicating that this entry is for content that was not directly entered by the user
* `source`: Where the content came from—a tool response shows the tool name, while a passage from the knowledge base is shown as retrieved content

When you need to determine which tool or document supplied sensitive content to the model, use `source` to trace it back. Blocked content is not provided to the model, and the conversation itself does not stop.

### Export Execution Logs <a href="#export-logs" id="export-logs"></a>

Clicking “<mark style="color:blue;">Export</mark>” on the right side of the filter bar creates an export request based on the **current filters** (assistant, Hook, type, action, result, trigger point, date range, and keyword) and generates an Excel file in the background. After the message “Export request created. Processing...” appears, you are automatically taken to the “<mark style="color:blue;">Export Requests</mark>” sub-page (you can also open it with the “<mark style="color:blue;">Export Requests</mark>” button next to “Export”).

The Export Requests page lists each export with its <mark style="color:blue;">status</mark> (Pending / Processing / Completed / Failed), the <mark style="color:blue;">user</mark> who started the export, <mark style="color:blue;">record count</mark>, <mark style="color:blue;">file size</mark>, <mark style="color:blue;">processing time</mark>, creation time, and <mark style="color:blue;">completion time</mark>. When the status is Completed, click “<mark style="color:blue;">Download</mark>” in the Actions column; when it is Failed, click “<mark style="color:blue;">View Error Details</mark>.” You can “<mark style="color:blue;">Delete</mark>” export files you no longer need.

{% hint style="info" %}
The export requests here contain only Hook execution logs. They are a separate list from “Export Requests” in the AgentOps left-side menu (exports of conversation logs and evaluation reports).
{% endhint %}

## <mark style="color:blue;">2. Control Whether Original Messages Are Logged</mark> <a href="#log-privacy-toggle" id="log-privacy-toggle"></a>

By default, execution logs **record only the processing result and do not retain the original sensitive content**. This prevents personal data or sensitive messages from being stored again in the logs.

If you need to see the original content during debugging, go to the Hook settings page and change the <mark style="color:blue;">Log original value before masking</mark> toggle from `off` to `on`. Once enabled, the logs also retain the original content before masking or blocking, making investigation easier.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-283ea3184f3a97f6a72bd3739e6973ce958d571d%2Fhook-settings-pii.png?alt=media" alt="Log original value before masking toggle"><figcaption><p>Use the “Log original value before masking” field on the Hook settings page to control this behavior. The default is off (only the type and count are recorded; original personal data is not retained). Change it to on only when debugging is required.</p></figcaption></figure>

{% hint style="warning" %}
**Privacy trade-off:** Enabling “Log original value” stores the original personal data or message content in the execution logs. **For security reasons, we recommend keeping it disabled during normal operation** and enabling it temporarily only when troubleshooting.
{% endhint %}

{% hint style="info" %}
Execution logs for “Semantic Personal Data Masking” inherently contain no original text: the detection service returns only the location and type of personal data, so the logs retain only the types and counts that were masked.
{% endhint %}

## <mark style="color:blue;">3. View Hook Execution Details from a Conversation</mark> <a href="#from-conversation" id="from-conversation"></a>

In addition to the centralized execution logs, you can also **trace actions from an actual conversation**. Go to <mark style="color:blue;">Customer Service Conversations</mark> → <mark style="color:blue;">All Conversations</mark> and open any conversation. You can then see which messages in that conversation were processed by Hook (masked or blocked) and the corresponding action taken at the time.

This allows you to understand directly why a message was masked or blocked while reviewing a customer conversation, without having to cross-reference a separate log.

## <mark style="color:blue;">4. Related Pages</mark> <a href="#related" id="related"></a>

* [Hook Message Interception Overview](/maiagent-user-guide/en/build/hook.md)—What Hook is, the four sources, and the seven standard templates
* [Add and Configure a Hook](/maiagent-user-guide/en/build/hook/setup.md)—How to create a Hook, configure parameters, and associate it with an AI assistant


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/maiagent-user-guide/en/build/hook/execution-logs.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.