Documentation
¶
Overview ¶
Package papertrail provides an API client for Papertrail (https://papertrailapp.com), a hosted log management service.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrNoTokenFound = errors.New("no Papertrail API token found in PAPERTRAIL_API_TOKEN or ~/.papertrail.yml")
Functions ¶
func CheckResponse ¶
CheckResponse checks the API response for errors, and returns them if present. A response is considered an error if it has a status code outside the 200 range. API error responses are expected to have either no response body, or a JSON response body that maps to ErrorResponse. Any other response body will be silently ignored.
func ReadToken ¶
ReadToken attempts to read the Papertrail API token from 2 sources, the PAPERTRAIL_API_TOKEN environment variable and the ~/.papertrail.yml file, in that order. It returns the token if found in either source, and otherwise returns ErrNoTokenFound. If an unexpected error occurs (e.g., while reading the config file), it returns that error.
Types ¶
type Client ¶
type Client struct {
// BaseURL is the base URL for all HTTP requests; by default,
// "https://papertrailapp.com/api/v1/".
BaseURL *url.URL
// UserAgent is the HTTP User-Agent to send with all requests.
UserAgent string
// contains filtered or unexported fields
}
A Client communicates with the Papertrail HTTP API.
func NewClient ¶
NewClient creates a new client for communicating with the Papertrail HTTP API.
Authentication is required to access the Papertrail API. To create a client whose requests are authenticated, use TokenTransport. For example:
t := &TokenTransport{Token: "my-token"} // obtain token from https://papertrailapp.com/user/edit
c := NewClient(t.Client())
// ...
func (*Client) Do ¶
Do sends an API request and returns the API response. The API response is decoded and stored in the value pointed to by v, or returned as an error if an API error has occurred.
func (*Client) NewRequest ¶
func (c *Client) NewRequest(method, urlPath string, opt interface{}, body interface{}) (*http.Request, error)
NewRequest creates an API request. A relative URL can be provided in urlStr, in which case it is resolved relative to the BaseURL of the Client. Relative URL paths should always be specified without a preceding slash. If opt is specified, its encoding (using go-querystring) is used as the request URL's querystring. If body is specified, the value pointed to by body is JSON encoded and included as the request body.
func (*Client) Search ¶
func (c *Client) Search(opt SearchOptions) (*SearchResponse, *http.Response, error)
Search returns log events that match the parameters specified in opt.
type ErrorResponse ¶
type ErrorResponse struct {
Response *http.Response `json:",omitempty"` // HTTP response that caused this error
Message string // error message
}
An ErrorResponse reports errors caused by an API request.
func (*ErrorResponse) Error ¶
func (r *ErrorResponse) Error() string
func (*ErrorResponse) HTTPStatusCode ¶
func (r *ErrorResponse) HTTPStatusCode() int
type Event ¶
type Event struct {
// ID is the unique Papertrail message ID (a 64-bit integer in base-10
// string format).
ID string `json:"id"`
// ReceivedAt is when Papertrail received the log entry (in ISO 8601
// timestamp format in the original JSON).
ReceivedAt time.Time `json:"received_at"`
// DisplayReceivedAt is a human-readable string of ReceivedAt in the
// timezone of the API token owner.
DisplayReceivedAt string `json:"display_received_at"`
// SourceName is the sender name.
SourceName string `json:"source_name"`
// SourceID is the unique Papertrail sender ID.
SourceID int `json:"source_id"`
// SourceIP is the IP address that originated this log entry.
SourceIP string `json:"source_ip"`
// Facility is the syslog facility.
Facility string `json:"facility"`
// Severity is the syslog severity.
Severity string `json:"severity"`
// Program is the syslog "tag" or "program" field if set. If not set, it is
// nil (JSON null).
Program *string `json:"program"`
// Message is the log entry's message.
Message string `json:"message"`
}
An Event is a log entry.
type SearchOptions ¶
type SearchOptions struct {
// SystemID filters the results to only those from the specified system.
SystemID string `url:"system_id,omitempty"`
// GroupID filters the results to only those from the specified group.
GroupID string `url:"group_id,omitempty"`
// Query filters the results to only those containing the query string.
Query string `url:"q,omitempty"`
// MaxID specifies that the response should only contain events whose ID is
// less than the specified ID. This is used when viewing older events.
MaxID string `url:"max_id,omitempty"`
// MinID specifies that the response should only contain events whose ID is
// greater than the specified ID.
MinID string `url:"min_id,omitempty"`
// MaxTime specifies that the response should only contain events before
// this time.
MaxTime time.Time `url:"max_time,unix,omitempty"`
// MinTime specifies that the response should only contain events after this
// time.
MinTime time.Time `url:"min_time,unix,omitempty"`
}
SearchOptions specify parameters to the Papertrail search HTTP API endpoint.
type SearchResponse ¶
type SearchResponse struct {
// MinID is the smallest event ID presented.
MinID string `json:"min_id"`
// MaxID is the highest event ID presented.
MaxID string `json:"max_id"`
// ReachedTimeLimit is whether Papertrail's per-request time lmit was
// reached before a full set of events was found.
ReachedTimeLimit bool `json:"reached_time_limit"`
// ReachedBeginning means that the entire searchable duration has been
// examined and no more matching messages are available.
ReachedBeginning bool `json:"reached_beginning"`
// MinTimeAt is the earliest event time presented.
MinTimeAt time.Time `json:"min_time_at"`
// Events holds the log messages in the response.
Events []*Event `json:"events"`
}
A SearchResponse is the response from the Papertrail HTTP API's search endpoint.
type TokenTransport ¶
type TokenTransport struct {
// Token is a valid Papertrail API token (which you can obtain from
// https://papertrailapp.com/user/edit).
Token string
// Transport is the underlying HTTP transport to use when making requests.
// It will default to http.DefaultTransport if nil.
Transport http.RoundTripper
}
TokenTransport authenticates HTTP requests to the Papertrail API by sending an X-Papertrail-Token header with the provided API token (which you can obtain from https://papertrailapp.com/user/edit).
func (*TokenTransport) Client ¶
func (t *TokenTransport) Client() *http.Client
Client returns an *http.Client that makes requests which are authenticated using the TokenTransport.
Source Files