> For the complete documentation index, see [llms.txt](https://docs.appfarm.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.appfarm.io/reference/operations/logs.md).

# Logs

The **Logs** view, under **Operations**, shows events recorded across your solution, from [action](/reference/actions.md) and schedule runs to API calls and client performance. It has two modes: **Stream**, a live feed of events as they happen, and **Query**, a search over stored entries. The mode selector is in the top right.

{% embed url="<https://www.youtube.com/watch?v=23VCMcMOuwo>" %}

{% hint style="info" %}
**Good to know**

Whether a run is logged depends on the platform version the environment runs on. Schedule logs are produced from version 156, and service logs from version 157. An environment on an older version, such as a production environment that has not been upgraded, does not produce these logs.
{% endhint %}

## Modes

**Stream** shows entries live as they are produced, so you can watch activity in real time while testing or debugging.

**Query** searches stored entries over a [time range](#time-range). Most filter changes run the query straight away. See [Filtering](#filtering) for when you need to click **Run query**.

## Filtering

The filter bar sits above the results. You can filter by:

* **All severities**: the [severity](#severity) level.
* **All environments**: the environment the entry was recorded in.
* **All sources**: the [log source](#log-sources).
* **Filter by message text**: shows only the loaded entries whose message contains the text.
* **Add filter**: a filter on a metadata field, using `=`, `>`, `>=`, `<`, or `<=`.

In **Query** mode, choosing a severity or a time range runs the query straight away. Changes to environments, sources, or the **Match** setting run the query when you close the menu. Changes made with **Add filter** don't run the query on their own. A banner shows that the results are out of date, and **Run query** loads the matching entries.

**Clear filters** appears when a filter is active. It resets every filter except the time range and runs the query.

### Time range

The time range sets the period to search in **Query** mode. The default is **Last 1 hour**. The presets are:

* **Last 1 minute**, **Last 5 minutes**, **Last 15 minutes**, **Last 30 minutes**
* **Last 1 hour**, **Last 6 hours**, **Last 12 hours**
* **Last 1 day**, **Last 2 days**, **Last 7 days**
* **Today**, **Yesterday**

**Today** starts at midnight local time, and **Yesterday** covers the whole previous day. Each run calculates the preset from the current time.

To search a window of your own:

* **Between…**: enter a **From** and a **To** time.
* **Around…**: enter a **Time** and the **Minutes before and after** it.

Times use the format `YYYY-MM-DD HH:mm`. Click **Apply range** to run the query. The selector then shows the start and end of the window.

## Results

The results table has three columns: **Severity**, **Local time**, and **Summary**. The **Summary** column tags each entry with its environment and source, followed by the message. Expand a row using the chevron on the left to see its full detail and metadata. See [Entry fields](#entry-fields) for what is recorded.

### Distribution

Above the results, the **Distribution** chart shows the volume of matching entries over the selected time range, colored by severity. The total entry count for the current result set is shown alongside it. Clicking a bar in the **Distribution** chart sets the time range to that bar and runs the query.

### Exporting

Download the current result set as JSON using the download button above the results.

### Metadata values

Click a metadata value in an expanded entry to open a menu with these options:

| Option                    | Description                                                                                                                                                                                                                                                     |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Open in Create**        | Opens the app, flow, action, action node, schedule, object class, service, or endpoint the value refers to. The option names the item, for example **Open Flow in Create**. Shown only when the value is the ID of something that still exists in the solution. |
| **Show matching entries** | Adds a filter on the field and value, and runs the query. Available for top-level metadata fields.                                                                                                                                                              |
| **Add field to summary**  | Shows the field's value in the **Summary** column of every entry that has the field. Select **Remove field from summary** to take it away again.                                                                                                                |
| **Copy value**            | Copies the value to the clipboard.                                                                                                                                                                                                                              |

The filters, summary fields, and time range are kept in the page URL, so you can share a link to the same view.

## Log sources

Each entry belongs to a source. A source is a stream of one kind of event, with its own metadata. Filter by source with **All sources**.

| Source                                        | What it captures                                                                                                                                                                                  |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [**Action**](#action)                         | [Flow](/reference/flows.md), [service](/reference/services.md) and [app](/reference/apps.md) action runs. Logging must be enabled per action. Read more [here](/reference/actions.md#properties). |
| [**Scheduler**](#scheduler)                   | Flow and service schedule runs.                                                                                                                                                                   |
| [**API request**](#api-request)               | Calls to service and flow API endpoints.                                                                                                                                                          |
| [**Client performance**](#client-performance) | Client-side performance in your apps, keyed by app and user.                                                                                                                                      |

The **All sources** menu also lists **Authorization**, **Security audit**, and **Account audit**.

## Entry fields

Every entry carries a common set of fields, followed by metadata specific to its source. Expand a row to see them.

| Field               | Description                                                                                                                                                                          |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Timestamp**       | When the event occurred, in UTC.                                                                                                                                                     |
| **Severity**        | The entry's [severity](#severity) level.                                                                                                                                             |
| **Source**          | The [log source](#log-sources).                                                                                                                                                      |
| **Origin**          | Where the entry came from, shown as a path such as flow › action or service › endpoint. Click a step to open it in Appfarm Create. Shown when the items still exist in the solution. |
| **Environment**     | The [environment](/reference/configuration/environments.md) the event was recorded in.                                                                                               |
| **Appfarm version** | The Appfarm version the solution was running. Shown when recorded.                                                                                                                   |
| **Message**         | A short summary of the event.                                                                                                                                                        |

### Action

Action runs are logged only when **Enable Log** is selected on the action's **Action settings** tab. **Custom Log Fields** set up there are recorded under `customFields` on the entry, alongside the metadata below. Read more on how to set up action logging [here](/reference/actions.md#debugging).

| Field                    | Description                                                                                                                |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
| `action_id`              | The action that ran.                                                                                                       |
| `action_node_id`         | The action node in focus. On a failure, the node that failed. On a caught exception, the node that threw the error.        |
| `catch_action_node_id`   | On a caught exception, the [Catch exception](/library/action-nodes/catch-exception.md) action node that handled the error. |
| `app_id`                 | The app the action ran in.                                                                                                 |
| `flow_id`                | The flow the action ran in.                                                                                                |
| `execution_time_ms`      | How long the run took, in milliseconds.                                                                                    |
| `status`                 | The run result, `success` or `failed`.                                                                                     |
| `caught_exception_count` | The number of exceptions caught during the run. Shown only when at least one exception was caught.                         |
| `triggered_by`           | What the action ran as, `user` or `service_account`.                                                                       |
| `user_id`                | The user the action ran as.                                                                                                |
| `service_account_id`     | The [service account](/reference/security/service-accounts.md) the action ran as.                                          |
| `error_code`             | On a failure or a caught exception, the error code, if the error has one.                                                  |
| `error_custom_code`      | On a failure or a caught exception, the custom error code, if one is set.                                                  |
| `error_name`             | On a failure or a caught exception, the error type.                                                                        |
| `error_message`          | On a failure or a caught exception, the error message.                                                                     |

When a Catch exception action node catches an error in an app or flow action, the error is logged as a separate entry with the **Warning** severity, alongside the entry for the run. The entry has no `status`, so a filter on `status` doesn't match it. A run logs at most 10 of these entries. The run's own entry keeps its `status`, and its `caught_exception_count` includes every caught exception, including those over the limit.

{% hint style="info" %}
**Good to know**

Users who open an app with [unauthenticated access](/how-to/authentication-and-access-control/unauthenticated-access.md) without signing in don't produce **Action** or **Client performance** entries from the app. A flow they run from the app is logged with `triggered_by` set to `service_account` and the service account that represents them in `service_account_id`.
{% endhint %}

### Scheduler

| Field               | Description                                                        |
| ------------------- | ------------------------------------------------------------------ |
| `schedule_id`       | The schedule that ran.                                             |
| `duration_ms`       | How long the run took, in milliseconds.                            |
| `execution_status`  | The run result, for example `completed`.                           |
| `method`            | For a service schedule, the HTTP method used to call the endpoint. |
| `status_code`       | For a service schedule, the HTTP status code returned.             |
| `status_text`       | For a service schedule, the HTTP status text returned.             |
| `url`               | For a service schedule, the endpoint URL called.                   |
| `error_code`        | On a failure, the error code.                                      |
| `error_custom_code` | On a failure, the custom error code, if one is set.                |
| `error_name`        | For a flow schedule, on a failure, the error type.                 |
| `error_message`     | For a flow schedule, on a failure, the error message.              |

`schedule_id`, `duration_ms`, `execution_status`, `error_code`, and `error_custom_code` apply to both flow and service schedules. `method`, `status_code`, `status_text`, and `url` apply only to service schedules, which run by calling an endpoint. The schedule's name is shown in the entry message and in **Origin**.

### API request

The identifier fields depend on the endpoint type, and some fields depend on whether the call ran synchronously or asynchronously.

| Field                               | Description                                                           |
| ----------------------------------- | --------------------------------------------------------------------- |
| `flow_id`, `flow_endpoint_id`       | For a flow API endpoint, the flow and the endpoint that was called.   |
| `service_id`, `service_endpoint_id` | For a service endpoint, the service and the endpoint that was called. |
| `method`                            | The HTTP method used.                                                 |
| `url`                               | The request URL.                                                      |
| `execution_status`                  | The result, for example `completed`.                                  |
| `status_code`                       | The HTTP status code returned, on a synchronous request.              |
| `duration_ms`                       | How long the request took, in milliseconds.                           |
| `async_job`                         | Whether the request ran asynchronously.                               |
| `job_id`                            | An identifier for the job, on an asynchronous request.                |
| `triggered_by`                      | What triggered the request, for example `user`.                       |
| `user_id`                           | The user the request ran as.                                          |

### Client performance

Logs one entry each time a signed-in user loads an app in the solution, with the load time and the size of the initial data. The message has the form `Initial app load - elapsed time: <time>ms, initial data: <time>ms, size: <size>`.

| Field                     | Description                                                                                                  |
| ------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `app_id`                  | The app that was loaded.                                                                                     |
| `metric_name`             | `app_initial_load`.                                                                                          |
| `app_loaded_ms`           | The time from when the page started loading until the app's **On App Load** event finished, in milliseconds. |
| `initial_data_load_ms`    | How long the initial data took to load, in milliseconds.                                                     |
| `initial_data_size_bytes` | The size of the initial data, in bytes.                                                                      |
| `user_id`                 | The user who loaded the app.                                                                                 |
| `user_agent`              | The browser user agent.                                                                                      |

If the initial data fails to load, an entry with `metric_name` `initial_data_failed` is also logged.

## Severity

Each entry has a severity, shown in the **Severity** column. The **All severities** filter selects which levels appear, from highest to lowest: **Emergency**, **Critical**, **Error**, **Warning**, **Notice**, **Info**, and **Debug**.

The **Match** setting controls how the choice applies. **And higher** shows the selected level and every level above it. **Exact** shows only the selected level.


---

# 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.appfarm.io/reference/operations/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.
