Documentation forPapertrail

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 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:

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

Setup

Choose link URL

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:

Copy
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:

Copy
https://papertrailapp.com/groups/<groupId>/events

or:

Copy
https://papertrailapp.com/systems/<systemName>/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:

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

To link to a saved search, use:

Copy
https://papertrailapp.com/searches/<searchId>

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.

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.

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.

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:

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

Examples

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

Copy
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:

Copy
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):

Copy
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:

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

See HTTP API to perform search queries directly.

The scripts are not supported under any SolarWinds support program or service. The scripts are provided AS IS without warranty of any kind. SolarWinds further disclaims all warranties including, without limitation, any implied warranties of merchantability or of fitness for a particular purpose. The risk arising out of the use or performance of the scripts and documentation stays with you. In no event shall SolarWinds or anyone else involved in the creation, production, or delivery of the scripts be liable for any damages whatsoever (including, without limitation, damages for loss of business profits, business interruption, loss of business information, or other pecuniary loss) arising out of the use of or inability to use the scripts or documentation.