Errors

An error or a logged error message captured by an agent occurring in a monitored service.

Error Schema

The APM Server uses JSON Schema for validating requests. The specification for errors is defined below:

{
    "$id": "docs/spec/errors/v2_error.json",
    "type": "object",
    "description": "An error or a logged error message captured by an agent occurring in a monitored service",
    "allOf": [

        { "$ref": "common_error.json"  },
        { "$ref": "../timestamp_epoch.json" },
        {
            "properties": {
                "id": {
                    "type": ["string"],
                    "description": "Hex encoded 128 random bits ID of the error.",
                    "maxLength": 1024
                },
                "trace_id": {
                    "description": "Hex encoded 128 random bits ID of the correlated trace. Must be present if transaction_id and parent_id are set.",
                    "type": ["string", "null"],
                    "maxLength": 1024
                },
                "transaction_id": {
                    "type": ["string", "null"],
                    "description": "Hex encoded 64 random bits ID of the correlated transaction. Must be present if trace_id and parent_id are set.",
                    "maxLength": 1024
                },
                "parent_id": {
                    "description": "Hex encoded 64 random bits ID of the parent transaction or span. Must be present if trace_id and transaction_id are set.",
                    "type": ["string", "null"],
                    "maxLength": 1024
                },
                "transaction": {
                    "type": ["object", "null"],
                    "description": "Data for correlating errors with transactions",
                    "properties": {
                        "sampled": {
                            "type": ["boolean", "null"],
                            "description": "Transactions that are 'sampled' will include all available information. Transactions that are not sampled will not have 'spans' or 'context'. Defaults to true."
                        }
                    }
                }
            },
            "allOf": [
                { "required": ["id"] },
                { "if": {"required": ["transaction_id"], "properties": {"transaction_id": { "type": "string" }}},
                  "then": { "required": ["trace_id"], "properties": {"trace_id": { "type": "string" }}} },
                { "if": {"required": ["trace_id"], "properties": {"trace_id": { "type": "string" }}},
                  "then": { "required": ["parent_id"], "properties": {"parent_id": { "type": "string" }}} },
                { "if": {"required": ["parent_id"], "properties": {"parent_id": { "type": "string" }}},
                  "then": { "required": ["transaction_id"], "properties": {"transaction_id": { "type": "string" }}} }
            ]
        }
    ]
}
{
    "$id": "docs/spec/errors/common_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", "null"]
                },
                "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."
                }
            },
            "anyOf": [
                {"required": ["message"], "properties": {"message": {"type": "string"}}},
                {"required": ["type"], "properties": {"type": {"type": "string"}}}
            ]
        },
        "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"]
        }
    },
    "anyOf": [
        { "required": ["exception"], "properties": {"exception": { "type": "object" }} },
        { "required": ["log"], "properties": {"log": { "type": "object" }} }
    ]
}