Increase your RavenDB observability with Grafana Cloud and OpenTelemetry

What you will learn

• How to enable OpenTelemetry in RavenDB
• How to connect your RavenDB to Grafana Cloud
• How to create basic visualization in Grafana Cloud

Introduction

Increasing your system’s observability is often much appreciated, but setting up database monitoring can become complex. That’s why, in this article, we’ll precisely guide you through setting up OpenTelemetry to use RavenDB with Grafana Cloud. This will allow you to create pretty dashboards that visualize metrics seamlessly.

OpenTelemetry is a collection of APIs, SDKs, and tools. RavenDB uses it to instrument, generate, collect, and export telemetry data (metrics, logs, and traces) to help you analyze its performance and behavior.

Feature availability & future releases

Cloud availability

Before we dive in – when writing this article, OpenTelemetry is unavailable for RavenDB Cloud, but it will land in the first quarter of 2025. Until then, please use the RavenDB Cloud Monitoring feature or metrics available from the ‘Products’ view and click the heart symbol.

OpenTelemetry Dashboard coming soon

In the future, an OpenTelemetry RavenDB dashboard might be ready to go with just a few clicks. Look out for releases.

Prerequisites

What you will need:

• Grafana Cloud account
• RavenDB cluster with database

RavenDB database

Before connecting RavenDB to Grafana, ensure your RavenDB cluster is running. To learn more about installation and our Setup Wizard, click here.

Download RavenDB from its website, extract it, and launch Raven.Server.exe or from the server directory. Once the terminal generates a URL, open it in your browser, accept the EULA, and create a new cluster. Choose your security level, proceed with the setup, and click “Finish” unless you have specific requirements.

Grafana Cloud account

With a RavenDB server ready, you will also need a Grafana Cloud account. To create an account, go to the Grafana website and select the ‘Create Account’ button. You want to fill in your E-mail and password or use one of the other sign-in options. 

Now, you must choose your stack URL and deployment region, which should be as close to your RavenDB server as possible. Once you’ve completed this, let’s begin configuring your Grafana.

Setup

Getting stuff from Grafana

Now that you have prepared everything you need—Grafana Cloud account and RavenDB database server—it’s time to connect everything. First, let’s skip templates. No template can help in our case. Select ‘I’m already familiar with Grafana. Skip Setup’ at the bottom of the setup window.

Next, on your home page, choose ‘Add users.’ That will take you to the Grafana Cloud panel, where you will get all the needed options. On the left side, under Grafana Cloud, click on your domain name. On the list, find OpenTelemetry and click ‘Configure’.

Putting things into settings.json

Once you are on the OpenTelemetry configuration page, we can start setting up your connection. In your RavenDB directory, open the ‘Server’ directory and open ‘settings.json’. You need to turn on OpenTelemetry. To do that, paste the following code inside existing brackets:

  "Monitoring.OpenTelemetry.Enabled": true,

  "Monitoring.OpenTelemetry.OpenTelemetryProtocol.Headers": "Authorization=Basic SPACE_FOR_YOUR_TOKEN",

  "Monitoring.OpenTelemetry.OpenTelemetryProtocol.Endpoint": "https://otlp-gateway-prod-your-region.grafana.net/otlp/v1/metrics",

  "Monitoring.OpenTelemetry.OpenTelemetryProtocol.Protocol": "HttpProtobuf",

Don’t close the window, we will return here later. Now, come back to Grafana. From the OpenTelemetry config, copy an endpoint that starts with:

https://otlp-gateway-prod-your-region.grafana.net/otlp

Instead of ‘your-region’, your Grafana Cloud server should have an endpoint region. After pasting it in settings into Monitoring.OpenTelemetry.OpenTelemetryProtocol.Endpoint append URL path /1/metric at the end so that it is like the following:

  "Monitoring.OpenTelemetry.OpenTelemetryProtocol.Endpoint":
"https://otlp-gateway-prod-your-region.grafana.net/otlp/v1/metrics",

Afterward, go back to your Grafana and find ‘Password / API Token’ where you want to click ‘Generate now’ placed next to it. In the popup window, choose your token name and click the ‘Create token’ button.

After it generates your token, you can close this popup and look under it in the ‘Environment Variables’ section. There, you want to copy the key starting with ‘Authorization=Basic’ and paste it into ‘”Monitoring.OpenTelemetry.OpenTelemetryProtocol.Headers”:’ So it looks similar to that:

"Monitoring.OpenTelemetry.OpenTelemetryProtocol.Headers": "Authorization=Basic MTEwMTcwOTpnbGN...4ta="

Then you can add some code below HttpProtobuf. They enable a few non-default options:

  "Monitoring.OpenTelemetry.Meters.AspNetCore.Enabled": true,

  "Monitoring.OpenTelemetry.Meters.Runtime.Enabled": true,

  "Monitoring.OpenTelemetry.Meters.Server.GC.Enabled": true

After pasting your token, save your settings.json and restart the RavenDB server. Returning to your web browser, you can go to the Grafana Cloud panel and choose launch under Grafana. This will let you go back to your home page. To check the connection, unfold ‘Explore’ on the left bar, then ‘Metrics’, and click ‘Let’s start!’. You should see available metrics there. If you don’t see any metrics immediately, it is possible that your server hasn’t sent any data yet. RavenDB sends OpenTelemetry data once a minute, so you need to be patient. Such metrics should look like this.

Creating the CPU Dashboard

We’ve successfully connected. Let’s make a simple one-metric dashboard. 

Open the left bar again and click on the ‘Dashboards’ section. Then, on this site’s right side, click ‘New’ and choose ‘New dashboard’. Next, you want to ‘Add visualization’ and choose grafanacloud with your stack name and default tag.

Now, you have many options and probably don’t know where to start. First, let’s add a new metric. The option to do that is on the bottom bar. Click on ‘Select metric’ and search for CPU. Then scroll down to the bottom of the list and select ‘ravendb_server_resources_cpu_process’. 

After selecting this, you need to press the ‘Run queries’ button, which should show you a chart (can be a straight line).

You have your first metric, but let’s add more finishing touches. On the right bar, change the title to ‘Current CPU usage %’. 

Next, scroll down lower until you find standard options. Choose ‘Misc’ and ‘Percent (0-100)’ in the’ Unit’ options. If you look lower, you can see the Min and Max options. You should set the Minimum to 0 and the Maximum to 100. You can also change the ‘Display name’ that you can find under Max. You should also set ‘No value’ to ‘0’ so your chart will know what to display if there is no data.

Next, you can scroll down to the threshold options and change “Show threshold” to ‘As filled regions and lines (dashed) to see when your usage goes above 80%.

Once you have your visualization set, you need to change the manual refresh on top to 1m so it refreshes automatically every minute.

And that’s it. Your dashboard now has a functioning metric. You can save this visualization at the top right side of the window.

Summary

We prepared and connected your RavenDB database to the Grafana cloud using OpenTelemetry and also created a basic visualization of CPU usage for your new dashboard. This increases database observability and can be broadly expanded to meet your needs.