[APM] Add "Queries and data model" section to APM readme (#114025)

x-pack/plugins/apm/dev_docs/apm_queries.md

@@ -4,7 +4,7 @@ Transactions are stored in two different formats:
 
 #### Individual transactions document
 
-A single transaction with a latency of 2ms
+A single transaction event where `transaction.duration.us` is the latency.
 
 ```json
 {
@@ -18,7 +18,7 @@ A single transaction with a latency of 2ms
 or
 
 #### Aggregated (metric) document
-A pre-aggregated document where `_doc_count` is the number of original transactions, and `transaction.duration.histogram` is the latency distribution. 
+A pre-aggregated document where `_doc_count` is the number of transaction events, and `transaction.duration.histogram` is the latency distribution. 
 
 ```json
 {
@@ -34,7 +34,7 @@ A pre-aggregated document where `_doc_count` is the number of original transacti
 }
 ```
 
-The decision to use aggregated transactions or not is determined in [`getSearchAggregatedTransactions`](https://github.com/elastic/kibana/blob/a2ac439f56313b7a3fc4708f54a4deebf2615136/x-pack/plugins/apm/server/lib/helpers/aggregated_transactions/index.ts#L53-L79) and then used to [specify the index](https://github.com/elastic/kibana/blob/a2ac439f56313b7a3fc4708f54a4deebf2615136/x-pack/plugins/apm/server/lib/suggestions/get_suggestions.ts#L30-L32) and the [latency field](https://github.com/elastic/kibana/blob/a2ac439f56313b7a3fc4708f54a4deebf2615136/x-pack/plugins/apm/server/lib/alerts/chart_preview/get_transaction_duration.ts#L62-L65)
+The decision to use aggregated transactions or not is determined in [`getSearchAggregatedTransactions`](https://github.com/elastic/kibana/blob/a2ac439f56313b7a3fc4708f54a4deebf2615136/x-pack/plugins/apm/server/lib/helpers/aggregated_transactions/index.ts#L53-L79) and then used to specify [the transaction index](https://github.com/elastic/kibana/blob/a2ac439f56313b7a3fc4708f54a4deebf2615136/x-pack/plugins/apm/server/lib/suggestions/get_suggestions.ts#L30-L32) and [the latency field](https://github.com/elastic/kibana/blob/a2ac439f56313b7a3fc4708f54a4deebf2615136/x-pack/plugins/apm/server/lib/alerts/chart_preview/get_transaction_duration.ts#L62-L65)
 
 ### Latency
 
@@ -77,7 +77,7 @@ Noteworthy fields: `transaction.duration.us`, `transaction.duration.histogram`
 }
 ```
 
-Please note: `metricset.name: transaction` was only recently introduced. To retain backwards compatability we still use the old filter `{ "exists": { "field": "transaction.duration.histogram" }}` when filtering for aggregated transactions.
+Please note: `metricset.name: transaction` was only recently introduced. To retain backwards compatability we still use the old filter `{ "exists": { "field": "transaction.duration.histogram" }}` when filtering for aggregated transactions ([see example](https://github.com/elastic/kibana/blob/2c8686770e64b82cf8e1db5a22327d40d5f8ce45/x-pack/plugins/apm/server/lib/helpers/aggregated_transactions/index.ts#L89-L95)).
 
 ### Throughput
 

x-pack/plugins/apm/dev_docs/learning_material.md

@@ -0,0 +1,12 @@
+# Suggested reading and learning material
+
+The following list outlines recommened materials for new-comers to APM UI.
+
+### Elasticsearch
+ - [What is Elasticsearch?](https://www.elastic.co/guide/en/elasticsearch/reference/current/elasticsearch-intro.html)
+ - [Search your data](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-your-data.html#search-your-data)
+ - [Query DSL](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl.html)
+ - [Aggregations](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations.html)
+
+### Observability
+  - [Observability Fundamentals](https://learn.elastic.co/elasticians/learn/course/internal/view/elearning/391/observability-fundamentals)

x-pack/plugins/apm/dev_docs/local_setup.md

@@ -43,8 +43,7 @@ This will create:
 
 ## Debugging Elasticsearch queries
 
-All APM api endpoints accept `_inspect=true` as a query param that will result in the underlying ES query being outputted in the Kibana backend process.
+All APM api endpoints accept `_inspect=true` as a query param that will output all Elasticsearch queries performed in that request. It will be available in the browser response and on localhost it is also available in the Kibana Node.js process output.
 
 Example:
 `/api/apm/services/my_service?_inspect=true`
-diff --git a/x-pack/plugins/apm/dev_docs/linting.md b/x-pack/plugins/apm/dev_docs/linting.md

x-pack/plugins/apm/readme.md

@@ -22,6 +22,7 @@ yarn storybook apm
 All files with a .stories.tsx extension will be loaded. You can access the development environment at http://localhost:9001.
 
 ## Further resources
+- [Queries and data model](./dev_docs/apm_queries.md)
 - [VSCode setup instructions](./dev_docs/vscode_setup.md)
 - [Github PR commands](./dev_docs/github_commands.md)
 - [Routing and Linking](./dev_docs/routing_and_linking.md)