Quickly Trace and Understand The Key Concepts of VictoriaMetrics

6 min readJan 23, 2024

Introduction

Hi, I am Kouki, a system engineer from WESEEK, Inc. in Japan.

This article is a hands-on summary of the “Key Concepts — VictoriaMetrics” from the VictoriaMetrics documentation. My motivation for writing the article is as follows.

First, I couldn’t find any tutorials on the web where I could register my data and query by myself. Also, “Key Concepts — VictoriaMetrics” is easy to understand, with explanations and images, but it took some trials and errors to try on my own.

*Key Concepts explains the behavior of VictoriaMetrics with images like the one below, so I think it is a beneficial document for understanding.

This article contains:
· Try to Touch Key Concepts
∘ Preparation
∘ Launch VictoriaMetrics with docker command
∘ Register your data with VictoriaMetrics
∘ Confirm whether the data has been registered
∘ Trace Query data in Key concepts
· Conclusion

Try to Touch Key Concepts

Preparation

For this tutorial, I will assume that you have already established the following environment.

You should be able to type docker commands ( docker run … etc.)
You should have curl commands installed.
(optional*) jq command is installed.

Launch VictoriaMetrics with docker command

Use Quick start — VictoriaMetrics as reference & add -retentionPeriod=100y option to start up VictoriaMetrics.

The docker image tag is v1.85.3. in this case (Because there is a possibility of discrepancy with the article if it is latest).

The command option -retentionPeriod specifies the retention period of the data, as described in the VictoriaMetrics documentation. The default is 1 month (after which the data will be deleted), but in this tutorial, we plan to register data older than 1 month, so we specify 100y as a higher value.

The VictoriaMetrics README also states that the retention period cannot be set to “infinite” and should be set to 100y.

Register your data with VictoriaMetrics

The document describes the following data. From left to right, “Metrics Name”, “Data Value”, and “Time Stamp (Unix Time Stamp (milliseconds)”.

Note that 2022-05–10 10:00:00 is listed as a comment, but when checked in UTC, it is 2022-05–10 08:00:00 (minus 2 hours). Commands from here on will be based on the time minus 2 hours from the time listed in the official document.

I have prepared and implemented a simple ruby script that outputs a string of curl commands from space-delimited text. Since this script only outputs the above curl command, it is not very important and can be skipped.

Confirm whether the data has been registered

Let’s check if the data has been registered by the curl command described above. The time of the first data is set to 2022–05-10T08:00:00.000Z because the time is minus two hours, as described in “Notes”.

Trace Query data in Key concepts

Instant query

Let’s start with the Query data in Key concepts. It is recommended to open the Query data page of Key concepts in advance for smooth reading.

First, let’s try Instant query. Let’s try to throw a query at the time minus 2 hours.

The key point here is that “the value 3 was responded to even though there is no data for 2022-05–10T08:03:00.00 in the registered data”. (In the original data, between #2022–05–10 10:02:00 and #2022–05–10 10:04:00)

Please read the official description for more details.

Range query

Next, Let’s try the Range query.

You can see that the intended value is returned.

Again, a point to note is that the JSON response listed in the Range query includes the number 7, but 5is probably the correct value here.

The explanatory text also includes a figure as shown below.

The explanatory text also states the following, along with a diagram.

Check the shape of the graph in VM UI

VictoriaMetrics has a WebUI called VM UI that allows you to throw queries and see the results. (http://localhost:8428/vmui/ if you are on localhost)

Let’s check if the graph looks like the one shown in the image above.

When the screen appears, check the “Trace query” checkbox, change the “Step value” to 60 seconds (1 minute) to align the condition with the document image, and press the “EXECUTE QUERY” button to execute the query.

You can confirm that the “Range query” is as shown in the image.

If you would like to touch the VM UI yourself, you can do the same by clicking the button in the upper right corner of the screen that says “LAST 30 MINUTES” by default, specifying the time, and following the above procedure (setting Step Value and Trace Query).

Note that the query is based on the time zone of the browser you are using, so if your time zone is JST, set the query to plus 9 hours.

In the Range Query specified in curl above, it is 2022-05–10T07:59:00.000Z ~ 2022-05–10T08:17:00.000Z, so in JST it is 2022-05–10 16:59:00 ~ 2022-05–10 17:17:00.

Conclusion

Although I have cut out much of the explanations for each chapter of the document, we hope that through this article we have created an environment in which you can practically try VictoriaMetrics.

I would like to close with a list of interesting things that you can try.

Change “step=1m” to “step=1s” in “Range query” and count the number of data returned by jq (officially stated to be about 1000, but it is about 800).
Change the command line options passed to VictoriaMetrics, looking at the documentation.
Set retention period back to default and try to register the data in this article (You probably can’t register the data, but you may want to look at the docker logs to see if it works).

I hope this article helps you to better understand VictoriaMetrics.

About Us💡

In addition, we want to introduce a little more about GROWI, an open software developed by WESEEK, Inc.

GROWI is a wiki service with features-rich support for efficient information storage within the company. It also boasts high security and various authentication methods are available to simplify authentication management, including LDAP/OAuth/SAML.

GROWI originated in Japan and GROWI OSS is FREE for anyone to download and use in English.

For more information, go to GROWI.org to learn more about us. You can also follow our Facebook to see updates about our service.