You are looking at documentation for an alpha release.
Error API
editError API
editThe APM Server exposes an API Endpoint to send error records. Unless you are implementing an agent, you don’t need to know about the specifics of this API.
To send error records you need to send a HTTP POST request to APM Server errors endpoint.
Information pertaining to the error record must be sent as a JSON object to the endpoint.
Find more information about:
Schema Definition
editThe APM Server uses a JSON Schema for validating the transaction requests. Find details on how the schema is defined:
Payload
edit{
"$schema": "http://json-schema.org/draft-04/schema#",
"$id": "docs/spec/errors/wrapper.json",
"title": "Errors Wrapper",
"description": "List of errors wrapped in an object containing some other attributes normalized away form the errors themselves",
"type": "object",
"properties": {
"app": {
"$ref": "../app.json"
},
"errors": {
"type": "array",
"items": {
"$ref": "error.json"
},
"minItems": 1
},
"system": {
"$ref": "../system.json"
}
},
"required": ["app", "errors"]
}
Error
edit{
"$schema": "http://json-schema.org/draft-04/schema#",
"$id": "docs/spec/errors/error.json",
"type": "object",
"description": "Data captured by an agent representing an event occurring in a monitored app",
"properties": {
"context": {
"$ref": "./../context.json"
},
"culprit": {
"description": "Function call which was the primary perpetrator of this event.",
"type": ["string", "null"]
},
"exception": {
"description": "A standard exception.",
"type": ["object", "null"],
"properties": {
"code": {
"type": ["string", "number", "null"],
"maxLength": 1024
},
"message": {
"description": "The exception's error message.",
"type": "string"
},
"module": {
"description": "Describes the exception type's module namespace.",
"type": ["string", "null"],
"maxLength": 1024
},
"attributes": {
"type": ["object", "null"]
},
"stacktrace": {
"type": ["array", "null"],
"items": {
"$ref": "./../stacktrace_frame.json"
},
"minItems": 0
},
"type": {
"type": ["string", "null"],
"maxLength": 1024
},
"uncaught": {
"type": ["boolean", "null"]
}
},
"required": ["message"]
},
"id": {
"type": ["string", "null"],
"description": "UUID for the error",
"pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
},
"log": {
"type": ["object", "null"],
"properties": {
"level": {
"description": "The record severity.",
"type": ["string", "null"],
"default": "error",
"enum": ["debug", "info", "warning", "error", "fatal"],
"maxLength": 1024
},
"logger_name": {
"description": "The name of the logger which created the record.",
"type": ["string", "null"],
"default": "default",
"maxLength": 1024
},
"message": {
"description": "The exception's error message.",
"type": "string"
},
"param_message": {
"description": "A parametrized message. E.g. Could not connect to %s. The property message is still required, and should be equal to the param_message, but with placeholders replaced. In some situations the param_message is used to group errors together. The string is not interpreted, so feel free to use whichever placeholders makes sense in the client languange.",
"type": ["string", "null"],
"maxLength": 1024
},
"stacktrace": {
"type": ["array", "null"],
"items": {
"$ref": "./../stacktrace_frame.json"
},
"minItems": 0
}
},
"required": ["message"]
},
"timestamp": {
"type": "string",
"format": "date-time",
"pattern": "Z$",
"description": "Recorded time of the error, UTC based and formatted as YYYY-MM-DDTHH:mm:ss.sssZ"
}
},
"required": ["timestamp"],
"anyOf": [
{
"required": ["exception"]
},
{
"required": ["log"]
}
]
}
App
edit{
"$schema": "http://json-schema.org/draft-04/schema#",
"$id": "doc/spec/app.json",
"title": "App",
"type": "object",
"properties": {
"agent": {
"type": "object",
"properties": {
"name": {
"type": "string",
"maxLength": 1024
},
"version": {
"type": "string",
"maxLength": 1024
}
},
"required": ["name", "version"]
},
"argv": {
"type": ["array", "null"],
"minItems": 0
},
"framework": {
"type": ["object", "null"],
"properties": {
"name": {
"type": "string",
"maxLength": 1024
},
"version": {
"type": "string",
"maxLength": 1024
}
},
"required": ["name", "version"]
},
"language": {
"type": ["object", "null"],
"properties": {
"name": {
"type": "string",
"maxLength": 1024
},
"version": {
"type": ["string", "null"],
"maxLength": 1024
}
},
"required": ["name"]
},
"name": {
"description": "Immutable name of the app emitting this event",
"type": "string",
"pattern": "^[a-zA-Z0-9 _-]+$",
"maxLength": 1024
},
"pid": {
"type": ["number", "null"]
},
"process_title": {
"type": ["string", "null"],
"maxLength": 1024
},
"runtime": {
"type": ["object", "null"],
"properties": {
"name": {
"type": "string",
"maxLength": 1024
},
"version": {
"type": "string",
"maxLength": 1024
}
},
"required": ["name", "version"]
},
"version": {
"description": "Version of the app emitting this event",
"type": ["string", "null"],
"maxLength": 1024
}
},
"required": ["agent", "name"]
}
System
edit{
"$schema": "http://json-schema.org/draft-04/schema#",
"$id": "doc/spec/system.json",
"title": "System",
"type": "object",
"properties": {
"architecture": {
"description": "Architecture of the system the agent is running on.",
"type": ["string", "null"],
"maxLength": 1024
},
"hostname": {
"description": "Hostname of the system the agent is running on.",
"type": ["string", "null"],
"maxLength": 1024
},
"platform": {
"description": "Name of the system platform the agent is running on.",
"type": ["string", "null"],
"maxLength": 1024
}
}
}
Context
edit{
"$schema": "http://json-schema.org/draft-04/schema#",
"$id": "doc/spec/context.json",
"title": "Context",
"description": "Any arbitrary contextual information regarding the event, captured by the agent, optionally provided by the user",
"type": ["object", "null"],
"properties": {
"custom": {
"description": "An arbitrary mapping of additional metadata to store with the event.",
"type": ["object", "null"],
"regexProperties": true,
"patternProperties": {
"^[^.*\"]*$": {}
},
"additionalProperties": false
},
"response": {
"type": ["object", "null"],
"properties": {
"finished": {
"type": ["boolean", "null"]
},
"headers": {
"type": ["object", "null"],
"properties": {
"content-type": {
"type": ["string", "null"]
}
}
},
"headers_sent": {
"type": ["boolean", "null"]
},
"status_code": {
"type": ["number", "null"]
}
}
},
"request": {
"$ref": "request.json"
},
"tags": {
"type": ["object", "null"],
"regexProperties": true,
"patternProperties": {
"^[^.*\"]*$": {
"type": "string",
"maxLength": 1024
}
},
"additionalProperties": false
},
"user": {
"$ref": "user.json"
}
}
}
Stacktrace Frame
edit{
"$schema": "http://json-schema.org/draft-04/schema#",
"$id": "docs/spec/stacktrace.json",
"title": "Stacktrace",
"type": "object",
"description": "A stacktrace frame, contains various bits (most optional) describing the context of the frame",
"properties": {
"abs_path": {
"description": "The absolute path of the file involved in the stack frame",
"type": ["string", "null"]
},
"colno": {
"description": "Column number",
"type": ["number", "null"]
},
"context_line": {
"description": "The line of code part of the stack frame",
"type": ["string", "null"]
},
"filename": {
"description": "The relative filename of the code involved in the stack frame, used e.g. to do error checksumming",
"type": "string"
},
"function": {
"description": "The function involved in the stack frame",
"type": ["string", "null"]
},
"in_app": {
"type": ["boolean", "null"]
},
"lineno": {
"description": "The line number of code part of the stack frame, used e.g. to do error checksumming",
"type": "number"
},
"module": {
"description": "The module to which frame belongs to",
"type": ["string", "null"]
},
"post_context": {
"description": "The lines of code after the stack frame",
"type": ["array", "null"],
"minItems": 0
},
"pre_context": {
"description": "The lines of code before the stack frame",
"type": ["array", "null"],
"minItems": 0
},
"vars": {
"description": "Local variables for this stack frame",
"type": ["object", "null"],
"properties": {}
}
},
"required": ["filename", "lineno"]
}
Request
edit{
"$schema": "http://json-schema.org/draft-04/schema#",
"$id": "docs/spec/http.json",
"title": "Request",
"description": "If a log record was generated as a result of a http request, the http interface can be used to collect this information.",
"type": "object",
"properties": {
"body": {
"description": "Data should only contain the request body (not the query string). It can either be a dictionary (for standard HTTP requests) or a raw request body.",
"type": ["object", "string", "null"]
},
"env": {
"description": "The env variable is a compounded of environment information passed from the webserver.",
"type": ["object", "null"],
"properties": {}
},
"headers": {
"description": "Should include any headers sent by the requester. Cookies will be taken by headers if supplied.",
"type": ["object", "null"],
"properties": {
"content-type": {
"type": ["string", "null"]
},
"cookie": {
"description": "Cookies sent with the request. It is expected to have values delimited by semicolons.",
"type": ["string", "null"]
},
"user-agent": {
"type": ["string", "null"]
}
}
},
"http_version": {
"description": "HTTP version.",
"type": "string",
"maxLength": 1024
},
"method": {
"description": "HTTP method.",
"type": "string",
"maxLength": 1024
},
"socket": {
"type": ["object", "null"],
"properties": {
"encrypted": {
"description": "Indicates whether request was sent as SSL/HTTPS request.",
"type": ["boolean", "null"]
},
"remote_address": {
"type": ["string", "null"]
}
}
},
"url": {
"description": "A complete Url, with scheme, host and path.",
"type": "object",
"properties": {
"raw": {
"type": ["string", "null"],
"maxLength": 1024
},
"protocol": {
"type": ["string", "null"],
"maxLength": 1024
},
"hostname": {
"type": ["string", "null"],
"maxLength": 1024
},
"port": {
"type": ["string", "null"],
"maxLength": 1024
},
"pathname": {
"type": ["string", "null"],
"maxLength": 1024
},
"search": {
"description": "The search describes the query string of the request. It is expected to have values delimited by ampersands.",
"type": ["string", "null"],
"maxLength": 1024
},
"hash": {
"type": ["string", "null"],
"maxLength": 1024
}
}
},
"cookies": {
"description": "A parsed key-value object of cookies",
"type": ["object", "null"]
}
},
"required": ["url", "method"]
}
User
edit{
"$schema": "http://json-schema.org/draft-04/schema#",
"$id": "docs/spec/user.json",
"title": "User",
"description": "Describes the authenticated User for a request.",
"type": "object",
"properties": {
"id": {
"type": ["string", "number", "null"],
"maxLength": 1024
},
"email": {
"type": ["string", "null"],
"maxLength": 1024
},
"username": {
"type": ["string", "null"],
"maxLength": 1024
}
}
}
Examples
editSend an example request to the APM Server:
curl http://localhost:8200/v1/errors \ --header "Content-Type: application/json" \ --data @docs/data/intake-api/generated/error/payload.json
See examples on how an error request to the APM Server can look like:
Payload with an Error
edit{
"app": {
"name": "1234_app-12a3",
"version": "5.1.3",
"pid": 1234,
"process_title": "node",
"argv": [
"node",
"server.js"
],
"language": {
"name": "ecmascript",
"version": "8"
},
"runtime": {
"name": "node",
"version": "8.0.0"
},
"framework": {
"name": "Express",
"version": "1.2.3"
},
"agent": {
"name": "elastic-node",
"version": "3.14.0"
}
},
"system": {
"hostname": "prod1.example.com",
"architecture": "x64",
"platform": "darwin"
},
"errors": [
{
"id": "9f0e9d64-c185-4d21-a6f4-4673ed561ec8",
"timestamp": "2017-05-09T15:04:05.999999Z",
"culprit": "my.module.function_name",
"log": {
"message": "My app could not talk to the database named foobar",
"param_message": "My app could not talk to the database named %s",
"logger_name": "my.logger.name",
"level": "warning",
"stacktrace": [
{
"abs_path": "/real/file/name.py",
"filename": "file/name.py",
"function": "foo",
"vars": {
"key": "value"
},
"pre_context": [
"line1",
"line2"
],
"context_line": "line3",
"in_app": false,
"lineno": 3,
"module": "App::MyModule",
"colno": 4,
"post_context": [
"line4",
"line5"
]
},
{
"filename": "lib/instrumentation/index.js",
"lineno": 102,
"function": "instrumented",
"in_app": false,
"abs_path": "/Users/watson/code/node_modules/elastic/lib/instrumentation/index.js",
"vars": {
"key": "value"
},
"pre_context": [
" var trans = this.currentTransaction",
"",
" return instrumented",
"",
" function instrumented () {",
" var prev = ins.currentTransaction",
" ins.currentTransaction = trans"
],
"context_line": " var result = original.apply(this, arguments)",
"post_context": [
" ins.currentTransaction = prev",
" return result",
"}",
"}",
"",
"Instrumentation.prototype._recoverTransaction = function (trans) {",
" if (this.currentTransaction === trans) return"
]
}
]
},
"exception": {
"message": "The username root is unknown",
"type": "DbError",
"module": "__builtins__",
"code": 42,
"uncaught": true,
"attributes": {
"foo": "bar"
},
"stacktrace": [
{
"abs_path": "/real/file/name.py",
"filename": "file/name.py",
"function": "foo",
"vars": {
"key": "value"
},
"pre_context": [
"line1",
"line2"
],
"context_line": "line3",
"in_app": false,
"lineno": 3,
"module": "App::MyModule",
"colno": 4,
"post_context": [
"line4",
"line5"
]
},
{
"filename": "lib/instrumentation/index.js",
"lineno": 102,
"function": "instrumented",
"in_app": false,
"abs_path": "/Users/watson/code/node_modules/elastic/lib/instrumentation/index.js",
"vars": {
"key": "value"
},
"pre_context": [
" var trans = this.currentTransaction",
"",
" return instrumented",
"",
" function instrumented () {",
" var prev = ins.currentTransaction",
" ins.currentTransaction = trans"
],
"context_line": " var result = original.apply(this, arguments)",
"post_context": [
" ins.currentTransaction = prev",
" return result",
"}",
"}",
"",
"Instrumentation.prototype._recoverTransaction = function (trans) {",
" if (this.currentTransaction === trans) return"
]
}
]
},
"context": {
"request": {
"socket": {
"remote_address": "12.53.12.1",
"encrypted": true
},
"http_version": "1.1",
"method": "POST",
"url": {
"protocol": "https:",
"hostname": "www.example.com",
"port": "8080",
"pathname": "/p/a/t/h",
"search": "?query=string",
"hash": "#hash",
"raw": "/p/a/t/h?query=string#hash"
},
"headers": {
"user-agent": "Mozilla Chrome Edge",
"content-type": "text/html",
"cookie": "c1=v1; c2=v2",
"some-other-header": "foo",
"array": [
"foo",
"bar",
"baz"
]
},
"cookies": {
"c1": "v1",
"c2": "v2"
},
"env": {
"SERVER_SOFTWARE": "nginx",
"GATEWAY_INTERFACE": "CGI/1.1"
},
"body": "Hello World"
},
"response": {
"status_code": 200,
"headers": {
"content-type": "application/json"
},
"headers_sent": true,
"finished": true
},
"user": {
"id": 99,
"username": "foo",
"email": "foo@example.com"
},
"tags": {
"organization_uuid": "9f0e9d64-c185-4d21-a6f4-4673ed561ec8"
},
"custom": {
"my_key": 1,
"some_other_value": "foo bar",
"and_objects": {
"foo": [
"bar",
"baz"
]
}
}
}
},
{
"id": "9f0e9d68-c185-4d21-a6f4-4673ed561ec8",
"timestamp": "2017-05-09T15:04:05.1Z",
"exception": {
"message": "foo is not defined",
"code": "35"
}
},
{
"id": "9f0e9d68-c185-4d21-a6f4-4673ed561ec8",
"timestamp": "2017-05-09T15:04:05Z",
"exception": {
"message": "foo.bar is not a function"
}
},
{
"id": "9f0e9d67-c185-4d21-a6f4-4673ed561ec8",
"timestamp": "2017-05-09T15:04:05.999Z",
"log": {
"message": "Cannot read property 'baz' of undefined"
}
}
]
}
Payload with an Error with minimal Exception Information
edit{
"app": {
"name": "1234_app-12a3",
"agent": {
"name": "python",
"version": "1.0"
}
},
"errors": [
{
"timestamp": "2017-05-09T15:04:05.999999Z",
"exception": {
"message": ""
}
}
]
}
Payload with an Error with minimal Log Information
edit{
"app": {
"name": "1234_app-12a3",
"agent": {
"name": "python",
"version": "1.0"
}
},
"errors": [
{
"timestamp": "2017-05-09T15:04:05.999999Z",
"log": {
"message": ""
}
}
]
}