> 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/hook/execution-logs.md).

# Hook Execution Logs

View logs for each Hook interception or modification, control whether original message content is recorded, and trace Hook execution details for individual messages from conversations.

Every Hook interception, modification, and pass-through is logged. For regulated industries (finance, healthcare, government), **"traceability" is itself a compliance requirement** — when issues arise, you need to trace "which message, triggered by which rule, with what action, at what time."

<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>Execution logs (Audit Log) provide a complete record of each action: matched rule, action taken, processing result, and timestamp, with keyword search, assistant filtering, and report export support</p></figcaption></figure>

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

Navigate to <mark style="color:blue;">AgentOps</mark> → <mark style="color:blue;">Hook Execution Logs</mark> from the left menu. You can see the following for each execution entry:

* **Time** — When it occurred
* **Assistant** — Which AI assistant triggered it
* **Matched Rule** — Which Hook handled it
* **Action** — What was done (mask/rewrite, block, or pass-through)
* **Status** — Processing result

You can filter by **date range, assistant, and keywords**, and **export reports** for further audit analysis. The top of the page also displays statistics for **total executions, 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 logs list"><figcaption><p>Execution logs list: Each entry shows the AI assistant, Hook name, trigger point, action, and result. You can see actual actions such as PII masking replacing phone numbers with [REDACTED_PHONE], and sensitive keywords and prompt injections being blocked</p></figcaption></figure>

### View Individual Log Details <a href="#log-detail" id="log-detail"></a>

Click on any log entry to see the complete context of that action: **basic information (Hook name, type, trigger point, action, result), related information, and message content**, giving you a clear picture of 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="Hook execution log entry details"><figcaption><p>Entry details: Using PII masking as an example, you can see the action is "modify" and the message content has been masked as [REDACTED_PHONE]</p></figcaption></figure>

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

By default, execution logs **only record the "action result" without retaining the original sensitive content** — this prevents PII or sensitive messages from being stored again in the logs.

If you need to see "what the original content looked like" during debugging, go to the Hook settings page and change the <mark style="color:blue;">Record original values before masking</mark> toggle from `off` to `on`. When enabled, logs will additionally retain the original content before masking/blocking, making it easier to investigate issues.

<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="Record original values before masking toggle"><figcaption><p>Control via the "Record original values before masking" field on the Hook settings page: default is off (only records type and count, not original PII), switch to on only when debugging is needed</p></figcaption></figure>

{% hint style="warning" %}
**Privacy trade-off:** Enabling "Record original values" means the original PII/message content will be stored in execution logs. **For security reasons, it is recommended to keep this off by default** and only enable it temporarily when troubleshooting is needed.
{% endhint %}

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

In addition to centralized execution logs, you can also **trace back from actual conversations**: Navigate to <mark style="color:blue;">Customer Service</mark> → <mark style="color:blue;">All Conversations</mark>, open any conversation, and you can see which messages in that conversation were processed by Hooks (masked or blocked), along with the corresponding actions taken.

This allows you to understand "why this message was masked/blocked" directly while reviewing customer conversations, without having to cross-reference logs separately.

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

* [Hook Message Interception Overview](/maiagent-user-guide/en/hook/hook.md) — What Hooks are and the five standard templates
* [Create and Configure Hooks](/maiagent-user-guide/en/hook/setup.md) — How to create, configure parameters, and link to AI assistants


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.