Skip to content

Latest commit

 

History

History
395 lines (318 loc) · 15.5 KB

2.0.0.md

File metadata and controls

395 lines (318 loc) · 15.5 KB
Raw

API Log Format (ALF) v2.0.0 (Proposed)

Data Structure

Log messages are REQUIRED to be sent in UTF-8 encoding, other encodings are forbidden.

Summary of HAR object types:

/ (root)

This object represents the root of exported data.

{
  "version" : "2.0.0",
  "creator" : {},
  "service" : {},
  "entries": []
}
name type required default description
version String ✔️ 2.0.0 Version number of the format
creator Object ✔️ N/A Name and version info of the log creator application
service Object ✖️ N/A Service data (e.g. Galileo)
entries Array ✔️ N/A List of all exported (tracked) requests

service

"service": {
  "token": "<service token>",
  "environment": "<environment name>"
}
name type required description
token String ✔️ Service Token (e.g. Galileo Analytics)
environment String ✖️ server environment name

creator

"creator": {
  "name": "galileo-agent-node",
  "version": "1.0.0"
}
name type required default description
name String ✔️ N/A Name of the application used to export the log
version String ✔️ N/A Version of the application used to export the log

entries

This object represents an array with all exported HTTP requests.

"entries": [
  {
    "startedDateTime": "2016-03-13T03:47:16.937Z",
    "serverIPAddress": "10.10.10.10",
    "clientIPAddress": "10.10.10.20",
    "time": 82,
    "request": {},
    "response": {},
    "timings": {}
  }
]
name type required default description
startedDateTime String ✔️ N/A Date and time stamp of the request start (ISO 8601)
serverIPAddress String ✖️ N/A IP address of the server that was connected (result of DNS resolution)
clientIPAddress String ✖️ N/A IP address of the client originating the request
time Number ✔️ 0 Total elapsed time of the request in milliseconds.
request Object ✔️ N/A Detailed info about the request
response Object ✔️ N/A Detailed info about the response
timings Object ✔️ N/A Detailed timing info about request/response round trip

time: is the sum of all timings available in the timings object

request

This object contains detailed info about performed request.

"request": {
  "httpVersion": "HTTP/1.1",
  "method": "POST",
  "url": "https://mockbin.org/request",
  "headersSize": 62,
  "bodyCaptured": true,
  "bodySize": 25,
  "queryString" : [],
  "headers": [],
  "content" : {}
}
name type required default description
httpVersion String ✖️ N/A Request HTTP Version
method String ✔️ N/A Request method
url String ✔️ N/A Absolute URL of the request (query & fragments are not included)
headersSize Number ✔️ 0 Total number of bytes from the start of the HTTP request message until (and including) the double CRLF before the body
bodyCaptured Boolean ✔️ false Indicates whether the request body info was captured
bodySize Number ✔️ 0 Size of the request body in bytes (e.g. POST payload)
queryString Array ✖ N/A List of query parameter objects
headers Array ✔️ N/A List of header objects
content Object ✖️ N/A Details about the request body
  • bodyCaptured indicates whether the bodySize zero value is due to an empty body, or a failure to capture body info by the logging agent
  • The total request size sent can be computed as follows (if both values are available):
let totalSize = entry.request.headersSize + entry.request.bodySize

response

This object contains detailed info about the response.

"response": {
  "httpVersion": "HTTP/1.1",
  "status": 200,
  "statusText": "OK",
  "headersSize": 87,
  "bodyCaptured": true,
  "bodySize": 25,
  "headers": [],
  "content": {}
}
name type required default description
httpVersion String ✖️ N/A Response HTTP Version
status Number ✔️ N/A Response status
statusText String ✔️ N/A Response status description
headersSize Number ✔️ 0 Total number of bytes from the start of the HTTP response message until (and including) the double CRLF before the body
bodyCaptured Boolean ✔️ false Indicates whether the request body info was captured
bodySize Number ✔️ 0 Size of the received response body in bytes. Set to 0 in case of responses coming from the cache (e.g. 304)
headers Array ✔️ N/A List of header objects
content Object ✖️ N/A Details about the response body
  • bodyCaptured indicates whether the bodySize zero value is due to an empty body, or a failure to capture body info by the logging agent
  • The total response size received can be computed as follows (if both values are available):
let totalSize = entry.response.headersSize + entry.response.bodySize

headers

This object contains list of all headers (used in request and response objects).

"headers": [
  { "name": "accept", "value": "*/*" },
  { "name": "content-length", "value": "25" },
  { "name": "content-type", "value": "application/json" }
]
name type required default description
name String ✔️ N/A The name of the header
value String ✔️ N/A The header value

queryString

This object contains list of all parameters & values parsed from a query string, if any (embedded in request object).

"queryString": [
  { "name": "foo", "value": "bar" },
  { "name": "baz", "value": "hey" }
]
name type required default description
name String ✔️ N/A The name of the query
value String ✔️ N/A The query value

content

This object describes details about message body (embedded in request and response objects).

"content": {
  "text": "W2JpbmFyeSBkYXRhXQ==",
  "encoding": "base64"
}
name type required default description
text String ✔️️ N/A Response body sent from the server.
encoding String ✔️ plain Encoding used for response text field e.g "base64"
  • encoding field is useful for including binary responses (e.g. images).
  • The text field is populated with textual content only
  • The text field is either HTTP decoded text or a encoded (e.g. "base64") representation of the message body
  • Leave out the entire content object if the message body was not captured, or sent.
Example

original

<html><head></head><body/></html>\n

encoded

"content": {
  "text": "PGh0bWw+PGhlYWQ+PC9oZWFkPjxib2R5Lz48L2h0bWw+XG4=",
  "encoding": "base64"
}

timings

This object describes various phases within request-response round trip.

"timings": {
  "send": 0.06,
  "wait": 87.26,
  "receive": 0.24
}
name type required default description
send Number ✔️ N/A Time required to send HTTP request to the server
wait Number ✔️ N/A Waiting for a response from the server
receive Number ✔️ N/A Time required to read entire response from the server
  • All times are specified in milliseconds.
  • The time value for the request must be equal to the sum of the timings supplied in this section.

Custom Fields

The specification DOES NOT allow adding custom or additional fields.

Versioning Scheme

The spec follows Semantic Versioning

Given a version number: MAJOR.MINOR.PATCH, the:

  • MAJOR version increment indicates incompatible API changes
  • MINOR version increment indicates added functionality in a backwards-compatible manner
  • PATCH version increment indicates backwards-compatible bug fixes.

What's New

Summary of changes from v1.1.0:

Relocated
Renamed
New
Removed
  • har
  • har.log
  • request.postData.mimeType
  • response.content.mimeType
  • timings.blocked
  • timings.connect

Full Example

{
  "version": "2.0.0",
  "creator": {
    "name": "galileo-agent-node",
    "version": "1.0.0"
  },
  "service": {
    "token": "<my service token>",
    "environment": "PRODUCTION"
  },
  "entries": [
    {
      "startedDateTime": "2016-03-13T03:47:16.937Z",
      "serverIPAddress": "10.10.10.10",
      "clientIPAddress": "10.10.10.20",
      "time": 82,
      "request": {
        "method": "POST",
        "url": "https://mockbin.org/request",
        "httpVersion": "HTTP/1.1",
        "queryString": [
          { "name": "foo", "value": "bar" },
          { "name": "baz", "value": "hey" }
        ],
        "headers": [
          { "name": "accept", "value": "*/*" },
          { "name": "content-length", "value": "25" },
          { "name": "content-type", "value": "application/json" }
        ],
        "headersSize": 62,
        "bodyCaptured": true,
        "bodySize": 25,
        "content": {
          "text": "{\"foo\":\"bar\",\"baz\":\"hey\"}",
          "encoding": "plain"
        }
      },
      "response": {
        "status": 200,
        "statusText": "OK",
        "httpVersion": "HTTP/1.1",
        "headers": [
          { "name": "content-length", "value": "25" },
          { "name": "content-type",   "value": "application/json; charset=utf-8" },
          { "name": "x-powered-by",   "value": "mockbin" }
        ],
        "content": {
          "text": "eyJmb28iOiJiYXIiLCJiYXoiOiJoZXkifQ==",
          "encoding": "base64"
        },
        "headersSize": 87,
        "bodyCaptured": true,
        "bodySize": 25
      },
      "timings": {
        "send": 0.06,
        "wait": 87.26,
        "receive": 0.24
      }
    }
  ]
}