A newer version is available. For the latest information, see the
current release documentation.
Error API
editError API
editThe following section contains information about:
Endpoint
editSend 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 Definition
editThe APM Server uses JSON Schema for validating requests. The specification for errors is defined bellow: * Payload * Error * Service * System * Context * Stacktrace Frame * Request * User
Payload
edit{
"$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"]
}
Error
edit{
"$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"]
}
]
}
Service
edit{
"$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"]
}
System
edit{
"$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
}
}
}
Context
edit{
"$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 Frame
edit{
"$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"]
}
Request
edit{
"$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"]
}
User
edit{
"$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
}
}
}
Examples
editRequest 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 Error
edit{
"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": "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"
]
}
}
},
"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 Information
edit{
"service": {
"name": "1234_service-12a3",
"agent": {
"name": "python",
"version": "1.0"
}
},
"errors": [
{
"exception": {
"message": ""
}
}
]
}
Payload with an Error with minimal Log Information
edit{
"service": {
"name": "1234_service-12a3",
"agent": {
"name": "python",
"version": "1.0"
}
},
"errors": [
{
"log": {
"message": ""
}
}
]
}