AppEnlight is now Open Source! Read more here...

Reports API Interface

https://api.appenlight.com/api/reports?protocol_version=0.5

All access to the API is secured by https protocol.

All data is expected to be sent via json payloads with the header Content-Type: application/json

All requests are normally authenticated by passing headers:

X-appenlight-api-key: APIKEY - server side requests

X-appenlight-public-api-key: PUBLIC_APIKEY - client side requests(javascript) - you want to use this for CORS support

The key values can be passed as query parameters for all endpoints as public_api_key=YOURPUBKEY. This might be required, especially for JavaScript clients.

So all requests like:

https://api.appenlight.com/api/reports?protocol_version=0.5&public_api_key=XXXX

will work too.

Anatomy of request to reporting API:

[{
"client": "your-client-name-python",
"language": "python",
"view_name": "views/foo:bar",
"server": "SERVERNAME/INSTANCENAME",
"priority": 5,
"error": "OMG ValueError happened",
"occurences":1,
"http_status": 500,
"tags": [["tag1","value"], ["tag2", 5]],
"username": "USER",
"url": "HTTP://SOMEURL",
"ip": "127.0.0.1",
"start_time": "2013-12-05T21:46:38.955371",
"end_time": "2013-12-05T21:47:00.577239",
"user_agent": "BROWSER_AGENT",
"extra": [["message","CUSTOM MESSAGE"], ["custom_value", "some payload"]],
"request_id": "SOME_UUID",
"request": {"REQUEST_METHOD": "GET",
         "PATH_INFO": "/FOO/BAR",
         "POST": {"FOO":"BAZ","XXX":"YYY"}
         },
"slow_calls":[{
               "start": "2011-09-25T21:46:38.974148",
               "end": "2011-09-25T21:46:39.123188",
               "type": "sql",
               "subtype": "postgresql",
               "parameters": ["QPARAM1","QPARAM2","QPARAMX"],
               "statement": "QUERY"
               }],
"request_stats": {
                "main": 0.50779,
                "nosql": 0.01008,
                "nosql_calls": 17.0,
                "remote": 0.0,
                "remote_calls": 0.0,
                "sql": 0.42423,
                "sql_calls": 1.0,
                "tmpl": 0.0,
                "tmpl_calls": 0.0,
                "custom": 0.0,
                "custom_calls": 0.0
            },
"traceback": [
            {"cline": "return foo_bar_baz(1,2,3)",
            "file": "somedir/somefile.py",
            "fn": "somefunction",
            "module": "somemodule",
            "line": 454,
            "vars": [["a_list",
                     ["1",2,"4","5",6]],
                     ["b", {"1": "2", "ccc": "ddd", "1": "a"}],
                     ["obj", "<object object at 0x7f0030853dc0>"]]
                     },
            {"cline": "OMG ValueError happened",
            "file": "",
            "fn": "",
            "module": "",
            "line": "",
            "vars": []}
            ]
}]

A request to API is basically a list of reports.

A report is a dictionary (array) of values; some of the values that you can send can be data structures like dictionaries/lists.

At minimum, an error report request must contain:

  • A list with at least one report
  • A single report needs to contain at least one url or view_name keys

Possible keys of a report group object

Parameter Description
client optional

Contains information about what kind of client accessed the API

Example values: "some-custom-client-name"

language optional

Language that the report is generated for - can impact indexing/UI looks

Example values: python, php, javascript

view_name optional saved up to 128 chars

Specifies the view/code block executed for transaction/web request - used by default in grouping

Example values: views/foo:bar

server optional saved up to 128 chars

Specifies the name of the machine or instance that the application is running on - can be used in grouping

Example values: somemachine.network

priority optional

Base priority level for the report - default value: 5

Example values: 3

error optional saved up to 512 chars

Contains the error/exception text for the report, if not present the reports are being classified as slowness reports instead exception reports

Example values: TypeError: foo happened

occurences optional

Base counter of occurences for the report - default value: 1

Example values: 128

http_status optional

Request HTTP status for the report - default value: 200

Example values: 500

username optional saved up to 255 chars

Contains an identifier of the user that the request failed for

Example values: ergo, 5

url optional saved up to 1024 chars

Contains the full request url including get params

Example values: http://127.0.0.1/foo/bar?baz=5

ip optional saved up to 39 chars

Contains the IP address of the client that executed the request

Example values: 192.168.0.1, 2001:0db8:0000:0000:0000:0000:1428:57ab

start_time optional

Contains the starting time of the request in UTC - will be used to calculate request duration, default: current UTC time of report arrival

Example values: 2013-12-05T21:46:38.955371

end_time optional

Contains the finish time of the request in UTC - will be used to calculate request duration

Example values: 2013-12-05T21:46:39.351371

user_agent optional saved up to 512 chars

Contains the user agent of client that initiated the request

Example values: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/35.0.1916.47 Safari/537.36

message optional saved up to 2048 chars

Contains a custom message attached to report

Example values: I'm attached to this report

group_string optional

All reports sent with the same group string will be grouped together

Example values: 86982b00-5fbb-11e4-a252-0002a5d5c51b

request_id optional saved up to 40 chars

Contains UUID identifier of this report, can be used to corellate log entries with reports - default: generated UUID

Example values: 86982b00-5fbb-11e4-a252-0002a5d5c51b

request optional

Contains a dictionary object that holds keys and values for HTTP and CGI vars of report's request

Example values:

{"REQUEST_METHOD": "GET",
 "PATH_INFO": "/FOO/BAR",
 "POST": {"FOO":"BAZ","XXX":"YYY"}
}

slow_calls optional

Contains a list of dictionaries describing slow calls for this request

Example values:

[
{"start": "2011-09-25T21:46:38.974148",
 "end": "2011-09-25T21:46:39.123188",
 "type": "sql",
 "subtype": "postgresql",
 "parameters": ["QPARAM1","QPARAM2","QPARAMX"],
 "statement": "QUERY"}
]
}

request_stats optional

Contains a dictionary holding current request statistics, where "main" is the total time of the whole request

Example values:

{"main": 0.50779,     # total request time
"nosql": 0.01008,     # time spent executing noSQL datastore calls
"nosql_calls": 17.0,  # number of sql calls
"remote": 0.0,
"remote_calls": 0.0,
"sql": 0.42423,
"sql_calls": 1.0,
"tmpl": 0.0,
"tmpl_calls": 0.0,
"custom": 0.0,
"custom_calls": 0.0}

extra optional

Contains a list of key/value pairs that are used to annotate reports with extra information

Example values:

[["message","CUSTOM MESSAGE"], ["custom_value", "some payload"]]

tags optional

Contains a list of key/value pairs that are used to tag requests for later searching

Example values:

[["tag1","value"], ["tag2", 5]]

traceback optional

Contains a list of dictionaries describing lines of the exception traceback, having optionally attached framelocal variables to them

Example values:

[
 {"cline": "return foo_bar_baz(1,2,3)",            # current frame line
  "file": "somedir/somefile.py",                   # file location
  "fn": "somefunction",                            # function name
  "module": "module",                              # module name
  "line": 454,                                     # line number
  "vars": [["a_list",                              # variables present in current frame
           ["1",2,"4","5",6]],
          ["b", {"1": "2", "ccc": "ddd", "1": "a"}],
          ["obj", ""]]},
 {"cline": "OMG ValueError happened",
  "file": "",
  "fn": "",
  "line": "",
  "vars": []}
  ]