Accessing Application Logs as an Add-on Partner
Last updated December 03, 2024
Table of Contents
Add-on Partners can access an app’s log data after a customer installs your add-on on their app. If you’re building an add-on that requires log access, create a log drain on behalf of the app to receive log data.
Log drains allow an add-on to read application logs. To write to the application log, see Add-on Partner Log Integration.
Log drains are currently unavailable in Fir. Add-ons requiring log drains are incompatible with Fir-generation apps.
To set it up application log access, you first need to request it through the manifest.
Add-on Manifest
The manifest must tell Heroku that your add-on requires permission to set up the log drain. Add syslog_drain to the list of permissions in the requires property:
{
"id": "myaddon",
"api": {
"requires": ["syslog_drain"]
//...
}
}
Despite the name (syslog_drain), drains aren’t limited to the syslog:// protocol. In fact, HTTPS drains are preferred. See the user docs on log drains for more details.
Provisioning Call
When the add-on provisions, Heroku’s systems generate a unique log drain token for that attachment. Use this token to identify logs sent to the drain.
Relying on the Heroku-provided drain token instead of a unique field in a url like a port or api key ensures that no one can copy and paste or use drain URLs in a manual context. That restriction lets you to use the Platform API to update a drain in the future, and know that all valid instances of the URL get updated.
The provisioning call contains the log drain token. The content of our POST to the /heroku/resources endpoint is described here. With the syslog_drain feature enabled, the log_drain_token field gets added to the provision payload:
{
// ...
"log_drain_token": "d.01234567-89ab-cdef-0123-456789abcdef"
}
The response is:
{
"id": 456,
"config": { ... },
"log_drain_url": "https://example.com/",
"message": "your message here"
}
Heroku then starts directing app logs to the provided drain URL. We recommend using HTTPS URLs for the log_drain_url. See the user docs on log drains for more details.
When an app provisions an add-on successfully, the user can see the drain created on behalf of the add-on in the log drain list.
$ heroku drains
https://two.example.org
-----------------------------
[Dummy Addon]