Documentation Table of Contents

8. Logs & Monitoring

Understanding what's happening inside your application is essential for maintaining reliability, diagnosing issues, and making informed decisions about scaling and optimisation. Build provides comprehensive observability tools that give you clear visibility into your application's behaviour without overwhelming you with complexity or requiring you to configure third-party services.

From real-time log streaming to performance metrics and dashboards, you have everything you need to quickly diagnose issues, track trends over time, and ensure your apps are running smoothly—all accessible directly from the Build dashboard. Whether you're investigating a spike in error rates, tracking down a slow endpoint, or simply keeping an eye on traffic patterns, Build's monitoring tools are designed to surface the information you need without unnecessary noise.

8.1 Viewing logs (in the UI)

Each app includes a Logs tab that displays a live stream of your application's output. Logs are streamed in real-time, allowing you to monitor activity as it happens—particularly useful for debugging issues, watching deployments roll out, or verifying that a recent code change is behaving as expected.

The log viewer aggregates output from all of your app's dynos into a single unified stream, so you don't need to connect to individual instances to see what's happening. Timestamps are displayed alongside each log entry, making it straightforward to correlate events across your application.

To help you find what you're looking for quickly, the log viewer includes several filtering options:

• Search filtering – Enter a search term to filter logs to only those entries matching your query. This is useful for isolating logs from a specific request ID, user session, or error message.
• Quick filters – One-click buttons allow you to filter by common HTTP response code categories (2xx, 3xx, 4xx, 5xx), making it easy to isolate successful requests, redirects, client errors, or server errors with a single click.

The log stream displays recent history when you first open the tab, then continues to update in real-time as new entries arrive. If you need to pause the stream to examine a particular entry more closely, you can scroll up in the log viewer—the stream will continue to automatically update and show you the end of the log unless you click Autoscroll, which pauses the scrolling, allowing you to investigate further up in the log history.

8.2 Viewing logs (using the CLI)

While the Build dashboard provides a convenient visual interface for viewing logs, you may prefer to work directly from the command line. The Build CLI offers full access to your application's logs with additional flexibility for scripting, filtering, and integration with other command-line tools.

To view logs using the CLI, use the bld logs command:

$ bld logs -a my-app

This displays the most recent log entries for the specified application. By default, the command outputs a snapshot of recent logs and then exits—useful for quickly checking what's happened without committing to a continuous stream.

Tailing Logs in Real-Time

To stream logs continuously (similar to the dashboard's live view), use the --tail flag:

$ bld logs -a my-app --tail

The stream will continue until you interrupt it with Ctrl+C. This is particularly useful when monitoring a deployment in progress or debugging an issue in real-time.

Filtering by Process Type

If your application defines multiple process types in its Procfile (such as web, worker, or scheduler), you can filter logs to show output from a specific process using the --process flag:

$ bld logs -a my-app -p worker

This is especially helpful when debugging background job issues without the noise of web request logs, or vice versa.

Controlling Output Length

By default, the CLI returns a reasonable number of recent log lines. To retrieve more or fewer lines, use the --count flag:

$ bld logs -a my-app --count=500

This is useful when you need to look further back in history or when piping output to other tools for analysis.

Filtering by Log Source

Build distinguishes between two log sources:

• app – Logs generated by your running application (stdout and stderr from your dynos).
• build – Logs generated during the build process (dependency installation, asset compilation, etc.).

To view only build logs—useful when troubleshooting deployment failures—use the --source flag:

$ bld logs -a my-app --source=build

Combining Flags

Flags can be combined for more targeted output. For example, to tail only the web process logs:

$ bld logs -a my-app --tail --process=web

Or to retrieve the last 100 lines from your worker process:

$ bld logs -a my-app -p worker -c 100

Piping to Other Tools

Because the CLI outputs logs to stdout, you can easily pipe the output to other command-line tools for filtering, searching, or processing:

$ bld logs -a my-app -c 1000 | grep "ERROR"

$ bld logs -a my-app --tail | grep --line-buffered "payments"

Tip: When piping a tailed log stream through grep, use the --line-buffered flag to ensure output appears immediately rather than being buffered.

Command Reference

8.3 Log drains (forwarding to external services)

While Build's built-in log viewer is ideal for real-time debugging and quick investigations, you may already have an established logging workflow using a third-party log aggregation service. If you use a service such as BetterStack, Papertrail, Datadog etc., then you can forward your Build logs directly to that service using a Log Drain.

Log drains create a continuous stream of your application's logs to an external HTTPS endpoint or syslog destination. Once configured, every log entry generated by your app is automatically forwarded to your chosen provider in addition to appearing in Build's log viewer.

There are several reasons you might want to configure a log drain:

• Centralised logging – If you run infrastructure outside of Build, log drains allow you to aggregate logs from all your systems into a single location for unified searching and analysis.
• Custom alerting – Third-party logging services often provide sophisticated alerting capabilities, allowing you to trigger notifications based on error rates, specific log patterns, or anomaly detection.
• Extended retention – Build retains logs for a limited period. If you need to keep logs for compliance, auditing, or historical analysis purposes, forwarding them to an external service ensures they're preserved for as long as you need.
• Advanced analysis – Dedicated logging platforms offer powerful query languages, visualisation tools, and machine learning features that go beyond what's available in Build's built-in viewer.

To configure a log drain, navigate to your app and then click the Settings tab, on this page locate the Log Drains section.  Click the Log Drain icon on the top right of the page to create a new Log Drain:

You'll need to provide the destination URL for the Endpoint field and a Token. Consult your logging provider’s documentation for more information about how to get these values from those services. Once you have them and have entered and saved this form, Build will begin forwarding logs immediately. You can configure multiple log drains if you need to send logs to more than one destination.

8.4 Metrics and dashboards

Beyond logs, Build provides a Metrics tab for each app that offers at-a-glance insight into your application's health and performance. While logs tell you what happened, metrics help you understand patterns and trends over time—making them invaluable for capacity planning, performance optimization, and identifying issues before they become critical.

Use the time range selector in the top-right corner of the metrics dashboard to toggle between three views:

• 2 hours – Ideal for investigating recent incidents or monitoring the immediate impact of a deployment.
• 2 days – Useful for spotting daily traffic patterns and comparing current performance against yesterday.
• 7 days – Provides a broader view for identifying weekly trends, gradual performance degradation, or longer-term growth patterns.

The metrics dashboard is organised into three graphs, each providing a different perspective on your application's behaviour:

Requests

The requests graph displays incoming request volume over time, broken down by HTTP status code category. This visualisation makes it easy to spot anomalies—such as a sudden spike in 4xx client errors that might indicate a broken link or API integration issue, or an increase in 5xx server errors that could signal a bug or resource constraint.

This graph also highlights dyno restarts, displayed as markers on the timeline. Correlating restart events with changes in traffic patterns or error rates can be invaluable when diagnosing stability issues. For example, if you notice a pattern of restarts coinciding with traffic spikes, it may indicate that your dynos are running out of memory under load.

Another useful feature is that “interactive sessions” events are also displayed on the timeline, this could be useful to identify if somebody connected up to the app using the Build CLI tool and performed an operation that implicated performance. Note that a full screen recording of these interactive sessions is available from the Overview tab of an app, look for the View ephemeral log option in the Latest Activity box.

Performance

The performance graph tracks response time metrics, giving you visibility into how quickly your application is serving requests. Rather than showing a simple average—which can mask problems affecting a subset of users—Build displays percentile-based metrics:

• p50 (median) – The response time that 50% of requests complete within. This represents the typical experience for most users.
• p95 – The response time that 95% of requests complete within. This helps you understand the experience for users on the slower end of the spectrum.
• p99 – The response time that 99% of requests complete within. Useful for identifying outliers and worst-case scenarios.
• Max – The slowest response time recorded in each time period. While often noisy, dramatic spikes in max response time can indicate specific problematic requests worth investigating.

When analysing performance data, pay particular attention to the gap between p50 and p99. A large gap suggests inconsistent performance—some requests are completing quickly while others are significantly slower. This pattern often points to issues such as database queries that are fast in some cases but slow in others, external API calls with variable latency, or resource contention under certain conditions.

Bandwidth

The bandwidth graph tracks data transfer rates over time, displaying both:

• TX (transmitted) – Data sent from your application to clients. High TX values typically correlate with serving large responses, file downloads, or media content.
• RX (received) – Data received by your application from clients. Spikes in RX often correspond to file uploads or requests with large payloads.

Monitoring bandwidth helps you understand your application's data transfer patterns and can be useful for identifying unexpected changes—such as a sudden increase in outbound traffic that might indicate an inefficient API response or a client repeatedly requesting large resources.