Split spec into multiple files

[felixbarny]

This splits the monolithic spec into smaller files. It also creates a README.md on the agents dir and renames docs/agents to specs/agents.

We started that with recent spec proposals like #307 and https://github.com/elastic/apm/pull/314/files. Mainly because the files are more coherent and smaller that way. When having the whole spec in one file, that could grow quite big. Especially going forward when we’ll hopefully have specs for all new cross-agent features.

This will cause quite a few conflicts with existing spec PRs. I want to merge this one first and then I’ll resolve the conflicts on the spec PRs. This will make it clearer what has actually changed on the spec PRs.

Preview: https://github.com/felixbarny/apm/tree/modular-spec/specs/agents

[beniwohli]

Generally, I like it a lot. Did you consider merging some of the shorter "chapters", e.g. spans and transactions, or exception tracking and log correlation? That would give those pages a bit more substance.

[felixbarny]

I think the missing substance mainly means that these areas are underspecified at the moment.
For example, #314 will add more content that doesn't apply to transactions but only to spans. For that spec, I'm actually thinking about putting it in tracing-spans-discarding.md, or similar.
#307 will add more to the distributed tracing and sampling specs, #299 will add more to the transaction and span specs.

For exception tracking and log correlation, I think those topics are not related enough to be in one file.

In general, I'm more comfortable with short spec files than mixing things that are not coherent. Similar to how I'd structure source code.

[felixbarny]

felixbarny removed the request for review from elastic/apm-pm

because there are no actual changes to the spec, only it's structure

[axw]

Thanks! I think this will be much more maintainable and readable.

[felixbarny]

Based on the many 👍 I got on slack, I'm going to merge this now so that I can rebase the other spec PRs on top of it.