A newer version is available. For the latest information, see the
current release documentation.
Transaction API
editTransaction API
editThe following section contains information about:
Endpoint
editSend a HTTP POST request to the APM Server transactions endpoint:
http(s)://{hostname}:{port}/v1/transactions
For RUM send a HTTP POST request to the APM Server rum transactions endpoint instead:
http(s)://{hostname}:{port}/v1/rum/transactions
Schema Definition
editThe APM Server uses JSON Schema for validating requests. The specification for transactions is defined bellow:
Payload
edit{
"$id": "docs/spec/transactions/payload.json",
"title": "Transactions payload",
"description": "List of transactions wrapped in an object containing some other attributes normalized away from the transactions themselves",
"type": "object",
"properties": {
"service": {
"$ref": "../service.json"
},
"process": {
"$ref": "../process.json"
},
"system": {
"$ref": "../system.json"
},
"transactions": {
"type": "array",
"items": {
"$ref": "transaction.json"
},
"minItems": 1
}
},
"required": ["service", "transactions"]
}
Transaction
edit{
"$id": "docs/spec/transactions/transaction.json",
"type": "object",
"description": "Data captured by an agent representing an event occurring in a monitored service",
"properties": {
"context": {
"$ref": "../context.json"
},
"duration": {
"type": "number",
"description": "How long the transaction took to complete, in ms with 3 decimal points"
},
"id": {
"type": "string",
"description": "UUID for the transaction, referred by its spans",
"pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
},
"name": {
"type": ["string","null"],
"description": "Generic designation of a transaction in the scope of a single service (eg: 'GET /users/:id')",
"maxLength": 1024
},
"result": {
"type": ["string", "null"],
"description": "The result of the transaction. For HTTP-related transactions, this should be the status code formatted like 'HTTP 2xx'.",
"maxLength": 1024
},
"timestamp": {
"type": ["string", "null"],
"pattern": "Z$",
"format": "date-time",
"description": "Recorded time of the transaction, UTC based and formatted as YYYY-MM-DDTHH:mm:ss.sssZ"
},
"spans": {
"type": ["array", "null"],
"items": {
"$ref": "span.json"
},
"minItems": 0
},
"type": {
"type": "string",
"description": "Keyword of specific relevance in the service's domain (eg: 'request', 'backgroundjob', etc)",
"maxLength": 1024
},
"marks": {
"type": ["object", "null"],
"description": "A mark captures 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.",
"patternProperties": {
"^[^.*\"]*$": {
"$ref": "mark.json"
}
},
"additionalProperties": false
},
"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."
},
"span_count": {
"type": ["object", "null"],
"properties": {
"dropped": {
"type": ["object", "null"],
"properties": {
"total": {
"type": ["integer","null"],
"description": "Number of spans that have been dropped by the agent recording the transaction."
}
}
}
}
}
},
"required": ["id", "duration", "type"]
}
Span
edit{
"$id": "docs/spec/transactions/span.json",
"type": "object",
"properties": {
"id": {
"type": ["integer", "null"],
"description": "The locally unique ID of the span."
},
"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."
}
}
}
}
},
"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
},
"parent": {
"type": ["integer", "null"],
"description": "The locally unique ID of the parent of the span."
},
"stacktrace": {
"type": ["array", "null"],
"description": "List of stack frames with variable attributes (eg: lineno, filename, etc)",
"items": {
"$ref": "../stacktrace_frame.json"
},
"minItems": 0
},
"start": {
"type": "number",
"description": "Offset relative to the transaction's timestamp identifying the start of the span, in milliseconds"
},
"type": {
"type": "string",
"description": "Keyword of specific relevance in the service's domain (eg: 'db.postgresql.query', 'template.erb', etc)",
"maxLength": 1024
}
},
"dependencies": {
"parent": {
"required": ["id"]
}
},
"required": ["duration", "name", "start", "type"]
}
Service
edit{
"$id": "doc/spec/service.json",
"title": "Service",
"type": "object",
"properties": {
"agent": {
"description": "Name and version of the Elastic APM agent",
"type": "object",
"properties": {
"name": {
"description": "Name of the Elastic APM agent, e.g. \"Python\"",
"type": "string",
"maxLength": 1024
},
"version": {
"description": "Version of the Elastic APM agent, e.g.\"1.0.0\"",
"type": "string",
"maxLength": 1024
}
},
"required": ["name", "version"]
},
"framework": {
"description": "Name and version of the web framework used",
"type": ["object", "null"],
"properties": {
"name": {
"type": "string",
"maxLength": 1024
},
"version": {
"type": "string",
"maxLength": 1024
}
},
"required": ["name", "version"]
},
"language": {
"description": "Name and version of the programming language used",
"type": ["object", "null"],
"properties": {
"name": {
"type": "string",
"maxLength": 1024
},
"version": {
"type": ["string", "null"],
"maxLength": 1024
}
},
"required": ["name"]
},
"name": {
"description": "Immutable name of the service emitting this event",
"type": "string",
"pattern": "^[a-zA-Z0-9 _-]+$",
"maxLength": 1024
},
"environment": {
"description": "Environment name of the service, e.g. \"production\" or \"staging\"",
"type": ["string", "null"],
"maxLength": 1024
},
"runtime": {
"description": "Name and version of the language runtime running this service",
"type": ["object", "null"],
"properties": {
"name": {
"type": "string",
"maxLength": 1024
},
"version": {
"type": "string",
"maxLength": 1024
}
},
"required": ["name", "version"]
},
"version": {
"description": "Version of the service emitting this event",
"type": ["string", "null"],
"maxLength": 1024
}
},
"required": ["agent", "name"]
}
System
edit{
"$id": "doc/spec/system.json",
"title": "System",
"type": ["object", "null"],
"properties": {
"architecture": {
"description": "Architecture of the system the agent is running on.",
"type": ["string", "null"],
"maxLength": 1024
},
"hostname": {
"description": "Hostname of the system the agent is running on.",
"type": ["string", "null"],
"maxLength": 1024
},
"platform": {
"description": "Name of the system platform the agent is running on.",
"type": ["string", "null"],
"maxLength": 1024
}
}
}
Context
edit{
"$id": "doc/spec/context.json",
"title": "Context",
"description": "Any arbitrary contextual information regarding the event, captured by the agent, optionally provided by the user",
"type": ["object", "null"],
"properties": {
"custom": {
"description": "An arbitrary mapping of additional metadata to store with the event.",
"type": ["object", "null"],
"patternProperties": {
"^[^.*\"]*$": {}
},
"additionalProperties": false
},
"response": {
"type": ["object", "null"],
"properties": {
"finished": {
"description": "A boolean indicating whether the response was finished or not",
"type": ["boolean", "null"]
},
"headers": {
"description": "A mapping of HTTP headers of the response object",
"type": ["object", "null"],
"properties": {
"content-type": {
"type": ["string", "null"]
}
}
},
"headers_sent": {
"type": ["boolean", "null"]
},
"status_code": {
"description": "The HTTP status code of the response.",
"type": ["integer", "null"]
}
}
},
"request": {
"$ref": "request.json"
},
"tags": {
"type": ["object", "null"],
"description": "A flat mapping of user-defined tags with string values.",
"patternProperties": {
"^[^.*\"]*$": {
"type": ["string", "null"],
"maxLength": 1024
}
},
"additionalProperties": false
},
"user": {
"$ref": "user.json"
}
}
}
Stacktrace Frame
edit{
"$id": "docs/spec/stacktrace_frame.json",
"title": "Stacktrace",
"type": "object",
"description": "A stacktrace frame, contains various bits (most optional) describing the context of the frame",
"properties": {
"abs_path": {
"description": "The absolute path of the file involved in the stack frame",
"type": ["string", "null"]
},
"colno": {
"description": "Column number",
"type": ["integer", "null"]
},
"context_line": {
"description": "The line of code part of the stack frame",
"type": ["string", "null"]
},
"filename": {
"description": "The relative filename of the code involved in the stack frame, used e.g. to do error checksumming",
"type": "string"
},
"function": {
"description": "The function involved in the stack frame",
"type": ["string", "null"]
},
"library_frame": {
"description": "A boolean, indicating if this frame is from a library or user code",
"type": ["boolean", "null"]
},
"lineno": {
"description": "The line number of code part of the stack frame, used e.g. to do error checksumming",
"type": "integer"
},
"module": {
"description": "The module to which frame belongs to",
"type": ["string", "null"]
},
"post_context": {
"description": "The lines of code after the stack frame",
"type": ["array", "null"],
"minItems": 0,
"items": {
"type": "string"
}
},
"pre_context": {
"description": "The lines of code before the stack frame",
"type": ["array", "null"],
"minItems": 0,
"items": {
"type": "string"
}
},
"vars": {
"description": "Local variables for this stack frame",
"type": ["object", "null"],
"properties": {}
}
},
"required": ["filename", "lineno"]
}
Request
edit{
"$id": "docs/spec/http.json",
"title": "Request",
"description": "If a log record was generated as a result of a http request, the http interface can be used to collect this information.",
"type": ["object", "null"],
"properties": {
"body": {
"description": "Data should only contain the request body (not the query string). It can either be a dictionary (for standard HTTP requests) or a raw request body.",
"type": ["object", "string", "null"]
},
"env": {
"description": "The env variable is a compounded of environment information passed from the webserver.",
"type": ["object", "null"],
"properties": {}
},
"headers": {
"description": "Should include any headers sent by the requester. Cookies will be taken by headers if supplied.",
"type": ["object", "null"],
"properties": {
"content-type": {
"type": ["string", "null"]
},
"cookie": {
"description": "Cookies sent with the request. It is expected to have values delimited by semicolons.",
"type": ["string", "null"]
},
"user-agent": {
"type": ["string", "null"]
}
}
},
"http_version": {
"description": "HTTP version.",
"type": ["string", "null"],
"maxLength": 1024
},
"method": {
"description": "HTTP method.",
"type": "string",
"maxLength": 1024
},
"socket": {
"type": ["object", "null"],
"properties": {
"encrypted": {
"description": "Indicates whether request was sent as SSL/HTTPS request.",
"type": ["boolean", "null"]
},
"remote_address": {
"type": ["string", "null"]
}
}
},
"url": {
"description": "A complete Url, with scheme, host and path.",
"type": "object",
"properties": {
"raw": {
"type": ["string", "null"],
"description": "The 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.",
"maxLength": 1024
},
"protocol": {
"type": ["string", "null"],
"description": "The protocol of the request, e.g. 'https:'.",
"maxLength": 1024
},
"full": {
"type": ["string", "null"],
"description": "The full, possibly agent-assembled URL of the request, e.g https://example.com:443/search?q=elasticsearch#top.",
"maxLength": 1024
},
"hostname": {
"type": ["string", "null"],
"description": "The hostname of the request, e.g. 'example.com'.",
"maxLength": 1024
},
"port": {
"type": ["string", "null"],
"description": "The port of the request, e.g. '443'",
"maxLength": 1024
},
"pathname": {
"type": ["string", "null"],
"description": "The path of the request, e.g. '/search'",
"maxLength": 1024
},
"search": {
"description": "The search describes the query string of the request. It is expected to have values delimited by ampersands.",
"type": ["string", "null"],
"maxLength": 1024
},
"hash": {
"type": ["string", "null"],
"description": "The hash of the request URL, e.g. 'top'",
"maxLength": 1024
}
}
},
"cookies": {
"description": "A parsed key-value object of cookies",
"type": ["object", "null"]
}
},
"required": ["url", "method"]
}
User
edit{
"$id": "docs/spec/user.json",
"title": "User",
"description": "Describes the authenticated User for a request.",
"type": ["object", "null"],
"properties": {
"id": {
"description": "Identifier of the logged in user, e.g. the primary key of the user",
"type": ["string", "integer", "null"],
"maxLength": 1024
},
"email": {
"description": "Email of the logged in user",
"type": ["string", "null"],
"maxLength": 1024
},
"username": {
"description": "The username of the logged in user",
"type": ["string", "null"],
"maxLength": 1024
}
}
}
Examples
editRequest example:
curl http://localhost:8200/v1/transactions \ --header "Content-Type: application/json" \ --data @docs/data/intake-api/generated/transaction/payload.json
Example transaction requests:
Payload with several Transactions
edit{
"service": {
"name": "1234_service-12a3",
"version": "5.1.3",
"environment": "staging",
"language": {
"name": "ecmascript",
"version": "8"
},
"runtime": {
"name": "node",
"version": "8.0.0"
},
"framework": {
"name": "Express",
"version": "1.2.3"
},
"agent": {
"name": "elastic-node",
"version": "3.14.0"
}
},
"process": {
"pid": 1234,
"ppid": 6789,
"title": "node",
"argv": [
"node",
"server.js"
]
},
"system": {
"hostname": "prod1.example.com",
"architecture": "x64",
"platform": "darwin"
},
"transactions": [
{
"id": "945254c5-67a5-417e-8a4e-aa29efcbfb79",
"name": "GET /api/types",
"type": "request",
"duration": 32.592981,
"result": "success",
"timestamp": "2017-05-30T18:53:27.154Z",
"sampled": true,
"span_count": {
"dropped": {
"total": 2
}
},
"context": {
"request": {
"socket": {
"remote_address": "12.53.12.1",
"encrypted": true
},
"http_version": "1.1",
"method": "POST",
"url": {
"protocol": "https:",
"full": "https://www.example.com/p/a/t/h?query=string#hash",
"hostname": "www.example.com",
"port": "8080",
"pathname": "/p/a/t/h",
"search": "?query=string",
"hash": "#hash",
"raw": "/p/a/t/h?query=string#hash"
},
"headers": {
"user-agent": "Mozilla Chrome Edge",
"content-type": "text/html",
"cookie": "c1=v1; c2=v2",
"some-other-header": "foo",
"array": [
"foo",
"bar",
"baz"
]
},
"cookies": {
"c1": "v1",
"c2": "v2"
},
"env": {
"SERVER_SOFTWARE": "nginx",
"GATEWAY_INTERFACE": "CGI/1.1"
},
"body": {
"str": "hello world",
"additional": {
"foo": {},
"bar": 123,
"req": "additional information"
}
}
},
"response": {
"status_code": 200,
"headers": {
"content-type": "application/json"
},
"headers_sent": true,
"finished": true
},
"user": {
"id": "99",
"username": "foo",
"email": "foo@example.com"
},
"tags": {
"organization_uuid": "9f0e9d64-c185-4d21-a6f4-4673ed561ec8"
},
"custom": {
"my_key": 1,
"some_other_value": "foo bar",
"and_objects": {
"foo": [
"bar",
"baz"
]
},
"(": "not a valid regex and that is fine"
}
},
"spans": [
{
"id": 0,
"parent": null,
"name": "SELECT FROM product_types",
"type": "db.postgresql.query",
"start": 2.83092,
"duration": 3.781912,
"stacktrace": [
{
"function": "onread",
"abs_path": "net.js",
"filename": "net.js",
"lineno": 547,
"library_frame": true,
"vars": {
"key": "value"
},
"module": "some module",
"colno": 4,
"context_line": "line3",
"pre_context": [
" var trans = this.currentTransaction",
""
],
"post_context": [
" ins.currentTransaction = prev",
" return result",
"}"
]
},
{
"filename": "my2file.js",
"lineno": 10
}
],
"context": {
"db": {
"instance": "customers",
"statement": "SELECT * FROM product_types WHERE user_id=?",
"type": "sql",
"user": "readonly_user"
},
"http": {
"url": "http://localhost:8000"
}
}
},
{
"id": 1,
"parent": 0,
"name": "GET /api/types",
"type": "request",
"start": 0,
"duration": 32.592981
},
{
"id": 2,
"parent": 1,
"name": "GET /api/types",
"type": "request",
"start": 1.845,
"duration": 3.5642981,
"stacktrace": [],
"context": {}
},
{
"id": 3,
"parent": 2,
"name": "GET /api/types",
"type": "request",
"start": 0,
"duration": 13.9802981,
"stacktrace": null,
"context": null
}
],
"marks": {
"navigationTiming": {
"appBeforeBootstrap": 608.9300000000001,
"navigationStart": -21
},
"another_mark": {
"some_long": 10,
"some_float": 10.0
},
"performance": {}
}
},
{
"id": "85925e55-b43f-4340-a8e0-df1906ecbf7a",
"name": "GET /api/types",
"type": "request",
"duration": 13.980558,
"result": "failure",
"timestamp": "2017-05-30T18:53:42.281Z",
"spans": [],
"sampled": true
},
{
"id": "85925e55-b43f-4340-a8e0-df1906ecbf78",
"name": "GET /api/types",
"type": "request",
"duration": 13.980558,
"result": "200",
"timestamp": "2017-05-30T18:53:42Z",
"sampled": false
},
{
"id": "85925e55-b43f-4340-a8e0-df1906ecbfa9",
"name": "GET /api/types",
"type": "request",
"duration": 13.980558,
"result": "200",
"timestamp": "2017-05-30T18:53:42.281999Z",
"sampled": true,
"span_count": {
"dropped": {
"total": 258
}
},
"spans": [
{
"id": 15,
"name": "SELECT FROM product_types",
"type": "db.postgresql.query",
"start": 2.83092,
"duration": 3.781912,
"stacktrace": [],
"context": {
"db": {
"instance": "customers",
"statement": "SELECT * FROM product_types WHERE user_id=?",
"type": "sql",
"user": "readonly_user"
}
}
}
]
}
]
}
Payload with a minimal Transaction
edit{
"service": {
"name": "service1",
"agent": {
"name": "python",
"version": "1.0"
}
},
"transactions": [
{
"id": "945254c5-67a5-417e-8a4e-aa29efcbfb79",
"type": "request",
"duration": 32.592981
}
]
}
Payload with a Transaction with a minimal Span
edit{
"service": {
"name": "service1",
"agent": {
"name": "python",
"version": "1.0"
}
},
"transactions": [
{
"id": "945254c5-67a5-417e-8a4e-aa29efcbfb79",
"type": "request",
"duration": 32.592981,
"timestamp": "2017-05-30T18:53:27.154Z",
"spans": [
{
"id": 100000000000,
"name": "GET /api/types",
"type": "request",
"start": 0,
"duration": 32.592981
}
]
}
]
}