Logs & Debugging

Access real-time application logs, build logs, and deployment logs to debug issues quickly. Search, filter, and stream logs directly from the dashboard or via CLI and API. For a unified view of logs alongside requests, traces, errors, and revenue events, see the Observe page.

Types of logs

Temps provides several types of logs to help you understand what's happening with your application:

Accessing logs

Via Dashboard

Application Logs:

Build Logs:

Deployment Logs:

1. Navigate to Deployments
2. Select a deployment
3. View step-by-step deployment logs
4. See which steps succeeded or failed

Via CLI

# View application logs (last 100 lines)
bunx @temps-sdk/cli runtime-logs --project my-project --environment production --tail 100

# Follow logs in real-time
bunx @temps-sdk/cli runtime-logs --project my-project --environment production --follow

# View logs for a specific deployment
bunx @temps-sdk/cli deployments logs --project my-project --deployment 123 --follow

# View deployment logs and limit output
bunx @temps-sdk/cli deployments logs --project my-project --deployment 123 --lines 200

Via API

# Get container logs
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://your-temps-instance.com/api/projects/{project_id}/environments/{environment_id}/containers/{container_id}/logs?tail=100"

# Stream logs (Server-Sent Events)
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://your-temps-instance.com/api/projects/{project_id}/environments/{environment_id}/containers/{container_id}/logs/stream"

# Get deployment logs
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://your-temps-instance.com/api/projects/{project_id}/deployments/{deployment_id}/logs"

Log history and live viewer

The in-dashboard log viewer has two modes — History for querying past log data and Live for streaming real-time output. Both are available on the Logs tab of any container.

History tab

The History tab lets you query stored log data across configurable time windows.

Time-range presets

The time-range selector offers the following built-in presets:

• 15m — last 15 minutes
• 1h — last 1 hour
• 6h — last 6 hours
• 24h — last 24 hours
• Last 7 days — rolling 7-day window
• Last 30 days — rolling 30-day window
• Custom range... — opens a date/time picker (see below)

Custom date/time range

Selecting Custom range... opens a date range picker with HH:MM precision. The picker pre-fills with the boundaries of the previously active preset so you have a sensible starting point. Set your start and end timestamps, then apply to load results.

Full-text search and the 24-hour cap

The search box supports full-text search across log messages. When the active time range exceeds 24 hours, full-text search is automatically disabled and the search input shows a tooltip explaining the cap. This is a server-side limit (MAX_FULLTEXT_HOURS). To use full-text search, select a preset of 24h or shorter, or set a custom range within a 24-hour window. Log level filters and other non-text filters remain available for any range.

Chronological ordering and scroll anchoring

Results are displayed in chronological order — oldest entries at the top, newest at the bottom — matching the convention of tools like journalctl and tail -f. When the first page loads, the viewer anchors the scroll position to the bottom so you immediately see the most recent entries without manually scrolling down.

Auto-loading older pages

Scrolling up near the top of the log list automatically triggers the next page of older entries. The viewer uses an IntersectionObserver sentinel placed 200px from the top: when the sentinel enters the viewport, older log pages are fetched and prepended above the current content. Scroll position is preserved during the prepend so the view does not jump. A Load older button is also present as an accessible fallback for keyboard and assistive-technology users.

Live tab

The Live tab streams log output from running containers as it arrives.

Status row

A status row at the top of the Live viewer displays real-time throughput information:

Live · 1,842 lines · ~34 lps

• lines — total lines received in the current session
• lps — lines per second, computed from a 5-second sliding window

When the incoming rate reaches or exceeds 60 lps, an amber sampled chip appears next to the counter. This indicates the buffer is rolling faster than can be rendered at full fidelity; the viewer continues to display logs but may skip intermediate lines to maintain readability.

Interval polling mode

The Live tab includes an Every Ns interval mode (selectable as Every 5s, Every 30s, or Every 60s). In this mode the viewer polls /api/logs/search with page_size=500 on each interval rather than holding a WebSocket connection open. The first poll fires immediately on entering the tab — there is no empty-screen delay while waiting for the first interval to elapse. This mode is useful when you want periodic snapshots rather than a continuous stream.

Auto-follow behavior

The Live viewer tracks new log entries and automatically scrolls to the bottom as they arrive. Scrolling up disengages auto-follow so you can review earlier output without the view jumping away. Auto-follow distinguishes between deliberate scroll input and programmatic layout changes:

• Disengages follow: wheel events, touch scroll, keyboard navigation
• Does not disengage follow: layout reflows caused by multi-line log entries expanding

Auto-follow re-engages when you scroll back to within 8px of the bottom. To re-engage manually, scroll to the bottom of the viewer.

Per-line fade-in

Freshly arrived log batches fade in over 120ms (opacity 0 to 1). The animation is suppressed automatically when the user's system has prefers-reduced-motion set.

Logs from worker nodes

In a multi-node cluster, containers running on remote worker nodes appear in both the History and Live viewers alongside control-plane containers — their logs are streamed back to the control plane and stored in the same searchable history. Two extra filters help you slice across a busy project:

• Node — limit to a specific worker node, or show all nodes interleaved (the default).
• Container — limit to one container, or show all containers interleaved (the default).

Each line carries a source column showing which container and worker node it came from, so a combined "all containers / all nodes" view stays readable. See Multi-node deployment → Remote-node logs for how collection works.

Log levels

Temps supports structured logging with different log levels:

Searching and filtering logs

Search by Text

Use the search box in the logs viewer to find specific messages:

• Exact match: "error connecting to database"
• Case-insensitive: ERROR matches error, Error, ERROR
• Partial match: database finds all lines containing "database"

Note: full-text search is only available when the active time range is 24 hours or less. See Full-text search and the 24-hour cap above.

Filter by Log Level

Filter logs to show only specific levels:

1. Click the Filter button in the logs viewer
2. Select log levels (Success, Info, Warning, Error)
3. View filtered results

Filter by Time Range

View logs from specific time periods:

1. Use the Time Range selector
2. Choose a preset (15m, 1h, 6h, 24h, Last 7 days, Last 30 days) or select Custom range...
3. Logs update to show only the selected period

Filter by Deployment

Temps captures and persists logs for every deployment — not just the currently active one. Logs from completed, failed, rolled-back, and historical deployments are all retained and fully accessible. This makes it possible to audit what happened during a past release without needing to redeploy.

Accessing logs for a past or historical deployment:

You can use the --deployment flag with any deployment ID — active or historical — when fetching logs via the CLI:

# View logs for a specific deployment (active or past)
bunx @temps-sdk/cli deployments logs --project my-project --deployment 123

# Follow a deployment's log output while it is in progress
bunx @temps-sdk/cli deployments logs --project my-project --deployment 123 --follow

# Fetch the last 500 lines from a completed deployment
bunx @temps-sdk/cli deployments logs --project my-project --deployment 123 --lines 500

Deployment logs are retained for 90 days (see Log Retention below). Within that window you can read the full output of any deployment by its ID regardless of whether it is currently active.

Real-time log streaming

Stream logs in real-time to see events as they happen:

In Dashboard

1. Open the Logs tab for a container
2. Switch to the Live tab
3. Logs update automatically as new entries arrive
4. Scroll to bottom to see latest logs; scroll up to pause auto-follow

Via API

// JavaScript example - Server-Sent Events
const eventSource = new EventSource(
  `/api/projects/${projectId}/environments/${environmentId}/containers/${containerId}/logs/stream`,
  {
    headers: {
      Authorization: `Bearer ${token}`,
    },
  },
);

eventSource.onmessage = (event) => {
  const logEntry = JSON.parse(event.data);
  console.log(logEntry.message);
};

Structured logging best practices

To get the most out of Temps logging, use structured logging in your application:

JSON Logging

// Node.js example
console.log(
  JSON.stringify({
    level: "info",
    message: "User logged in",
    userId: 123,
    timestamp: new Date().toISOString(),
  }),
);

# Python example
import json
import logging

logging.info(json.dumps({
    'level': 'info',
    'message': 'User logged in',
    'user_id': 123,
    'timestamp': datetime.now().isoformat()
}))

Log Levels

Use appropriate log levels:

// Debug - detailed information for debugging
console.debug("Processing request", { requestId, userId });

// Info - general informational messages
console.info("User logged in", { userId });

// Warning - potential issues
console.warn("Rate limit approaching", { userId, requests: 95 });

// Error - errors that need attention
console.error("Database connection failed", { error: err.message });

Include Context

Always include relevant context in logs:

// Good: Includes context
console.log(
  JSON.stringify({
    level: "error",
    message: "Payment processing failed",
    userId: 123,
    orderId: 456,
    amount: 99.99,
    error: error.message,
    timestamp: new Date().toISOString(),
  }),
);

// Bad: Missing context
console.error("Payment failed");

Log retention

Access control for deployment logs

All deployment log endpoints — including historical deployments — require authentication. Access is scoped to members of the project that owns the deployment.

• Authentication: Every request to the logs API must include a valid Bearer token (Authorization: Bearer YOUR_TOKEN). Unauthenticated requests are rejected with 401 Unauthorized.
• Project-scoped authorization: A user or API token can only read logs for deployments that belong to a project they are a member of. Attempting to access logs for a deployment in a project you are not a member of returns 403 Forbidden, regardless of whether the deployment is active or historical.
• API token requirements: When using the CLI or API directly, use a project-scoped API token. You can mint one via bunx @temps-sdk/cli api-key create --project my-project or from the project settings page in the dashboard.
• Audit log coverage: Reads of deployment logs (including historical ones) are recorded in the Audit Logs so administrators can trace who accessed which deployment logs and when.

Downloading logs

Download logs for offline analysis or archival:

Via Dashboard

1. Open the Logs tab
2. Apply any filters you need
3. Click Download button
4. Choose format (text or JSON)
5. Save to your computer

Via API

# Download container logs
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://your-temps-instance.com/api/projects/{project_id}/environments/{environment_id}/containers/{container_id}/logs/download" \
  -o logs.txt

# Download deployment logs
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://your-temps-instance.com/api/projects/{project_id}/deployments/{deployment_id}/logs/download" \
  -o deployment-logs.txt

Troubleshooting with logs

Application crashes

Symptoms: Container restarts, 502 errors.

What to check:

• Look for error logs immediately before the restart
• Check for out-of-memory errors
• Review exception stack traces
• Check for unhandled promise rejections (Node.js)

ERROR: Unhandled exception
TypeError: Cannot read property 'id' of undefined
    at /app/src/routes/users.js:45:12

Slow performance

Symptoms: High response times, timeouts.

What to check:

• Search for slow or timeout in logs
• Look for database query logs with high durations
• Check for external API call delays
• Review request processing times

WARN: Database query took 5.2s
INFO: External API call completed in 3.1s

Deployment failures

Symptoms: Deployments failing to complete.

What to check:

• Review build logs for compilation errors
• Check for missing dependencies
• Look for configuration errors
• Review deployment step logs

ERROR: Build failed
npm ERR! code ELIFECYCLE
npm ERR! errno 1
npm ERR! build: `next build`

Connection issues

Symptoms: Database or external service connection errors.

What to check:

• Search for connection or connect errors
• Look for timeout messages
• Check for authentication failures
• Review network-related errors

ERROR: Failed to connect to database
Error: connect ECONNREFUSED 127.0.0.1:5432

For automatic error capture with stack traces and grouped error history, see error tracking. To correlate logs with CPU, memory, and uptime metrics, see monitoring.