Transaction API

The following section contains information about:

Endpoint

Send 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

The APM Server uses JSON Schema for validating requests. The specification for transactions is defined bellow:

Payload

{
    "$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

{
    "$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

{
    "$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

{
    "$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

{
    "$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

{
    "$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

{
    "$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

{
    "$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

{
    "$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

Request 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

{
    "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

{
    "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

{
    "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
                }
            ]
        }
    ]
}