Quickly Trace and Understand The Key Concepts of VictoriaMetrics
Tags: docker, victoriametrics, programming, infastructure
Published: 2024-05-14 14:00:00

## 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.

![Overall](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/yxqraen4ke16e9yfjep4.png)



---

## 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](https://docs.victoriametrics.com/quick-start/#starting-vm-single-via-docker) as reference & add `-retentionPeriod=100y` option to start up VictoriaMetrics.

![Start up VictoriaMetrics](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/fge4ymbjfhge6euyk5jg.png)

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](https://docs.victoriametrics.com/?highlight=retentionPeriod#operation). 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`.

![VictoriaMetrics README](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/qrv0hsfxklxrk3zoy6v1.png)

![Single-note VictoriaMetrics](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/w6xecd3r6jj7pfvdj598.png)

### Register your data with VictoriaMetrics
Register the data in the “Query data” section of [Key Concepts — VictoriaMetrics](https://docs.victoriametrics.com/keyconcepts/#query-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.

![Register data against the /api/v1/importendpoint with the curl command.](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/jhr7e7hc0l3gruvep1ls.png)

Register data against the `/api/v1/import` endpoint with the curl command.

![curl command](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/o03ceifzbv6b96jlrnyb.png)

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.

![simple ruby](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ftus4e7kjbu946qehv9o.png)

### 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”.

![Check](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/06c0h1l1d966gx5f82vx.png)

### Trace Query data in Key concepts

**1. Instant query**

Let’s start with the [Query data in Key concepts](https://docs.victoriametrics.com/keyconcepts/#query-data). 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.

![Instant query](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/jgtq1d3m870jygjnwkxx.png)

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`)

![Instant query1](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/r5po6tcenjxk9winnh7s.png)

Please read the [official description](https://docs.victoriametrics.com/keyconcepts/#instant-query) for more details.

**2. Range query**

Next, Let’s try the Range query.

![Range query](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/in0ro745ra9afs4568xd.png)

You can see that the intended value is returned.

Again, a point to note is that the JSON response listed in the [Range query](https://docs.victoriametrics.com/keyconcepts/#range-query) includes the number `7`, but `5` is probably the correct value here.

The explanatory text also includes a figure as shown below.

![Range query1](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/elaokq0xk6knpaoxxk7j.png)

![explanation](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/vxnsmbmqzlgio5xlyplj.png)

**3. 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. 

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.

![Check the shape](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/gvdzar8rj7mrimdz7jh0.png)

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](https://docs.growi.org/en/admin-guide/?utm_source=dev+community&utm_medium=referral&utm_campaign=Quickly_Trace_and_Understand_The_Key_Concepts_of_VictoriaMetrics) and use **in English**.

For more information, go to [GROWI.org](https://growi.org/en/?utm_source=dev+community&utm_medium=referral&utm_campaign=Quickly_Trace_and_Understand_The_Key_Concepts_of_VictoriaMetrics) to learn more about us. You can also follow our [Facebook](https://www.facebook.com/people/GROWIcloud/100089272547238/) to see updates about our service.

![GROWI.org](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/1rhpa0qcdukeall2vfsj.png)