|
| 1 | + |
| 2 | +This guide explains how to build custom charts for metrics in OpenObserve using PromQL. The goal is to help new and advanced users understand how raw metrics data transforms into a fully rendered chart through predictable and repeatable steps. |
| 3 | + |
| 4 | +## How metric data flows into a chart |
| 5 | +Metrics data in OpenObserve follows a fixed transformation pipeline: |
| 6 | + |
| 7 | +`Metrics data in OpenObserve > PromQL query > Matrix JSON > Transform into timestamp-value pairs > Render chart` |
| 8 | + |
| 9 | +This data pipeline never changes. Only two things vary: |
| 10 | + |
| 11 | +- The **PromQL query** |
| 12 | +- The **JavaScript transformation logic** that prepares data based on the chart you want to build |
| 13 | + |
| 14 | +The example uses the `container_cpu_time metric` and builds a time-series line chart. |
| 15 | + |
| 16 | + |
| 17 | +## How to build the custom chart for metrics using PromQL |
| 18 | + |
| 19 | +??? "Prerequisites" |
| 20 | + ### Prerequisites |
| 21 | + |
| 22 | + Before building a custom chart, ensure the following: |
| 23 | + |
| 24 | + - You have metrics data available in a metrics stream. |
| 25 | + - You know the basics of PromQL. |
| 26 | + - You know basic JavaScript because custom charts require writing JavaScript inside the editor. |
| 27 | + - You know the chart type you want to create and the data structure that chart expects. |
| 28 | + |
| 29 | +??? "Step 1: Explore the metrics data" |
| 30 | + ### Step 1: Explore the metrics data |
| 31 | + |
| 32 | + OpenObserve stores metrics as time series with labels and values. To understand how your metrics look, explore them directly: |
| 33 | + |
| 34 | + 1. Go to **Streams**. |
| 35 | + 2. Click the **Metrics** tab. |
| 36 | + 3. Navigate to the metrics stream. For example, `container_cpu_time` |
| 37 | +  |
| 38 | + 4.Click **Explore.** |
| 39 | +  |
| 40 | + This takes you to the **Logs** page and shows a time-series view: |
| 41 | +  |
| 42 | + <br> |
| 43 | + |
| 44 | + The two most important fields for charting are: |
| 45 | + |
| 46 | + - `timestamp` |
| 47 | + - `value` |
| 48 | + |
| 49 | + All charts ultimately use these two fields. |
| 50 | + |
| 51 | +??? "Step 2: Decide the chart you want to build" |
| 52 | + ### Step 2: Decide the chart you want to build |
| 53 | + |
| 54 | + Before you write a query or JavaScript, you must decide the chart type because every chart expects a specific structure. |
| 55 | + |
| 56 | + For example: |
| 57 | + |
| 58 | + - A line chart requires `[timestamp, value]` pairs |
| 59 | + - A bar chart requires `[category, value]` pairs |
| 60 | + - A multi-series chart requires an array of datasets |
| 61 | + |
| 62 | + Knowing the expected structure helps you prepare the right PromQL query and the right JavaScript transformation. |
| 63 | + |
| 64 | + |
| 65 | +??? "Step 3: Create a dashboard and select the metrics dataset" |
| 66 | + ### Step 3: Create a dashboard and select the metrics dataset |
| 67 | + |
| 68 | + 1. In the left navigation panel, select **Dashboards** and open or create a dashboard. |
| 69 | + 2. Add a panel and go to **Custom Chart** mode. |
| 70 | + 3. In the **Fields** section on the left, set **Stream Type** to **metrics**. |
| 71 | + 4. Select your metrics stream from the dropdown. For example: `container_cpu_time` |
| 72 | + |
| 73 | + This ensures that the PromQL query will run against the correct metrics dataset. |
| 74 | + |
| 75 | +??? "Step 4: Query and view your PromQL data" |
| 76 | + ### Step 4: Query and view your PromQL data |
| 77 | + Before building any chart, you must query the required metric. You can view the raw PromQL response to understand the structure that your JavaScript code must transform. |
| 78 | + |
| 79 | + 1. Navigate to the bottom of the panel editor. |
| 80 | + 2. The query editor section appears with two modes, **PromQL** and **Custom SQL**. |
| 81 | + 3. Click **PromQL** to switch the editor into PromQL mode. |
| 82 | + 4. In the PromQL editor, enter a PromQL expression. For example: `container_cpu_time{}` |
| 83 | + 5. To understand the data structure returned by the PromQL query, paste the following JavaScript in the code editor: |
| 84 | + ```js linenums="1" |
| 85 | + console.clear(); |
| 86 | + console.log("=== RAW DATA ARRAY ==="); |
| 87 | + console.log(data); |
| 88 | + |
| 89 | + // Pretty JSON view |
| 90 | + console.log("=== RAW DATA (Pretty JSON) ==="); |
| 91 | + console.log(JSON.stringify(data, null, 2)); |
| 92 | + |
| 93 | + // Print first query object safely |
| 94 | + if (Array.isArray(data) && data.length > 0) { |
| 95 | + console.log("=== FIRST QUERY OBJECT ==="); |
| 96 | + console.dir(data[0]); // Removed depth option |
| 97 | + } |
| 98 | + |
| 99 | + // Minimal valid option to avoid rendering errors |
| 100 | + option = { |
| 101 | + xAxis: { type: "time" }, |
| 102 | + yAxis: { type: "value" }, |
| 103 | + series: [] |
| 104 | + }; |
| 105 | + ``` |
| 106 | + 6. Select the time range in the time range selector. |
| 107 | + 7. Open your browser developer tools. Right-click anywhere inside the dashboard and select **Inspect**. |
| 108 | + 7. Open the **Console** tab. |
| 109 | + 8. In the panel editor, click **Apply**. |
| 110 | +  |
| 111 | + You get to see the complete raw PromQL response. |
| 112 | + |
| 113 | + !!! note "How to interpret it" |
| 114 | + OpenObserve returns PromQL data in the following structure: |
| 115 | + ```js linenums="1" |
| 116 | + [ |
| 117 | + { |
| 118 | + resultType: "matrix", |
| 119 | + result: [ |
| 120 | + { |
| 121 | + metric: { ...labels... }, |
| 122 | + values: [ |
| 123 | + [timestamp, value], |
| 124 | + |
| 125 | + ... |
| 126 | + ] |
| 127 | + } |
| 128 | + |
| 129 | + ] |
| 130 | + |
| 131 | + } |
| 132 | + |
| 133 | + ] |
| 134 | + ``` |
| 135 | + Here, |
| 136 | + |
| 137 | + - The outer array represents all PromQL queries in the panel. If you run one query, the array contains one item. |
| 138 | + - `resultType`: "matrix" indicates that PromQL returned time-series data. |
| 139 | + - The `result` array contains one entry for each time series in the query result. |
| 140 | + - Each metric object contains the labels that identify the series, such as `k8s_pod_name`, `container_id`, or `service_name`. |
| 141 | + - The `values` array contains the actual time-series datapoints. Each entry is `[timestamp, value]` where: |
| 142 | + |
| 143 | + - `timestamp` is in Unix seconds |
| 144 | + - `value` is the metric value at that moment |
| 145 | + |
| 146 | + This structure does not change. All metric visualizations in custom charts follow this same model. This is the starting point for all PromQL-based custom charts. |
| 147 | + |
| 148 | +??? "Step 5: Understand how to transform the data and render the chart" |
| 149 | + ### Step 5: Understand how to transform the data and render the chart |
| 150 | + Now that you have inspected the raw PromQL response, you can prepare the data and build a chart. |
| 151 | + Every PromQL-based custom chart in OpenObserve follows the same pipeline: |
| 152 | + `data > transform > series > option > chart` |
| 153 | + The following subsections explain each part in the correct order. |
| 154 | + |
| 155 | + #### `data`: The raw PromQL matrix |
| 156 | + This is the starting point. `data` object is automatically available inside your custom chart editor. It holds the raw response from your PromQL query. |
| 157 | + |
| 158 | + As shown in step 4, you will see the `data` object in the following structure: |
| 159 | + ```js linenums="1" |
| 160 | + [ |
| 161 | + { |
| 162 | + "resultType": "matrix", |
| 163 | + "result": [ |
| 164 | + { |
| 165 | + "metric": { |
| 166 | + "k8s_pod_name": "o2c-openobserve-collector-agent-collector-rkggr", |
| 167 | + "container_id": "d622222c9880db586ef3a81614ef720b5030e5a4c404ff89d1616abc117cf867" |
| 168 | + }, |
| 169 | + "values": [ |
| 170 | + [1763035098, "39370.53"], |
| 171 | + [1763035101, "39370.53"], |
| 172 | + ... |
| 173 | + ] |
| 174 | + } |
| 175 | + ] |
| 176 | + } |
| 177 | + ] |
| 178 | + ``` |
| 179 | + Here: |
| 180 | + |
| 181 | + - Each object inside result represents one metric series. |
| 182 | + - The metric object holds all identifying labels. |
| 183 | + - The values array holds the actual time-series data as `[timestamp, value]`. |
| 184 | + |
| 185 | + |
| 186 | + #### Transformation: Convert raw datapoints into chart-friendly points |
| 187 | + This is where you prepare the data for visualization. The chart that you want to build expects the data in a specific format, where each point is `[x, y]`. |
| 188 | + |
| 189 | + - `x` > time (in ISO format) |
| 190 | + - `y` > numeric value |
| 191 | + |
| 192 | + Perform the following conversion in JavaScript: |
| 193 | + ```js linenums="1" |
| 194 | + const points = item.values.map(([timestamp, value]) => [ |
| 195 | + new Date(timestamp * 1000).toISOString(), |
| 196 | + Number(value) |
| 197 | + ]); |
| 198 | + ``` |
| 199 | + After this step, you have clean, chart-ready data such as: |
| 200 | + ```js linenums="1" |
| 201 | + [ |
| 202 | + ["2025-11-13T09:18:00Z", 39370.53], |
| 203 | + ["2025-11-13T09:18:03Z", 39370.80] |
| 204 | + ] |
| 205 | + ``` |
| 206 | + !!! note "Note" |
| 207 | + Every chart type, whether line, bar, or scatter, starts with this transformation. Only how you display it changes later. |
| 208 | + |
| 209 | + #### `series`: Build one chart series per metric |
| 210 | + `series` is an array you create in your JavaScript code. Each entry in series describes one visual line, bar set, scatter set, and so on. |
| 211 | + |
| 212 | + Each entry has: |
| 213 | + |
| 214 | + - A name for the legend |
| 215 | + - A type such as line |
| 216 | + - A data array with the points you want to plot |
| 217 | + |
| 218 | + For example: |
| 219 | + |
| 220 | + ```js linenums="1" |
| 221 | + series.push({ |
| 222 | + name: item.metric.k8s_pod_name || "default", |
| 223 | + type: "line", |
| 224 | + data: points, |
| 225 | + smooth: true, |
| 226 | + showSymbol: false |
| 227 | + }); |
| 228 | + ``` |
| 229 | + |
| 230 | + #### `option`: Define the final chart configuration |
| 231 | + `option` defines how the chart looks and behaves. It tells the system what axes to use, whether to display tooltips or legends, and how to organize the visual elements. |
| 232 | + ```js linenums="1" |
| 233 | + option = { |
| 234 | + tooltip: { trigger: "axis" }, |
| 235 | + legend: { type: "scroll" }, |
| 236 | + xAxis: { type: "time", name: "Time" }, |
| 237 | + yAxis: { type: "value", name: "CPU Time" }, |
| 238 | + series |
| 239 | + }; |
| 240 | + ``` |
| 241 | + The `series` array you built earlier is now linked here. |
| 242 | + |
| 243 | +??? "Step 6: Transform the data and render the chart" |
| 244 | + ### Step 6: Transform the data and render the chart |
| 245 | + |
| 246 | + Here is the complete JavaScript code example that combines all steps mentioned in Step 5. |
| 247 | + <br> |
| 248 | + |
| 249 | + **PromQL query:** |
| 250 | + ``` |
| 251 | + container_cpu_time{} |
| 252 | + ``` |
| 253 | + <br> |
| 254 | + |
| 255 | + **JavaScript code:** |
| 256 | + |
| 257 | + ```js linenums="1" |
| 258 | + // Step 1: prepare an empty list of series |
| 259 | + const series = []; |
| 260 | + |
| 261 | + // Step 2: read the PromQL response from OpenObserve |
| 262 | + if (Array.isArray(data) && data.length > 0) { |
| 263 | + const query = data[0]; |
| 264 | + if (query.result && Array.isArray(query.result)) { |
| 265 | + for (const item of query.result) { |
| 266 | + if (!Array.isArray(item.values)) { |
| 267 | + continue; |
| 268 | + } |
| 269 | + |
| 270 | + // Step 3: convert [timestamp, value] to [ISO time, number] |
| 271 | + const points = item.values.map(([timestamp, value]) => [ |
| 272 | + new Date(timestamp * 1000).toISOString(), |
| 273 | + Number(value) |
| 274 | + ]); |
| 275 | + |
| 276 | + // Step 4: choose a label for the legend |
| 277 | + const name = |
| 278 | + item.metric.k8s_pod_name || |
| 279 | + item.metric.container_id || |
| 280 | + "unknown"; |
| 281 | + |
| 282 | + // Step 5: add one line series for this metric |
| 283 | + series.push({ |
| 284 | + name: name, |
| 285 | + type: "line", |
| 286 | + data: points, |
| 287 | + smooth: true, |
| 288 | + showSymbol: false |
| 289 | + }); |
| 290 | + |
| 291 | + } |
| 292 | + |
| 293 | + } |
| 294 | + |
| 295 | + } |
| 296 | + |
| 297 | + // Step 6: define how the chart should be drawn |
| 298 | + |
| 299 | + option = { |
| 300 | + tooltip: { trigger: "axis" }, |
| 301 | + legend: { type: "scroll", top: "top" }, |
| 302 | + xAxis: { type: "time", name: "Time" }, |
| 303 | + yAxis: { type: "value", name: "Value" }, |
| 304 | + series: series |
| 305 | + }; |
| 306 | + ``` |
| 307 | + |
| 308 | + The line chart uses `[timestamp, value]` pairs and plots each metric as a line across time. |
| 309 | + |
| 310 | +??? "Step 7: View the result" |
| 311 | + ### Step 7: View the result |
| 312 | +  |
| 313 | + Select the time range from the time range selector and click **Apply** to render your chart. |
| 314 | + |
| 315 | + Each unique metric label combination will appear as a separate line. |
| 316 | + |
| 317 | +!!! note "Note" |
| 318 | + You can use the same JavaScript code to create other charts that use [timestamp, value]. For example, bar charts or scatter charts. Only change the **type** in the above JavaScript code: |
| 319 | + ``` |
| 320 | + type: "bar" |
| 321 | + ``` |
| 322 | + or |
| 323 | + |
| 324 | + ``` |
| 325 | + type: "scatter" |
| 326 | + ``` |
0 commit comments