Linking to logs

Introduction

Add a “Show logs” link to your own internal dashboard, without any API integration. Jump straight from your dashboard to the related logs.

Here’s how to generate a dynamic “Show related logs” link anywhere you have a user ID, string, UUID, timestamp, request ID, email address, or system name that an engineer may want to investigate further.

Example

Imagine you’re sending logs from a Web app to Papertrail, and they include an IP address. Your app’s admin dashboard probably tracks the IP that a user most recently logged in from. Have your admin dashboard dynamically generate a “See user’s history” link (to all request logs containing that IP), or links to see logs from specific sessions or events by timestamp.

Generate a link like this:

https://papertrailapp.com/events?q=1.2.3.4&time=1318901406

Setup

Decide whether you want to link to all events, only events from a specific group or log sender, or events matching an existing saved search. To link to all events, link to:

https://papertrailapp.com/events

To link to a specific group or system, navigate to events from that group or system in Papertrail. The URL in your browser is the URL to link to. These typically follow the format:

https://papertrailapp.com/groups/<group number>/events

or:

https://papertrailapp.com/systems/<system name>/events

The trailing /events is optional but avoids an unnecessary redirect. To link to multiple systems/senders which do not exist as a group, use the source search attribute. For example, to search for "Fatal error" within all senders containing the string acme-web, use:

https://papertrailapp.com/events?q=source:acme-web+"Fatal error"

To link to a saved search, use:

https://papertrailapp.com/searches/<search ID>

To obtain a search’s ID, visit the Dashboard and look at the URL (in the link to this search). The number after the last slash is the ID.

Heroku add-on users

Using Papertrail’s Heroku add-on? Instead of linking to the URL above, link to the addons-sso.heroku.com URL shown on bookmarkable URL.

This will redirect through Heroku’s single sign-on. Papertrail will still honor the original URL query parameters. For example:

https://addons-sso.heroku.com/apps/electrocuting-elephant-83/addons/papertrail?q=abc

Linking to systems

With a few exceptions, links to systems can use their Papertrail display name (as shown in Papertrail’s dashboard). This makes it easy to generate dynamic links from a monitoring service, without needing to first find the system’s Papertrail ID.

Here’s how name-based URLs let us add a related logs link to New Relic without using Papertrail’s API at all.

Include timestamp or search query

After deciding which set of events to link to, optionally add a timestamp in the time query parameter and/or a search query in the q query parameter.

Note: Linking to a saved search essentially provides the search query. For that reason, only the time parameter may be used in links to saved searches; the q parameter is not relevant.

Examples

Here’s an example that searches for 1.2.3.4 (in all logs):

https://papertrailapp.com/events?q=1.2.3.4

Here’s another example, searching for error in logs from the system named bigserver, seeked to 2 hours ago:

https://papertrailapp.com/systems/bigserver/events?q=error&time=2+hours+ago

The time value can be an absolute time in seconds since the epoch (Unix time):

https://papertrailapp.com/systems/bigserver/events?time=1318901406

Absolute timestamps should be in UTC.

You can also refer to a saved search instead of providing the search query as a parameter:

https://papertrailapp.com/searches/42?time=1318901406

See HTTP API to perform search queries directly.