# Simplified PromQL

## Getting started

Create your first chart using a PromQL query. Start by creating a dashboard in [Dashboards](https://telemetry.betterstack.com/team/0/dashboards) → **Create dashboard**.

Create a new chart on your dashboard and use a query like the one below:

```promql
[label Average rate of http requests]
avg(rate(http_requests_total))
```

[warning]
#### Simplified PromQL querying can only be used to query metrics
For querying logs, please use one of our other options
[/warning]

PromQL (Prometheus Query Language) is designed for querying time series data. In Betterstack, we've adapted a subset of PromQL to work with log data, allowing you to leverage some of your existing PromQL knowledge. Note that our implementation currently has some limitations:

1. The only supported function is `rate()`.
2. Some of the more advanced queries may not be supported yet

## Supported operations

Betterstack supports the following PromQL operations:

- Basic metric selection
- Label matching (e.g., `{label="value"}`)
- Aggregation operators with `by` and `without` clauses
- The `rate()` function
- Mathematical operations between series with the same tags

Aggregation operators include:

- `sum`: Calculate the sum of elements in the vector
- `avg`: Calculate the average of elements in the vector
- `min`: Select the minimum element of the vector
- `max`: Select the maximum element of the vector
- `count`: Count the number of elements in the vector
- `topk`: Select the k largest elements of the vector
- `bottomk`: Select the k smallest elements of the vector

## Examples

See the examples below for full queries using PromQL in Betterstack.

### HTTP request rate by method

```promql
[label Query the rate of HTTP requests]
sum by (method) (rate(http_requests_total))
```

This query returns the rate of HTTP requests, grouped by HTTP method.

### CPU usage rate by pod

```promql
[label Query CPU usage]
rate(container_cpu_usage_seconds_total{container!=""}) without (id)
```

This query returns the per-second rate of CPU usage over the last 15 minutes for each pod, excluding the "id" label.

### Average memory usage rate

```promql
[label Query memory usage by instance]
avg by (instance) (rate(process_resident_memory_bytes))
```

This query calculates the average per-second rate of memory usage for each instance.

### Top 5 most frequently accessed API endpoints

```promql
[label Query the top 5 most used api endpoints]
topk(5, sum by (endpoint) (rate(api_requests_total)))
```

This query returns the top 5 API endpoints with the highest per-second request rate.

### Network I/O rate by interface

```promql
[label Query the network transmission of each interface]
sum by (interface) (rate(network_transmit_bytes_total))
```

This query returns the per-second rate of network transmission (in bytes), grouped by network interface.

## Need help?

Please let us know at hello@betterstack.com.  
We're happy to help! 🙏