Forward Upsun and Blackfire logs

You might use a service to analyze logs from various parts of your fleet. You might want to consolidate all your logs in one place that everyone has access to without needing to grant them access to each project individually.

In such cases, forward your logs from Upsun and Blackfire to a third-party service. You can use a service with an integration or any service that supports a syslog endpoint or HTTP endpoint.

Logs to stdout and stderr are forwarded. Logs in files can’t be forwarded.

To enable log forwarding in a project, you need to be a project admin. You also need your project to have the capability for log forwarding. To get a price quote, contact Sales.

Use a log forwarding integration

Certain services have a specific integration for forwarding logs. If your third-party service isn’t supported, you can forward to a syslog endpoint.

Integrated third-party services

Integrations exist for the following third-party services to enable log forwarding:

• New Relic
• Splunk
• Sumo Logic

Enable a log forwarding integration

Using the CLI

To enable log forwarding for a specific project using the Upsun CLI, follow the steps for your selected service.

To start forwarding logs, trigger a redeploy.

In the Console

To enable log forwarding for a specific project from the Console, follow these steps:

1. Navigate to your project.
2. Click Settings.
3. Click Integrations.
4. Click Add Integration.
5. Select the integration you want to enable.
6. In the Configure your integration window, specify your configuration options.
7. Click Add Integration. The new integration overview is displayed, and you can view your logs in the Activity section.

Forward to a syslog endpoint

Syslog is a standard protocol for transferring log messages. Many third-party services offer endpoints for ingesting syslog events. You can forward your Upsun and Blackfire logs to any of those endpoints.

upsun integration:add --type syslog --syslog-host INGESTION_HOST --syslog-port INGESTION_HOST_PORT

Forward to an HTTP endpoint

Some third-party services, such as Elasticsearch and OpenSearch, support ingesting log messages through an HTTP endpoint. You can use HTTP forwarding to forward Upsun and Blackfire logs to such third-party services.

HTTP forwarding makes a POST HTTP request with an application/json body while forwarding the log messages to the endpoint.

As an example, to forward logs to Elasticsearch using HTTP log forwarding, run the following command:

upsun integration:add --type httplog --url "https://ELASTICSEARCH_URL/INDEX_NAME/_doc" --header "Authorization: Basic <basic_auth_token>" --header "Content-Type: application/json"

type and url are the only properties required for all endpoints. Optionally, you can use the headers property to pass additional headers in the HTTP requests.

Note that if your endpoint URL includes a PORT, that can also be included in the --url flag:

upsun integration:add --type httplog --url "https://ELASTICSEARCH_URL:PORT/INDEX_NAME/_doc" --header "Authorization: Basic <basic_auth_token>" --header "Content-Type: application/json"

Once you’ve added the service, to start forwarding logs trigger a redeploy.

Log levels

Your app may output logs with distinct severity levels. But as Plaform.sh only reads logs from stdout, this distinction is lost and everything gets logged at INFO level.

To preserve the original log level, use a language-specific syslog module/package for logging.

The following example code snippets show how logs can be written to Syslog:

openlog("", LOG_PID, LOG_LOCAL0);
syslog(LOG_INFO, "Operation started");
syslog(LOG_ERR, "Operation failed");
closelog();

import logging
import logging.handlers

logger = logging.getLogger(__name__)
logger.setLevel(logging.DEBUG)
handler = logging.handlers.SysLogHandler(address="/dev/log")
logger.addHandler(handler)

logger.info("Operation started")
logger.error("Operation failed")

import syslog

syslog.openlog(logoption=syslog.LOG_PID, facility=syslog.LOG_LOCAL0)
syslog.syslog(syslog.LOG_INFO, "Operation started")
syslog.syslog(syslog.LOG_ERR, "Operation failed")
syslog.closelog()

package main

import (
	"log"
	"log/syslog"
)

func main() {
	logger, err := syslog.NewLogger(syslog.LOG_LOCAL0|syslog.LOG_INFO, log.LstdFlags)
	if err != nil {
		panic(err)
	}

	logger.Println("Operation started...")
	logger.Fatalln("Operation failed")
}

package main

import (
	"fmt"
	"log"
	"log/syslog"
)

func main() {
	syslogWriter, err := syslog.Dial("", "", syslog.LOG_LOCAL0|syslog.LOG_INFO, "")
	if err != nil {
		log.Fatal(err)
	}
	defer syslogWriter.Close()

	fmt.Fprintf(syslogWriter, "Operation has started")
	syslogWriter.Err("Operation failed")
}