> ## Documentation Index > Fetch the complete documentation index at: https://developer.upsun.com/llms.txt > Use this file to discover all available pages before exploring further. # Upsun Cloud log-analyzer agent > Automatically surface notable errors and anomalies in your logs. The log-analyzer agent scans a configurable time window, limited by your project's log retention, and generates an AI-powered report with prioritized findings. # Upsun Cloud log-analyzer agent The `log-analyzer-agent` scans an application or environment's logs on Upsun Cloud over a time window and reports what is notable: errors, anomalies, and operational issues worth your attention. If nothing is notable, it states that clearly instead. It runs with no user in the loop and is read-only: it never modifies your project, environment, or source code. The agent reads from the same log data as [Log Explorer](https://developer.upsun.com/docs/observability/logs/log-explorer.md), the Console's **Logs** tab: Log Explorer gives you visibility into your logs, and this agent gives you in-depth, actionable analysis of them. ## Run as an Upsun Cloud task The agent runs as an Upsun Cloud [`task`](https://developer.upsun.com/docs/configure-apps/tasks), so it requires no local installation. If the task doesn't appear after you add it in step 1 below, [contact support](https://developer.upsun.com/docs/core-concepts/get-support.md) to check your project's version. Because it reads the same log data as Log Explorer, the agent shares its [availability](https://developer.upsun.com/docs/observability/logs/log-explorer.md#availability): AWS or Google Cloud Platform (GCP) projects only. It isn't available on Microsoft Azure or OVHcloud projects, and HIPAA projects are excluded. The only credential you supply is an LLM provider API key. Set `MODEL` to `anthropic` (the default) to use `ANTHROPIC_API_KEY`, or to `openai` to use `OPENAI_API_KEY`. You bring your own key, and your provider bills the tokens the agent consumes directly to you. See [What a run costs](#what-a-run-costs). Store the API key as a [sensitive variable](https://developer.upsun.com/docs/development/variables/set-variables.md#variable-options) rather than passing it inline. Passing it inline exposes the secret in shell history. To use OpenAI, store `env:OPENAI_API_KEY` the same way. ```bash theme={null} upsun variable:create -p --level project --name env:ANTHROPIC_API_KEY \ --value "" --sensitive true --visible-runtime true ``` > [!WARNING] > > An Anthropic key must be scoped to a single workspace. A multi-workspace (identity-linked) key > needs a workspace ID on every request, which the agent can't supply, and the run stops in > preflight. ### 1. Add the task to your Upsun Cloud configuration Add the following to `.upsun/config.yaml`: ```yaml theme={null} tasks: log-analyzer-agent: base: "log-analyzer-agent" ``` Commit the change and deploy it so the task is available on your environment: ```bash theme={null} git add .upsun/config.yaml git commit -m "Add log-analyzer agent task" upsun push ``` ### 2. Run the agent You can run the agent from the Console, or through the CLI and API. The project, environment, and source checkout are always the task's own. You can't point the agent at a different project or environment. #### From the Console Run the log-analyzer agent from [Log Explorer](https://developer.upsun.com/docs/observability/logs/log-explorer.md), the environment's **Logs** tab. Only users with the Contributor role or above can see that tab, so only they can launch the agent this way. 1. Open the environment's **Logs** tab and set the time window and filters you want analyzed. The agent starts from that scope, but can widen it if your filters would otherwise hide the root cause. 2. Click **Analyze `` logs**, confirm the window and filters, and switch provider if your project holds keys for both. The agent picks the model for that provider. Console runs use the default maximum findings (`5`) and budget cap (\$5). To change them, use the [CLI or API](#from-the-cli-or-api) instead. 3. Click **Analyze logs**. If you haven't added the agent yet, you'll see a **Help with logs** button instead. It opens a card linking to this page and to [Log Explorer](https://developer.upsun.com/docs/observability/logs/log-explorer.md). After the analysis completes, the results appear in the run's **Report** tab and in the task's [activity log](https://developer.upsun.com/docs/observability/logs/access-logs.md#activity-logs) as a report: a one-sentence summary of log health, a top recommendation, and a priority-ordered list of findings. An empty findings list isn't a failure: it means the agent scanned the window and found nothing worth flagging, and the recommendation reads `No action needed.`. #### From the CLI or API Replace the project ID and environment with yours. If you don't set `FROM_TIMESTAMP` or `TO_TIMESTAMP`, the agent analyzes logs from the last 24 hours: ```bash theme={null} upsun e:curl -p -e -X POST /tasks/log-analyzer-agent/run --json '{}' ``` To change the provider, maximum findings, or budget cap, pass any of the [task environment variables](#task-environment-variables) under `variables.env`. For example, to use OpenAI and lower the cost ceiling: ```bash theme={null} upsun e:curl -p -e -X POST /tasks/log-analyzer-agent/run \ --json '{"variables":{"env":{"MODEL":"openai","MAX_BUDGET_USD":"2"}}}' ``` Or set a custom window and filters together: ```bash theme={null} upsun e:curl -p -e -X POST /tasks/log-analyzer-agent/run \ --json '{"variables":{"env":{"FROM_TIMESTAMP":"","TO_TIMESTAMP":"","LOG_FILTERS":"{\"severities\":[\"ERROR\"],\"severities_mode\":\"1\"}"}}}' ``` ### Analysis window By default, the agent analyzes the last 24 hours. Set `FROM_TIMESTAMP` and `TO_TIMESTAMP` to choose a different window, up to a maximum of 45 days, the Logs API's own limit. Your project's [log retention](https://developer.upsun.com/docs/observability/logs/log-explorer.md#retention) is 24 hours, well under that 45-day cap, and it's a hard cutoff: no logs older than 24 hours are accessible to the agent, regardless of the window you set. ### What you get back Each run produces a single report: * **Summary**: a one-sentence assessment of the environment's log health over the window. * **Recommendation**: what to address first. `No action needed.` when there's nothing to report. * **Findings**: up to 15 entries, ordered highest priority first. Each finding includes: * **Title** and **description** of what's happening. * **Priority** (`low`, `medium`, `high`, or `critical`): the agent's judgment of urgency, not the raw log severity. A `WARNING` can be high priority; a one-off `ERROR` can be low. * **Evidence**: a representative quoted log line, or, for an absence (like a cron that went silent), what was expected versus observed. * **Recommendation**: a concrete next step. * Optionally, the [**log kind**](https://developer.upsun.com/docs/observability/logs/log-explorer.md#log-kinds) it came from (`access`, `application`, `cron`, `deployment`, or `platform`) and the **unit, service, or instance** it concerns. ### Task environment variables Pass additional variables under `variables.env` in the run command. | Env var | Default | Description | | - | - | - | | `FROM_TIMESTAMP` | (binary default: `to - 86400`) | Window start in Unix seconds. Window capped at 45 days. See [Analysis window](#analysis-window). | | `TO_TIMESTAMP` | (binary default: now) | Window end in Unix seconds. | | `CLONE_TIMEOUT` | `900` | Timeout in seconds for cloning the environment's source. Raise for very large repos. | | `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` | (required) | Provider API key, read by the binary directly from env. `MODEL=anthropic` uses `ANTHROPIC_API_KEY`; `MODEL=openai` uses `OPENAI_API_KEY`. Set it as a sensitive variable, not inline. | | `MODEL` | `anthropic` | LLM provider: `anthropic` or `openai`. The agent picks its model for that provider. | | `LOG_LEVEL` | `info` | `trace`, `debug`, `info`, `warn`, `error`, `fatal`, or `silent`. | | `MAX_FINDINGS` | `5` | Integer 1–15. | | `MAX_BUDGET_USD` | `5` | Cost ceiling in USD. The agent aborts at the next turn boundary when exceeded. | | `LOG_FILTERS` | (none) | The [Log Explorer](https://developer.upsun.com/docs/observability/logs/log-explorer.md) filters to start from, as a JSON object. Nine dimensions are accepted: `severities`, `log_kinds`, `services`, `units`, `instances`, `hosts`, `commands`, `container_ids`, and `container_images`. Each is paired with a `_mode` of `"1"` (keep only these values) or `"-1"` (exclude them, the default). At most 45 values per list, and the whole set must fit a 4096-character query fragment. Any other key is refused. Example: `{"severities":["ERROR","CRITICAL"],"severities_mode":"1"}`. The agent may widen beyond these filters. Populated automatically when you launch from Log Explorer. | | `QUIET` | `false` | Read by the binary directly from env; `0`/`false`/`no`/`off` to disable. | | `VERBOSE` | `false` | Read by the binary directly from env; `0`/`false`/`no`/`off` to disable. | Variables with a binary default are the agent's own defaults. The task only passes a flag when the variable is set. `--project` and `--environment` are locked to the runtime's `PLATFORM_PROJECT` and `PLATFORM_BRANCH` and cannot be overridden through environment variables. ### Log Explorer filter names Each [Log Explorer](https://developer.upsun.com/docs/observability/logs/log-explorer.md) filter maps to a `LOG_FILTERS` key and its `_mode` counterpart: | Log Explorer filter | `LOG_FILTERS` key | Mode key | | - | - | - | | Kind | `log_kinds` | `log_kinds_mode` | | Severities | `severities` | `severities_mode` | | Services | `services` | `services_mode` | | Units | `units` | `units_mode` | | Instances | `instances` | `instances_mode` | | Hosts | `hosts` | `hosts_mode` | | Commands | `commands` | `commands_mode` | | Container IDs | `container_ids` | `container_ids_mode` | | Container Images | `container_images` | `container_images_mode` | ## Data access and handling ### What the agent can read The agent can access the following data on your environment, read-only. It reads only what it needs for the analysis: * **Logs**: it starts from the time window and filters you set, but isn't confined to them. It may also read other logs from the environment for context, across any [log kind](https://developer.upsun.com/docs/observability/logs/log-explorer.md#log-kinds) (`access`, `application`, `cron`, `deployment`, `platform`), to find the full picture behind a finding. * **Other observability data** through the Upsun Cloud API: deployments, activities and activity logs, HTTP traffic, server metrics, Upsun Blackfire recommendations and profiles, and continuous profiling data. * **Source code**: a shallow clone of the environment's branch tip. The agent never writes to your project, environment, or source, and it can't inspect any project or environment other than the one the task runs on. ### Data handling and storage The agent sends the data it reads to the LLM provider that you set in `MODEL`, using your own API key. That provider processes the request under your own account with them, subject to your agreement with that provider. If your data includes content that your organization restricts from leaving your infrastructure, confirm that sending it to your chosen provider is acceptable before running the agent. The run's activity log holds the report and the agent's live progress: the commands it runs and its notes, which can quote your logs or source. Beyond the activity log, Upsun doesn't separately store the log and source content the agent reads. Run parameters such as the time window, filters, and provider are visible like any other task run, in the environment's activity log. Your provider API key is the one exception: because activity entries persist and stay readable, the task never copies the key into a run's visible variables. It's read directly from the project variable you set, so it never appears in the run history. ## What a run costs Upsun Cloud doesn't charge for the log-analyzer agent itself. There is no license, subscription, or per-run fee. Each run costs you the compute of the [task container](https://developer.upsun.com/docs/configure-apps/tasks.md#resources-variables-and-access) it runs in, billed per second at the resources you allocate to the task. Task compute cost is the same regardless of the provider you use. Your LLM provider then bills the tokens the agent consumes to your own API key, and this billing varies by provider (see the table below). Upsun doesn't resell those tokens, and task compute doesn't cover them. The `MAX_BUDGET_USD` variable (default `5`) caps spend per run. The agent checks it between turns, so a run can go over it by the cost of one turn. > [!NOTE] > > The figures below come from a 3-hour test on one small app, not a full default 24-hour run, so actual cost is likely higher, especially on larger projects. Cost varies with project size, traffic, time window, and cache hits. | Provider | Approximate cost per run | | - | - | | `anthropic` | Under \$1 | | `openai` | A few cents | These figures apply to the current agent release. A later release can change them. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.