Accessing Application Logs as an Add-on Partner
Last updated 17 September 2020
Table of Contents
Add-on Partners can access an app’s log data once a customer installs your add-on on their app. If you’re building an add-on that requires this access, you can create a log drain on behalf of the app and receive the log data.
Log drains allow your add-on to read application logs. If you’d like to write to them, see this documentation.
To set it up, you first need to request it through the manifest.
Add-on manifest
The manifest will need to tell Heroku that your add-on requires permission to set up the log drain. This is done by adding syslog_drain to the list if permissions in the requires property:
{
"id": "myaddon",
"api": {
"requires": ["syslog_drain"]
//...
}
}
Despite the name (syslog_drain), drains are not 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 is provisioned, Heroku’s systems will generate a unique log drain token for that attachment. Add-on Partners should 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 drain urls can not be copy/pasted and used in a manual context. That restriction in turn allows you to use the platform api to update a drain in the future, and know that all valid instances of the url have been updated.
The provisioning call will contain the log drain token. The content of our POST to the /heroku/resources endpoint is described here. When the syslog_drain feature is enabled, the log_drain_token field will be added to the provision payload:
{
// ...
"log_drain_token": "d.01234567-89ab-cdef-0123-456789abcdef"
}
and the response would be:
{
"id": 456,
"config": { ... },
"log_drain_url": "https://example.com/",
"message": "your message here"
}
Heroku will then start 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.
IP Allowlist API
Finally, allow inbound traffic from Heroku’s Logplex IPs. Retrieve the list by sending an unauthenticated HTTP GET request to https://api.heroku.com/vendor/logplex/allowlist.
The call returns a JSON array of IP addresses, similar to:
[
"184.73.5.216",
"50.16.41.187",
"50.19.0.98",
"50.19.146.67",
"184.72.174.202",
"50.16.56.45",
"50.16.160.94",
"50.17.56.172",
//...
]
Since this list will change periodically, we recommend updating it once every hour.
When an app provisions an add-on successfully, the user will be able to see the drain created on behalf of the add-on in the log drain list.
$ heroku drains
https://two.example.org
-----------------------------
[Dummy Addon]