Spans
editSpans
editSpans are events captured by an agent occurring in a monitored service.
Span Schema
editAPM Server uses JSON Schema to validate requests. The specification for spans is defined on GitHub and included below:
{
"$id": "docs/spec/v2/span",
"type": "object",
"properties": {
"action": {
"description": "Action holds the specific kind of event within the sub-type represented by the span (e.g. query, connect)",
"type": [
"null",
"string"
],
"maxLength": 1024
},
"child_ids": {
"description": "ChildIDs holds a list of successor transactions and/or spans.",
"type": [
"null",
"array"
],
"items": {
"type": "string",
"maxLength": 1024
},
"minItems": 0
},
"composite": {
"description": "Composite holds details on a group of spans represented by a single one.",
"type": [
"null",
"object"
],
"properties": {
"compression_strategy": {
"description": "A string value indicating which compression strategy was used. The valid values are `exact_match` and `same_kind`.",
"type": "string"
},
"count": {
"description": "Count is the number of compressed spans the composite span represents. The minimum count is 2, as a composite span represents at least two spans.",
"type": "integer",
"minimum": 2
},
"sum": {
"description": "Sum is the durations of all compressed spans this composite span represents in milliseconds.",
"type": "number",
"minimum": 0
}
},
"required": [
"compression_strategy",
"count",
"sum"
]
},
"context": {
"description": "Context holds arbitrary contextual information for the event.",
"type": [
"null",
"object"
],
"properties": {
"db": {
"description": "Database contains contextual data for database spans",
"type": [
"null",
"object"
],
"properties": {
"instance": {
"description": "Instance name of the database.",
"type": [
"null",
"string"
]
},
"link": {
"description": "Link to the database server.",
"type": [
"null",
"string"
],
"maxLength": 1024
},
"rows_affected": {
"description": "RowsAffected shows the number of rows affected by the statement.",
"type": [
"null",
"integer"
]
},
"statement": {
"description": "Statement of the recorded database event, e.g. query.",
"type": [
"null",
"string"
]
},
"type": {
"description": "Type of the recorded database event., e.g. sql, cassandra, hbase, redis.",
"type": [
"null",
"string"
]
},
"user": {
"description": "User is the username with which the database is accessed.",
"type": [
"null",
"string"
]
}
}
},
"destination": {
"description": "Destination contains contextual data about the destination of spans",
"type": [
"null",
"object"
],
"properties": {
"address": {
"description": "Address is the destination network address: hostname (e.g. 'localhost'), FQDN (e.g. 'elastic.co'), IPv4 (e.g. '127.0.0.1') IPv6 (e.g. '::1')",
"type": [
"null",
"string"
],
"maxLength": 1024
},
"port": {
"description": "Port is the destination network port (e.g. 443)",
"type": [
"null",
"integer"
]
},
"service": {
"description": "Service describes the destination service",
"type": [
"null",
"object"
],
"properties": {
"name": {
"description": "Name is the identifier for the destination service, e.g. 'http://elastic.co', 'elasticsearch', 'rabbitmq' ( DEPRECATED: this field will be removed in a future release",
"type": [
"null",
"string"
],
"maxLength": 1024
},
"resource": {
"description": "Resource identifies the destination service resource being operated on e.g. 'http://elastic.co:80', 'elasticsearch', 'rabbitmq/queue_name' DEPRECATED: this field will be removed in a future release",
"type": "string",
"maxLength": 1024
},
"type": {
"description": "Type of the destination service, e.g. db, elasticsearch. Should typically be the same as span.type. DEPRECATED: this field will be removed in a future release",
"type": [
"null",
"string"
],
"maxLength": 1024
}
},
"required": [
"resource"
]
}
}
},
"http": {
"description": "HTTP contains contextual information when the span concerns an HTTP request.",
"type": [
"null",
"object"
],
"properties": {
"method": {
"description": "Method holds information about the method of the HTTP request.",
"type": [
"null",
"string"
],
"maxLength": 1024
},
"request": {
"description": "Request describes the HTTP request information.",
"type": [
"null",
"object"
],
"properties": {
"id": {
"description": "ID holds the unique identifier for the http request.",
"type": [
"null",
"string"
]
}
}
},
"response": {
"description": "Response describes the HTTP response information in case the event was created as a result of an HTTP request.",
"type": [
"null",
"object"
],
"properties": {
"decoded_body_size": {
"description": "DecodedBodySize holds the size of the decoded payload.",
"type": [
"null",
"integer"
]
},
"encoded_body_size": {
"description": "EncodedBodySize holds the size of the encoded payload.",
"type": [
"null",
"integer"
]
},
"headers": {
"description": "Headers holds the http headers sent in the http response.",
"type": [
"null",
"object"
],
"additionalProperties": false,
"patternProperties": {
"[.*]*$": {
"type": [
"null",
"array",
"string"
],
"items": {
"type": "string"
}
}
}
},
"status_code": {
"description": "StatusCode sent in the http response.",
"type": [
"null",
"integer"
]
},
"transfer_size": {
"description": "TransferSize holds the total size of the payload.",
"type": [
"null",
"integer"
]
}
}
},
"status_code": {
"description": "Deprecated: Use Response.StatusCode instead. StatusCode sent in the http response.",
"type": [
"null",
"integer"
]
},
"url": {
"description": "URL is the raw url of the correlating HTTP request.",
"type": [
"null",
"string"
]
}
}
},
"message": {
"description": "Message holds details related to message receiving and publishing if the captured event integrates with a messaging system",
"type": [
"null",
"object"
],
"properties": {
"age": {
"description": "Age of the message. If the monitored messaging framework provides a timestamp for the message, agents may use it. Otherwise, the sending agent can add a timestamp in milliseconds since the Unix epoch to the message's metadata to be retrieved by the receiving agent. If a timestamp is not available, agents should omit this field.",
"type": [
"null",
"object"
],
"properties": {
"ms": {
"description": "Age of the message in milliseconds.",
"type": [
"null",
"integer"
]
}
}
},
"body": {
"description": "Body of the received message, similar to an HTTP request body",
"type": [
"null",
"string"
]
},
"headers": {
"description": "Headers received with the message, similar to HTTP request headers.",
"type": [
"null",
"object"
],
"additionalProperties": false,
"patternProperties": {
"[.*]*$": {
"type": [
"null",
"array",
"string"
],
"items": {
"type": "string"
}
}
}
},
"queue": {
"description": "Queue holds information about the message queue where the message is received.",
"type": [
"null",
"object"
],
"properties": {
"name": {
"description": "Name holds the name of the message queue where the message is received.",
"type": [
"null",
"string"
],
"maxLength": 1024
}
}
},
"routing_key": {
"description": "RoutingKey holds the optional routing key of the received message as set on the queuing system, such as in RabbitMQ.",
"type": [
"null",
"string"
]
}
}
},
"service": {
"description": "Service related information can be sent per span. Information provided here will override the more generic information retrieved from metadata, missing service fields will be retrieved from the metadata information.",
"type": [
"null",
"object"
],
"properties": {
"agent": {
"description": "Agent holds information about the APM agent capturing the event.",
"type": [
"null",
"object"
],
"properties": {
"ephemeral_id": {
"description": "EphemeralID is a free format ID used for metrics correlation by agents",
"type": [
"null",
"string"
],
"maxLength": 1024
},
"name": {
"description": "Name of the APM agent capturing information.",
"type": [
"null",
"string"
],
"maxLength": 1024
},
"version": {
"description": "Version of the APM agent capturing information.",
"type": [
"null",
"string"
],
"maxLength": 1024
}
}
},
"environment": {
"description": "Environment in which the monitored service is running, e.g. `production` or `staging`.",
"type": [
"null",
"string"
],
"maxLength": 1024
},
"framework": {
"description": "Framework holds information about the framework used in the monitored service.",
"type": [
"null",
"object"
],
"properties": {
"name": {
"description": "Name of the used framework",
"type": [
"null",
"string"
],
"maxLength": 1024
},
"version": {
"description": "Version of the used framework",
"type": [
"null",
"string"
],
"maxLength": 1024
}
}
},
"id": {
"description": "ID holds a unique identifier for the service.",
"type": [
"null",
"string"
]
},
"language": {
"description": "Language holds information about the programming language of the monitored service.",
"type": [
"null",
"object"
],
"properties": {
"name": {
"description": "Name of the used programming language",
"type": [
"null",
"string"
],
"maxLength": 1024
},
"version": {
"description": "Version of the used programming language",
"type": [
"null",
"string"
],
"maxLength": 1024
}
}
},
"name": {
"description": "Name of the monitored service.",
"type": [
"null",
"string"
],
"maxLength": 1024,
"pattern": "^[a-zA-Z0-9 _-]+$"
},
"node": {
"description": "Node must be a unique meaningful name of the service node.",
"type": [
"null",
"object"
],
"properties": {
"configured_name": {
"description": "Name of the service node",
"type": [
"null",
"string"
],
"maxLength": 1024
}
}
},
"origin": {
"description": "Origin contains the self-nested field groups for service.",
"type": [
"null",
"object"
],
"properties": {
"id": {
"description": "Immutable id of the service emitting this event.",
"type": [
"null",
"string"
]
},
"name": {
"description": "Immutable name of the service emitting this event.",
"type": [
"null",
"string"
]
},
"version": {
"description": "The version of the service the data was collected from.",
"type": [
"null",
"string"
]
}
}
},
"runtime": {
"description": "Runtime holds information about the language runtime running the monitored service",
"type": [
"null",
"object"
],
"properties": {
"name": {
"description": "Name of the language runtime",
"type": [
"null",
"string"
],
"maxLength": 1024
},
"version": {
"description": "Version of the language runtime",
"type": [
"null",
"string"
],
"maxLength": 1024
}
}
},
"target": {
"description": "Target holds information about the outgoing service in case of an outgoing event",
"type": [
"null",
"object"
],
"properties": {
"name": {
"description": "Immutable name of the target service for the event",
"type": [
"null",
"string"
]
},
"type": {
"description": "Immutable type of the target service for the event",
"type": [
"null",
"string"
]
}
},
"anyOf": [
{
"properties": {
"type": {
"type": "string"
}
},
"required": [
"type"
]
},
{
"properties": {
"name": {
"type": "string"
}
},
"required": [
"name"
]
}
]
},
"version": {
"description": "Version of the monitored service.",
"type": [
"null",
"string"
],
"maxLength": 1024
}
}
},
"tags": {
"description": "Tags are a flat mapping of user-defined tags. On the agent side, tags are called labels. Allowed value types are string, boolean and number values. Tags are indexed and searchable.",
"type": [
"null",
"object"
],
"additionalProperties": {
"type": [
"null",
"string",
"boolean",
"number"
],
"maxLength": 1024
}
}
}
},
"duration": {
"description": "Duration of the span in milliseconds. When the span is a composite one, duration is the gross duration, including \"whitespace\" in between spans.",
"type": "number",
"minimum": 0
},
"id": {
"description": "ID holds the hex encoded 64 random bits ID of the event.",
"type": "string",
"maxLength": 1024
},
"links": {
"description": "Links holds links to other spans, potentially in other traces.",
"type": [
"null",
"array"
],
"items": {
"type": "object",
"properties": {
"span_id": {
"description": "SpanID holds the ID of the linked span.",
"type": "string",
"maxLength": 1024
},
"trace_id": {
"description": "TraceID holds the ID of the linked span's trace.",
"type": "string",
"maxLength": 1024
}
},
"required": [
"span_id",
"trace_id"
]
},
"minItems": 0
},
"name": {
"description": "Name is the generic designation of a span in the scope of a transaction.",
"type": "string",
"maxLength": 1024
},
"otel": {
"description": "OTel contains unmapped OpenTelemetry attributes.",
"type": [
"null",
"object"
],
"properties": {
"attributes": {
"description": "Attributes hold the unmapped OpenTelemetry attributes.",
"type": [
"null",
"object"
]
},
"span_kind": {
"description": "SpanKind holds the incoming OpenTelemetry span kind.",
"type": [
"null",
"string"
]
}
}
},
"outcome": {
"description": "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. It can be used for calculating error rates for outgoing requests.",
"type": [
"null",
"string"
],
"enum": [
"success",
"failure",
"unknown",
null
]
},
"parent_id": {
"description": "ParentID holds the hex encoded 64 random bits ID of the parent transaction or span.",
"type": "string",
"maxLength": 1024
},
"sample_rate": {
"description": "SampleRate applied to the monitored service at the time where this span was recorded.",
"type": [
"null",
"number"
]
},
"stacktrace": {
"description": "Stacktrace connected to this span event.",
"type": [
"null",
"array"
],
"items": {
"type": "object",
"properties": {
"abs_path": {
"description": "AbsPath is the absolute path of the frame's file.",
"type": [
"null",
"string"
]
},
"classname": {
"description": "Classname of the frame.",
"type": [
"null",
"string"
]
},
"colno": {
"description": "ColumnNumber of the frame.",
"type": [
"null",
"integer"
]
},
"context_line": {
"description": "ContextLine is the line from the frame's file.",
"type": [
"null",
"string"
]
},
"filename": {
"description": "Filename is the relative name of the frame's file.",
"type": [
"null",
"string"
]
},
"function": {
"description": "Function represented by the frame.",
"type": [
"null",
"string"
]
},
"library_frame": {
"description": "LibraryFrame indicates whether the frame is from a third party library.",
"type": [
"null",
"boolean"
]
},
"lineno": {
"description": "LineNumber of the frame.",
"type": [
"null",
"integer"
]
},
"module": {
"description": "Module to which the frame belongs to.",
"type": [
"null",
"string"
]
},
"post_context": {
"description": "PostContext is a slice of code lines immediately before the line from the frame's file.",
"type": [
"null",
"array"
],
"items": {
"type": "string"
},
"minItems": 0
},
"pre_context": {
"description": "PreContext is a slice of code lines immediately after the line from the frame's file.",
"type": [
"null",
"array"
],
"items": {
"type": "string"
},
"minItems": 0
},
"vars": {
"description": "Vars is a flat mapping of local variables of the frame.",
"type": [
"null",
"object"
]
}
},
"anyOf": [
{
"properties": {
"classname": {
"type": "string"
}
},
"required": [
"classname"
]
},
{
"properties": {
"filename": {
"type": "string"
}
},
"required": [
"filename"
]
}
]
},
"minItems": 0
},
"start": {
"description": "Start is the offset relative to the transaction's timestamp identifying the start of the span, in milliseconds.",
"type": [
"null",
"number"
]
},
"subtype": {
"description": "Subtype is a further sub-division of the type (e.g. postgresql, elasticsearch)",
"type": [
"null",
"string"
],
"maxLength": 1024
},
"sync": {
"description": "Sync indicates whether the span was executed synchronously or asynchronously.",
"type": [
"null",
"boolean"
]
},
"timestamp": {
"description": "Timestamp holds the recorded time of the event, UTC based and formatted as microseconds since Unix epoch",
"type": [
"null",
"integer"
]
},
"trace_id": {
"description": "TraceID holds the hex encoded 128 random bits ID of the correlated trace.",
"type": "string",
"maxLength": 1024
},
"transaction_id": {
"description": "TransactionID holds the hex encoded 64 random bits ID of the correlated transaction.",
"type": [
"null",
"string"
],
"maxLength": 1024
},
"type": {
"description": "Type holds the span's type, and can have specific keywords within the service's domain (eg: 'request', 'backgroundjob', etc)",
"type": "string",
"maxLength": 1024
}
},
"required": [
"id",
"trace_id",
"name",
"parent_id",
"type",
"duration"
],
"anyOf": [
{
"properties": {
"start": {
"type": "number"
}
},
"required": [
"start"
]
},
{
"properties": {
"timestamp": {
"type": "integer"
}
},
"required": [
"timestamp"
]
}
]
}