IMPORTANT: No additional bug fixes or documentation updates
will be released for this version. For the latest information, see the
current release documentation.
Transactions
editTransactions
editTransactions are events corresponding to an incoming request or similar task occurring in a monitored service.
Transaction Schema
editAPM Server uses JSON Schema to validate requests. The specification for transactions is defined on GitHub and included below:
{
"$id": "docs/spec/v2/transaction",
"type": "object",
"properties": {
"context": {
"description": "Context holds arbitrary contextual information for the event.",
"type": [
"null",
"object"
],
"properties": {
"cloud": {
"description": "Cloud holds fields related to the cloud or infrastructure the events are coming from.",
"type": [
"null",
"object"
],
"properties": {
"origin": {
"description": "Origin contains the self-nested field groups for cloud.",
"type": [
"null",
"object"
],
"properties": {
"account": {
"description": "The cloud account or organization id used to identify different entities in a multi-tenant environment.",
"type": [
"null",
"object"
],
"properties": {
"id": {
"description": "The cloud account or organization id used to identify different entities in a multi-tenant environment.",
"type": [
"null",
"string"
]
}
}
},
"provider": {
"description": "Name of the cloud provider.",
"type": [
"null",
"string"
]
},
"region": {
"description": "Region in which this host, resource, or service is located.",
"type": [
"null",
"string"
]
},
"service": {
"description": "The cloud service name is intended to distinguish services running on different platforms within a provider.",
"type": [
"null",
"object"
],
"properties": {
"name": {
"description": "The cloud service name is intended to distinguish services running on different platforms within a provider.",
"type": [
"null",
"string"
]
}
}
}
}
}
}
},
"custom": {
"description": "Custom can contain additional metadata to be stored with the event. The format is unspecified and can be deeply nested objects. The information will not be indexed or searchable in Elasticsearch.",
"type": [
"null",
"object"
]
},
"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"
]
}
}
},
"page": {
"description": "Page holds information related to the current page and page referers. It is only sent from RUM agents.",
"type": [
"null",
"object"
],
"properties": {
"referer": {
"description": "Referer holds the URL of the page that 'linked' to the current page.",
"type": [
"null",
"string"
]
},
"url": {
"description": "URL of the current page",
"type": [
"null",
"string"
]
}
}
},
"request": {
"description": "Request describes the HTTP request information in case the event was created as a result of an HTTP request.",
"type": [
"null",
"object"
],
"properties": {
"body": {
"description": "Body only contais the request bod, not the query string information. It can either be a dictionary (for standard HTTP requests) or a raw request body.",
"type": [
"null",
"string",
"object"
]
},
"cookies": {
"description": "Cookies used by the request, parsed as key-value objects.",
"type": [
"null",
"object"
]
},
"env": {
"description": "Env holds environment variable information passed to the monitored service.",
"type": [
"null",
"object"
]
},
"headers": {
"description": "Headers includes any HTTP headers sent by the requester. Cookies will be taken by headers if supplied.",
"type": [
"null",
"object"
],
"additionalProperties": false,
"patternProperties": {
"[.*]*$": {
"type": [
"null",
"array",
"string"
],
"items": {
"type": "string"
}
}
}
},
"http_version": {
"description": "HTTPVersion holds information about the used HTTP version.",
"type": [
"null",
"string"
],
"maxLength": 1024
},
"method": {
"description": "Method holds information about the method of the HTTP request.",
"type": "string",
"maxLength": 1024
},
"socket": {
"description": "Socket holds information related to the recorded request, such as whether or not data were encrypted and the remote address.",
"type": [
"null",
"object"
],
"properties": {
"encrypted": {
"description": "Encrypted indicates whether a request was sent as TLS/HTTPS request. DEPRECATED: this field will be removed in a future release.",
"type": [
"null",
"boolean"
]
},
"remote_address": {
"description": "RemoteAddress holds the network address sending the request. It should be obtained through standard APIs and not be parsed from any headers like 'Forwarded'.",
"type": [
"null",
"string"
]
}
}
},
"url": {
"description": "URL holds information sucha as the raw URL, scheme, host and path.",
"type": [
"null",
"object"
],
"properties": {
"full": {
"description": "Full, possibly agent-assembled URL of the request, e.g. https://example.com:443/search?q=elasticsearch#top.",
"type": [
"null",
"string"
],
"maxLength": 1024
},
"hash": {
"description": "Hash of the request URL, e.g. 'top'",
"type": [
"null",
"string"
],
"maxLength": 1024
},
"hostname": {
"description": "Hostname information of the request, e.g. 'example.com'.\"",
"type": [
"null",
"string"
],
"maxLength": 1024
},
"pathname": {
"description": "Path of the request, e.g. '/search'",
"type": [
"null",
"string"
],
"maxLength": 1024
},
"port": {
"description": "Port of the request, e.g. '443'. Can be sent as string or int.",
"type": [
"null",
"string",
"integer"
],
"maxLength": 1024
},
"protocol": {
"description": "Protocol information for the recorded request, e.g. 'https:'.",
"type": [
"null",
"string"
],
"maxLength": 1024
},
"raw": {
"description": "Raw unparsed URL of the HTTP request line, e.g https://example.com:443/search?q=elasticsearch. This URL may be absolute or relative. For more details, see https://www.w3.org/Protocols/rfc2616/rfc2616-sec5.html#sec5.1.2.",
"type": [
"null",
"string"
],
"maxLength": 1024
},
"search": {
"description": "Search contains the query string information of the request. It is expected to have values delimited by ampersands.",
"type": [
"null",
"string"
],
"maxLength": 1024
}
}
}
},
"required": [
"method"
]
},
"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"
]
},
"finished": {
"description": "Finished indicates whether the response was finished or not.",
"type": [
"null",
"boolean"
]
},
"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"
}
}
}
},
"headers_sent": {
"description": "HeadersSent indicates whether http headers were sent.",
"type": [
"null",
"boolean"
]
},
"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"
]
}
}
},
"service": {
"description": "Service related information can be sent per event. 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
}
},
"user": {
"description": "User holds information about the correlated user for this event. If user data are provided here, all user related information from metadata is ignored, otherwise the metadata's user information will be stored with the event.",
"type": [
"null",
"object"
],
"properties": {
"domain": {
"description": "Domain of the logged in user",
"type": [
"null",
"string"
],
"maxLength": 1024
},
"email": {
"description": "Email of the user.",
"type": [
"null",
"string"
],
"maxLength": 1024
},
"id": {
"description": "ID identifies the logged in user, e.g. can be the primary key of the user",
"type": [
"null",
"string",
"integer"
],
"maxLength": 1024
},
"username": {
"description": "Name of the user.",
"type": [
"null",
"string"
],
"maxLength": 1024
}
}
}
}
},
"dropped_spans_stats": {
"description": "DroppedSpanStats holds information about spans that were dropped (for example due to transaction_max_spans or exit_span_min_duration).",
"type": [
"null",
"array"
],
"items": {
"type": "object",
"properties": {
"destination_service_resource": {
"description": "DestinationServiceResource identifies the destination service resource being operated on. e.g. 'http://elastic.co:80', 'elasticsearch', 'rabbitmq/queue_name'.",
"type": [
"null",
"string"
],
"maxLength": 1024
},
"duration": {
"description": "Duration holds duration aggregations about the dropped span.",
"type": [
"null",
"object"
],
"properties": {
"count": {
"description": "Count holds the number of times the dropped span happened.",
"type": [
"null",
"integer"
],
"minimum": 1
},
"sum": {
"description": "Sum holds dimensions about the dropped span's duration.",
"type": [
"null",
"object"
],
"properties": {
"us": {
"description": "Us represents the summation of the span duration.",
"type": [
"null",
"integer"
],
"minimum": 0
}
}
}
}
},
"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
]
},
"service_target_name": {
"description": "ServiceTargetName identifies the instance name of the target service being operated on",
"type": [
"null",
"string"
],
"maxLength": 512
},
"service_target_type": {
"description": "ServiceTargetType identifies the type of the target service being operated on e.g. 'oracle', 'rabbitmq'",
"type": [
"null",
"string"
],
"maxLength": 512
}
}
},
"minItems": 0
},
"duration": {
"description": "Duration how long the transaction took to complete, in milliseconds with 3 decimal points.",
"type": "number",
"minimum": 0
},
"experience": {
"description": "UserExperience holds metrics for measuring real user experience. This information is only sent by RUM agents.",
"type": [
"null",
"object"
],
"properties": {
"cls": {
"description": "CumulativeLayoutShift holds the Cumulative Layout Shift (CLS) metric value, or a negative value if CLS is unknown. See https://web.dev/cls/",
"type": [
"null",
"number"
],
"minimum": 0
},
"fid": {
"description": "FirstInputDelay holds the First Input Delay (FID) metric value, or a negative value if FID is unknown. See https://web.dev/fid/",
"type": [
"null",
"number"
],
"minimum": 0
},
"longtask": {
"description": "Longtask holds longtask duration/count metrics.",
"type": [
"null",
"object"
],
"properties": {
"count": {
"description": "Count is the total number of of longtasks.",
"type": "integer",
"minimum": 0
},
"max": {
"description": "Max longtask duration",
"type": "number",
"minimum": 0
},
"sum": {
"description": "Sum of longtask durations",
"type": "number",
"minimum": 0
}
},
"required": [
"count",
"max",
"sum"
]
},
"tbt": {
"description": "TotalBlockingTime holds the Total Blocking Time (TBT) metric value, or a negative value if TBT is unknown. See https://web.dev/tbt/",
"type": [
"null",
"number"
],
"minimum": 0
}
}
},
"faas": {
"description": "FAAS holds fields related to Function as a Service events.",
"type": [
"null",
"object"
],
"properties": {
"coldstart": {
"description": "Indicates whether a function invocation was a cold start or not.",
"type": [
"null",
"boolean"
]
},
"execution": {
"description": "The request id of the function invocation.",
"type": [
"null",
"string"
]
},
"id": {
"description": "A unique identifier of the invoked serverless function.",
"type": [
"null",
"string"
]
},
"name": {
"description": "The lambda function name.",
"type": [
"null",
"string"
]
},
"trigger": {
"description": "Trigger attributes.",
"type": [
"null",
"object"
],
"properties": {
"request_id": {
"description": "The id of the origin trigger request.",
"type": [
"null",
"string"
]
},
"type": {
"description": "The trigger type.",
"type": [
"null",
"string"
]
}
}
},
"version": {
"description": "The lambda function version.",
"type": [
"null",
"string"
]
}
}
},
"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
},
"marks": {
"description": "Marks capture the timing of a significant event during the lifetime of a transaction. Marks are organized into groups and can be set by the user or the agent. Marks are only reported by RUM agents.",
"type": [
"null",
"object"
],
"additionalProperties": {
"type": [
"null",
"object"
],
"additionalProperties": {
"type": [
"null",
"number"
]
}
}
},
"name": {
"description": "Name is the generic designation of a transaction in the scope of a single service, eg: 'GET /users/:id'.",
"type": [
"null",
"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 transaction with a limited set of permitted values, describing the success or failure of the transaction from the service's perspective. It is used for calculating error rates for incoming requests. Permitted values: success, failure, unknown.",
"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": [
"null",
"string"
],
"maxLength": 1024
},
"result": {
"description": "Result of the transaction. For HTTP-related transactions, this should be the status code formatted like 'HTTP 2xx'.",
"type": [
"null",
"string"
],
"maxLength": 1024
},
"sample_rate": {
"description": "SampleRate applied to the monitored service at the time where this transaction was recorded. Allowed values are [0..1]. A SampleRate \u003c1 indicates that not all spans are recorded.",
"type": [
"null",
"number"
]
},
"sampled": {
"description": "Sampled indicates whether or not the full information for a transaction is captured. If a transaction is unsampled no spans and less context information will be reported.",
"type": [
"null",
"boolean"
]
},
"session": {
"description": "Session holds optional transaction session information for RUM.",
"type": [
"null",
"object"
],
"properties": {
"id": {
"description": "ID holds a session ID for grouping a set of related transactions.",
"type": "string",
"maxLength": 1024
},
"sequence": {
"description": "Sequence holds an optional sequence number for a transaction within a session. It is not meaningful to compare sequences across two different sessions.",
"type": [
"null",
"integer"
],
"minimum": 1
}
},
"required": [
"id"
]
},
"span_count": {
"description": "SpanCount counts correlated spans.",
"type": "object",
"properties": {
"dropped": {
"description": "Dropped is the number of correlated spans that have been dropped by the APM agent recording the transaction.",
"type": [
"null",
"integer"
]
},
"started": {
"description": "Started is the number of correlated spans that are recorded.",
"type": "integer"
}
},
"required": [
"started"
]
},
"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
},
"type": {
"description": "Type expresses the transaction's type as keyword that has specific relevance within the service's domain, eg: 'request', 'backgroundjob'.",
"type": "string",
"maxLength": 1024
}
},
"required": [
"trace_id",
"id",
"type",
"span_count",
"duration"
]
}