A newer version is available. For the latest information, see the
current release documentation.
Error APIedit
The following section contains information about:
Endpointedit
Send a HTTP POST
request to the APM Server errors
endpoint:
http(s)://{hostname}:{port}/v1/errors
For RUM send a HTTP POST
request to the rum errors
endpoint instead:
http(s)://{hostname}:{port}/v1/rum/errors
Schema Definitionedit
The APM Server uses JSON Schema for validating requests. The specification for errors is defined bellow: * Payload * Error * Service * System * Context * Stacktrace Frame * Request * User
Payloadedit
{ "$id": "docs/spec/errors/payload.json", "title": "Errors payload", "description": "List of errors wrapped in an object containing some other attributes normalized away from the errors themselves", "type": "object", "properties": { "service": { "$ref": "../service.json" }, "process": { "$ref": "../process.json" }, "errors": { "type": "array", "items": { "$ref": "error.json" }, "minItems": 1 }, "system": { "$ref": "../system.json" } }, "required": ["service", "errors"] }
Erroredit
{ "$id": "docs/spec/errors/error.json", "type": "object", "description": "Data captured by an agent representing an event occurring in a monitored service", "properties": { "context": { "$ref": "./../context.json" }, "culprit": { "description": "Function call which was the primary perpetrator of this event.", "type": ["string", "null"] }, "exception": { "description": "Information about the originally thrown error.", "type": ["object", "null"], "properties": { "code": { "type": ["string", "integer", "null"], "maxLength": 1024, "description": "The error code set when the error happened, e.g. database error code." }, "message": { "description": "The original 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 }, "handled": { "type": ["boolean", "null"], "description": "Indicator whether the error was caught somewhere in the code or not." } }, "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"], "description": "Additional information added when logging the error.", "properties": { "level": { "description": "The severity of the record.", "type": ["string", "null"], "maxLength": 1024 }, "logger_name": { "description": "The name of the logger instance used.", "type": ["string", "null"], "default": "default", "maxLength": 1024 }, "message": { "description": "The additionally logged 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","null"], "format": "date-time", "pattern": "Z$", "description": "Recorded time of the error, UTC based and formatted as YYYY-MM-DDTHH:mm:ss.sssZ" }, "transaction": { "type": ["object", "null"], "description": "Data for correlating errors with transactions", "properties": { "id": { "type": ["string", "null"], "description": "UUID for the transaction", "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}$" } } } }, "anyOf": [ { "required": ["exception"] }, { "required": ["log"] } ] }
Serviceedit
{ "$id": "doc/spec/service.json", "title": "Service", "type": "object", "properties": { "agent": { "description": "Name and version of the Elastic APM agent", "type": "object", "properties": { "name": { "description": "Name of the Elastic APM agent, e.g. \"Python\"", "type": "string", "maxLength": 1024 }, "version": { "description": "Version of the Elastic APM agent, e.g.\"1.0.0\"", "type": "string", "maxLength": 1024 } }, "required": ["name", "version"] }, "framework": { "description": "Name and version of the web framework used", "type": ["object", "null"], "properties": { "name": { "type": "string", "maxLength": 1024 }, "version": { "type": "string", "maxLength": 1024 } }, "required": ["name", "version"] }, "language": { "description": "Name and version of the programming language used", "type": ["object", "null"], "properties": { "name": { "type": "string", "maxLength": 1024 }, "version": { "type": ["string", "null"], "maxLength": 1024 } }, "required": ["name"] }, "name": { "description": "Immutable name of the service emitting this event", "type": "string", "pattern": "^[a-zA-Z0-9 _-]+$", "maxLength": 1024 }, "environment": { "description": "Environment name of the service, e.g. \"production\" or \"staging\"", "type": ["string", "null"], "maxLength": 1024 }, "runtime": { "description": "Name and version of the language runtime running this service", "type": ["object", "null"], "properties": { "name": { "type": "string", "maxLength": 1024 }, "version": { "type": "string", "maxLength": 1024 } }, "required": ["name", "version"] }, "version": { "description": "Version of the service emitting this event", "type": ["string", "null"], "maxLength": 1024 } }, "required": ["agent", "name"] }
Systemedit
{ "$id": "doc/spec/system.json", "title": "System", "type": ["object", "null"], "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 } } }
Contextedit
{ "$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"], "patternProperties": { "^[^.*\"]*$": {} }, "additionalProperties": false }, "response": { "type": ["object", "null"], "properties": { "finished": { "description": "A boolean indicating whether the response was finished or not", "type": ["boolean", "null"] }, "headers": { "description": "A mapping of HTTP headers of the response object", "type": ["object", "null"], "properties": { "content-type": { "type": ["string", "null"] } } }, "headers_sent": { "type": ["boolean", "null"] }, "status_code": { "description": "The HTTP status code of the response.", "type": ["integer", "null"] } } }, "request": { "$ref": "request.json" }, "tags": { "type": ["object", "null"], "description": "A flat mapping of user-defined tags with string values.", "patternProperties": { "^[^.*\"]*$": { "type": ["string", "null"], "maxLength": 1024 } }, "additionalProperties": false }, "user": { "$ref": "user.json" } } }
Stacktrace Frameedit
{ "$id": "docs/spec/stacktrace_frame.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": ["integer", "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"] }, "library_frame": { "description": "A boolean, indicating if this frame is from a library or user code", "type": ["boolean", "null"] }, "lineno": { "description": "The line number of code part of the stack frame, used e.g. to do error checksumming", "type": "integer" }, "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, "items": { "type": "string" } }, "pre_context": { "description": "The lines of code before the stack frame", "type": ["array", "null"], "minItems": 0, "items": { "type": "string" } }, "vars": { "description": "Local variables for this stack frame", "type": ["object", "null"], "properties": {} } }, "required": ["filename", "lineno"] }
Requestedit
{ "$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", "null"], "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", "null"], "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"], "description": "The raw, unparsed URL of the HTTP request line, e.g https://example.com:443/search?q=elasticsearch. This URL may be absolute or relative. For more details, see https://www.w3.org/Protocols/rfc2616/rfc2616-sec5.html#sec5.1.2.", "maxLength": 1024 }, "protocol": { "type": ["string", "null"], "description": "The protocol of the request, e.g. 'https:'.", "maxLength": 1024 }, "full": { "type": ["string", "null"], "description": "The full, possibly agent-assembled URL of the request, e.g https://example.com:443/search?q=elasticsearch#top.", "maxLength": 1024 }, "hostname": { "type": ["string", "null"], "description": "The hostname of the request, e.g. 'example.com'.", "maxLength": 1024 }, "port": { "type": ["string", "null"], "description": "The port of the request, e.g. '443'", "maxLength": 1024 }, "pathname": { "type": ["string", "null"], "description": "The path of the request, e.g. '/search'", "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"], "description": "The hash of the request URL, e.g. 'top'", "maxLength": 1024 } } }, "cookies": { "description": "A parsed key-value object of cookies", "type": ["object", "null"] } }, "required": ["url", "method"] }
Useredit
{ "$id": "docs/spec/user.json", "title": "User", "description": "Describes the authenticated User for a request.", "type": ["object", "null"], "properties": { "id": { "description": "Identifier of the logged in user, e.g. the primary key of the user", "type": ["string", "integer", "null"], "maxLength": 1024 }, "email": { "description": "Email of the logged in user", "type": ["string", "null"], "maxLength": 1024 }, "username": { "description": "The username of the logged in user", "type": ["string", "null"], "maxLength": 1024 } } }
Examplesedit
Request example:
curl http://localhost:8200/v1/errors \ --header "Content-Type: application/json" \ --data @docs/data/intake-api/generated/error/payload.json
Example error requests:
Payload with an Erroredit
{ "service": { "name": "1234_service-12a3", "version": "5.1.3", "environment": "staging", "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" } }, "process": { "pid": 1234, "ppid": 7788, "title": "node", "argv": [ "node", "server.js" ] }, "system": { "hostname": "prod1.example.com", "architecture": "x64", "platform": "darwin" }, "errors": [ { "id": "5f0e9d64-c185-4d21-a6f4-4673ed561ec8", "timestamp": "2017-05-09T15:04:05.999999Z", "culprit": "my.module.function_name", "log": { "message": "My service could not talk to the database named foobar", "param_message": "My service could not talk to the database named %s", "logger_name": "my.logger.name", "level": "warning", "stacktrace": [ { "abs_path": "/real/file/name.py", "filename": "/webpack/file/name.py", "function": "foo", "vars": { "key": "value" }, "pre_context": [ "line1", "line2" ], "context_line": "line3", "library_frame": false, "lineno": 3, "module": "App::MyModule", "colno": 4, "post_context": [ "line4", "line5" ] }, { "filename": "lib/instrumentation/index.js", "lineno": 102, "function": "instrumented", "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, "handled": false, "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", "library_frame": true, "lineno": 3, "module": "App::MyModule", "colno": 4, "post_context": [ "line4", "line5" ] }, { "filename": "lib/instrumentation/index.js", "lineno": 102, "function": "instrumented", "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:", "full": "https://www.example.com/p/a/t/h?query=string#hash", "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": "[email protected]" }, "tags": { "organization_uuid": "9f0e9d64-c185-4d21-a6f4-4673ed561ec8" }, "custom": { "my_key": 1, "some_other_value": "foo bar", "and_objects": { "foo": [ "bar", "baz" ] } } }, "transaction": { "id": "945254c5-67a5-417e-8a4e-aa29efcbfb79" } }, { "id": "8f0e9d68-c185-4d21-a6f4-4673ed561ec8", "timestamp": "2017-05-09T15:04:05.1Z", "exception": { "message": "foo is not defined", "code": "35" } }, { "id": "7f0e9d68-c185-4d21-a6f4-4673ed561ec8", "timestamp": "2017-05-09T15:04:05Z", "exception": { "message": "foo.bar is not a function" } }, { "id": "0f0e9d67-c185-4d21-a6f4-4673ed561ec8", "timestamp": "2017-05-09T15:04:05.999Z", "log": { "level": "custom log level", "message": "Cannot read property 'baz' of undefined" } } ] }
Payload with an Error with minimal Exception Informationedit
{ "service": { "name": "1234_service-12a3", "agent": { "name": "python", "version": "1.0" } }, "errors": [ { "exception": { "message": "" } } ] }
Payload with an Error with minimal Log Informationedit
{ "service": { "name": "1234_service-12a3", "agent": { "name": "python", "version": "1.0" } }, "errors": [ { "log": { "message": "" } } ] }