Spansedit

Spans are events captured by an agent occurring in a monitored service.

Span Schemaedit

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

{
    "$id": "docs/spec/spans/v2_span.json",
    "type": "object",
    "description": "An event captured by an agent occurring in a monitored service",
    "allOf": [
        { "$ref": "common_span.json"  },
        { "$ref": "../timestamp_epoch.json" },
        {
            "properties": {
                "id": {
                    "description": "Hex encoded 64 random bits ID of the span.",
                    "type": "string",
                    "maxLength": 1024
                },
                "transaction_id": {
                    "type": "string",
                    "description": "Hex encoded 64 random bits ID of the correlated transaction.",
                    "maxLength": 1024
                },
                "trace_id": {
                    "description": "Hex encoded 128 random bits ID of the correlated trace.",
                    "type": "string",
                    "maxLength": 1024
                },
                "parent_id": {
                    "description": "Hex encoded 64 random bits ID of the parent transaction or span.",
                    "type": "string",
                    "maxLength": 1024
                },
                "start": {
                    "type": ["number", "null"],
                    "description": "Offset relative to the transaction's timestamp identifying the start of the span, in milliseconds"
                },
                "subtype": {
                    "type": ["string", "null"],
                    "description": "A further sub-division of the type (e.g. postgresql, elasticsearch)",
                    "maxLength": 1024
                },
                "action": {
                    "type": ["string", "null"],
                    "description": "The specific kind of event within the sub-type represented by the span (e.g. query, connect)",
                    "maxLength": 1024
                }
            },
            "required": ["id", "transaction_id", "trace_id", "parent_id"]
        },
        { "anyOf":[
                {"required": ["timestamp"], "properties": {"timestamp": { "type": "integer" }}},
                {"required": ["start"], "properties": {"start": { "type": "number" }}}
            ]
        }
    ]
}
{
    "$id": "docs/spec/spans/common_span.json",
    "type": "object",
    "properties": {
        "context": {
            "type": ["object", "null"],
            "description": "Any other arbitrary data captured by the agent, optionally provided by the user",
            "properties": {
                "db": {
                    "type": ["object", "null"],
                    "description": "An object containing contextual data for database spans",
                    "properties": {
                        "instance": {
                           "type": ["string", "null"],
                           "description": "Database instance name"
                        },
                        "statement": {
                           "type": ["string", "null"],
                           "description": "A database statement (e.g. query) for the given database type"
                        },
                        "type": {
                           "type": ["string", "null"],
                           "description": "Database type. For any SQL database, \"sql\". For others, the lower-case database category, e.g. \"cassandra\", \"hbase\", or \"redis\""
                        },
                        "user": {
                           "type": ["string", "null"],
                           "description": "Username for accessing database"
                        }
                    }
                },
                "http": {
                    "type": ["object", "null"],
                    "description": "An object containing contextual data of the related http request.",
                    "properties": {
                        "url": {
                            "type": ["string", "null"],
                            "description": "The raw url of the correlating http request."
                        },
                        "status_code": {
                            "type": ["integer", "null"],
                            "description": "The status code of the http request."
                        },
                        "method": {
                            "type": ["string", "null"],
                            "maxLength": 1024,
                            "description": "The method of the http request."
                        }
                    }
                },
                "tags": {
                    "$ref": "../tags.json"
                }
            }
        },
        "duration": {
            "type": "number",
            "description": "Duration of the span in milliseconds"
        },
        "name": {
            "type": "string",
            "description": "Generic designation of a span in the scope of a transaction",
            "maxLength": 1024
        },
        "stacktrace": {
            "type": ["array", "null"],
            "description": "List of stack frames with variable attributes (eg: lineno, filename, etc)",
            "items": {
                "$ref": "../stacktrace_frame.json"
            },
            "minItems": 0
        },
        "type": {
            "type": "string",
            "description": "Keyword of specific relevance in the service's domain (eg: 'db.postgresql.query', 'template.erb', etc)",
            "maxLength": 1024
        },
        "sync": {
            "type": ["boolean", "null"],
            "description": "Indicates whether the span was executed synchronously or asynchronously."
        }
    },
    "required": ["duration", "name", "type"]
}