Official Definitions for Transaction and Trace

[gingerwizard]

Request for official definitions for these in the docs. There seems to be some variation depending on the agent. This is more useful for messaging and when communicating in the field.

@asawariS @jamiesmith

[roncohen]

@gingerwizard there are some big naming changes coming up, we'll make sure we get a proper definition written after.

[gingerwizard]

@roncohen if would be nice to know how the schema changes as well between rc2 and GA. Nothing formal just some of the big points. I suspect it will be easier for us to recapture our dataset.

[roncohen]

@gingerwizard we try to keep https://github.com/elastic/apm-server/blob/master/CHANGELOG.asciidoc#breaking-changes updated.

[gingerwizard]

@roncohen super useful thanks.

[simitt]

We currently embed the json spec for the input API in the official docs for transactions and errors.
The embedded schema definitions contain descriptions for the objects and keys, e.g.

I'd appreciate if we werent duplicating descriptions, as this gets easily out of sync.
What do you think about removing the description from the json schema files and instead explicitly add a description section to the docs to make it more user friendly?

[roncohen]

I think this issue meant to ask for a couple of paragraphs that explains the general data model in the big picture and how the different document types are related. E.g. what is a span? What does a span represent? How does it relate to transactions? etc.

People can then go into details in the field descriptions that we already have.