A newer version is available. For the latest information, see the
current release documentation.
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.
The following section contains information about:
Endpoint
editTo send an error record you need to send a HTTP POST request to the APM Server errors endpoint:
http(s)://{hostname}:{port}/v1/errors
To send a record for an error monitored by the
JavaScript Frontend Agent
you need to send a HTTP POST request to the experimental APM Server client-side errors endpoint:
http(s)://{hostname}:{port}/v1/client-side/errors
Information pertaining to the error record must be sent as a JSON object to the endpoint.
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/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{
"$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 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",
"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",
"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}$",
"maxLength": 1024
}
}
}
},
"anyOf": [
{
"required": ["exception"]
},
{
"required": ["log"]
}
]
}
Service
edit{
"$schema": "http://json-schema.org/draft-04/schema#",
"$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{
"$schema": "http://json-schema.org/draft-04/schema#",
"$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{
"$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": {
"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.",
"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_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{
"$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", "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{
"$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", "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
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{
"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": ""
}
}
]
}