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/error.json",
    "type": "object",
    "description": "An error or a logged error message captured by an agent occurring in a monitored service",
    "allOf": [
        { "$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."
                        },
                        "type": {
                            "type": ["string", "null"],
                            "description": "Keyword of specific relevance in the service's domain (eg: 'request', 'backgroundjob', etc)",
                            "maxLength": 1024
                        }
                    }
                },
                "context": {
                    "$ref": "./../context.json"
                },
                "culprit": {
                    "description": "Function call which was the primary perpetrator of this event.",
                    "type": ["string", "null"],
                    "maxLength": 1024
                },
                "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"]
                }
            },
            "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" }}} }
            ],
            "anyOf": [
                { "required": ["exception"], "properties": {"exception": { "type": "object" }} },
                { "required": ["log"], "properties": {"log": { "type": "object" }} }
            ]
        }
    ]
}