A newer version is available. For the latest information, see the
current release documentation.
Spansedit
Spans are events captured by an agent occurring in a monitored service.
Span Schemaedit
APM Server uses JSON Schema to validate requests. The specification for spans is defined on GitHub and included below:
{
"$id": "docs/spec/spans/span.json",
"type": "object",
"description": "An event captured by an agent occurring in a monitored service",
"allOf": [
{ "$ref": "../timestamp_epoch.json" },
{ "$ref": "../span_type.json" },
{ "$ref": "../span_subtype.json" },
{
"properties": {
"id": {
"description": "Hex encoded 64 random bits ID of the span.",
"type": "string",
"maxLength": 1024
},
"transaction_id": {
"type": ["string", "null"],
"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
},
"child_ids": {
"description": "List of successor transactions and/or spans.",
"type": ["array", "null"],
"minItems": 0,
"maxLength": 1024,
"items": {
"type": "string",
"maxLength": 1024
}
},
"start": {
"type": ["number", "null"],
"description": "Offset relative to the transaction's timestamp identifying the start of the span, in milliseconds"
},
"sample_rate": {
"description": "Sampling rate",
"type": ["number", "null"]
},
"action": {
"type": ["string", "null"],
"description": "The specific kind of event within the sub-type represented by the span (e.g. query, connect)",
"maxLength": 1024
},
"outcome": {
"$ref": "../outcome.json",
"description": "The outcome of the span: success, failure, or unknown. Outcome may be one of a limited set of permitted values describing the success or failure of the span. This field can be used for calculating error rates for outgoing requests."
},
"context": {
"type": ["object", "null"],
"description": "Any other arbitrary data captured by the agent, optionally provided by the user",
"properties": {
"destination": {
"type": ["object", "null"],
"description": "An object containing contextual data about the destination for spans",
"properties": {
"address": {
"type": ["string", "null"],
"description": "Destination network address: hostname (e.g. 'localhost'), FQDN (e.g. 'elastic.co'), IPv4 (e.g. '127.0.0.1') or IPv6 (e.g. '::1')",
"maxLength": 1024
},
"port": {
"type": ["integer", "null"],
"description": "Destination network port (e.g. 443)"
},
"service": {
"description": "Destination service context",
"type": ["object", "null"],
"properties": {
"type": {
"description": "Type of the destination service (e.g. 'db', 'elasticsearch'). Should typically be the same as span.type.",
"type": ["string", "null"],
"maxLength": 1024
},
"name": {
"description": "Identifier for the destination service (e.g. 'http://elastic.co', 'elasticsearch', 'rabbitmq')",
"type": ["string", "null"],
"maxLength": 1024
},
"resource": {
"description": "Identifier for the destination service resource being operated on (e.g. 'http://elastic.co:80', 'elasticsearch', 'rabbitmq/queue_name')",
"type": ["string", "null"],
"maxLength": 1024
}
},
"required": ["type", "name", "resource"]
}
}
},
"db": {
"type": ["object", "null"],
"description": "An object containing contextual data for database spans",
"properties": {
"instance": {
"type": ["string", "null"],
"description": "Database instance name"
},
"link": {
"type": ["string", "null"],
"maxLength": 1024,
"description": "Database link"
},
"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"
},
"rows_affected": {
"type": ["integer", "null"],
"description": "Number of rows affected by the SQL statement (if applicable)"
}
}
},
"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": "Deprecated: Use span.context.http.response.status_code instead."
},
"method": {
"type": ["string", "null"],
"maxLength": 1024,
"description": "The method of the http request."
},
"response": {
"$ref": "../http_response.json"
}
}
},
"tags": {
"$ref": "../tags.json"
},
"service": {
"description": "Service related information can be sent per event. Provided information will override the more generic information from metadata, non provided fields will be set according to the metadata information.",
"properties": {
"agent": {
"description": "Name and version of the Elastic APM agent",
"type": [
"object",
"null"
],
"properties": {
"name": {
"description": "Name of the Elastic APM agent, e.g. \"Python\"",
"type": [
"string",
"null"
],
"maxLength": 1024
},
"version": {
"description": "Version of the Elastic APM agent, e.g.\"1.0.0\"",
"type": [
"string",
"null"
],
"maxLength": 1024
},
"ephemeral_id": {
"description": "Free format ID used for metrics correlation by some agents",
"type": ["string", "null"],
"maxLength": 1024
}
}
},
"name": {
"description": "Immutable name of the service emitting this event",
"type": [
"string",
"null"
],
"pattern": "^[a-zA-Z0-9 _-]+$",
"maxLength": 1024
}
}
},
"message": {
"$ref": "../message.json"
}
}
},
"duration": {
"type": "number",
"description": "Duration of the span in milliseconds",
"minimum": 0
},
"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
},
"sync": {
"type": ["boolean", "null"],
"description": "Indicates whether the span was executed synchronously or asynchronously."
}
},
"required": ["duration", "name", "type", "id","trace_id", "parent_id"]
},
{ "anyOf":[
{"required": ["timestamp"], "properties": {"timestamp": { "type": "integer" }}},
{"required": ["start"], "properties": {"start": { "type": "number" }}}
]
}
]
}