Skip to content

Latest commit

 

History

History
755 lines (619 loc) · 35.5 KB

1.0.0.md

File metadata and controls

755 lines (619 loc) · 35.5 KB
Raw

API Log Format (ALF) v1.0.0 (Deprecated)

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",
  "serviceToken": "<service token>",
  "environment": "<environment name>",
  "clientIPAddress": "<origin address>",
  "har": {},
}
name type required default description
version String ✔️ 2.0.0 Version number of the format
serviceToken String ✔️ N/A Service Token (e.g. Galileo Analytics)
environment String ✖️ N/A server environment name
clientIPAddress String ✖️ N/A IP address of the client originating the request
har Object ✔️ N/A please refer to the Official HAR (HTTP Archive Format) Spec

log

This object represents the root of exported data.

"log": {
  "version" : "1.2",
  "creator" : {},
  "browser" : {},
  "pages": [],
  "entries": [],
  "comment": ""
}
name type required default description
version string ✔️ 1.3 Version number of the format
creator object ✔️ N/A Name and version info of the log creator application
browser object ✖️ N/A Name and version info of used browser
pages array ✖️ N/A List of all exported (tracked) pages
entries array ✔️ N/A List of all exported (tracked) requests
comment string ✖️ N/A A comment provided by the user or the application

There is one page object for every exported web page and one entry object for every HTTP request. In case when an HTTP trace tool isn't able to group requests by a page, the pages array is empty and individual requests doesn't have a parent page.

creator

"creator": {
  "name": "Firebug",
  "version": "1.6",
  "comment": ""
}
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
comment string ✖️ N/A A comment provided by the user or the application

browser

"browser": {
  "name": "Firefox",
  "version": "3.6",
  "comment": ""
}
name type required default description
name string ✔️ N/A Name of the browser used to export the log
version string ✔️ N/A Version of the browser used to export the log
comment string ✖️ N/A A comment provided by the user or the application

pages

This object represents list of exported pages.

"pages": [
  {
    "startedDateTime": "2009-04-16T12:07:25.123+01:00",
    "id": "page_0",
    "title": "Test Page",
    "pageTimings": {},
    "comment": ""
  }
]
name type required default description
startedDateTime string ✔️ N/A Date and time stamp for the beginning of the page load (ISO 8601)
id string ✔️ N/A Unique identifier of a page within the log. Entries use it to refer the parent page
title string ✔️ N/A Page title
pageTimings object ✔️ N/A Detailed timing info about page load
comment string ✖️ N/A A comment provided by the user or the application

pageTimings

This object describes timings for various events (states) fired during the page load. All times are specified in milliseconds. If a time info is not available appropriate field is set to -1

"pageTimings": {
  "onContentLoad": 1720,
  "onLoad": 2500,
  "comment": ""
}
name type required default description
onContentLoad number ✖️ -1 Content of the page loaded. Number of milliseconds since page load started (page.startedDateTime)
onLoad number ✖️ -1 Page is loaded (onLoad event fired). Number of milliseconds since page load started (page.startedDateTime)
comment string ✖️ N/A A comment provided by the user or the application

Depeding on the browser, onContentLoad property represents DOMContentLoad event or document.readyState == interactive.

entries

This object represents an array with all exported HTTP requests. Sorting entries by startedDateTime (starting from the oldest) is preferred way how to export data since it can make importing faster. However the reader application should always make sure the array is sorted (if required for the import).

"entries": [
  {
    "pageref": "page_0",
    "startedDateTime": "2009-04-16T12:07:23.596Z",
    "time": 50,
    "request": {},
    "response": {},
    "cache": {},
    "timings": {},
    "serverIPAddress": "10.0.0.1",
    "connection": "52492",
    "comment": ""
  }
]
name type required default description
pageref string ✖️ N/A Unique Reference to the parent page
startedDateTime string ✔️ N/A Date and time stamp of the request start (ISO 8601)
time number ✔️ 0 Total elapsed time of the request in milliseconds. This is the sum of all timings available in the timings object (i.e. not including -1 values)
request object ✔️ N/A Detailed info about the request
response object ✔️ N/A Detailed info about the response
cache object ✔️ N/A Info about cache usage
timings object ✔️ N/A Detailed timing info about request/response round trip
serverIPAddress string ✖️ N/A IP address of the server that was connected (result of DNS resolution)
connection string ✖️ N/A Unique ID of the parent TCP/IP connection, can be the client or server port number.
comment string ✖️ N/A A comment provided by the user or the application

connection: Note that a port number doesn't have to be unique identifier in cases where the port is shared for more connections. If the port isn't available for the application, any other unique connection ID can be used instead (e.g. connection index)

request

This object contains detailed info about performed request.

"request": {
  "method": "GET",
  "url": "http://www.example.com/path/?param=value",
  "httpVersion": "HTTP/1.1",
  "cookies": [],
  "headers": [],
  "queryString" : [],
  "postData" : {},
  "headersSize" : 150,
  "bodySize" : 0,
  "comment" : ""
}
name type required default description
method string ✔️ N/A Request method
url string ✔️ N/A Absolute URL of the request (fragments are not included)
httpVersion string ✔️ N/A Request HTTP Version
cookies array ✔️ N/A List of cookie objects
headers array ✔️ N/A List of header objects
queryString array ✔️ N/A List of query parameter objects
postData object ✖️ N/A Posted data info
headersSize number ✔️ -1 Total number of bytes from the start of the HTTP request message until (and including) the double CRLF before the body
bodySize number ✔️ -1 Size of the request body in bytes (e.g. POST data payload)
comment string ✖️ N/A A comment provided by the user or the application

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": {
  "status": 200,
  "statusText": "OK",
  "httpVersion": "HTTP/1.1",
  "cookies": [],
  "headers": [],
  "content": {},
  "redirectURL": "",
  "headersSize" : 160,
  "bodySize" : 850,
  "comment" : ""
}
name type required default description
status number ✔️ N/A Response status
statusText string ✔️ N/A Response status description
httpVersion string ✔️ N/A Response HTTP Version
cookies array ✔️ N/A List of cookie objects
headers array ✔️ N/A List of header objects
content object ✔️ N/A Details about the response body
redirectURL string ✔️ N/A Redirection target URL from the Location response header
headersSize number ✔️ -1 Total number of bytes from the start of the HTTP response message until (and including) the double CRLF before the body
bodySize number ✔️ -1 Size of the received response body in bytes. Set to 0 in case of responses coming from the cache (304)
comment string ✖️ N/A A comment provided by the user or the application
  • headersSize: The size of received response-headers is computed only from headers that are really received from the server. Additional headers appended by the browser are not included in this number, but they appear in the list of header objects.
  • The total response size received can be computed as follows (if both values are available):
let totalSize = entry.response.headersSize + entry.response.bodySize

cookies

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

"cookies": [
  {
    "name": "TestCookie",
    "value": "Cookie Value",
    "path": "/",
    "domain": "www.janodvarko.cz",
    "expires": "2009-07-24T19:20:30.123+02:00",
    "httpOnly": false,
    "secure": false,
    "comment": ""
  }
]
name type required default description
name string ✔️ N/A The name of the cookie
value string ✔️ N/A The cookie value
path string ✖️ N/A The path pertaining to the cookie
domain string ✖️ N/A The host of the cookie
expires string ✖️ N/A Cookie expiration time. (ISO 8601)
httpOnly boolean ✖️ N/A Set to true if the cookie is HTTP only, false otherwise
secure boolean ✖️ N/A trueif the cookie was transmitted over ssl,false` otherwise
comment string ✖️ N/A A comment provided by the user or the application

headers

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

"headers": [
  {
    "name": "Accept-Encoding",
    "value": "gzip,deflate",
    "comment": ""
  },
  {
    "name": "Accept-Language",
    "value": "en-us,en;q=0.5",
    "comment": ""
  }
]
name type required default description
name string ✔️ N/A The name of the header
value string ✔️ N/A The header value
comment string ✖️ N/A A comment provided by the user or the application

queryString

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

"queryString": [
  {
    "name": "param1",
    "value": "value1",
    "comment": ""
  },
  {
    "name": "param1",
    "value": "value1",
    "comment": ""
  }
]
name type required default description
name string ✔️ N/A The name of the query
value string ✔️ N/A The query value
comment string ✖️ N/A A comment provided by the user or the application

postData

This object describes posted data, if any (embedded in request object).

"postData": {
  "mimeType": "multipart/form-data",
  "params": [],
  "text" : "plain posted data",
  "comment": ""
}
name type required default description
mimeType string ✔️ N/A Mime type of posted data
params array ✔️ * N/A List of posted parameters (in case of URL encoded parameters)
text string ✔️ * N/A Plain text posted data
comment string ✖️ N/A A comment provided by the user or the application
  • text and params fields are mutually exclusive.

params

List of posted parameters, if any (embedded in postData object).

"params": [
  {
    "name": "paramName",
    "value": "paramValue",
    "fileName": "example.pdf",
    "contentType": "application/pdf",
    "comment": ""
  }
]
name type required default description
name string ✔️ N/A name of a posted parameter
value string ✖️ N/A value of a posted parameter or content of a posted file
fileName string ✖️ N/A name of a posted file
contentType string ✖️ N/A content type of a posted file
comment string ✖️ N/A A comment provided by the user or the application
Example

encoded

"postData": {
  "mimeType": "multipart/form-data",
  "comment": "",
  "params": [
    {
      "name": "image",
      "value": "W2JpbmFyeSBkYXRhXQ==",
      "encoding": "base64",
      "fileName": "example.jpg",
      "contentType": "image/jpeg",
      "comment": ""
    }
  ]
}

content

This object describes details about response content (embedded in response object).

"content": {
  "size": 33,
  "compression": 0,
  "mimeType": "text/html; charset=utf-8",
  "text": "\n",
  "comment": ""
}
name type required default description
size number ✔️ N/A Length of the returned content in bytes. Should be equal to response.bodySize if there is no compression and bigger when the content has been compressed
compression number ✖️ N/A Number of bytes saved
mimeType string ✔️ N/A MIME type of the response text (value of the Content-Type response header). The charset attribute of the MIME type is included (if available)
text string ✖️ N/A Response body sent from the server or loaded from the browser cache.
encoding string ✖️ N/A Encoding used for response text field e.g "base64"
comment string ✖️ N/A A comment provided by the user or the application
  • 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 response body
  • Leave out the encoding field if the text field is HTTP decoded (decompressed & unchunked), than trans-coded from its original character set into UTF-8
  • Before setting the text field, the HTTP response is decoded (decompressed & unchunked), than trans-coded from its original character set into UTF-8.
    • Additionally, it can be encoded using e.g. base64.
    • Ideally, the application should be able to unencode a base64 blob and get a byte-for-byte identical resource to what the browser operated on.
  • encoding field is useful for including binary responses (e.g. images) into the HAR file.
Example

original

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

encoded

"content": {
  "size": 33,
  "compression": 0,
  "mimeType": "text/html; charset=utf-8",
  "text": "PGh0bWw+PGhlYWQ+PC9oZWFkPjxib2R5Lz48L2h0bWw+XG4=",
  "encoding": "base64",
  "comment": ""
}

cache

This objects contains info about a request coming from browser cache.

"cache": {
  "beforeRequest": {},
  "afterRequest": {},
  "comment": ""
}
name type required default description
beforeRequest object ✖️ N/A State of a cache entry before the request
afterRequest object ✖️ N/A State of a cache entry after the request
comment string ✖️ N/A A comment provided by the user or the application
Example 1

No cache information are available (or you can just leave out the entire field).

"cache": {}
Example 2

Info about the cache entry before request is not available and there is no cache entry after the request.

"cache": {
  "afterRequest": null
}
Example 3

No cache entry before nor after the request.

"cache": {
  "beforeRequest": null,
  "afterRequest": null
}
Example 4

Indicate that the entry was not in the cache but was store after the content was downloaded by the request.

"cache": {
  "beforeRequest": null,
  "afterRequest": {
    "expires": "2009-04-16T15:50:36",
    "lastAccess": "2009-16-02T15:50:34",
    "eTag": "",
    "hitCount": 0,
    "comment": ""
  }
}

beforeRequest / afterRequest

"beforeRequest": {
  "expires": "2009-04-16T15:50:36",
  "lastAccess": "2009-16-02T15:50:34",
  "eTag": "",
  "hitCount": 0,
  "comment": ""
}
name type required default description
expires string ✖️ N/A Expiration time of the cache entry
lastAccess string ✔️ N/A The last time the cache entry was opened
eTag string ✔️ N/A Etag
hitCount number ✔️ N/A The number of times the cache entry has been opened
comment string ✖️ N/A A comment provided by the user or the application

timings

This object describes various phases within request-response round trip. All times are specified in milliseconds.

"timings": {
  "blocked": 0,
  "dns": -1,
  "connect": 15,
  "send": 20,
  "wait": 38,
  "receive": 12,
  "ssl": -1,
  "comment": ""
}
name type required default description
blocked number ✖️ -1 Time spent in a queue waiting for a network connection
dns number ✖️ -1 DNS resolution time. The time required to resolve a host name
connect number ✖️ -1 Time required to create TCP connection
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 (or cache)
ssl number ✖️ -1 Time required for SSL/TLS negotiation.
comment string ✖️ N/A A comment provided by the user or the application
  • If the ssl field is defined then the time is also included in the connect field (to ensure backward compatibility with HAR v1.1)
  • The send, wait and receive timings are not optional and must have non-negative values.
  • An exporting tool can omit the blocked, dns, connect and ssl, timings on every request if it is unable to provide them.
  • Tools that can provide these timings can set their values to -1 if they don’t apply. For example, connect would be -1 for requests which re-use an existing connection.
  • The time value for the request must be equal to the sum of the timings supplied in this section (excluding any -1 values).
  • The Following must be true in case there are no -1 values (entry is an object in log.entries) :
entry.time == entry.timings.blocked + entry.timings.dns + entry.timings.connect
              entry.timings.send + entry.timings.wait + entry.timings.receive
Full Example
{
  "version": "1.0.0",
  "serviceToken": "<my service token>",
  "environment": "PRODUCTION",
  "clientIPAddress": "10.10.10.20",
  "har": {
    "log": {
      "version": "1.2",
      "creator": {
        "name": "HAR Logger",
        "version": "1.0.0"
      },
      "entries": [
        {
          "startedDateTime": "2016-03-13T03:47:16.937Z",
          "serverIPAddress": "10.10.10.10",
          "time": 82,
          "request": {
            "method": "POST",
            "url": "https://mockbin.org/request",
            "httpVersion": "HTTP/1.1",
            "queryString": [
              { "name": "foo", "value": "bar" },
              { "name": "baz", "value": "abc" }
            ],
            "headers": [
              { "name": "accept", "value": "*/*" },
              { "name": "content-length", "value": "25" },
              { "name": "content-type", "value": "application/x-www-form-urlencoded" }
            ],
            "cookies": [
              {
                "name": "foo",
                "expires": "2015-02-10T07:33:17.146Z",
                "value": "bar",
                "httpOnly": false,
                "secure": false
              }
            ],
            "headersSize": 62,
            "bodySize": 25,
            "postData": {
              "mimeType": "application/x-www-form-urlencoded",
              "text": "foo=bar&bar=baz",
              "params": [
                { "name": "foo", "value": "bar" },
                { "name": "bar", "value": "baz" }
              ]
            }
          },
          "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" }
            ],
            "cookies": [{
              "name": "TestCookie",
              "value": "Cookie Value",
              "path": "/",
              "domain": "www.janodvarko.cz",
              "expires": "2009-07-24T19:20:30.123+02:00",
              "httpOnly": false,
              "secure": false,
            }],
            "content": {
              "size": 23,
              "mimeType": "application/json",
              "text": "{\"foo\": \"bar\"}",
              "compression": -17
            },
            "redirectURL": "",
            "headersSize": 87,
            "bodySize": 25
          },
          "cache": {
            "beforeRequest": null,
            "afterRequest": {
              "expires": "2009-04-16T15:50:36",
              "lastAccess": "2009-16-02T15:50:34",
              "eTag": "",
              "hitCount": 0,
            }
          },
          "timings": {
            "blocked": -1,
            "dns": -1,
            "connect": -1,
            "send": 0.06,
            "wait": 87.26,
            "receive": 0.24,
            "ssl": -1
          },
          "connection": "3178207"
        }
      ]
    }
  }
}