Skip to main content

​
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, 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, so it requires no local installation. If the task doesn’t appear after you add it in step 1 below, contact support to check your project’s version. Because it reads the same log data as Log Explorer, the agent shares its 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. Store the API key as a sensitive variable 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.
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:
Commit the change and deploy it so the task is available on your environment:

​
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, 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 <N> 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 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. After the analysis completes, the results appear in the run’s Report tab and in the task’s activity log 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:
To change the provider, maximum findings, or budget cap, pass any of the task environment variables under variables.env. For example, to use OpenAI and lower the cost ceiling:
Or set a custom window and filters together:

​
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 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 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. 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 filter maps to a LOG_FILTERS key and its _mode counterpart:

​
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 (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 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.
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.
These figures apply to the current agent release. A later release can change them.
Last modified on October 23, 2026