mirror of
https://github.com/elastic/kibana.git
synced 2025-04-24 09:48:58 -04:00
Update APM queries development doc (#114268)
* Add links to field references and GET requests to the examples * Add troubleshooting info for failed requests * Add data model and running examples section * Add GET requests for query examples * Add `metricset` possible values Co-authored-by: Søren Louv-Jansen <sorenlouv@gmail.com> * Add transaction based and metric based queries Co-authored-by: Søren Louv-Jansen <sorenlouv@gmail.com>
This commit is contained in:
Giorgos Bamparopoulos
GitHub
parent
ab7e3e8d39
commit
2dece3d446
1 changed files with 126 additions and 31 deletions
|
|
@ -1,3 +1,9 @@
|
|||
# Data model
|
||||
Elastic APM agents capture different types of information from within their instrumented applications. These are known as events, and can be spans, transactions, errors, or metrics. You can find more information [here](https://www.elastic.co/guide/en/apm/get-started/current/apm-data-model.html).
|
||||
|
||||
# Running examples
|
||||
You can run the example queries on the [edge cluster](https://edge-oblt.elastic.dev/) or any another cluster that contains APM data.
|
||||
|
||||
# Transactions
|
||||
|
||||
Transactions are stored in two different formats:
|
||||
|
|
@ -34,6 +40,8 @@ A pre-aggregated document where `_doc_count` is the number of transaction events
|
|||
}
|
||||
```
|
||||
|
||||
You can find all the APM transaction fields [here](https://www.elastic.co/guide/en/apm/server/current/exported-fields-apm-transaction.html).
|
||||
|
||||
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
|
||||
|
|
@ -45,6 +53,7 @@ Noteworthy fields: `transaction.duration.us`, `transaction.duration.histogram`
|
|||
#### Transaction-based latency
|
||||
|
||||
```json
|
||||
GET apm-*-transaction-*,traces-apm*/_search?terminate_after=1000
|
||||
{
|
||||
"size": 0,
|
||||
"query": {
|
||||
|
|
@ -61,6 +70,7 @@ Noteworthy fields: `transaction.duration.us`, `transaction.duration.histogram`
|
|||
#### Metric-based latency
|
||||
|
||||
```json
|
||||
GET apm-*-metric-*,metrics-apm*/_search?terminate_after=1000
|
||||
{
|
||||
"size": 0,
|
||||
"query": {
|
||||
|
|
@ -85,14 +95,64 @@ Throughput is the number of transactions per minute. This can be calculated usin
|
|||
|
||||
Noteworthy fields: None (based on `doc_count`)
|
||||
|
||||
```js
|
||||
#### Transaction-based throughput
|
||||
|
||||
```json
|
||||
GET apm-*-transaction-*,traces-apm*/_search?terminate_after=1000
|
||||
{
|
||||
"size": 0,
|
||||
"query": {
|
||||
// same filters as for latency
|
||||
"bool": {
|
||||
"filter": [{ "terms": { "processor.event": ["transaction"] } }]
|
||||
}
|
||||
},
|
||||
"aggs": {
|
||||
"throughput": { "rate": { "unit": "minute" } }
|
||||
"timeseries": {
|
||||
"date_histogram": {
|
||||
"field": "@timestamp",
|
||||
"fixed_interval": "60s"
|
||||
},
|
||||
"aggs": {
|
||||
"throughput": {
|
||||
"rate": {
|
||||
"unit": "minute"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
#### Metric-based throughput
|
||||
|
||||
```json
|
||||
GET apm-*-metric-*,metrics-apm*/_search?terminate_after=1000
|
||||
{
|
||||
"size": 0,
|
||||
"query": {
|
||||
"bool": {
|
||||
"filter": [
|
||||
{ "terms": { "processor.event": ["metric"] } },
|
||||
{ "term": { "metricset.name": "transaction" } }
|
||||
]
|
||||
}
|
||||
},
|
||||
"aggs": {
|
||||
"timeseries": {
|
||||
"date_histogram": {
|
||||
"field": "@timestamp",
|
||||
"fixed_interval": "60s"
|
||||
},
|
||||
"aggs": {
|
||||
"throughput": {
|
||||
"rate": {
|
||||
"unit": "minute"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
|
@ -102,11 +162,41 @@ Noteworthy fields: None (based on `doc_count`)
|
|||
Failed transaction rate is the number of transactions with `event.outcome=failure` per minute.
|
||||
Noteworthy fields: `event.outcome`
|
||||
|
||||
```js
|
||||
#### Transaction-based failed transaction rate
|
||||
|
||||
```json
|
||||
GET apm-*-transaction-*,traces-apm*/_search?terminate_after=1000
|
||||
{
|
||||
"size": 0,
|
||||
"query": {
|
||||
// same filters as for latency
|
||||
"bool": {
|
||||
"filter": [{ "terms": { "processor.event": ["transaction"] } }]
|
||||
}
|
||||
},
|
||||
"aggs": {
|
||||
"outcomes": {
|
||||
"terms": {
|
||||
"field": "event.outcome",
|
||||
"include": ["failure", "success"]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Metric-based failed transaction rate
|
||||
|
||||
```json
|
||||
GET apm-*-metric-*,metrics-apm*/_search?terminate_after=1000
|
||||
{
|
||||
"size": 0,
|
||||
"query": {
|
||||
"bool": {
|
||||
"filter": [
|
||||
{ "terms": { "processor.event": ["metric"] } },
|
||||
{ "term": { "metricset.name": "transaction" } }
|
||||
]
|
||||
}
|
||||
},
|
||||
"aggs": {
|
||||
"outcomes": {
|
||||
|
|
@ -121,7 +211,7 @@ Noteworthy fields: `event.outcome`
|
|||
|
||||
# System metrics
|
||||
|
||||
System metrics are captured periodically (every 60 seconds by default).
|
||||
System metrics are captured periodically (every 60 seconds by default). You can find all the System Metrics fields [here](https://www.elastic.co/guide/en/apm/server/current/exported-fields-system.html).
|
||||
|
||||
### CPU
|
||||
|
||||
|
|
@ -146,6 +236,7 @@ Noteworthy fields: `system.cpu.total.norm.pct`, `system.process.cpu.total.norm.p
|
|||
#### Query
|
||||
|
||||
```json
|
||||
GET apm-*-metric-*,metrics-apm*/_search?terminate_after=1000
|
||||
{
|
||||
"size": 0,
|
||||
"query": {
|
||||
|
|
@ -185,18 +276,17 @@ Noteworthy fields: `system.memory.actual.free`, `system.memory.total`,
|
|||
|
||||
#### Query
|
||||
|
||||
```js
|
||||
```json
|
||||
GET apm-*-metric-*,metrics-apm*/_search?terminate_after=1000
|
||||
{
|
||||
"size": 0,
|
||||
"query": {
|
||||
"bool": {
|
||||
"filter": [
|
||||
{ "terms": { "processor.event": ["metric"] }},
|
||||
{ "terms": { "metricset.name": ["app"] }}
|
||||
|
||||
// ensure the memory fields exists
|
||||
{ "terms": { "metricset.name": ["app"] }},
|
||||
{ "exists": { "field": "system.memory.actual.free" }},
|
||||
{ "exists": { "field": "system.memory.total" }},
|
||||
{ "exists": { "field": "system.memory.total" }}
|
||||
]
|
||||
}
|
||||
},
|
||||
|
|
@ -213,7 +303,7 @@ Noteworthy fields: `system.memory.actual.free`, `system.memory.total`,
|
|||
}
|
||||
```
|
||||
|
||||
Above example is overly simplified. In reality [we do a bit more](https://github.com/elastic/kibana/blob/fe9b5332e157fd456f81aecfd4ffa78d9e511a66/x-pack/plugins/apm/server/lib/metrics/by_agent/shared/memory/index.ts#L51-L71) to properly calculate memory usage inside containers
|
||||
The above example is overly simplified. In reality [we do a bit more](https://github.com/elastic/kibana/blob/fe9b5332e157fd456f81aecfd4ffa78d9e511a66/x-pack/plugins/apm/server/lib/metrics/by_agent/shared/memory/index.ts#L51-L71) to properly calculate memory usage inside containers. Please note that an [Exists Query](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-exists-query.html) is used in the filter context in the query to ensure that the memory fields exist.
|
||||
|
||||
|
||||
|
||||
|
|
@ -268,6 +358,7 @@ Noteworthy fields: `transaction.name`, `transaction.type`, `span.type`, `span.su
|
|||
#### Query
|
||||
|
||||
```json
|
||||
GET apm-*-metric-*,metrics-apm*/_search?terminate_after=1000
|
||||
{
|
||||
"size": 0,
|
||||
"query": {
|
||||
|
|
@ -330,6 +421,7 @@ A pre-aggregated document with 73 span requests from opbeans-ruby to elasticsear
|
|||
The latency between a service and an (external) endpoint
|
||||
|
||||
```json
|
||||
GET apm-*-metric-*,metrics-apm*/_search?terminate_after=1000
|
||||
{
|
||||
"size": 0,
|
||||
"query": {
|
||||
|
|
@ -360,6 +452,7 @@ Captures the number of requests made from a service to an (external) endpoint
|
|||
#### Query
|
||||
|
||||
```json
|
||||
GET apm-*-metric-*,metrics-apm*/_search?terminate_after=1000
|
||||
{
|
||||
"size": 0,
|
||||
"query": {
|
||||
|
|
@ -372,10 +465,17 @@ Captures the number of requests made from a service to an (external) endpoint
|
|||
}
|
||||
},
|
||||
"aggs": {
|
||||
"throughput": {
|
||||
"rate": {
|
||||
"field": "span.destination.service.response_time.count",
|
||||
"unit": "minute"
|
||||
"timeseries": {
|
||||
"date_histogram": {
|
||||
"field": "@timestamp",
|
||||
"fixed_interval": "60s"
|
||||
},
|
||||
"aggs": {
|
||||
"throughput": {
|
||||
"rate": {
|
||||
"unit": "minute"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
@ -390,27 +490,17 @@ Most Elasticsearch queries will need to have one or more filters. There are a co
|
|||
- stability: Running an aggregation on unrelated documents could cause the entire query to fail
|
||||
- performance: limiting the number of documents will make the query faster
|
||||
|
||||
```js
|
||||
```json
|
||||
GET apm-*-metric-*,metrics-apm*/_search?terminate_after=1000
|
||||
{
|
||||
"query": {
|
||||
"bool": {
|
||||
"filter": [
|
||||
// service name
|
||||
{ "term": { "service.name": "opbeans-go" }},
|
||||
|
||||
// service environment
|
||||
{ "term": { "service.environment": "testing" }}
|
||||
|
||||
// transaction type
|
||||
{ "term": { "transaction.type": "request" }}
|
||||
|
||||
// event type (possible values : transaction, span, metric, error)
|
||||
{ "term": { "service.environment": "testing" }},
|
||||
{ "term": { "transaction.type": "request" }},
|
||||
{ "terms": { "processor.event": ["metric"] }},
|
||||
|
||||
// metric set is a subtype of `processor.event: metric`
|
||||
{ "terms": { "metricset.name": ["transaction"] }},
|
||||
|
||||
// time range
|
||||
{
|
||||
"range": {
|
||||
"@timestamp": {
|
||||
|
|
@ -422,5 +512,10 @@ Most Elasticsearch queries will need to have one or more filters. There are a co
|
|||
}
|
||||
]
|
||||
}
|
||||
},
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Possible values for `processor.event` are: `transaction`, `span`, `metric`, `error`.
|
||||
|
||||
`metricset` is a subtype of `processor.event: metric`. Possible values are: `transaction`, `span_breakdown`, `transaction_breakdown`, `app`, `service_destination`, `agent_config`
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue