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": ""
            }
        }
    ]
}