LogExcerpt

From Ocean Framework Documentation Wiki
Jump to: navigation, search

The LogExcerpt resource has two public URLs. (For information about the difference between Public and Internal URLs and HATEOAS conventions, please see API Structure and Conventions.)

/v1/log_excerpts/<from>/<to>

The from and to parts of the URL are the start and end UTC time of the log excerpt, respectively, both expressed as integer milliseconds since the beginning of the Unix epoch.

Note that the interval is open: any entries with their timestamp equal to from will not be included in the results. Thus, the notation of the interval is

(from, to].
  • To convert a standard Unix epoch time in UTC to a millisecond timestamp, convert the timestamp to a float, multiply by 1000 and use the integer part of the result.
  • To convert a millisecond timestamp to a standard Unix epoch time in UTC, convert the timestamp to a float, divide by 1000 and use the integer part of the result to format a string in your local timezone. Append the fractional part to indicate the millisecond count.
 1364317959974 / 1000.0 = 1364317959.974
 1364317959 as Unix UTC timestamp: "2013-03-26T17:12:39Z"

The second URL form is

/v1/log_excerpts

It is used create single log lines using HTTP POST requests. Normally log data is transmitted and stored using ZeroMQ as a transport; in some cases, though, it's useful to be able to enter log data using discrete calls.

Structure

from
(Integer) the start time in UTC of the log excerpt, expressed in milliseconds since the beginning of the Unix epoch.
to
(Integer) the end time in UTC of the log excerpt, expressed in milliseconds since the beginning of the Unix epoch.
entries
(Array of Objects) a sorted array of strings describing each log entry. Log entries may be multi-line. Each string can be parsed as JSON. Log entries come in two varieties, both of which always have the following keys:

Common Log Attributes

  • timestamp - the time in UTC expressed in milliseconds since the beginning of the Unix epoch (Integer)
  • ip - the IP number of the machine. (String)
  • pid - the local process id. (Integer)
  • service - the name of the service. (String)
  • level - the severity of the log message. 0=DEBUG, 1=INFO, 2=WARN, 3=ERROR, 4=FATAL, 5=UNKNOWN. (Integer)

Simple Message Log Entry Attributes

If the following attribute is present, the log entry represents a simple log message:

  • msg - the log message itself. (String)

Request Cycle Log Entry Attributes

If msg isn't present, the log entry represents a full Ocean API request and will contain information on the whole request cycle. In this scenario, the following attributes will always be present:

  • status - the HTTP status code returned. (Integer)
  • method - the HTTP method used (POST, GET, PUT, DELETE). (String)
  • path - the request path (such as /v1/foo_bars?baz=quux). (String)
  • remote_ip - the IP of the consumer client, such as a web browser or another service (String)
  • runtime - the total duration of the request in milliseconds, including db_runtime and view_runtime. (Integer or Float)
  • db_runtime - the number of milliseconds spent on SQL requests. (Integer or Float)
  • view_runtime - the number of milliseconds spent formatting the JSON response. (Integer or Float)
Request Cycle Arguments

If parameter args were detected, the following attribute will be present:

  • params - a hash of parameter names and their values (such as {"foo": "quux", "id": "sudfg7634gsidhjf"}). (Object)

 

Request ApiUser and Token

If Ocean authorisation has taken place, the following attributes will be present:

  • token - the authentication token used. (String)
  • username - the username of the ApiUser authenticated by the token. (String)
  • cache_control - the value of the Cache-Control header in the response. (String)

If the HTTP header X-Metadata was present in the request, the following attribute will be present:

  • metadata - the first 128 characters of the X-Metadata header. (String)

 

Request Cycle Error Log Entry Attributes

If one or more API errors occurred (also implying that the response body will contain an _api_errors hash), the following attribute will be present:

  • _api_error - an array of API error messages (such as ["X-API-Token is missing"]). (Array)

 

If the request was halted by a Rails filter, e.g. for authentication or authorisation, the following attribute will be present:

  • filter - the halting filter (such as :x-api-token-required). (String)

 

In the case of a server side exception, the following two attributes will be present:

  • exception_message - the exception message. (String)
  • exception_backtrace - the backtrace. (Array)

 

{
 "log_excerpt": {
          "_links": {
            "self": {
              "href": "https://api.travelservices.se/v1/log_excerpts/1364133370061/1364133653493",
              "type": "application/json" },
          "from": 1364133370061,
          "to": 1364133653493,
          "entries": [
             "{\"timestamp\": 1364133380023, \"ip\": \"10.1.254.33\", \"pid\": 2345, \"level\": 1, \"msg\": \"Blah blah blah...\"}",
             "{\"timestamp\": 1364133380197, \"ip\": \"10.1.254.33\", \"pid\": 2712, \"level\": 1, \"msg\": \"Foo bar baz...\"}",
             "{\"timestamp\": 1364133380197, \"ip\": \"10.1.254.39\", \"pid\": 1980, \"level\": 4, \"msg\": \"Boom crash pow sock...\"}"
          ]
  }
}

Hyperlinks

The following hyperlink names are used in the following subsections. To retrieve the URL and Content-Type to use, use the _links hash. Note that the URI may change, and thus you should make no inference on how to construct similar URIs from any previous URI. For more information, refer to Hyperlink URIs are Opaque. You may store hyperlink URIs in permanent storage for later use.

The hyperlinks for a LogExcerpt resource are:

self
as always, the self hyperlink can be used to perform CRUD actions on the LogExcerpt resource.


GET self

Retrieves a LogExcerpt resource.

Long polling is available and is automatically activated if the following three conditions are all true:

  1. the log is empty of entries in the indicated interval /v1/log_excerpts/<from>/<to>,
  2. the query arg long_polling is present and true, /v1/log_excerpts/<from>/<to>?long_polling=true and
  3. the to time is in the future.

If this is the case, the request waits until new log data appears, only then sending the response. The operation may time out, in which case it should simply be retried. Long polling is sometimes called Comet programming and is a replacement for push technology, e.g. when interfacing to web browser clients. It is the preferred way to go over client-side polling, as it saves bandwidth and reduces server load. It is also the fastest way of pushing data to the web browser client.

Since the interval is open (i.e. you only get entries with a timestamp larger than from), you can simply use the timestamp of the latest known entry as the from argument in a long-polling request.

LogExcerpt resources are aggressively cached. Also, web browsers are allowed to cache log excerpts locally, which means re-issuing a GET of a LogExcerpt is a very cheap operation.

200
The operation was successful.


DELETE self

Deletes all log lines in the indicated range. There is no need to GET the resource first.

204
The delete operation was successful.


POST /v1/log_excerpts

Creates a new message entry in the log.

  • Required attributes (see the section on Structure above):
    • timestamp (Integer)
    • ip (String)
    • pid (Integer)
    • service (String)
    • level (Integer)
    • msg (String)
  • Extra attributes will also be included in the log entry.
204
The log entry was created successfully.