Tarantool 101, Guide 2: Build Yourself an IP Logging Microservice in 7 Basic Steps
Learn about tarantoolctl by seeing how to create a microservice that inserts the IP addresses of visitors to a webpage into a database.
Join the DZone community and get the full member experience.
Join For FreeThe in-memory database Tarantool is great for microservice architectures because it is versatile and self-sufficient:
It includes a full Lua application server that runs concurrent to its database server, which allows it to function without an additional back-end language.
It's fully ACID, so can handle transactional workloads.
It's persistent and can work with data sets larger than RAM.
But when you run a Tarantool microservice, you need a way to start it, keep it alive, and manage it. So this guide will demonstrate how to use tarantoolctl
, the utility that accomplishes these tasks for Tarantool instances. We'll learn tarantoolctl
by creating a microservice that inserts the IP addresses of visitors to a webpage into a database. Note that if you haven't read Tarantool 101: Guide 1, which teaches the absolute basics of Tarantool, you should probably start there (or at the very least, you'll need to install Tarantool as well as its HTTP module before using this guide).
The “training wheels” aspect of Guide 1 was that we ran everything from a single file. A Tarantool best practice, however, is to use two files for an instance: one for config code (which DBAs would presumably be responsible for) and one for application code (which developers would be responsible for). This enables you to, for example, run multiple Tarantool instances simultaneously with the same application code, using a different config file for each one.
1. Create the Config Code File Our Instance
So, let's begin by using nano
to create a config file for our application in the following location:
nano /etc/tarantool/instances.available/iplogger.lua
In the file, we'll place the code that a) calls and configures our database, b) creates a space after first checking whether a space with that name exists, c) creates a primary index — because at least one index is required for a Tarantool application, and d) calls in the application code from the file that we will create in the next step:
box.cfg{}
if not box.space.bigspace then
s = box.schema.space.create('bigspace')
s:create_index('primary',
{type = 'tree', parts = {1, 'unsigned'}})
end
local m = require('iplogger').start({...})
Now we will create a symlink to instances.enabled
from instances.available
(similar to NGINX):
ln -s /etc/tarantool/instances.available/iplogger.lua /etc/tarantool/instances.enabled
2. Create the Application Code File for Our Instance
Let's use nano
again to create the application code file in the following location:
nano /usr/share/tarantool/iplogger.lua
Then the code:
function handler(self)
local selfVar = self.peer.host;
box.space.bigspace:auto_increment{selfVar};
return self:render({
json = selfVar
})
end
function start()
local server = require('http.server').new(nil, 8081)
server:route({ path = '/'}, handler)
server:start()
end
return {
start = start;
}
Let’s begin by looking at the second function here, which is basically the same server code from Guide 1. However, we have wrapped it in the start
function and exported it, which enables us to call it from the config file that we made earlier. As regards the top function, similar to Guide 1, the server calls the handler
function on the root route. The handler function collects the IP (self.peer.host
) and then inserts it into the database using auto_increment
, which adds a new key to the database along with our data (which we assigned to the variable selfVar
). It then sends the data to the front end.
3. Check the Syntax
We can take a slight break for a moment to check the syntax of our two files. This is a nice additional functionality of tarantoolctl
:
tarantoolctl check /usr/share/tarantool/iplogger.lua
Then:
tarantoolctl check /etc/tarantool/instances.enabled/iplogger.lua
4. Start Application With tarantoolctl and Check Its Status
Now we can start our iplogger
application. tarantoolctl
can be started from any location on your server:
tarantoolctl start iplogger
You will get a message stating that the application has started. Once you receive that, you can check the status of the application with:
tarantoolctl status iplogger
5. Visit Our Server's IP and Log Our Browsing IP
We can now visit our server's IP, which will log our browsing IP. Similar to the previous tutorial, visit the server's IP on port 8081:
youripaddress:8081
You will see your browsing IP address displayed because we are sending it back from Tarantool to the browser. Refresh the page several times so that multiple records are inserted into the database.
6. Stop the Application
Now, let’s stop our application.
tarantoolctl stop iplogger
7. Show Our Logged Data
Next, we'll start the Tarantool console to see that our IPs were logged. This brings me to something that should be pointed out: the console cannot be run in just any directory like tarantoolctl
can. Rather, you need to run it in the same directory as your snapshot and log files. This can be specified in a config file but the default is /var/lib/tarantool
. So let’s go there:
cd /var/lib/tarantool/iplogger
Then:
tarantool
This is followed by the usual:
box.cfg{}
Now let’s display the contents of bigspace
:
box.space.bigspace:select()
You should see your IP records in tuples:
Additional Notes
There are a few other things I wanted to mention:
tarantoolctl
piggybacks on the Unix utilitysystemd
.The config file we used was tailored to our
iplogger
application buttarantoolctl
has its own config file, as well (etc/default/tarantool
), which overrides anything in the individual config files.It is generally advised to run one Tarantool application per CPU core at scale.
Now that you have seen how powerful, yet simple, Tarantool is, I hope that you will try out other ideas for microservices using it. Please let us know what you accomplish. I can be emailed directly at evan@tarantool.io, and if you would like to learn more about our enterprise support services, please fill out the form here.
Opinions expressed by DZone contributors are their own.
Comments