> ## Documentation Index
> Fetch the complete documentation index at: https://helpcenter.magure.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Execution logs and monitoring

> Execution activity logs, LLM cost and token tracking, structured operational logging, and record provenance across MagOneAI

MagOneAI gives you visibility into what your agents and workflows did through four mechanisms: **execution activity logs** that record every step of every run, **LLM token and cost tracking**, **structured operational logging** for platform operators, and **record provenance** stamped on the resources you create. This page explains what each one captures and how to use it.

<Note>
  MagOneAI does keep a dedicated, append-only audit log, but it is deliberately narrow: it records **privileged superadmin actions** (user, organization, platform, and MCP administration) in an immutable store that is inserted into and read, never updated or deleted, and is readable only by superadmins. It is not a general activity SIEM: it has no SIEM connectors and no configurable retention policies, and it does not capture ordinary workflow, agent, or data-access events. Day-to-day visibility into what your agents and workflows did comes from the execution and logging mechanisms described below. Because you self-host the platform, you own its logs and metrics and can forward them into your existing tooling at the infrastructure layer.
</Note>

## Execution activity logs

Every workflow run is an **execution**, and every step inside it is recorded as an **activity log**. Together they form a complete, replayable picture of what happened during a run.

### The execution record

Each execution stores:

* **Identity and scope** — Execution ID, project ID, use case ID, and the user who triggered it (`executed_by`)
* **Trigger** — Trigger type (in-app, chat, schedule, or API) and trigger context; for API-triggered runs, the API key that started it
* **Input and output** — The input the run received and its final output (and output format)
* **Outcome** — Status (pending, running, completed, failed, cancelled) and an error message on failure
* **Timing** — `created_at`, `started_at`, and `completed_at`

### Per-activity logs

For each activity in the run (agent, tool, conditional, parallel, human task, and so on), MagOneAI records:

* **Activity metadata** — Activity ID, activity type, and the execution sequence number for that pass
* **Status** — Started, completed, failed, or skipped
* **Input and output snapshots** — The data the activity received and the result it produced. For agent activities, the input snapshot reflects the dict actually sent to the model
* **Duration** — `started_at`, `completed_at`, and computed `duration_ms`
* **Errors** — The error message when an activity fails
* **Retries** — A `retry_count` that increments when Temporal retries the same pass
* **LLM metadata** — For agent activities, token counts and cost for the model call (`llm_metadata`)

<Tip>
  Activity logs are Temporal-retry-aware. A retried attempt of the same pass reuses its log row and bumps `retry_count`, while a goto self-loop that re-enters the same activity gets a fresh row per pass — so each loop iteration keeps its own inputs, outputs, and tool calls.
</Tip>

### Viewing execution logs

You review runs in **MagOneAI Studio**:

<Steps>
  <Step title="Open the execution list">
    In Studio, open a project and go to its execution history. The list is paginated and filterable by status, use case, trigger type, date range, and the user who ran it.
  </Step>

  <Step title="Open a run">
    Select an execution to see its full detail, including every activity log in sequence with status, timing, inputs, outputs, and any errors.
  </Step>

  <Step title="Review tokens and cost">
    Each run aggregates the total tokens and cost across its agent activities, so you can see what a workflow consumed end to end.
  </Step>
</Steps>

### Temporal execution history

Workflows run on **Temporal**, which keeps its own durable event history for each workflow execution. This history is the source of truth for retries and branching, and it can be replayed for debugging. Temporal's history is immutable within its own retention window and is separate from the activity logs stored in the application database.

## LLM token and cost tracking

Every LLM call is recorded so you can understand and control spend.

### What is tracked per call

For each model request, MagOneAI stores an **LLM usage** record:

* **Model and provider** — Which provider and model handled the request
* **Tokens** — Input tokens, output tokens, and (where the provider reports it) the prompt-cache read and write breakdown
* **Cost** — Total cost in USD, derived from the configured pricing
* **Status and linkage** — The request status, linked back to the execution and trigger source that produced it

### Summaries and breakdowns

Usage records roll up into summaries you can query:

* **Organization summary** — Total tokens and cost across the org, including prompt-cache hit visibility
* **By project** — Spend within a specific project, plus the underlying per-request records
* **By workflow** — Cost attributed to individual use cases
* **By source** — Spend grouped by what triggered the runs

Use these to spot the most expensive workflows and decide where a smaller or cheaper model would do.

## Structured operational logging

For platform operators, MagOneAI emits structured logs using structlog.

* **Structured key/value output** — Log lines carry `key=value` fields and ISO 8601 timestamps
* **Two render modes** — Human-readable colored output for the console in development, and pure JSON for shipping to Grafana Loki in production
* **Operational, not per-tenant** — These logs are for running and debugging the platform. They are not a per-tenant, queryable audit store, and they never contain secrets, tokens, `Authorization` headers, or PII

Security-relevant events surface here as warnings — for example, an access-denied attempt logs `org_access_denied` with the user and target org, and a decompression-bomb rejection logs `zip_safety_rejected`.

### Metrics instrumentation

The platform is instrumented with Prometheus-style metrics (LLM requests, tokens, and cost; execution and activity counts and durations; MCP tool calls; DB, Vault, and session metrics). These support operational monitoring. The `/metrics` endpoint is exposed only in non-production builds.

## Record provenance

Every resource you create carries provenance columns so you can answer "who created this and who changed it last."

* **Created and updated by** — Resources such as agents, use cases, projects, organizations, API keys, schedules, webhooks, files, and chat conversations stamp `created_by` / `updated_by` alongside `created_at` / `updated_at`
* **Soft delete** — Resources are deactivated with an `is_active` flag rather than being hard-deleted, so their history and provenance remain
* **Execution attribution** — Every execution records `executed_by` (or the API key, for API triggers), tying each run back to who started it

## Exporting execution data

You can export execution data from a project for reporting or offline analysis.

<Steps>
  <Step title="Filter the runs you need">
    Choose a project and narrow by status, use case, trigger type, date range, or the user who ran the workflow. You can optionally include child executions.
  </Step>

  <Step title="Export to Excel">
    The platform streams the matching executions as an Excel file.
  </Step>

  <Step title="Analyze offline">
    Open the export in a spreadsheet or load it into your BI tool for reporting.
  </Step>
</Steps>

## Troubleshooting with execution logs

Execution logs are the fastest way to understand why a run behaved the way it did.

### Example: debugging a failed workflow

<Steps>
  <Step title="Find the failed run">
    In Studio, locate the failed execution in the project's execution history.
  </Step>

  <Step title="Open the activity timeline">
    Open the run to see its activities in sequence, each with a status and timing.
  </Step>

  <Step title="Identify the failing activity">
    Find the activity marked failed and read its error message. Check `retry_count` to see whether Temporal already retried it.
  </Step>

  <Step title="Inspect inputs and outputs">
    Review the failing activity's input snapshot and any partial output to see what data it actually received.
  </Step>

  <Step title="Fix and re-run">
    Address the cause — a bad input, an expired credential, a misconfigured tool — and run the workflow again.
  </Step>
</Steps>

### Example: investigating cost

<Steps>
  <Step title="Open usage summaries">
    Review the organization or project usage summary to see total tokens and cost for the period.
  </Step>

  <Step title="Break it down">
    Use the by-workflow and by-source breakdowns to find which use cases and triggers are driving spend.
  </Step>

  <Step title="Drill into records">
    Open the per-request usage records for a project to see model, token counts, and prompt-cache hits behind the numbers.
  </Step>

  <Step title="Optimize">
    Shorten prompts, tune knowledge-base retrieval, or move simpler steps to a cheaper model.
  </Step>
</Steps>

## Best practices

<CardGroup cols={2}>
  <Card title="Review execution history" icon="list-check">
    Use Studio's execution history to debug failures and confirm workflows are behaving as intended.
  </Card>

  <Card title="Watch cost with usage summaries" icon="wallet">
    Check the org and project usage summaries regularly to catch runaway spend early.
  </Card>

  <Card title="Ship logs to your own stack" icon="share-nodes">
    Because you self-host, collect the platform's JSON logs (via Loki) and Prometheus metrics with your existing observability tooling.
  </Card>

  <Card title="Rely on provenance for accountability" icon="user-check">
    Use `created_by` / `updated_by` to answer who created or last changed a resource.
  </Card>
</CardGroup>

<Info>
  Execution logs and monitoring are most effective alongside the platform's other controls. Combine them with [RBAC](/security/rbac), [HashiCorp Vault](/security/secrets-management) for secrets, and network-level security for defense in depth.
</Info>

## Next steps

<CardGroup cols={2}>
  <Card title="Security overview" icon="shield-halved" href="/security/overview">
    Understand MagOneAI's defense-in-depth security architecture
  </Card>

  <Card title="Triggers and execution" icon="play" href="/workflows/triggers-and-execution">
    See how executions are triggered, retried, and monitored
  </Card>
</CardGroup>