Skip to main content
Version: v3.x (DDN)

Get Started with Hasura DDN and Prometheus

Overview​

This tutorial takes about twenty minutes to complete. You'll learn how to:

  • Set up a new Hasura DDN project
  • Connect it to a Prometheus instance
  • Generate Hasura metadata
  • Create a build
  • Run your first query

Additionally, we'll familiarize you with the steps and workflows necessary to iterate on your API.

This tutorial assumes you're starting from scratch; you'll connect a locally-running Prometheus instance — set up to scrape metrics from itself — to Hasura, but you can easily follow the steps if you already have an existing Prometheus server. Hasura will never modify your source schema.

Prerequisites​

Install the DDN CLI

Minimum version requirements

To use this guide, ensure you've installed/updated your CLI to at least v2.28.0.

Simply run the installer script in your terminal:

curl -L https://graphql-engine-cdn.hasura.io/ddn/cli/v4/get.sh | bash
ARM-based Linux Machines

Currently, the CLI does not support installation on ARM-based Linux systems.

Install Docker

The Docker-based workflow helps you iterate and develop locally without deploying any changes to Hasura DDN, making the development experience faster and your feedback loops shorter. You'll need Docker Compose v2.20 or later.

Validate the installation

You can verify that the DDN CLI is installed correctly by running:

ddn doctor

Tutorial​

Step 1. Authenticate your CLI​

Before you can create a new Hasura DDN project, you need to authenticate your CLI:
ddn auth login

This will launch a browser window prompting you to log in or sign up for Hasura DDN. After you log in, the CLI will acknowledge your login, giving you access to Hasura Cloud resources.

Step 2. Scaffold out a new local project​

Next, create a new local project:
ddn supergraph init my-project && cd my-project

Once you move into this directory, you'll see your project scaffolded out for you. You can view the structure by either running ls in your terminal, or by opening the directory in your preferred editor.

Step 3. Initialize your Prometheus connector​

In your project directory, run:
ddn connector init my_prometheus -i

From the dropdown, select hasura/prometheus (you can type to filter the list). Then, enter the following connection string when prompted:

http://local.hasura.dev:9090

Step 4. Start the local Prometheus instance​

Begin by creating a compose file for the Prometheus server:
touch app/connector/my_prometheus/compose.prometheus.yaml
Then, open the file and add the following:
services:
  prometheus:
    image: prom/prometheus:latest
    container_name: prometheus
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
    command:
      - "--config.file=/etc/prometheus/prometheus.yml"
In the same directory, create a Prometheus configuration file:
touch app/connector/my_prometheus/prometheus.yml
Then, open the file and add the following:
global:
  scrape_interval: 15s

scrape_configs:
  - job_name: "prometheus"
    static_configs:
      - targets: ["local.hasura.dev:9090"]
Run the container:
docker compose -f app/connector/my_prometheus/compose.prometheus.yaml up -d

You can open Prometheus by visiting: http://localhost:9090. Go ahead and navigate here and poke around...we'll need some requests against the server for our queries later!

Step 5. Introspect your Prometheus server​

Next, use the CLI to introspect your Prometheus server:
ddn connector introspect my_prometheus

After running this, you should see a representation of your Prometheus server's schema in the app/connector/my_prometheus/configuration.yaml file; you can view this using cat or open the file in your editor.

Additionally, you can check which resources are available — and their status — at any point using the CLI:
ddn connector show-resources my_prometheus

Step 6. Add your model​

Now, let's track a common counter metric as a model in your DDN metadata:
ddn model add my_prometheus prometheus_http_requests_total

Open the app/metadata directory and you'll find a newly-generated file: PrometheusHttpRequestsTotal.hml. The DDN CLI will use this Hasura Metadata Language file to represent the prometheus_http_requests_total metric from Prometheus in your API as a model.

Step 7. Create a new build​

To create a local build, run:
ddn supergraph build local

The build is stored as a set of JSON files in engine/build.

Step 8. Start your local services​

Start your local Hasura DDN Engine and Prometheus connector:
ddn run docker-start

Your terminal will be taken over by logs for the different services.

Step 9. Run your first query​

In a new terminal tab, open your local console:
ddn console --local

We'll write a GraphQL query that's the equivalent of this PromQL query:

sum(rate(prometheus_http_requests_total{job="prometheus"}[1m]))
In the GraphiQL explorer of the console, write this query:
query GET_REQUESTS_PER_SECOND {
  prometheusHttpRequestsTotal(
    args: { fn: [{ rate: "1m" }, { sum: [] }] }
    where: { timestamp: { _gt: "2025-03-26" }, job: { _eq: "prometheus" } }
  ) {
    timestamp
    value
  }
}
Change the _gt value

For the most accurate results, change the date value to a recent date.

You'll get a response that looks like this:
{
  "data": {
    "prometheusHttpRequestsTotal": [
      {
        "job": "prometheus",
        "timestamp": 1743004075,
        "value": 0.08889283968176363
      }
    ]
  }
}

Step 10. Add another model​

Add the process_cpu_seconds_total counter metric:
ddn model add my_prometheus process_cpu_seconds_total

In app/metadata you'll find a newly-generated file: ProcessCpuSecondsTotal.hml. This will be used to expose the counter metric via your supergraph API.

Step 11. Rebuild your project​

Next, create a new build:
ddn supergraph build local
Bring down the services by pressing CTRL+C and start them back up:
ddn run docker-start

Step 12. Query your new build​

Head back to your console and query the new model:
query GET_CPU_PROCESS_TOTAL {
  processCpuSecondsTotal(
    args: { fn: [{ rate: "1m" }, { sum: [] }] }
    where: { timestamp: { _gt: "2025-03-26" }, job: { _eq: "prometheus" } }
  ) {
    timestamp
    value
  }
}
You'll get a response that looks like this:
{
  "data": {
    "processCpuSecondsTotal": [
      {
        "timestamp": 1743010998,
        "value": 0.002222123461179495
      }
    ]
  }
}

Next steps​

Congratulations on completing your first Hasura DDN project with Prometheus! 🎉

Here's what you just accomplished:

  • You started with a fresh project and connected it to a local Prometheus server.
  • You set up metadata to represent your counter metrics, which acts as the blueprint for your API.
  • Then, you created a build — essentially compiling everything into a ready-to-use API — and successfully ran your first GraphQL queries to fetch data.
  • Along the way, you learned how to iterate on your schema and refresh your metadata to reflect changes.

Now, you're equipped to connect and expose your data, empowering you to iterate and scale with confidence. Great work!

Take a look at our Prometheus docs to learn more about how to use Hasura DDN with Prometheus. Or, if you're ready, get started with adding permissions to control access to your API.

© 2025 Hasura Inc. All rights reserved